[Page Shield] Add new ML scores (#17204)

Author: pedrosousa

src/content/changelogs/page-shield.yaml

@@ -5,6 +5,11 @@ productLink: "/page-shield/"
 productArea: Application security
 productAreaLink: /fundamentals/reference/changelog/security/
 entries:
+  - publish_date: "2024-09-30"
+    title: New machine learning (ML) scores for detected scripts
+    description: |-
+      In addition to the global integrity score, Page Shield now provides individual script scores (from 1 to 99) for the following malicious code detections: Magecart, Crypto mining, and Malware.
+
   - publish_date: "2024-09-18"
     title: Page Shield's script monitor now available in Free plan
     description: |-

src/content/docs/page-shield/how-it-works/malicious-script-detection.mdx

@@ -6,25 +6,39 @@ sidebar:
 head: []
 description: Page Shield implements different mechanisms to determine if a
   script or a connection is malicious.
-
 ---
 
 :::note
-
-This feature is available as a paid add-on for customers on an Enterprise plan. 
+This feature is available as a paid add-on for customers on an Enterprise plan.
 :::
 
 Page Shield implements different mechanisms to determine if a script, or a connection made by a script, is malicious. These mechanisms are:
 
-* Malicious URL checks
-* Malicious domain checks
-* Malicious script detection
+- Malicious script detection
+- Malicious URL checks
+- Malicious domain checks
 
 Any updates to the threat feeds will trigger new checks for previously detected scripts or connections so that the Page Shield dashboards always reflect the latest categorization.
 
+## Malicious script detection
+
+In this type of detection, Page Shield will download the script file and run it through a classifier. The classifier is a machine learning (ML) model that has learned to detect patterns of malicious operations such as [Magecart-type attacks](https://sansec.io/what-is-magecart).
+
+The script classifier will output a probability score for the script (also called the JS integrity score) between 1 and 99, where 1 means definitely malicious and 99 means definitely not malicious. This score, together with a threshold value, will determine if the malicious script detection system will classify the script as malicious or not.
+
+The score threshold for considering a script as malicious is currently set to 10. If the script classification score is below this value, the Page Shield dashboards will display the script as being malicious.
+
+In addition to the integrity score, Page Shield will also provide individual scores for different malicious code detections (scores from 1 to 99):
+
+- **Magecart**
+- **Crypto mining**
+- **Malware**
+
+You can configure [Malicious Script Alerts](/page-shield/reference/alerts/). You will receive an alert notification as soon as Cloudflare detects JavaScript code classified as malicious in your domain.
+
 ## Malicious URL checks
 
-Page Shield will search for the URLs of your JavaScript dependencies in threat feeds to determine if any of those scripts should be categorized as malicious.
+Page Shield will search for the URLs of your JavaScript dependencies in threat intelligence feeds to determine if any of those scripts should be categorized as malicious.
 
 The Page Shield dashboards display the scripts that were considered malicious at the top of the scripts list.
 
@@ -52,19 +66,19 @@ The score threshold for considering a script as malicious is currently set to 50
 
 You can configure [Malicious Script Alerts](/page-shield/reference/alerts/). You will receive an alert notification as soon as Cloudflare detects JavaScript code classified as malicious in your domain.
 
-***
+---
 
 ## Malicious script and connection categories
 
 Scripts and connections considered malicious are categorized based on data from threat intelligence feeds. The current categories are the following:
 
-* Security threats
-* Command-and-Control (C2) & Botnet
-* Cryptomining
-* Spyware
-* Phishing
-* Malware
-* Domain Generation Algorithm (DGA) domain
-* Typosquatting & Impersonation
+- Security threats
+- Command-and-Control (C2) & Botnet
+- Crypto mining
+- Spyware
+- Phishing
+- Malware
+- Domain Generation Algorithm (DGA) domain
+- Typosquatting & Impersonation
 
 Each script or connection considered malicious can belong to several categories.

src/content/docs/page-shield/reference/page-shield-api.mdx

@@ -12,7 +12,6 @@ You can enable and disable Page Shield, configure its settings, and fetch inform
 To authenticate API requests you need an [API token](/fundamentals/api/get-started/create-token/). For more information on the required API token permissions, refer to [Roles and permissions](/page-shield/reference/roles-and-permissions/).
 
 :::note
-
 Refer to [API deprecations](/fundamentals/api/reference/deprecations/) for details on Page Shield API changes.
 :::
 
@@ -64,9 +63,7 @@ The following table summarizes the available operations:
 
 ## API notes
 
-- The malicious script classification (`Malicious` or `Not malicious`) is not directly available in the API. To determine this classification, compare the script's `js_integrity_score` value with the classification threshold, which is currently set to 50. Scripts with a score value lower than the threshold are considered malicious.
-
-- The API provides two separate properties for malicious script/connection categories: `malicious_domain_categories` and `malicious_url_categories`, related to the `domain_reported_malicious` and `url_reported_malicious` properties, respectively. The Cloudflare dashboard displays all the categories in a single **Malicious category** field. For more information, refer to [Malicious script and connection categories](/page-shield/how-it-works/malicious-script-detection/#malicious-script-and-connection-categories).
+The malicious script classification (`Malicious` or `Not malicious`) is not directly available in the API. To determine this classification, compare the script's `js_integrity_score` value with the classification threshold, which is currently set to 10. Scripts with a score value lower than the threshold are considered malicious.
 
 ## Common API calls
 
@@ -148,6 +145,9 @@ curl "https://api.cloudflare.com/api/v4/zones/{zone_id}/page_shield/scripts?host
 			"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"
 		}
 		// (...)
@@ -197,6 +197,9 @@ curl "https://api.cloudflare.com/api/v4/zones/{zone_id}/page_shield/scripts?stat
 			"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"
 		}
 		// (...)
@@ -246,6 +249,9 @@ curl "https://api.cloudflare.com/api/v4/zones/{zone_id}/page_shield/scripts/8337
 		"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",
@@ -255,7 +261,12 @@ curl "https://api.cloudflare.com/api/v4/zones/{zone_id}/page_shield/scripts/8337
 		"versions": [
 			{
 				"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
-				"js_integrity_score": 50,
+				"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"
 			}
 		]