INTEGRITY Документация

← Cloudflare API Shield / api-shield / security / schema-validation

Настройка API

Используйте API для загрузки, активации, просмотра списка и удаления схем OpenAPI. Загруженная схема предоставляет Schema Profile для своих операций.

Настройка загруженной схемы

  1. Загрузите схему.
  2. Добавьте операции схемы в инвентарь Web Assets.
  3. Активируйте схему, чтобы включить оценку загруженного профиля.
  4. Направьте репрезентативный трафик через настроенные операции.
  5. Анализируйте cf.schema_validation.uploaded.violated в Анализ профиля.
  6. Настройте блокировку с помощью WAF Custom Rules.

Изменения настроек могут вступить в силу в течение нескольких минут.

Конфигурация

Загрузка и активация схемы

Загрузите схему с POST. В этом примере используется example_schema.yaml из текущего каталога.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Загрузить схему
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"kind": "openapi_v3",
		"name": "example_schema",
		"source": "<SOURCE>",
		"validation_enabled": true
	}'
{
	"result": {
		"schema": {
			"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
			"name": "example_schema",
			"kind": "openapi_v3",
			"source": "<SOURCE>",
			"created_at": "2023-04-03T15:10:08.902309Z"
		}
	},
	"success": true,
	"errors": [],
	"messages": []
}

По умолчанию проверка по загруженной схеме отключена. Задайте validation_enabled=true чтобы проверка была доступна во время загрузки.

Используйте PATCH чтобы включить проверку после анализа схемы.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Включение проверки для схемы
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/api_gateway/user_schemas/$SCHEMA_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"validation_enabled": true
	}'
{
	"result": {
		"schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0",
		"name": "api_schema.json",
		"kind": "openapi_v3",
		"validation_enabled": true,
		"created_at": "0001-01-01T00:00:00Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Активация делает доступной оценку загруженного профиля для настроенных операций. Она не настраивает противодействие.

Добавление операций схемы

Схемы содержат хосты, пути и методы, которые определяют операции. Операция представляет конечную точку в виде комбинации HTTP-метода, шаблона имени хоста и шаблона пути.

Schema Validation проверяет запросы только для операций, добавленных в Web Assets. Чтобы получить операции схемы и их конфигурацию, используйте GET.

команда cURL
curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json'
{
	"result": [
		{
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 30,
		"count": 1,
		"total_count": 1
	}
}

Чтобы получить информацию о конфигурации существующих операций, Cloudflare рекомендует передавать ?feature=schema_info параметр.

Добавьте операции схемы в Web Assets с помощью POST.

команда cURL
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '[
  {
   "method": "GET",
   "host": "example.com",
   "endpoint": "/pets",
  }
]'
{
	"result": [
		{
			"operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae",
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets",
			"last_updated": "2023-04-04T16:07:37.575971Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

Вы можете добавлять операции схемы, которых нет в Web Assets. Этот вызов API поддерживает до 20 операций и требует jq. Для схем с более чем 20 новыми операциями запустите команду повторно, чтобы добавить следующую партию.

команда cURL
response="$(curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&page=1&per_page=20&operation_status=new" --header "Authorization: Bearer <API_TOKEN>")" || exit 1
operations="$(printf "%s" "$response" | jq --exit-status ".result")" || exit 1

if [ "$(printf "%s" "$operations" | jq "length")" -eq 0 ]; then
	printf "No new operations found.\n"
else
	curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
	--header "Authorization: Bearer <API_TOKEN>" \
	--header "Content-Type: application/json" \
	--data "$operations" || exit 1
fi

Список всех схем

Список загруженных схем в зоне с помощью GET.

validation_enabled=true является необязательным параметром.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Список всех загруженных схем
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
    "result":  [
        {
	        "schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
	        "name": "example_schema",
	        "kind": "openapi_v3",
	        "source": "<SOURCE>",
	        "created_at": "2023-04-03T15:10:08.902309Z"
	    }
    ]
    "success": true,
    "errors":
    [],
    "messages":
    []
}

Удаление схемы

Вы можете удалить схему с помощью DELETE.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Удаление схемы
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}