← Cloudflare API Shield / api-shield / security

Ověřování schématu

API schéma definuje, které API požadavky jsou platné na základě několika vlastností požadavku, jako je cílový koncový bod, formát cesty nebo proměnné dotazu a HTTP metoda.

Schema Validation porovnává příchozí požadavky s nahraným schématem OpenAPI. Nahrané schéma určuje očekávanou strukturu požadavků pro Schema Profile.

Jakmile bude nahraný profil k dispozici, Cloudflare vygeneruje nepřetržitá detekce. Použijte cf.schema_validation.uploaded.violated , aby analyzoval a zmírnil porušení.

Detekce sama o sobě provoz nezmírňuje. Výsledky zkontrolujte v Analýza profilu před vynucení profilu pomocí Custom Rules.

Schema Validation 2.0 je aktuální verze. Referenční dokumentaci k předchozí verzi najdete v Konfigurace Classic Schema Validation.

Endpointy musí existovat jako operace v Webová aktiva > Operace. Nahrání přes dashboard automaticky přidá operace schématu.

Při použití API nebo Terraformu přidávejte operace schématu samostatně. Podrobnosti o automatizaci najdete v Konfigurace API nebo Terraform.

Uplatnění změn může trvat několik minut v závislosti na počtu operací.

Odstraněním nahraného schématu se zastaví vyhodnocování jeho profilu. Přiřazené operace zůstanou v inventáři Web Assets.

Pravidlo fallthrough odpovídá požadavkům, které neodpovídají žádné známé operaci. Toto vlastní pravidlo WAF použijte k ochraně proti neidentifikovaným koncovým bodům.

Pro vlastní logiku použijte cf.api_gateway.fallthrough_detected. Omezte platnost pravidla na název hostitele svého API nebo kořenovou cestu.

Cloudflare v současné době přijímá pouze Schémata OpenAPI v3 ↗. Přijímané formáty souborů jsou YAML (.yml nebo .yaml příponou souboru) a JSON (.json příponou souboru).

Schémata OpenAPI vygenerovaná různými nástroji nemusí být dostatečně přesná pro import do Schema validation. Použijte nástroj třetí strany, například Swagger Editor ↗ , abyste zajistili, že schémata vyhovují specifikaci OpenAPI.

Schema validation (import) v rámci Cloudflare API Shield a Učení schématu (export) závisí na OpenAPI Specification (OAS) v3.0 ↗.

Tato podpora zahrnuje všechny patch verze, například OAS v3.0.x. OAS v3.1 není podporováno a rozšíření podpory na OpenAPI 2.0 se neplánuje.

API Shield aktuálně nepodporuje některé funkce schémat API, mimo jiné: všechny odpovědi, externí odkazy, netriviální šablonování cest nebo unikátní položky.

Pro povolená schémata platí limit 10,000 celkových operací pro zákazníky s plánem Enterprise, kteří si předplatili API Shield. Chcete-li tento limit zvýšit, kontaktujte svůj account team.

Schema Validation kontroluje těla požadavků do maximální velikosti dané vaším plánem. Požadavky, které tento limit překročí, se proti nahranému schématu nevyhodnocují.

Výchozí limity velikosti těla jsou:

Pomocí protokolů požadavků porovnejte velikost těla požadavku s limitem vašeho plánu.

Limity pro zákazníky s plánem Free, Pro, Business nebo Enterprise, kteří nemají předplacený API Shield, najdete v Plány.

Přestože je specifikace OpenAPI striktně nevyžaduje, Schema validation tato pole vyžaduje bezpodmínečně.

• type ↗
  • U všech schémat je nutné nastavit typ. Pokud daný typ Schema validation nepodporuje, nastavte typ na string místo toho.

• schema ↗
  • Schema validation nepodporuje pole content v parametrech. Podrobnosti najdete v poznámky k ověřovaným a podporovaným polím níže. Místo toho je schéma u všech objektů parameters vyžadováno bezpodmínečně.

Podrobnosti o tom, které objekty a pole specifikace OpenAPI (OAS) Schema validation aktuálně podporuje, najdete v přehledu níže.

• url ↗
  • Schema validation nepodporuje relativní adresy URL.
• variables ↗
  • Proměnné serveru se neověřují.

• style ↗
  • Podporovány jsou pouze výchozí hodnoty: "simple" (parametry cesty nebo hlavičky) a "form" (parametry dotazu nebo cookie).
• explode ↗
  • Podporovány jsou pouze výchozí hodnoty: true (pro form) a false (pro simple).
• content ↗
  • Pole content není v parameters podporováno. Použijte místo něj pole schema.
• type ↗
  • Cloudflare v současné době neověřuje parametry typu objekt.

• $ref ↗
  • Externí ani relativní reference nejsou podporovány.

• content
  • Request Body Object ↗
  • Media Type Object ↗
    • Schema validation dokáže validovat application/json dokumenty. Pokud dané schéma povoluje jiné typy obsahu, Schema validation tyto požadavky přijme bez ověření.

• anyOf
  • Parameter Object ↗
  • Schema Object ↗
    • anyOf schémata nejsou v tuto chvíli v parametrických schématech podporována.

• format ↗
  • Ověřené formáty:
    • date-time
    • time
    • date
    • email
    • hostname
    • ipv4
    • ipv6
    • uri
    • uri-reference
    • iri
    • iri-reference
    • int32
    • int64
    • float
    • double
    • password
    • uuid
    • byte
    • uint64
• uniqueItems ↗
  • Toto pole v současnosti není ověřováno funkcí Schema validation.

API Shield dokáže rozpoznat specifikace těla požadavku obsažené v nahraných schématech a ověřit, že jim data příchozích požadavků API odpovídají.

Schema validation aktuálně podporuje validaci požadavků s content-type application/json.

Ve specifikaci OpenAPI jsou schémata těla požadavku přiřazena k rozsahům médií (media-ranges), například application/*, application/xml nebo application/json).

Když Cloudflare ověřuje příchozí požadavky, kontroluje u požadavku content-type odpovídá media-range zadanému v OpenAPI.

Když soubor OpenAPI například specifikuje application/* jako součást mapy obsahu těla požadavku, Cloudflare přijme požadavky s content-type application/xml a application/json. Nicméně pouze application/json těla budou ověřena podle dodaného schématu.

Cloudflare doporučuje udržovat media-ranges co nejužší tím, že je nastavíte na jednotlivý media-type. Pokud potřebujete na koncovém bodu API podporovat více content-types, můžete využít media-ranges se zástupnými znaky.

Opatrnosti je také třeba dbát, pokud je origin server nakonfigurován tak, aby prováděl MIME sniffing ↗. Pokud například požadavek s tělem JSON úmyslně obsahuje application/malicious content-type a Cloudflare byl nakonfigurován tak, aby povolil application/* media-ranges by se požadavek předal na origin bez ověření obsahu těla JSON. Origin, který ale hlavičku Content-Type ignoruje a tělo buď zkusmo deserializuje, nebo odhaduje typ MIME, může tělo JSON deserializovat s mylným předpokladem, že prošlo ověřením schématu těla.

Pokud proto potřebujete podporovat application/json a application/xml na stejném endpointu, můžete použít application/*. Cloudflare ověří zadané schéma pro těla požadavků, u kterých je content-type nastaven na application/json. Požadavky s content-type application/xml (a další odpovídající application/*) budou propuštěny. I tak důrazně doporučujeme na svém originu vypnout rozpoznávání typu obsahu (content-type sniffing).

Cloudflare umožňuje v mapě obsahu těla požadavku OpenAPI specifikovat následující media-ranges:

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

Rozsahy typů médií lze také nakonfigurovat tak, aby vynucovaly charset parametr. Cloudflare pro to akceptuje pouze charset parametr se statickou hodnotou utf-8 jako součást specifikace media-range, a je-li nakonfigurována, budeme obdobně vyžadovat, aby content-type požadavku nesl tuto znakovou sadu.

Tato část se věnuje běžným problémům, se kterými se můžete setkat při používání ověřování schémat.

A OneOf chyba omezení znamená, že požadavek porušil svůj nahraný profil. Jeho tělo neodpovídalo přesně jednomu oneOf ↗ možnost.

Požadavek byl neplatný z jednoho ze dvou důvodů:

• Neodpovídá žádnému: Datový obsah požadavku neodpovídal správně žádnému z dostupných podschémat. K tomu často dochází, když je nastaveno pole discriminator, ale datovému obsahu chybí další povinná pole pro daný typ.
• Odpovídá více: Datový obsah byl nejednoznačný a odpovídal více než jednomu podschématu. K tomu dochází u obecných schémat, například pokud datový obsah obsahuje jak email a phone pole, může odpovídat jak email a phone definice schématu, což porušuje pravidlo „přesně jeden“).

Chcete-li to opravit, porovnejte vzorkovaný požadavek s definicí jeho schématu. Požadavek může postrádat povinná pole nebo obsahovat neshodující se typy.

Zákazníci s API Security již mají přístup ke Schema Profiles prostřednictvím Schema Learning a Schema Validation. Cloudflare otevírá uzavřenou betu pro pozvané zákazníky s plánem Enterprise bez API Security. Zájemci mohou o zařazení požádat prostřednictvím svého account teamu. Přístup k uzavřené betě neznamená budoucí dostupnost v rámci plánu ani cenu.