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

Client-side security API

Вы можете включать и отключать мониторинг ресурсов client-side security, настраивать параметры и получать сведения об обнаруженных скриптах и подключениях с помощью client-side security API (ранее известный как Page Shield API).

Для аутентификации запросов API вам потребуется API-токен. Дополнительные сведения о необходимых разрешениях API-токена см. в Роли и разрешения.

Конечные точки

Вы можете получить полный адрес конечной точки, добавив client-side security API конечные точки к базовому URL-адресу API Cloudflare:

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

{zone_id} аргумент представляет собой ID зоны (шестнадцатеричную строку). Найти это значение можно в панели управления Cloudflare или с помощью /zones конечная точка.

{script_id} аргумент представляет собой ID скрипта (шестнадцатеричную строку). Это значение включается в ответ Список скриптов защиты на стороне клиента операция для каждого обнаруженного скрипта.

{connection_id} аргумент представляет собой ID соединения (шестнадцатеричную строку). Это значение включается в ответ операции API List client-side security connections для каждого обнаруженного соединения.

В следующей таблице приведены доступные операции:

Операция	Метод и URL-путь	Примечания
Получение настроек защиты на стороне клиента	`GET zones/{zone_id}/page_shield`	Получение настроек Client-Side Security (включая статус).
Обновление настроек client-side security	`PUT zones/{zone_id}/page_shield`	Обновляет настройки client-side security.
Список скриптов защиты на стороне клиента	`GET zones/{zone_id}/page_shield/scripts`	Получение списка обнаруженных скриптов.
Получение скрипта Client-Side Security	`GET zones/{zone_id}/page_shield/scripts/{script_id}`	Получение сведений о скрипте.
Список подключений защиты на стороне клиента	`GET zones/{zone_id}/page_shield/connections`	Получение списка обнаруженных соединений.
Получение соединения Client-Side Security	`GET zones/{zone_id}/page_shield/connections/{connection_id}`	Получение сведений о соединении.
Список файлов cookie защиты на стороне клиента	`GET zones/{zone_id}/page_shield/cookies`	Получение списка обнаруженных файлов cookie.
Получение файла cookie Client-Side Security	`GET zones/{zone_id}/page_shield/cookies/{cookie_id}`	Получение сведений о файле cookie.
Список правил безопасности контента	`GET zones/{zone_id}/page_shield/policies`	Получение списка всех настроенных правил безопасности контента.
Получение правила безопасности контента	`GET zones/{zone_id}/page_shield/policies/{policy_id}`	Получение сведений о правиле безопасности контента.
Создание правила безопасности контента	`POST zones/{zone_id}/page_shield/policies`	Создаёт правило безопасности контента с указанной конфигурацией.
Обновление правила безопасности контента	`PUT zones/{zone_id}/page_shield/policies/{policy_id}`	Обновляет существующее правило безопасности контента.
Удаление правила безопасности контента	`DELETE zones/{zone_id}/page_shield/policies/{policy_id}`	Удаляет существующее правило безопасности контента.

Примечания к API

Классификация вредоносного скрипта (Malicious или Not malicious) нельзя получить напрямую через API. Чтобы определить эту классификацию, сравните значение скрипта js_integrity_score значение с порогом классификации, который в настоящее время установлен на 10. Скрипты со значением оценки ниже этого порога считаются вредоносными.

Типичные вызовы API

Получение настроек защиты на стороне клиента

В этом примере запрашиваются текущие настройки Client-Side Security от Cloudflare, включая статус (enabled/disabled).

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Получение настроек защиты на стороне клиента

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": []
}

Включение Client-Side Security

В этом примере в указанной зоне включается Client-Side Security от Cloudflare.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Page Shield
Domain Page Shield
Zone Settings Write

Обновление настроек client-side security

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": []
}

Список обнаруженных скриптов

Это GET запрос получает список скриптов, обнаруженных Client-Side Security от Cloudflare для хоста example.net, запрашивая первую страницу с 15 элементами на странице. Строка запроса URL включает параметры фильтрации и постраничной навигации.

По умолчанию ответ будет включать только скрипты с active статус, если вы не указали status параметр фильтра в строке запроса URL.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Список обнаруженных скриптов

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

Некоторые поля из примера ответа могут быть недоступны в зависимости от вашего тарифного плана Cloudflare.

Сведения о доступных параметрах фильтрации, постраничного вывода и сортировки см. Справочник по API.

Список редко регистрируемых скриптов

Это GET запрос получает список редко регистрируемых скриптов для хоста example.net, запрашивая первую страницу с 15 элементами на странице. Строка запроса URL включает параметры фильтрации и постраничной навигации.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Список обнаруженных скриптов

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

Некоторые поля из примера ответа могут быть недоступны в зависимости от вашего тарифного плана Cloudflare.

Сведения о доступных параметрах фильтрации, постраничного вывода и сортировки см. Справочник по API.

Получение сведений об обнаруженном скрипте

Это GET запрос получает сведения о скрипте, обнаруженном Client-Side Security от Cloudflare, с ID скрипта 8337233faec2357ff84465a919534e4d.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Получение обнаруженного скрипта

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": []
}

Некоторые поля из примера ответа могут быть недоступны в зависимости от вашего тарифного плана Cloudflare.

Список обнаруженных соединений

Это GET запрос получает список подключений, обнаруженных Client-Side Security от Cloudflare, запрашивая первую страницу с 15 элементами на странице.

По умолчанию ответ будет включать только соединения с active статус, если вы не указали status параметр фильтра в строке запроса URL.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Список обнаруженных подключений

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

Сведения о доступных параметрах фильтрации, постраничного вывода и сортировки см. Справочник по API.

Получение сведений об обнаруженном подключении

Это GET запрос получает сведения о подключении, обнаруженном Client-Side Security от Cloudflare, с ID подключения 0a7bb628776f4e50a50d8594c4a01740.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Получение обнаруженного подключения

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": []
}

Список обнаруженных файлов cookie

Это GET запрос получает список cookie, обнаруженных Client-Side Security от Cloudflare, запрашивая первую страницу с 15 элементами на странице.

По умолчанию ответ будет включать только файлы cookie с active статус, если вы не указали status параметр фильтра в строке запроса URL.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Список обнаруженных файлов 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
	}
}

Сведения о доступных параметрах фильтрации, постраничного вывода и сортировки см. Выполняйте вызовы API.

Это GET запрос получает сведения о cookie, обнаруженном Client-Side Security от Cloudflare, с ID beee03ada7e047e79f076785d8cd8b8e.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Получение обнаруженного файла 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": []
}

Создание правила безопасности контента

Это POST запрос создает правило безопасности контента (ранее называвшееся политикой) с Log действие, определяя следующие скрипты как разрешённые в зависимости от того, где они размещены:

Скрипты, размещённые в myapp.example.com (не включает скрипты в example.com).
Скрипты, размещённые в cdnjs.cloudflare.com.
Скрипт Google Analytics с использованием полного URL.
Все скрипты с одинаковым источником (одинаковые схема HTTP или HTTPS и хост).

Все остальные скрипты вызвали бы нарушение правила, но не были бы заблокированы.

Подробнее о Content Security Policy (CSP) директивах и значениях см. в документация MDN ↗.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Page Shield
Domain Page Shield
Zone Settings Write

Создание правила безопасности контента

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

Чтобы создать правило безопасности контента с Allow действие вместо Log, используйте "action": "allow" в теле запроса. В случае такого правила все скрипты, не разрешённые этим правилом, будут заблокированы.

Client-side security API

Конечные точки

Примечания к API

Типичные вызовы API

Получение настроек защиты на стороне клиента

Включение Client-Side Security

Список обнаруженных скриптов

Список редко регистрируемых скриптов

Получение сведений об обнаруженном скрипте

Список обнаруженных соединений

Получение сведений об обнаруженном подключении

Список обнаруженных файлов cookie

Получение сведений об обнаруженном файле cookie

Создание правила безопасности контента