[Client-side security] ELI5 updates (#29649)

Author: pedrosousa

src/content/docs/client-side-security/alerts/index.mdx

@@ -20,9 +20,9 @@ New resource alerts require a Business plan or higher. Code change and malicious
 
 You can configure unscoped or scoped alerts:
 
-- **Unscoped alert**: An alert configured for all zones in your Cloudflare account. Unscoped alerts are triggered either daily, hourly, or immediately, depending on the [alert type](/client-side-security/alerts/alert-types/).
+- **Unscoped alert**: Covers all zones in your Cloudflare account. Unscoped alerts are triggered either daily, hourly, or immediately, depending on the [alert type](/client-side-security/alerts/alert-types/).
 
-- **Scoped alert**: An alert scoped to one or more zones. You must configure [content security rules](/client-side-security/rules/) for the zones you select to receive any notifications. Scoped alerts are triggered immediately. Rule violations will not trigger an alert. For more information, refer to [Scoped alerts](#scoped-alerts).
+- **Scoped alert**: Covers one or more specific zones. Requires [content security rules](/client-side-security/rules/) configured in those zones. Scoped alerts are triggered immediately and only notify you about resources that are covered by your rules. [Rule violations](/client-side-security/rules/violations/) do not trigger these alerts. For more information, refer to [Scoped alerts](#scoped-alerts).
 
 For alerts sent at regular intervals, you might experience a delay between adding a new script and receiving an alert.
 
@@ -45,7 +45,7 @@ For each scoped alert, Cloudflare does the following:
 3. If the resource is allowed by the rule, check if the new or modified resource should trigger the current alert.
 4. If the alert should trigger, send an alert notification to the configured destinations.
 
-When you create a scoped alert you will not receive notifications for resources that are not allowed by a policy (either [in allow or in log mode](/client-side-security/rules/#rule-actions)). These are [rule violations](/client-side-security/rules/violations/) that you can review in the dashboard, through GraphQL, or via Logpush.
+When you create a scoped alert you will not receive notifications for resources that are not allowed by a content security rule (either [in allow or in log mode](/client-side-security/rules/#rule-actions)). These are [rule violations](/client-side-security/rules/violations/) that you can review in the dashboard, through GraphQL, or via Logpush.
 
 :::note
 Scoped alerts only fire if the zone has at least one enabled content security rule.

src/content/docs/client-side-security/how-it-works/index.mdx

@@ -15,7 +15,7 @@ import { GlossaryTooltip } from "~/components";
 
 Cloudflare's client-side security helps manage <GlossaryTooltip term="client-side resource" prepend="A client-side resource is ">client-side resources</GlossaryTooltip> (which include scripts and their connections) loaded by your website visitors, and provides visibility on the [cookies](https://www.cloudflare.com/learning/privacy/what-are-cookies/) recently detected in HTTP traffic. Client-side security can trigger alert notifications when resources change or are considered malicious.
 
-Client-side security uses two types of <GlossaryTooltip term="content security policy (CSP)" link="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP">Content Security Policy (CSP)</GlossaryTooltip> HTTP headers for different purposes:
+Client-side security works by adding <GlossaryTooltip term="content security policy (CSP)" link="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP">Content Security Policy (CSP)</GlossaryTooltip> HTTP headers to your site's responses. CSP is a browser-native mechanism that controls which resources a page is allowed to load and where to send reports when a resource violates the policy. Cloudflare uses two types of CSP headers for different purposes:
 
 - For resource monitoring (scripts and connections)
 - To enforce content security rules or log violations of these rules
@@ -29,14 +29,14 @@ The following table compares the CSP HTTP headers used for monitoring resources
 | `content-security-policy-report-only`         | `content-security-policy-report-only` (log rules)<br/>`content-security-policy` (allow rules) |
 | Automatic — on when monitoring is enabled     | Manual — created via rules you define                                                         |
 | Added to a sample of HTML responses           | Added to 100% of matching responses (not sampled)                                             |
-| Reports everything by disallowing anything    | CSP directives come from your allowlist                                                       |
+| Reports all detected scripts and connections  | CSP directives come from your allowlist                                                       |
 | Browser sends violation reports to Cloudflare | Log rules report violations only<br/>Allow rules block disallowed resources                   |
 
 ## Header used for resource monitoring
 
-When you turn on resource monitoring, Cloudflare automatically adds a `content-security-policy-report-only` HTTP header to a sample of HTML responses. For details on the header format, refer to [CSP HTTP header format](/client-side-security/reference/csp-header/).
+When you turn on resource monitoring, Cloudflare automatically adds a `content-security-policy-report-only` HTTP header to a sample of HTML responses. This report-only header does not block anything. It uses CSP directives that cause browsers to generate violation reports for detected scripts and connections. For details on the header format, refer to [CSP HTTP header format](/client-side-security/reference/csp-header/).
 
-This header instructs the browser to report all loaded scripts and connections without blocking them. This allows Cloudflare to provide you with a list of all scripts running on your application and the connections they make to third-party endpoints. Cloudflare also monitors ingress and egress traffic for cookies, either set by origin servers or by the visitor's browser.
+Based on these reports, Cloudflare builds a list of all scripts running on your application and the connections they make to third-party endpoints. Cloudflare also monitors ingress and egress HTTP traffic for cookies, whether set by origin servers or by the visitor's browser.
 
 You cannot turn off the monitoring header while resource monitoring is enabled. Because the header is added to a sample of responses, there may be a [small delay](/client-side-security/troubleshooting/#cloudflare-does-not-show-any-client-side-resources-after-activation) between deploying a script or cookie and having its data displayed in the resource monitoring dashboards.
 

src/content/docs/client-side-security/how-it-works/malicious-script-detection.mdx

@@ -12,25 +12,25 @@ description: Cloudflare analyzes the JavaScript code of the scripts loaded by
 Domain-based threat intelligence is available to all customers. Malicious script detection and malicious URL checks require Client-Side Security Advanced.
 :::
 
-Cloudflare uses different mechanisms to determine if a script, or a connection made by a script, is malicious. These mechanisms are:
+Cloudflare uses three complementary mechanisms to determine if a script, or a connection made by a script, is malicious. Each mechanism checks at a different level — the script's code, the URL it is hosted at, or the domain it is served from:
 
-- Malicious script detection
-- Malicious URL checks
-- Malicious domain checks
+- **Malicious script detection** — Analyzes the actual JavaScript code for malicious behavior.
+- **Malicious URL checks** — Looks up script URLs against threat intelligence feeds.
+- **Malicious domain checks** — Looks up script domains against threat intelligence feeds.
 
 Any updates to the threat feeds will trigger new checks for previously detected scripts or connections so that the client-side resource monitoring dashboards always reflect the latest categorization.
 
 ## Malicious script detection
 
-Cloudflare analyzes the JavaScript code of the scripts loaded by your website visitors. This analysis uses machine learning, including an LLM powered by Workers AI, to reduce the false positive rate and focus on highlighting true positives such as [Magecart-type attacks](https://sansec.io/what-is-magecart).
+Cloudflare analyzes the JavaScript code of the scripts loaded by your website visitors. This analysis uses machine learning, including an LLM powered by Workers AI, to reduce the false positive rate and focus on highlighting true positives such as [Magecart-type attacks](https://sansec.io/what-is-magecart), where injected code skims payment card data from checkout forms.
 
 :::note
 Cloudflare uses open-source models for this analysis. Customer data is not used to train these models.
 :::
 
-The analysis assigns a score (also called JS integrity score) between 1 and 99 to each script version, classifying how malicious it is. A score of 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 analysis assigns a JS integrity score between 1 and 99 to each script version. Lower scores indicate higher risk: a score of 1 means definitely malicious, and 99 means definitely not malicious.
 
-The score threshold for considering a script as malicious is currently set to 10. If the script classification score is below this value, the monitoring dashboards will display the script as being malicious.
+Cloudflare classifies a script as malicious when its score falls below the threshold, which is currently set to 10. Scripts that score below this threshold appear as malicious in the monitoring dashboards.
 
 In addition to the integrity score, Cloudflare will also provide individual scores for different malicious code detections (scores from 1 to 99):
 

src/content/docs/client-side-security/index.mdx

@@ -21,7 +21,9 @@ Ensures the safety and privacy of your website visitors' browsing environment.
 
 <Plan type="all" />
 
-Client-side security (formerly Page Shield) helps manage resources loaded by your website visitors — including scripts, their connections, and cookies — and triggers alert notifications when resources change or are considered malicious.
+Websites load third-party scripts for analytics, ads, chat widgets, and payment forms. If an attacker compromises one of these scripts, they can steal visitor data directly from the browser, an attack known as a [client-side supply chain attack](https://www.cloudflare.com/learning/security/what-is-a-supply-chain-attack/). Client-side security (formerly Page Shield) gives you visibility into these resources and alerts you when something changes or looks malicious.
+
+Client-side security monitors scripts, connections, and cookies loaded by your website visitors. You can set up alert notifications and create content security rules to control which resources are allowed on your pages.
 
 Learn how to [get started](/client-side-security/get-started/).
 

src/content/docs/client-side-security/rules/index.mdx

@@ -16,9 +16,12 @@ import { GlossaryTooltip } from "~/components";
 Only available to customers with Client-Side Security Advanced.
 :::
 
-Content security rules (previously known as policies) define the resources allowed on your applications through <GlossaryTooltip term="content security policy (CSP)">Content Security Policy (CSP)</GlossaryTooltip> directives. These rules can log violations and also enforce an allowlist of resources, effectively blocking resources not included in the policies. These two types of content security rules are called log rules and allow rules, respectively.
+Content security rules (previously known as policies) define which resources your application is allowed to load. They work through <GlossaryTooltip term="content security policy (CSP)">Content Security Policy (CSP)</GlossaryTooltip> directives that Cloudflare adds to your HTTP responses. There are two types of content security rules:
 
-Create [allow rules](#rule-actions) to define a positive security model, also known as positive blocking. According to this model, you define what is allowed and reject everything else. Such an approach helps you reduce the attack surface for unwanted third-party scripts in your application.
+- **Log rules** report resources that fall outside your allowlist without blocking them.
+- **Allow rules** block any resource not explicitly listed.
+
+Create [allow rules](#rule-actions) to define an allowlist-based security model. You specify exactly which resources are permitted and everything else is rejected. This approach reduces the attack surface for unwanted third-party scripts in your application.
 
 A content security rule can control both client-side resources monitored by Cloudflare, such as scripts and their connections, and other types of resources. Refer to [Supported CSP directives](/client-side-security/rules/csp-directives/) for details.
 
@@ -30,8 +33,8 @@ Third-party service providers may require specific CSP directives. Refer to your
 
 A content security rule can perform one of the following actions:
 
-- **Log**: Cloudflare will log any resources not covered by the rule, without blocking any resources. Use this action to validate a new content security rule before deploying it. Resources not covered by the rule will be reported as [rule violations](/client-side-security/rules/violations/).
-- **Allow**: Cloudflare will block any resources not explicitly allowed by the content security rule. Switch to the _Allow_ action after validating a new rule with the _Log_ action, so that your content security rule does not block essential application resources, which would affect your application's end users. Rules with the _Allow_ action will log [rule violations](/client-side-security/rules/violations/) for any blocked resources.
+- **Log**: Cloudflare reports any resources not covered by the rule as [rule violations](/client-side-security/rules/violations/) without blocking them. Use this action to validate a new content security rule before deploying it.
+- **Allow**: Cloudflare blocks any resources not explicitly allowed by the rule and logs them as [rule violations](/client-side-security/rules/violations/). Switch to this action after validating a rule with the _Log_ action to avoid blocking essential application resources.
 
 For details on the CSP directives Cloudflare creates for each type of rule action, refer to [How client-side security works](/client-side-security/how-it-works/#headers-related-to-content-security-rules). For more information on the CSP directives supported by content security rules, refer to [Supported CSP directives](/client-side-security/rules/csp-directives/).
 

src/content/docs/client-side-security/rules/violations.mdx

@@ -13,7 +13,9 @@ import { Details, Render, GlossaryTooltip } from "~/components";
 Only available to customers with Client-Side Security Advanced.
 :::
 
-Shortly after you configure content security rules, the Cloudflare dashboard will start displaying any violations of those rules. This information will be available for rules with any [action](/client-side-security/rules/#rule-actions) (_Allow_ and _Log_).
+A rule violation occurs when a browser loads a resource that is not covered by one of your [content security rules](/client-side-security/rules/). For log rules, the resource loads normally but is reported. For allow rules, the browser blocks the resource.
+
+Shortly after you configure content security rules, the Cloudflare dashboard will start displaying any violations of those rules. This information is available for rules with any [action](/client-side-security/rules/#rule-actions) (_Allow_ and _Log_).
 
 Information about rule violations is also available via [GraphQL API](#get-rule-violations-via-graphql-api) and [Logpush](#get-rule-violations-via-logpush).
 
@@ -27,7 +29,7 @@ Use the [Cloudflare GraphQL API](/analytics/graphql-api/) to obtain rule violati
 
 - `pageShieldReportsAdaptiveGroups`
 
-You can query the dataset for rule violations occurred in the past 30 days.
+You can query the dataset for rule violations that occurred in the past 30 days.
 
 Use [introspection](/analytics/graphql-api/features/discovery/introspection/) to explore the available fields the GraphQL schema. For more information, refer to [Explore the GraphQL schema](/analytics/graphql-api/getting-started/explore-graphql-schema/).