[Page Shield] Customized alerts (#18500)

* Update alerts

* Update alerts that may become immediate

* Update alerts on policies (received feedback)

* Update heading

* Add changelog entry

* Add link

* Apply suggestions from code review

---------

Co-authored-by: Patricia Santa Ana <[email protected]>

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-12-02"
+    title: Alerts based on customer-defined policies
+    description: |-
+      You can now scope all of Page Shield's alert types to selected zones and their associated policies, alerting only on the resources that have been explicitly allowed.
+
   - publish_date: "2024-09-30"
     title: New machine learning (ML) scores for detected scripts
     description: |-

src/content/docs/page-shield/detection/configure-alerts.mdx

@@ -18,3 +18,32 @@ Only available to customers on a Business or Enterprise plan.
 <Render file="alerts-intro" />
 
 <Render file="alerts-configure" />
+
+## Alerts on policies
+
+:::note
+Applies to Enterprise customers with a paid add-on.
+:::
+
+If you have configured [allow policies](/page-shield/policies/#policy-actions) in a zone (policies which allow specific scripts and connections and block everything else), you can filter alert notifications according to those policies.
+
+When you set the **Policies of these zones** filter in a Page Shield alert, you will only receive the most relevant notifications based on the values of the allow policies you configured.
+
+For each alert configured with a filter, Page Shield will do the following:
+
+1. Check which allow policies in a zone are enabled.
+2. For every enabled policy, compare the URL of the new or changed resource against the allowed sources in the policy.
+3. If the resource is allowed by the policy, check if the new or modified resource should trigger the current Page Shield alert.
+4. If the alert should trigger, send an alert notification to the configured destinations.
+
+:::note
+When you set the **Policies of these zones** filter in an alert you will not receive notifications for resources blocked by an allow policy. These are [policy violations](/page-shield/policies/violations/) that you can review in the dashboard, through GraphQL, or via Logpush.
+:::
+
+You will not receive notifications for alerts configured with a **Policies of these zones** filter in the following cases:
+
+- No configured policies in the zone
+- Policy configured in log mode
+- Policy is not enabled
+
+For alerts without a **Policies of these zones** filter, you will receive alerts for resources detected in all your zones, and you may receive alerts about resources that are blocked by one of your configured allow policies.

src/content/docs/page-shield/get-started.mdx

@@ -32,7 +32,6 @@ Depending on your plan, you may be able to also review the connections made by s
 ## Configure alerts
 
 :::note
-
 Only available to customers on a Business or Enterprise plan.
 :::
 

src/content/docs/page-shield/reference/csp-header.mdx

@@ -14,7 +14,7 @@ The format of the <GlossaryTooltip term="content security policy (CSP)">Content
 content-security-policy-report-only: script-src 'none'; connect-src 'none'; report-uri https://csp-reporting.cloudflare.com/cdn-cgi/script_monitor/report?<QUERY_STRING>
 ```
 
-If you [configured the CSP reporting endpoint](/page-shield/reference/settings/#csp-reporting-endpoint) to use the same hostname, the HTTP header will have the following format:
+If you [configured the reporting endpoint](/page-shield/reference/settings/#reporting-endpoint) to use the same hostname, the HTTP header will have the following format:
 
 ```txt
 content-security-policy-report-only: script-src 'none'; connect-src 'none'; report-uri <YOUR_HOSTNAME>/cdn-cgi/script_monitor/report?<QUERY_STRING>

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

@@ -3,12 +3,11 @@ title: Configuration settings
 pcx_content_type: reference
 sidebar:
   order: 1
-
 ---
 
-import { GlossaryTooltip } from "~/components"
+import { GlossaryTooltip } from "~/components";
 
-## CSP reporting endpoint
+## Reporting endpoint
 
 When enabled, Page Shield uses a <GlossaryTooltip term="content security policy (CSP)">Content Security Policy (CSP)</GlossaryTooltip> [report-only HTTP header](/page-shield/reference/csp-header/) to gather information about all the scripts running on your application.
 
@@ -28,8 +27,8 @@ Enterprise customers with a paid add-on can change the reporting endpoint so tha
 
 Using the same hostname for CSP reporting may interfere with other Cloudflare products. Before selecting this option, ensure that your Cloudflare configuration complies with the following:
 
-* No rate limiting rules match the `cdn-cgi/*` URL path
-* No WAF custom rules match the `cdn-cgi/*` URL path
+- No rate limiting rules match the `cdn-cgi/*` URL path
+- No WAF custom rules match the `cdn-cgi/*` URL path
 
 ### Configure the reporting endpoint
 
@@ -64,6 +63,5 @@ To turn off Page Shield:
 3. In **Disable Page Shield**, select **Disable**.
 
 :::note
-
-Turning off Page Shield will not turn off [policies](/page-shield/policies/). To turn off policies, go to **Page Shield** > **Policies**. 
+Turning off Page Shield will not turn off [policies](/page-shield/policies/). To turn off policies, go to **Page Shield** > **Policies**.
 :::

src/content/notifications/index.yaml

@@ -243,15 +243,15 @@ entries:
     associatedProducts: Page Shield
     nextSteps: Investigate to confirm that it is an expected change.
     otherFilters: None.
-    additional_information: Triggered daily.
+    additional_information: Triggered daily. If configured with a zone filter, the alert is triggered immediately.
 
   - name: Page Shield New Domain Alert
     audience: "[Page Shield](/page-shield/) customers who want to receive a notification when resources from new host domains appear in their domain."
     availability: Business plans or higher.
     associatedProducts: Page Shield
     nextSteps: Investigate to confirm that it is an expected change.
     otherFilters: None.
-    additional_information: Triggered hourly.
+    additional_information: Triggered hourly. If configured with a zone filter, the alert is triggered immediately.
 
   - name: Page Shield New Malicious Domain Alert
     audience: "[Page Shield](/page-shield/) customers who want to receive a notification when resources from a known malicious domain appear in their domain. For more information, refer to [Malicious script and connection detection](/page-shield/how-it-works/malicious-script-detection/)."
@@ -289,7 +289,7 @@ entries:
     associatedProducts: Page Shield
     nextSteps: Investigate to confirm that it is an expected change.
     otherFilters: None.
-    additional_information: Triggered daily.
+    additional_information: Triggered daily. If configured with a zone filter, the alert is triggered immediately.
 
   - name: Page Shield New Resource Exceeds Max URL Length Alert
     audience: "[Page Shield](/page-shield/) customers who want to receive a notification when a resource's URL exceeds the maximum allowed length."

src/content/partials/page-shield/alerts-configure.mdx

@@ -1,13 +1,15 @@
 ---
 {}
-
 ---
 
 To set up alerts:
 
 1. Go to **Security** > **Page Shield**.
-2. In the **Settings** tab, select **Configure an alert**.
+2. In the **Settings** tab, select **Manage alerts**.
 3. Select an [alert type](/page-shield/reference/alerts/).
-4. Fill in the required information and select **Create**.
+4. Enter the notification name and description.
+5. (Optional) If you are an Enterprise customer with a paid add-on, you can [define the zones for which you want to filter alerts](/page-shield/detection/configure-alerts/#alerts-on-policies) based on the configured policies in **Policies of these zones**.
+6. Select one or more notification destinations (notification email, webhooks, and connected notification services).
+7. Select **Create**.
 
 To edit, delete, or disable an alert, go to your [account notifications](https://dash.cloudflare.com/?to=/:account/notifications).