← Cloudflare API Shield / api-shield / security

Schema validation

Схема API определяет, какие запросы API считаются допустимыми, на основе ряда свойств запроса, таких как целевая конечная точка, формат пути или переменных запроса и метод HTTP.

Schema Validation сравнивает входящие запросы с загруженной схемой OpenAPI. Загруженная схема задаёт ожидаемую структуру запроса для Schema Profile.

После того как загруженный профиль станет доступен, Cloudflare создаёт постоянное обнаружение. Используйте cf.schema_validation.uploaded.violated чтобы анализировать нарушения и противодействовать им.

Само по себе обнаружение не блокирует трафик. Просмотрите результаты в разделе Анализ профиля перед применение профиля с помощью Custom Rules.

Schema Validation 2.0 является текущей версией. Справочные материалы по предыдущей версии см. в Настройка Classic Schema Validation.

Конечные точки должны существовать как операции в Web Assets > Операции. При загрузке через дашборд операции схемы добавляются автоматически.

При использовании API или Terraform добавляйте операции схемы по отдельности. Подробнее об автоматизации см. в Настройка API или Terraform.

Применение изменений может занять несколько минут в зависимости от количества операций.

При удалении загруженной схемы прекращается оценка её профиля. Связанные операции остаются в инвентаре Web Assets.

Правило fallthrough соответствует запросам, которые не совпадают ни с одной известной операцией. Используйте это пользовательское правило WAF для защиты от неопознанных конечных точек.

Для пользовательской логики используйте cf.api_gateway.fallthrough_detected. Ограничьте область действия правила хостнеймом вашего API или корневым путём.

В настоящее время Cloudflare принимает только Схемы OpenAPI v3 ↗. Допустимые форматы файлов: YAML (.yml или .yaml расширение файла) и JSON (.json расширение файла).

Схемы OpenAPI, созданные разными инструментами, порой недостаточно точны для импорта в Schema validation. В этом случае используйте стороннее средство, например Swagger Editor ↗ чтобы убедиться, что схемы соответствуют спецификации OpenAPI.

Schema validation (импорт) в составе Cloudflare API Shield и Schema learning (экспорта) возможности зависят от OpenAPI Specification (OAS) v3.0 ↗.

Поддержка распространяется на все patch-версии, например OAS v3.0.x. OAS v3.1 не поддерживается, и расширять поддержку до OpenAPI 2.0 не планируется.

На данный момент API Shield не поддерживает некоторые возможности схем API, в том числе: все ответы, внешние ссылки, нетривиальное шаблонирование путей и уникальные элементы.

Существует ограничение в 10 000 операций для включённых схем для клиентов с планом Enterprise, подписанных на API Shield. Чтобы увеличить этот лимит, обратитесь к своей команде по работе с аккаунтом.

Schema Validation проверяет тело запроса до максимального размера, установленного для тарифного плана. Запросы, превышающие этот лимит, не проверяются по загруженной схеме.

Ограничения по умолчанию на размер тела запроса:

Используйте журналы запросов, чтобы сравнить размер тела запроса с лимитом вашего тарифного плана.

Сведения об ограничениях для клиентов на тарифах Free, Pro, Business или Enterprise без подписки на API Shield см. в Планы.

Хотя спецификация OpenAPI не требует этого строго, для Schema validation эти поля обязательны.

• type ↗
  • Для всех схем нужно задать тип. Если конкретный тип не поддерживается Schema validation, укажите тип string взамен.

• schema ↗
  • Schema validation не поддерживает поле content в параметрах. Подробнее см. в примечания о проверяемых и поддерживаемых полях ниже. Вместо этого схема строго обязательна для всех объектов parameters.

Подробные сведения о том, какие объекты и поля спецификации OpenAPI (OAS) поддерживает Schema validation в настоящее время, приведены ниже.

• url ↗
  • Schema validation не поддерживает относительные URL.
• variables ↗
  • Серверные переменные не проверяются.

• style ↗
  • Поддерживаются только значения по умолчанию: "simple" (параметры path или header) и "form" (параметры query или cookie).
• explode ↗
  • Поддерживаются только значения по умолчанию: true (для form) и false (для simple).
• content ↗
  • Поле content не поддерживается в parameters. Используйте вместо него поле schema.
• type ↗
  • В настоящее время Cloudflare не проверяет параметры типа object.

• $ref ↗
  • Внешние или относительные ссылки не поддерживаются.

• content
  • Request Body Object ↗
  • Media Type Object ↗
    • Schema validation может проверять application/json документов. Если данная схема допускает другие типы содержимого, Schema validation будет принимать такие запросы без проверки.

• anyOf
  • Parameter Object ↗
  • Schema Object ↗
    • anyOf схемы в настоящее время не поддерживаются в схемах параметров.

• format ↗
  • Допустимые форматы:
    • date-time
    • time
    • date
    • email
    • hostname
    • ipv4
    • ipv6
    • uri
    • uri-reference
    • iri
    • iri-reference
    • int32
    • int64
    • float
    • double
    • password
    • uuid
    • byte
    • uint64
• uniqueItems ↗
  • В настоящее время это поле не проверяется функцией Schema validation.

API Shield умеет распознавать спецификации тела запроса, содержащиеся в загруженных схемах, и проверять, соответствуют ли им данные входящих запросов к API.

Schema validation в настоящее время поддерживает проверку запросов с content-type application/json.

В спецификации OpenAPI схемы тела запроса связаны с media-range (например, application/*, application/xml или application/json).

Когда Cloudflare проверяет входящие запросы, она проверяет, что у запроса content-type соответствует диапазону media-range, указанному в OpenAPI.

Например, когда файл OpenAPI указывает application/* как часть карты содержимого тела запроса, Cloudflare будет принимать запросы с типами содержимого application/xml и application/json. Однако только application/json тела запросов будут проверяться по предоставленной схеме.

Cloudflare рекомендует делать media-ranges как можно более узкими, указывая отдельный media-type. Если конечной точке API нужно поддерживать несколько content-type, можно использовать media-ranges с подстановочными знаками.

Также стоит проявить осторожность, если origin-сервер настроен на выполнение MIME-сниффинг ↗. Например, если запрос с телом JSON намеренно содержит application/malicious content-type, и Cloudflare был настроен на разрешение application/* media-range, запрос будет передан источнику без проверки содержимого тела JSON. Однако источник, который игнорирует content-type и либо пробует десериализовать данные, либо определяет MIME-тип самостоятельно, может десериализовать тело JSON, ошибочно предположив, что проверка тела по схеме была пройдена.

Поэтому если вам нужно поддерживать application/json и application/xml на той же конечной точке, вы можете использовать application/*. Cloudflare будет проверять предоставленную схему для тел запросов, у которых content-type задан как application/json. Запросы с content-type application/xml (и другие, соответствующие application/*) будут пропущены. Тем не менее настоятельно рекомендуется отключить определение типа содержимого (content-type sniffing) на исходном сервере.

Cloudflare позволяет указывать следующие media-ranges в карте содержимого тела запроса OpenAPI:

• */*
• application/*
• application/json.

Диапазоны media-range также можно настроить для применения charset параметр. Для этого Cloudflare принимает только charset параметр со статическим значением utf-8 как часть спецификации media-range, и при соответствующей настройке мы также будем требовать, чтобы content-type запроса содержал этот charset.

В этом разделе рассматриваются типичные проблемы, с которыми вы можете столкнуться при использовании проверки схемы.

A OneOf ошибка ограничения означает, что запрос не соответствует загруженному профилю. Его тело не совпало ровно с одним oneOf ↗ опцию.

Запрос был недействителен по одной из двух причин:

• Соответствует нулю: тело запроса не соответствует ни одной из доступных подсхем. Обычно это происходит, если задано поле-дискриминатор, но в теле запроса отсутствуют другие обязательные поля для этого типа.
• Соответствует нескольким: тело запроса оказалось неоднозначным и соответствует сразу нескольким подсхемам. Это происходит с общими схемами, например если тело запроса включает как email и phone поле, оно может совпасть как с email и phone определение схемы, нарушая правило "exactly one").

Чтобы устранить проблему, сравните пример запроса с определением схемы. Возможно, в запросе отсутствуют обязательные поля или указаны несовместимые типы.

Клиенты с API Security уже имеют доступ к Schema Profiles через Schema Learning и Schema Validation. Cloudflare открывает закрытый бета-тест для приглашённых клиентов с тарифным планом Enterprise без API Security. Заинтересованные клиенты могут обратиться в свой account team, чтобы заявить об интересе. Доступ к закрытой бете не гарантирует доступность в будущих тарифных планах и не определяет их стоимость.