[Bots] bot detection alerts (#21929)

* bot alerts

* Apply suggestions from code review

* tiny edits

* Apply suggestions from code review

Author: patriciasantaana

src/content/docs/bots/reference/alerts.mdx

@@ -0,0 +1,71 @@
+---
+pcx_content_type: reference
+title: Bot Detection Alerts
+sidebar:
+  order: 4
+
+---
+
+import { AvailableNotifications } from "~/components"
+
+Bot alerts inform you when Cloudflare detects spikes in your traffic with any of the following characteristics:
+
+- A global spike in traffic that have a bot score of less than 30.
+- An increase in traffic on available dimensions in [Custom Bot Detection Alerts](#custom-bot-detection-alerts).
+- Filters of your choosing in [Custom Bot Detection Alerts](#custom-bot-detection-alerts).
+
+--- 
+
+## Alert types
+
+<AvailableNotifications product="Bots" />
+
+### Set up a bot detection alert
+
+To receive Bot alerts, you must [configure a notification](/notifications/get-started/). Notifications help you stay up to date with your Cloudflare account through email, PagerDuty, or webhooks, depending on your Cloudflare plan.
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
+2. Go to **Notifications**.
+3. In **Notifications**, select **Add**.
+4. Select **Bot Management** from the Product list.
+5. Choose one of the available bot detection alerts (depending on whether you want to set up custom filters and/or grouping):
+    - Bot Detection Alert
+    - Custom Bot Detection Alert
+6. Enter a notification name and (optionally) a description.
+7. Select the domain(s) to monitor for this alert.
+8. Configure a delivery method for the notification. The available delivery methods depend on your Cloudflare plan. For more information, refer to [Cloudflare Notifications](/notifications/).
+9. If you are creating a notification for Custom Bot Detection Alert, define the parameters that will filter the notifications you will receive.
+10. Select **Save**.
+
+---
+
+## Alert logic
+
+The Bot Detection Alert notifies users when Cloudflare detects an abnormal spike to their zone where the Z-score > [3.5](https://blog.cloudflare.com/introducing-thresholds-in-security-event-alerting-a-z-score-love-story/) and bot requests > 200/5 minutes in bot traffic (bot score < 30).
+
+Z-score is calculated with a long window duration of six hours and short window duration of five minutes.
+
+Bot Detection Alerts are delivered with Cloudflare’s Notifications system via email, webhook, or Pager Duty.
+
+You will not receive duplicate alerts within the same one-hour time frame, except in rare cases where different alert values simultaneously trigger alerts.
+
+In addition to the information above, Custom Bot Detection Alerts allow you to include or exclude certain conditions:
+
+- User-agent
+- Hostname
+- URI Path
+- IP Source Address
+- AS Num
+- JA3 Fingerprint
+- JA4 Fingerprint
+- Bot Detection IDs
+
+You can also choose to group by the following dimensions so that they can be alerted of volumetric anomalies based on:
+
+- JA4 Fingerprint (removes the filter of bot score < 30)
+- AS Num
+- Bot Detection IDs
+
+:::note
+Bot Detection Alerts exclude [verified bots](/bots/concepts/bot/verified-bots/categories/). 
+:::

src/content/docs/bots/reference/sample-terms.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Sample terms
 sidebar:
-  order: 4
+  order: 5
 
 ---
 

src/content/notifications/index.yaml

@@ -19,6 +19,25 @@ entries:
       * Argo Smart Routing has **Notify when total bytes of traffic exceeds** as a threshold.
       * Load Balancing has **Notify when total number of DNS Queries exceeds** as a threshold.
 
+  - name: Bot Detection Alert
+    audience: Enterprise customers who want to be notified when Cloudflare detects a spike in bot traffic on their zones.
+    availability: Accounts with at least one Enterprise zone.
+    associatedProducts: Bots
+    nextSteps: Select the [Security Analytics](/waf/analytics/security-analytics/) link enclosed in the alert message. Contact support if additional advice is needed on how to investigate the attack further.
+    otherFilters: None.
+    additional_information: After an alert is created on the dashboard, it may take up to 30 minutes before sufficient data is available to begin detecting traffic anomalies. Verified bot traffic is excluded from bot alerts.
+
+  - name: Custom Bot Detection Alert
+    audience: Enterprise customers who want to be notified when Cloudflare detects a spike in bot traffic on their zones.
+    availability: Accounts with at least one Enterprise zone.
+    associatedProducts: Bots
+    nextSteps: Select the [Security Analytics](/waf/analytics/security-analytics/) link enclosed in the alert message. Contact support if additional advice is needed on how to investigate the attack further.
+    otherFilters: Refer to the [alert logic](/bots/reference/alerts/#alert-logic) for more information on additional filters or groupings.
+    additional_information: |-
+      After an alert is created on the dashboard, it may take up to 30 minutes before sufficient data is available to begin detecting traffic anomalies. Verified bot traffic is excluded from both basic and advanced bot alerts.
+
+      Alerts with grouping could cause potential noise if you set them up for a high-traffic zone. Grouping alerts function as if you set up separate policies with a filter for each value. Alerts may trigger multiple values in the same group as long as the traffic for each value reaches the threshold of 200. 
+
   - name: Brand Protection Alerts
     audience: Customers who want a summary of activity related to [Brand Protection](/security-center/brand-protection/).
     availability: Professional plans or higher.