← Client-side security / client-side-security / reference

Client-side security API

Monitorování zdrojů v rámci zabezpečení na straně klienta můžete zapínat a vypínat, konfigurovat nastavení a získávat informace o zjištěných skriptech a připojeních pomocí API funkce client-side security (dříve známé jako Page Shield API).

Abyste mohli ověřovat požadavky API, potřebujete API token. Další informace o požadovaných oprávněních tokenu API najdete v Role a oprávnění.

Endpointy

Úplný koncový bod získáte připojením API funkce client-side security koncové body k základní adrese URL Cloudflare API:

https://api.cloudflare.com/client/v4

{zone_id} argument představuje ID zóny (hexadecimální řetězec). Tuto hodnotu najdete v Cloudflare dashboardu nebo pomocí rozhraní Cloudflare API /zones koncový bod.

{script_id} argument představuje ID skriptu (hexadecimální řetězec). Tato hodnota je součástí odpovědi Vypsání skriptů zabezpečení na straně klienta operaci pro každý zjištěný skript.

{connection_id} argument představuje ID připojení (hexadecimální řetězec). Tato hodnota je součástí odpovědi operace API List client-side security connections pro každé zjištěné připojení.

Následující tabulka shrnuje dostupné operace:

Operace	Metoda + část URL	Poznámky
Získání nastavení zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield`	Načte nastavení zabezpečení na straně klienta (včetně stavu).
Aktualizovat nastavení zabezpečení na straně klienta	`PUT zones/{zone_id}/page_shield`	Aktualizuje nastavení zabezpečení na straně klienta.
Vypsání skriptů zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/scripts`	Načte seznam zjištěných skriptů.
Získání skriptu zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/scripts/{script_id}`	Načte podrobnosti skriptu.
Vypsání připojení zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/connections`	Načte seznam zjištěných připojení.
Získání připojení zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/connections/{connection_id}`	Načte podrobnosti připojení.
Vypsání souborů cookie zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/cookies`	Načte seznam zjištěných souborů cookie.
Získání souboru cookie zabezpečení na straně klienta	`GET zones/{zone_id}/page_shield/cookies/{cookie_id}`	Načte podrobnosti souboru cookie.
Vypsání pravidel zabezpečení obsahu	`GET zones/{zone_id}/page_shield/policies`	Načte seznam všech nakonfigurovaných pravidel zabezpečení obsahu.
Získání pravidla zabezpečení obsahu	`GET zones/{zone_id}/page_shield/policies/{policy_id}`	Načte podrobnosti pravidla zabezpečení obsahu.
Vytvoření pravidla zabezpečení obsahu	`POST zones/{zone_id}/page_shield/policies`	Vytvoří pravidlo zabezpečení obsahu se zadanou konfigurací.
Aktualizovat pravidlo zabezpečení obsahu	`PUT zones/{zone_id}/page_shield/policies/{policy_id}`	Aktualizuje existující pravidlo zabezpečení obsahu.
Odstranění pravidla zabezpečení obsahu	`DELETE zones/{zone_id}/page_shield/policies/{policy_id}`	Odstraní existující pravidlo zabezpečení obsahu.

Poznámky k API

Klasifikace škodlivého skriptu (Malicious nebo Not malicious) není přímo dostupná v API. Chcete-li tuto klasifikaci určit, porovnejte js_integrity_score hodnotu s klasifikačním prahem, který je aktuálně nastaven na 10. Skripty s hodnotou skóre nižší než tento práh jsou považovány za škodlivé.

Běžná volání API

Získání nastavení zabezpečení na straně klienta

Tento příklad získá aktuální nastavení client-side security od Cloudflare, včetně stavu (povoleno/zakázáno).

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Získání nastavení zabezpečení na straně klienta

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"enabled": true,
		"updated_at": "2023-05-14T11:47:55.677555Z",
		"use_cloudflare_reporting_endpoint": true,
		"use_connection_url_path": false
	},
	"success": true,
	"errors": [],
	"messages": []
}

Povolení zabezpečení na straně klienta

Tento příklad povolí client-side security od Cloudflare v zadané zóně.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield
Zone Settings Write

Aktualizovat nastavení zabezpečení na straně klienta

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield" \
	--request PUT \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
	--json '{
		"enabled": true
	}'

{
	"result": {
		"enabled": true,
		"updated_at": "2023-05-14T11:50:41.756996Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Načtení seznamu zjištěných skriptů

Tento GET požadavek načte seznam skriptů zjištěných funkcí Client-Side Security od Cloudflare pro hostitele example.net, a vyžádá první stránku s 15 položkami na stránku. Řetězec dotazu URL obsahuje parametry pro filtrování a stránkování.

Ve výchozím nastavení bude odpověď obsahovat pouze skripty s active stav, pokud nezadáte status parametr filtru v řetězci dotazu URL.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Vypsání zjištěných skriptů

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts?hosts=example.net&page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "8337233faec2357ff84465a919534e4d",
			"url": "https://malicious.example.com/badscript.js",
			"added_at": "2023-05-18T10:51:10.09615Z",
			"first_seen_at": "2023-05-18T10:51:08Z",
			"last_seen_at": "2023-05-22T09:57:54Z",
			"host": "example.net",
			"domain_reported_malicious": false,
			"url_reported_malicious": true,
			"malicious_url_categories": ["Malware"],
			"first_page_url": "http://malicious.example.com/page_one.html",
			"status": "active",
			"url_contains_cdn_cgi_path": false,
			"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			"js_integrity_score": 10,
			"obfuscation_score": 10,
			"dataflow_score": 8,
			"malware_score": 8,
			"cryptomining_score": 9,
			"magecart_score": 8,
			"fetched_at": "2023-05-21T16:58:07Z"
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 24,
		"total_pages": 2
	}
}

Některá pole zobrazená v ukázkové odpovědi nemusí být dostupná v závislosti na vašem plánu Cloudflare.

Podrobnosti o dostupných parametrech filtrování, stránkování a řazení najdete v Referenční dokumentace API.

Načtení seznamu zřídka hlášených skriptů

Tento GET požadavek načte seznam zřídka hlášených skriptů pro hostitele example.net, a vyžádá první stránku s 15 položkami na stránku. Řetězec dotazu URL obsahuje parametry pro filtrování a stránkování.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Vypsání zjištěných skriptů

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts?hosts=example.net&page=1&per_page=15&status=infrequent" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "83c8da2267394ce8465b74c299658fea",
			"url": "https://scripts.example.com/anotherbadscript.js",
			"added_at": "2023-05-17T13:16:03.419619Z",
			"first_seen_at": "2023-05-17T13:15:23Z",
			"last_seen_at": "2023-05-18T09:05:20Z",
			"host": "example.net",
			"domain_reported_malicious": false,
			"url_reported_malicious": false,
			"first_page_url": "http://malicious.example.com/page_one.html",
			"status": "infrequent",
			"url_contains_cdn_cgi_path": false,
			"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
			"js_integrity_score": 48,
			"obfuscation_score": 49,
			"dataflow_score": 45,
			"malware_score": 45,
			"cryptomining_score": 37,
			"magecart_score": 49,
			"fetched_at": "2023-05-18T03:58:07Z"
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 17,
		"total_pages": 2
	}
}

Některá pole zobrazená v ukázkové odpovědi nemusí být dostupná v závislosti na vašem plánu Cloudflare.

Podrobnosti o dostupných parametrech filtrování, stránkování a řazení najdete v Referenční dokumentace API.

Získání podrobností zjištěného skriptu

Tento GET požadavek získá podrobnosti o skriptu zjištěném funkcí Client-Side Security od Cloudflare s ID skriptu 8337233faec2357ff84465a919534e4d.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Získání zjištěného skriptu

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts/8337233faec2357ff84465a919534e4d" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "8337233faec2357ff84465a919534e4d",
		"url": "https://malicious.example.com/badscript.js",
		"added_at": "2023-05-18T10:51:10.09615Z",
		"first_seen_at": "2023-05-18T10:51:08Z",
		"last_seen_at": "2023-05-22T09:57:54Z",
		"host": "example.net",
		"domain_reported_malicious": false,
		"url_reported_malicious": true,
		"malicious_url_categories": ["Malware"],
		"first_page_url": "http://malicious.example.com/page_one.html",
		"status": "active",
		"url_contains_cdn_cgi_path": false,
		"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
		"js_integrity_score": 48,
		"obfuscation_score": 49,
		"dataflow_score": 45,
		"malware_score": 42,
		"cryptomining_score": 32,
		"magecart_score": 44,
		"fetched_at": "2023-05-21T16:58:07Z",
		"page_urls": [
			"http://malicious.example.com/page_two.html",
			"http://malicious.example.com/page_three.html",
			"http://malicious.example.com/page_four.html"
		],
		"versions": [
			{
				"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
				"js_integrity_score": 48,
				"obfuscation_score": 49,
				"dataflow_score": 45,
				"malware_score": 42,
				"cryptomining_score": 32,
				"magecart_score": 44,
				"fetched_at": "2023-05-21T16:58:07Z"
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}

Některá pole zobrazená v ukázkové odpovědi nemusí být dostupná v závislosti na vašem plánu Cloudflare.

Načtení seznamu zjištěných připojení

Tento GET požadavek načte seznam připojení zjištěných funkcí Client-Side Security od Cloudflare a vyžádá první stránku s 15 položkami na stránku.

Ve výchozím nastavení bude odpověď obsahovat pouze spojení s active stav, pokud nezadáte status parametr filtru v řetězci dotazu URL.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Vypsání zjištěných připojení

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/connections?page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "0a7bb628776f4e50a50d8594c4a01740",
			"url": "https://malicious.example.com",
			"added_at": "2022-09-18T10:51:10.09615Z",
			"first_seen_at": "2022-09-18T10:51:08Z",
			"last_seen_at": "2022-09-02T09:57:54Z",
			"host": "example.net",
			"domain_reported_malicious": true,
			"malicious_domain_categories": ["Malware", "Spyware"],
			"url_reported_malicious": false,
			"malicious_url_categories": [],
			"first_page_url": "https://example.net/one.html",
			"status": "active",
			"url_contains_cdn_cgi_path": false
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 16,
		"total_pages": 2
	}
}

Podrobnosti o dostupných parametrech filtrování, stránkování a řazení najdete v Referenční dokumentace API.

Získání podrobností zjištěného připojení

Tento GET požadavek získá podrobnosti o připojení zjištěném funkcí Client-Side Security od Cloudflare s ID připojení 0a7bb628776f4e50a50d8594c4a01740.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Získání zjištěného připojení

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/connections/0a7bb628776f4e50a50d8594c4a01740" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "0a7bb628776f4e50a50d8594c4a01740",
		"url": "https://malicious.example.com",
		"added_at": "2022-09-18T10:51:10.09615Z",
		"first_seen_at": "2022-09-18T10:51:08Z",
		"last_seen_at": "2022-09-02T09:57:54Z",
		"host": "example.net",
		"domain_reported_malicious": true,
		"malicious_domain_categories": ["Malware", "Spyware"],
		"url_reported_malicious": false,
		"malicious_url_categories": [],
		"first_page_url": "https://example.net/one.html",
		"status": "active",
		"url_contains_cdn_cgi_path": false
	},
	"success": true,
	"errors": [],
	"messages": []
}

Načtení seznamu zjištěných souborů cookie

Tento GET požadavek načte seznam souborů cookie zjištěných funkcí Client-Side Security od Cloudflare a vyžádá první stránku s 15 položkami na stránku.

Ve výchozím nastavení bude odpověď obsahovat pouze soubory cookie s active stav, pokud nezadáte status parametr filtru v řetězci dotazu URL.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Vypsání zjištěných souborů cookie

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/cookies?page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "beee03ada7e047e79f076785d8cd8b8e",
			"type": "first_party",
			"name": "PHPSESSID",
			"host": "example.net",
			"domain_attribute": "example.net",
			"expires_attribute": "2024-10-21T12:28:20Z",
			"http_only_attribute": true,
			"max_age_attribute": null,
			"path_attribute": "/store",
			"same_site_attribute": "strict",
			"secure_attribute": true,
			"first_seen_at": "2024-05-06T10:51:08Z",
			"last_seen_at": "2024-05-07T11:56:01Z",
			"first_page_url": "example.net/store/products",
			"page_urls": ["example.net/store/products/1"]
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 16,
		"total_pages": 2
	}
}

Podrobnosti o dostupných parametrech filtrování, stránkování a řazení najdete v Volání API.

Tento GET požadavek získá podrobnosti o souboru cookie zjištěném funkcí Client-Side Security od Cloudflare s ID beee03ada7e047e79f076785d8cd8b8e.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Získání zjištěného souboru cookie

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/cookies/beee03ada7e047e79f076785d8cd8b8e" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "beee03ada7e047e79f076785d8cd8b8e",
		"type": "first_party",
		"name": "PHPSESSID",
		"host": "example.net",
		"domain_attribute": "example.net",
		"expires_attribute": "2024-10-21T12:28:20Z",
		"http_only_attribute": true,
		"max_age_attribute": null,
		"path_attribute": "/store",
		"same_site_attribute": "strict",
		"secure_attribute": true,
		"first_seen_at": "2024-05-06T10:51:08Z",
		"last_seen_at": "2024-05-07T11:56:01Z",
		"first_page_url": "example.net/store/products",
		"page_urls": ["example.net/store/products/1"]
	},
	"success": true,
	"errors": [],
	"messages": []
}

Vytvoření pravidla zabezpečení obsahu

Tento POST požadavek vytvoří pravidlo zabezpečení obsahu (dříve nazývané zásada) s Log akci, přičemž následující skripty definujete jako povolené podle toho, kde jsou hostované:

Skripty hostované na myapp.example.com (což nezahrnuje skripty v example.com).
Skripty hostované na cdnjs.cloudflare.com.
Skript Google Analytics identifikovaný pomocí své úplné URL adresy.
Všechny skripty se stejným origin (stejné schéma HTTP nebo HTTPS a hostname).

Všechny ostatní skripty by způsobily porušení pravidla, ale tyto skripty by nebyly blokovány.

Více informací o Content Security Policy (CSP) směrnicích a hodnotách najdete v Dokumentace MDN ↗.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Page Shield
Domain Page Shield
Zone Settings Write

Vytvoření pravidla zabezpečení obsahu

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/policies" \
	--request POST \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
	--json '{
		"description": "My first content security rule in log mode",
		"action": "log",
		"expression": "http.host eq \"myapp.example.com\"",
		"enabled": "true",
		"value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js '\''self'\''"
	}'

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"id": "<RULE_ID>",
		"description": "My first content security rule in log mode",
		"action": "log",
		"expression": "http.host eq \"myapp.example.com\"",
		"enabled": "true",
		"value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js 'self'"
	}
}

Chcete-li vytvořit pravidlo zabezpečení obsahu pomocí Allow akci místo Log, použijte "action": "allow" v těle požadavku. V případě takového pravidla by byly všechny skripty, které pravidlo nepovoluje, blokovány.

Client-side security API

Endpointy

Poznámky k API

Běžná volání API

Získání nastavení zabezpečení na straně klienta

Povolení zabezpečení na straně klienta

Načtení seznamu zjištěných skriptů

Načtení seznamu zřídka hlášených skriptů

Získání podrobností zjištěného skriptu

Načtení seznamu zjištěných připojení

Získání podrobností zjištěného připojení

Načtení seznamu zjištěných souborů cookie

Získání podrobností zjištěného souboru cookie

Vytvoření pravidla zabezpečení obsahu