INTEGRITY Dokumentace

← Cloudflare One / cloudflare-one / traffic-policies / http-policies

Zabezpečení registru balíčků

Gateway dokáže rozpoznat stahování softwarových balíčků napříč sedmi hlavními ekosystémy balíčků a poskytuje vám kontrolu nad provozem dodavatelského řetězce pomocí zásad. Když vývojář nebo pipeline CI/CD stáhne balíček přes Gateway, proxy identifikuje protokol registru z URL požadavku a extrahuje ekosystém balíčku, název, verzi a jmenný prostor. Poté můžete psát zásady HTTP pomocí pkg.* selektory a povolte nebo zablokujte stahování balíčků v libovolné granularitě, od blokování celého ekosystému až po omezení jediné verze balíčku.

Jak to funguje

Detekce balíčků funguje výhradně na základě struktury URL adresy HTTP požadavku. Gateway rozpoznává rozhraní API každého podporovaného registrového protokolu, nikoli název hostitele, který provoz obsluhuje. To znamená, že detekce funguje stejně bez ohledu na to, zda provoz směřuje na oficiální veřejný registr, samostatně hostované zrcadlo, firemní proxy registr, jako je Artifactory nebo Nexus, nebo na jiný kompatibilní endpoint. Pokud cesta URL odpovídá struktuře známého stahování z registru, Gateway ji klasifikuje.

Detekce funguje na principu fail open. Pokud nelze URL klasifikovat jako stažení balíčku, požadavek pokračuje jako běžný provoz mimo balíčky. Selhání klasifikace nikdy neblokuje ani nenaruší instalaci balíčku.

Podporované ekosystémy

Gateway detekuje stahování balíčků pro následující ekosystémy:

Ecosystem Příklad vzoru artefaktu Namespace
npm /{package}/-/{package}-{version}.tgz Rozsah (například @babel)
PyPI /packages/{hash}/{hash}/{hash}/{package}-{version}.whl ,
RubyGems /gems/{package}-{version}.gem ,
Cargo /crates/{package}/{package}-{version}.crate ,
Go /{module}/@v/{version}.zip Cesta modulu
Maven /maven2/{group}/{artifact}/{version}/{artifact}-{version}.jar ID skupiny
NuGet /{package}/{version}/{package}.{version}.nupkg ,

Detekovaná operace

První verze rozpoznává stáhnout operace. Download je jedinou operací, u které lze název balíčku, verzi a ekosystém odvodit z cesty URL napříč všemi podporovanými registry. Ostatní operace, jako resolve (vyhledávání metadat) a publish, používají jiné endpointy, hostitele nebo metody HTTP, které vyžadují další signál nad rámec cesty URL.

Selektory

Následující selektory jsou k dispozici pro Zásady HTTP s akcemi Allow a Block:

Selektor Název UI Příklad API Popis
pkg.ecosystem Package Ecosystem pkg.ecosystem == "npm" Ekosystém balíčku zjištěný z URL adresy požadavku.
pkg.name Package Name pkg.name == "lodash" Název balíčku extrahovaný z URL adresy stahování.
pkg.version Package Version pkg.version == "4.17.21" Verze balíčku extrahovaná z URL adresy stahování. Podporuje přesnou shodu i porovnávací operátory citlivé na daný ekosystém.
pkg.namespace Package Namespace pkg.namespace == "@babel" Obor názvů balíčku, pokud to daný ekosystém podporuje. U npm jde o scope, u Maven o group ID a u Go o cestu k modulu.
pkg.purl Package URL pkg.purl == "pkg:npm/[email protected]" Package URL (PURL) ↗ odvozené z detekovaných souřadnic. Dostupné pouze v API.

Sestavit výrazy v dashboardu

V dashboardu Package Ecosystem je hlavní selektor. Po jeho výběru se zobrazí vnořená pole pro zadání názvu balíčku, verze a namespace. Platí tato pravidla:

Při přímém použití API lze tyto selektory ve wirefilter výrazech kombinovat volně a bez těchto omezení.

Operátory pro porovnání verzí

pkg.version selektor kromě přesné shody řetězců podporuje i porovnávací operátory citlivé na ekosystém. Každý ekosystém používá vlastní nativní sémantiku verzování:

Ecosystem Standard verzování
npm SemVer
Cargo SemVer
PyPI PEP 440
RubyGems Gem::Version
Go Verze modulů Go
Maven Pořadí verzí Maven
NuGet Normalizace a řazení NuGet

Podporovány jsou následující porovnávací operátory:

Operátor Syntaxe API Popis
equals == Normalizovaná rovnost pomocí pravidel identity specifických pro daný ekosystém.
not equals != Negace normalizované rovnosti.
větší než > Verze je vyšší než zadaná hodnota podle nativního řazení.
větší nebo rovno >= Verze je vyšší nebo rovna zadané hodnotě.
menší než < Verze je nižší než zadaná hodnota.
menší nebo rovno <= Verze je nižší nebo rovna zadané hodnotě.

Když nelze řetězec verze rozebrat podle pravidel verzování daného ekosystému, nebo když zjištěný ekosystém neodpovídá kontextu porovnání, porovnání nevrátí žádnou shodu. Patří sem !=, což znamená, že verze, kterou nelze analyzovat, neodpovídá ničemu.

Příklady zásad

Blokovat všechna stahování z konkrétního ekosystému

Chcete-li zablokovat veškeré stahování balíčků PyPI napříč vaší organizací:

Selektor Operátor Hodnota Akce
Package Ecosystem je pypi Block

Výraz Wirefilter:

pkg.ecosystem == "pypi"

Blokovat konkrétní balíček

Chcete-li zablokovat známý škodlivý nebo nežádoucí balíček npm bez ohledu na verzi:

Selektor Operátor Hodnota Logika Akce
Package Ecosystem je npm And Block
Package Name je event-stream

Výraz Wirefilter:

pkg.ecosystem == "npm" and pkg.name == "event-stream"

Blokovat zranitelné verze balíčku

Chcete-li zablokovat všechny verze lodash níže 4.17.21, což je verze, ve které byla opravena chyba CVE-2021-23337:

Selektor Operátor Hodnota Logika Akce
Package Ecosystem je npm And Block
Package Name je lodash And
Package Version menší než 4.17.21

Výraz Wirefilter:

pkg.ecosystem == "npm" and pkg.name == "lodash" and pkg.version < "4.17.21"

Omezte balíčky na schválené zrcadlo registru

Chcete-li povolit stahování balíčků npm pouze prostřednictvím firemní instance Artifactory a zablokovat všechna ostatní stahování npm, vytvořte dvě zásady:

Zásada 1: Allow schváleného mirroru (vyšší priorita):

Selektor Operátor Hodnota Logika Akce
Package Ecosystem je npm And Allow
Host je npm.internal.example.com

Výraz Wirefilter:

pkg.ecosystem == "npm" and http.request.host == "npm.internal.example.com"

Zásada 2: Block všech ostatních stahování npm (nižší priorita):

Selektor Operátor Hodnota Akce
Package Ecosystem je npm Block

Výraz Wirefilter:

pkg.ecosystem == "npm"

Protože detekce vychází z registrového protokolu, a ne z hostname, platí to jak pro veřejné registry.npmjs.org a vaše interní zrcadlo na adrese npm.internal.example.com jsou detekovány jako provoz npm. Zásada 1 (s vyšší prioritou) povoluje schválené zrcadlo a zásada 2 blokuje vše ostatní.

Blokovat konkrétní balíček, pokud nepochází ze schváleného hostitele

Chcete-li povolit stahování citlivého interního balíčku pouze prostřednictvím firemního registru a zablokovat jej ze všech ostatních zdrojů:

Zásada 1: Allow ze schváleného hostitele (vyšší priorita):

Selektor Operátor Hodnota Logika Akce
Package Ecosystem je npm And Allow
Package Namespace je @acme And
Package Name je internal-sdk And
Host je npm.internal.example.com

Výraz Wirefilter:

pkg.ecosystem == "npm" and pkg.namespace == "@acme" and pkg.name == "internal-sdk" and http.request.host == "npm.internal.example.com"

Zásada 2: Block ze všech ostatních hostitelů (nižší priorita):

Selektor Operátor Hodnota Logika Akce
Package Ecosystem je npm And Block
Package Namespace je @acme And
Package Name je internal-sdk

Výraz Wirefilter:

pkg.ecosystem == "npm" and pkg.namespace == "@acme" and pkg.name == "internal-sdk"

Detekce a zrcadla

Detekce balíčků klasifikuje provoz na základě struktury cesty URL v rozhraní API pro stahování daného registru. Nespoléhá na porovnávání se seznamem známých názvů hostitelů registrů. Díky tomuto návrhu je každý server poskytující balíčky s kompatibilním rozvržením URL rozpoznán stejným způsobem, ať už se jedná o:

http.request.host selektor zůstává k dispozici pro zásady, které potřebují rozlišovat mezi konkrétními hostiteli registru. Kombinací pkg.* selektory s http.request.host, můžete napsat pravidla, která uplatňují různé akce podle toho, odkud se balíček stahuje.

Protokolování

Když Gateway zjistí stahování balíčku, jsou metadata balíčku zahrnuta v protokolu Gateway HTTP log. Tato data jsou k dispozici v Protokoly aktivity Gateway a prostřednictvím Logpush.

Pole protokolu aktivit

V protokolu aktivity Gateway jsou k dispozici následující pole balíčku:

Pole Popis
Package Ecosystem Zjištěný typ registru (například npm, pypi, cargo).
Package URL (PURL) Řetězec Package URL odvozený z detekovaných souřadnic (například pkg:npm/[email protected]).

Pole Logpush

Metadata balíčku jsou k dispozici v PackageInfo objekt v gateway_http Logpush dataset:

Pole Typ Popis
PackageInfo.Ecosystem string Zjištěný ekosystém balíčku.
PackageInfo.Namespace string Obor názvů balíčku, pokud existuje.
PackageInfo.Name string Název balíčku.
PackageInfo.Version string Řetězec verze balíčku.
PackageInfo.Purl string Řetězec Package URL.

Omezení