bola attack detection

Author: patriciasantaana

src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx

@@ -69,6 +69,10 @@ Cloudflare automatically runs risk scans every 24 hours on your saved endpoints.
 
 `cf-risk-size-anomaly`: Automatically added when an endpoint experiences a spike in response body size over the last 24 hours.
 
+`cf-risk-bola-enumeration`: Automatically added when an endpoint experiences successful responses with drastic differences in the number of unique elements requested by different user sessions.
+
+`cf-risk-bola-pollution`: Automatically added when an endpoint experiences successful responses where parameters are found in multiple places in the request.
+
 :::note
 Cloudflare will only add authentication labels to endpoints with successful response codes. Refer to the below table for more details.
 :::

src/content/docs/api-shield/security/bola-attack-detection.mdx

@@ -0,0 +1,62 @@
+---
+pcx_content_type: concept
+type: overview
+title: Broken Object Level Authorization attack detection
+sidebar:
+  badge:
+    text: Beta
+  order: 10
+  label: BOLA attack detection
+---
+
+import { Badge } from "~/components";
+
+A Broken Object Level Authorization (BOLA) attack is where an application or API fails to properly verify if a user has permission to access specific private data.
+
+Bugs in the application or API allow attackers to bypass authorization checks and access sensitive information by manipulating and iterating through object identifiers
+
+Vulnerabilities can occur at any time, including in the original application's deployment. However, changes or upgrades to authentication and authorization policies can also introduce these bugs.
+
+BOLA attacks are as dangerous as account takeover. A successful BOLA attack allows the attacker to access or change data that they should not have ownership over.
+
+Cloudflare labels endpoints with BOLA risk when we detect two distinct signals common with BOLA attacks: **Parameter pollution** and **Enumeration**.
+
+- **Parameter pollution**: Cloudflare detects anomalies where one or more successful requests containing a value in an expected path, query string, header, or body parameter have that value duplicated in an unexpected, similar location. 
+
+    This behavior may be indicative of attackers trying to confuse the API’s authorization system and bypass security controls.
+
+- **Enumeration**: Cloudflare detects anomalies where one or more sessions makes successful requests to any one API endpoint changing variable values out of the norm, trying to get information from the API. 
+
+:::note
+Sessions that have more random behavior or repetition have a higher chance of triggering an alert. 
+:::
+
+## Examples
+
+### Parameter pollution attack
+
+**Endpoint**: `GET /api/v1/credit-cards/{cardId}`
+
+- **Normal behavior**: `cardId` is sent in a path variable.
+- **Attacker behavior**:`cardId` is also sent as a query parameter, which triggers old and undocumented code that looks for cards in the query parameter that lacks the authorization check: `GET /api/v1/credit-cards/{cardId}?cardId=12345`.
+
+### BOLA enumeration attack
+
+**Endpoint**: `GET /api/v1/credit-cards/{cardId}`
+
+- **Normal behavior**: Users request one to two credit cards per session.
+- **Attack behavior**: Attackers request hundreds of credit card values per session. 
+
+## Process
+
+For beta customers, API Shield searches for and highlights BOLA attacks on your APIs. Cloudflare learns visitor traffic patterns over time to know when API access to specific objects is likely a Broken Object Level Authorization enumeration attack. We inform you what API endpoints are being targeted by automatically labeling them using the following risk labels:
+
+`cf-risk-bola-enumeration`: Automatically added when an endpoint experiences successful responses with drastic differences in the number of unique elements requested by different user sessions.
+
+`cf-risk-bola-pollution`: Automatically added when an endpoint experiences successful responses where parameters are found in multiple places in the request.
+
+If you see one of these labels on your API endpoints, check its authorization policy with your developer team to find any authorization bugs. Additionally, you can reach out to Cloudflare for a customized report about the behavior, including attacker identifiers that you can use to confirm attack reach and impact.
+
+## Availability
+
+BOLA attack detection is available in a closed beta. Contact your account team if you are interested in BOLA attack detection for your API.