← Cloudflare API Shield / api-shield / security

Настройка Vulnerability Scanner через API

Используйте Cloudflare Vulnerability Scanner, чтобы проверить конечные точки вашего API на уязвимости, например Broken Object Level Authorization (BOLA). В этом руководстве описано, как запустить первое сканирование на уязвимости через Cloudflare API.

Предварительные требования

Необходимо иметь:

Хотя бы одна зона в аккаунте.
Схема OpenAPI, описывающая API, который вы хотите просканировать.
Учётные данные API для вашей цели. Сканеру нужно проходить аутентификацию от имени разных пользователей, чтобы проверять наличие уязвимостей BOLA.

Процесс

Создание API-токена

Все запросы API используют базовый URL-адрес https://api.cloudflare.com/client/v4/ и выполните аутентификацию с помощью Bearer токен в Authorization заголовок.

Создание API-токена в панели управления Cloudflare со следующим разрешения ограниченный целевым аккаунтом: Аккаунт > API Gateway > Изменить

Сохраните API-токен и Account Tag из раздела учётной записи Обзор на странице панели управления Cloudflare в качестве переменных окружения для использования в следующих командах.

export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"

Создание целевой среды

Целевая среда определяет, что именно должен сканировать сканер. На данный момент поддерживается только один тип цели: zone.

Найдите Zone Tag на странице зоны Обзор на странице панели управления Cloudflare и экспортируйте его.

export ZONE_TAG="<YOUR_ZONE_TAG>"

Используйте следующее POST запрос для создания целевой среды.

команда cURL

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/target_environments" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Production API",
    "description": "Main production zone for API scanning",
    "target": {
      "type": "zone",
      "zone_tag": "'"${ZONE_TAG}"'"
    }
  }'

Сохраните ID целевой среды из ответа в переменную TARGET_ENV_ID.

(Необязательно) Вы можете проверить целевую среду, выполнив GET запрос по следующему URL-адресу.

https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/target_environments/${TARGET_ENV_ID}

Создать наборы учетных данных

На данный момент сканер поддерживает только сканирование BOLA. Для этого нужны два набора учетных данных:

Владелец: легитимный пользователь, которому принадлежат тестируемые ресурсы.
Злоумышленник: другой легитимный пользователь, у которого не должно быть доступа к ресурсам владельца.

Сканер выполняет аутентификацию от имени обоих пользователей и проверяет, может ли злоумышленник получить доступ к ресурсам владельца. Каждый набор учётных данных оформляется как credential set, включающий одну или несколько учётных записей.

Используйте следующее POST запросов, чтобы создать набор учётных данных Owner и набор учётных данных Attacker.

Набор учётных данных владельца

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Owner Credentials" }'

# Export the ID from the response
export OWNER_CRED_SET_ID="<OWNER_CRED_SET_ID>"

Набор учётных данных злоумышленника

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Attacker Credentials" }'

# Export the ID from the response
export ATTACKER_CRED_SET_ID="<ATTACKER_CRED_SET_ID>"

Добавление учётных данных в каждый набор учётных данных

Элемент учётных данных описывает один токен аутентификации или значение сессии, которое сканер добавляет к своим запросам.

Используйте следующее POST запросов, чтобы добавить учётные данные владельца и злоумышленника в каждый набор.

Учётные данные владельца (Header)

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/${OWNER_CRED_SET_ID}/credentials" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Owner Bearer Token",
    "location": "header",
    "location_name": "authorization",
    "value": "Bearer eyJhbGciOiJSUzI1NiIs...owner-token"
  }'

Учётные данные злоумышленника (Cookie)

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/${ATTACKER_CRED_SET_ID}/credentials" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Attacker Session Cookie",
    "location": "cookie",
    "location_name": "session_id",
    "value": "attacker-session-token-value"
  }'

(Необязательно) Вы можете получить список всех учётных данных в наборе с помощью GET запрос по следующему URL-адресу.

https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/<CRED_SET_ID>/credentials

Start a scan

Когда целевое окружение и два набора учетных данных готовы, можно запускать BOLA-сканирование.

Убедитесь, что ваша схема OpenAPI отформатирована как строка, например с помощью jq.

OPEN_API_SCHEMA=$(jq -c . < openapi.json)

Используйте следующее POST запрос для запуска сканирования.

команда cURL

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n \
    --arg te_id "$TARGET_ENV_ID" \
    --arg schema "$OPEN_API_SCHEMA" \
    --arg owner "$OWNER_CRED_SET_ID" \
    --arg attacker "$ATTACKER_CRED_SET_ID" \
    '{
      target_environment_id: $te_id,
      scan_type: "bola",
      open_api: $schema,
      credential_sets: { owner: $owner, attacker: $attacker }
    }')"

Сохраните ID скана из ответа.

export SCAN_ID="<SCAN_ID>"

Проверить статус сканирования можно с помощью GET запрос.

команда cURL

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

Получите отчёт о сканировании

После того как сканирование получит статус completed, доступен отчёт с подробными результатами по проверенным уязвимостям.

команда cURL

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

Обобщить результаты отчёта может быть проще с помощью jq.

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq '.result.report.report.tests[] | {test_verdict: .verdict, steps: [.steps | to_entries[] | {step: (.key + 1), method: .value.request.method, url: .value.request.url, role: .value.request.credential_set.role, status: (if .value.errors | length > 0 then "error" else "ok" end)}]}'

Добавление jq команда суммирует вывод. В следующем примере злоумышленник успешно получил доступ к DELETE конечная точка на шаге 3.

{
	"test_verdict": "warning",
	"steps": [
		{
			"step": 1,
			"method": "POST",
			"url": "https://api.example.com/v1/orders",
			"role": "owner",
			"status": "ok"
		},
		{
			"step": 2,
			"method": "GET",
			"url": "https://api.example.com/v1/orders",
			"role": "attacker",
			"status": "ok"
		},
		{
			"step": 3,
			"method": "DELETE",
			"url": "https://api.example.com/v1/orders/bdc64e8a-deec-4374-92c0-4fe91d1650bb",
			"role": "attacker",
			"status": "error"
		}
	]
}

Пример шаблона опроса

Обычная практика: опрашивать статус сканирования до его завершения, а затем получать отчёт.

Пример

while true; do
  STATUS=$(curl --silent \
    "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
    --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq -r '.result.status // empty')

  echo "Scan status: ${STATUS:-unknown}"

  case "$STATUS" in
    completed) echo "Scan finished. Fetching report..."; break ;;
    failed)    echo "Scan failed." >&2; exit 1 ;;
    *)         sleep 10 ;;
  esac
done

curl --silent \
"https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}/report" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq .

Ограничения

Если во время открытой бета-версии у вас большие спецификации OpenAPI, их может быть полезно оптимизировать для сканера.

Модель ИИ, которая используется для построения плана сканирования вашего API, имеет ограничение контекста в 128k токенов. Это соответствует размеру файла на диске примерно от 40 до 60kB. Если ваша схема превышает этот размер, может потребоваться разделить её на несколько меньших файлов.

Аналогично, более полные результаты сканирования можно получить, создав отдельные файлы OpenAPI для каждого смыслового сценария использования. Например, если ваше приложение поддерживает изменение аккаунта, публикацию в социальных сетях и добавление в избранное, разделение спецификации на несколько файлов по этим сценариям может показать более широкое покрытие тестами в ходе бета-тестирования.

Доступность

Сканер уязвимостей пока доступен только клиентам API Shield с планом Enterprise. В будущем Cloudflare добавит новые типы сканирования и расширит доступность сканера.

Справочник

Расположение учетных данных

При создании учетных данных location поле определяет, куда сканер добавляет учетные данные при выполнении запросов.

Расположение	`location_name`	Пример сценария использования
заголовок	Название HTTP-заголовка	`Authorization` заголовок с `Bearer` токен.
cookie	Имя cookie	`session_id` cookie с токеном сессии.

Набор учётных данных может включать несколько элементов. Например, API, для которого требуется как Bearer токен в Authorization заголовок и CSRF токен в X-CSRF-Token заголовок будет иметь два отдельных учётных данных, настроенных в своём наборе.