← Cloudflare API Shield / api-shield / security

Konfigurace Vulnerability Scanner přes API

Pomocí Cloudflare Vulnerability Scanner testujte své endpointy API na zranitelnosti, jako je Broken Object Level Authorization (BOLA). Tento návod vysvětluje, jak spustit svůj první sken zranitelností pomocí Cloudflare API.

Předpoklady

Musíte mít:

Alespoň jedna zóna v účtu.
Schéma OpenAPI popisující API, které chcete skenovat.
Přihlašovací údaje API pro váš cíl. Skener se potřebuje ověřit jako různí uživatelé, aby mohl testovat zranitelnosti BOLA.

Proces

Vytvořte token API

Všechny požadavky API používají základní adresu URL https://api.cloudflare.com/client/v4/ a ověřte se pomocí Bearer tokenu v Authorization hlavička.

Vytvořte token API v Cloudflare dashboardu s následujícím oprávnění omezené na cílový účet: Účet > API Gateway > Úprava

Uložte si svůj API token a Account Tag ze stránky vašeho účtu Přehled v Cloudflare dashboardu jako proměnné prostředí, které použijete v následujících příkazech.

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

Vytvoření cílového prostředí

Cílové prostředí určuje, co má skener skenovat. V současné době je jediným podporovaným typem cíle zóna.

Svůj Zone Tag najdete na stránce zóny Přehled v Cloudflare dashboardu a exportujte ji.

export ZONE_TAG="<YOUR_ZONE_TAG>"

Použijte následující POST požadavek k vytvoření cílového prostředí.

příkaz 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}"'"
    }
  }'

Uložte si ID cílového prostředí z odpovědi do proměnné TARGET_ENV_ID.

(Volitelné) Cílové prostředí můžete ověřit vytvořením GET požadavek na následující URL.

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

Vytvořit sady přihlašovacích údajů

Skener v současnosti podporuje sken typu BOLA. Ten vyžaduje dvě sady přihlašovacích údajů:

Vlastník: legitimní uživatel, kterému patří testované zdroje.
Útočník: jiný legitimní uživatel, který by neměl mít přístup k prostředkům vlastníka.

Skener se přihlásí jako oba uživatelé a zkontroluje, zda útočník může přistupovat ke zdrojům vlastníka. Každý soubor přihlašovacích údajů je uspořádán do sady přihlašovacích údajů obsahující jeden nebo více přihlašovacích údajů.

Použijte následující POST požadavky pro vytvoření sady přihlašovacích údajů Owner a sady přihlašovacích údajů Attacker.

Sada přihlašovacích údajů vlastníka

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>"

Sada přihlašovacích údajů útočníka

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>"

Přidejte přihlašovací údaje do každé sady přihlašovacích údajů

Přihlašovací údaj popisuje jeden ověřovací token nebo hodnotu relace, kterou skener připojuje ke svým požadavkům.

Použijte následující POST požadavky pro přidání přihlašovacích údajů vlastníka a útočníka do jednotlivých sad.

Přihlašovací údaj vlastníka (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"
  }'

Přihlašovací údaj útočníka (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"
  }'

(Volitelné) Všechny přihlašovací údaje v sadě můžete vypsat pomocí GET požadavek na následující URL.

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

Spustit skenování

Jakmile máte připravené cílové prostředí a dvě sady přihlašovacích údajů, můžete spustit sken BOLA.

Ujistěte se, že je vaše schéma OpenAPI naformátováno jako řetězec, například pomocí jq.

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

Použijte následující POST požadavek pro zahájení skenování.

příkaz 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 }
    }')"

Uložte si ID skenování z odpovědi.

export SCAN_ID="<SCAN_ID>"

Stav skenu můžete zkontrolovat pomocí GET požadavek.

příkaz cURL

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

Načtení zprávy o skenování

Jakmile bude mít sken stav completed, je k dispozici report s podrobnými výsledky testovaných zranitelností.

příkaz cURL

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

Výsledky reportu se vám možná bude snazší shrnout pomocí 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)}]}'

Přidání jq příkaz shrne výstup. V následujícím příkladu útočník úspěšně získal přístup k DELETE endpoint v kroku 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"
		}
	]
}

Příklad vzoru pollingu

Běžným postupem je dotazovat se na stav skenování, dokud se nedokončí, a poté stáhnout zprávu.

Příklad

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 .

Omezení

Pokud máte během veřejné beta verze rozsáhlé specifikace OpenAPI, může být vhodné je pro skener optimalizovat.

Model AI, který se používá k sestavení plánu skenování vašeho API, má kontextový limit 128k tokenů. To odpovídá přibližně 40 až 60kB velikosti souboru na disku. Pokud je vaše schéma větší než tato velikost, možná budete muset schéma rozdělit do menších souborů.

Důkladnější výsledky skenování obdobně získáte, pokud vytvoříte samostatné soubory OpenAPI podle jednotlivých případů užití. Pokud například vaše aplikace podporuje úpravu účtu, sdílení na sociálních sítích a přidávání do oblíbených, rozdělení specifikace do více souborů podle těchto případů užití může v průběhu beta verze ukázat vyšší pokrytí testy.

Dostupnost

Skener zranitelností je momentálně k dispozici pouze pro zákazníky Enterprise API Shield. Cloudflare v budoucnu doplní další typy skenování a rozšíří tak dostupnost skeneru.

Referenční informace

Umístění přihlašovacích údajů

Při vytváření přihlašovacích údajů location pole určuje, kam skener připojí přihlašovací údaj během požadavků.

Umístění	`location_name`	Příklad použití
hlavička	Název hlavičky HTTP	`Authorization` hlavičku s `Bearer` token.
cookie	Název cookie	`session_id` cookie s tokenem relace.

Sada přihlašovacích údajů může obsahovat více přihlašovacích údajů. Například API, které vyžaduje jak Bearer tokenu v Authorization hlavička a CSRF tokenu v X-CSRF-Token hlavička by měla ve své sadě nastavena dvě samostatná pověření.