Merge pull request #2212 from aziontech/EDU-6664-waf-exceptions-api-endpoints

docs(waf): add API documentation for WAF Exceptions and update termin…

Author: egermano

src/content/docs/en/pages/main-menu/reference/secure/edge-firewall/web-application-firewall/custom-allowed-rule.mdx

@@ -1,16 +1,20 @@
 ---
-title: WAF Custom Allowed Rules
+title: WAF Exceptions
 description: >-
-  Optimize the security of your application with Custom Allowed Rules for
-  WAF.
-meta_tags: 'waf, security, edge computing'
+  Optimize the security of your application with Exceptions for
+  WAF. Create, manage, and automate exception rules via API or Console.
+meta_tags: 'waf, security, edge computing, exceptions, api'
 namespace: >-
   documentation_products_edge_firewall_web_application_firewall_custom_allowed_rules
 permalink: >-
   /documentation/products/secure/firewall/web-application-firewall/custom-allowed-rules/
 ---
 
-**Web Application Firewall (WAF) Custom Allowed Rules** are configurations that explicitly allow certain request patterns to bypass blocking, overriding the standard WAF security rules that would otherwise identify these requests as potentially malicious. They operate at a high level, analyzing specific components of HTTP requests, such as parameters (ARGS), request body contents (BODY), or the URL path (URL). Each rule is defined with a unique identifier, a match string, and an application zone, ensuring that the security filter remains effective while minimizing blocks on requests containing characteristics considered necessary or legitimate by the user, thus reducing false positives.
+**Web Application Firewall (WAF) Exceptions** are configurations that explicitly allow certain request patterns to bypass blocking, overriding the standard WAF security rules that would otherwise identify these requests as potentially malicious. They operate at a high level, analyzing specific components of HTTP requests, such as parameters (ARGS), request body contents (BODY), or the URL path (URL). Each exception is defined with a unique identifier, a match string, and an application zone, ensuring that the security filter remains effective while minimizing blocks on requests containing characteristics considered necessary or legitimate by the user, thus reducing false positives.
+
+:::note
+Exceptions were previously referred to as **Allowed Rules** in the Console interface. The API now uses the **Exceptions** terminology. Both terms refer to the same functionality.
+:::
 
 ## Prerequisites
 
@@ -162,6 +166,160 @@ See the list of all available internal rules below:
 | 1311    | Possible XSS attack: close square bracket `]` found in `Body`, `Path`, `Query String` or `Cookies`.                                        |
 | 1312    | Possible XSS attack: tilde character `~` found in `Body`, `Path`, `Query String`, or `Cookies`.                                            |
 | 1314    | Possible XSS attack: `` ` `` (*backtick*) found in `Body`, `Path`, `Query String`, or `Cookies`.                                    |
+
+---
+
+## Managing Exceptions via API
+
+You can manage WAF Exceptions programmatically using the Azion API. This enables you to automate the creation, update, and deletion of exceptions, integrate WAF calibration into CI/CD pipelines, and build custom tools for managing your security posture.
+
+### API endpoints
+
+The Exceptions API provides the following operations:
+
+| Operation | Endpoint | Description |
+|-----------|----------|-------------|
+| List | `GET /v4/edge_firewall/wafs/{waf_id}/exceptions` | List all exceptions for a WAF Rule Set |
+| Create | `POST /v4/edge_firewall/wafs/{waf_id}/exceptions` | Create a new exception |
+| Retrieve | `GET /v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id}` | Get details of a specific exception |
+| Update | `PUT /v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id}` | Update an existing exception |
+| Partial update | `PATCH /v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id}` | Update specific fields of an exception |
+| Delete | `DELETE /v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id}` | Delete an exception |
+
+For complete API specifications, refer to the [Azion API reference](https://api.azion.com/v4#/operations/list_waf_exceptions).
+
+### Listing exceptions
+
+To retrieve all exceptions configured for a WAF Rule Set:
+
+```bash
+curl --request GET \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]'
+```
+
+Response example:
+
+```json
+{
+  "count": 2,
+  "results": [
+    {
+      "id": 1234,
+      "rule_id": 1000,
+      "reason": "Allow legitimate API traffic",
+      "match_zone": "query_string",
+      "match_pattern": "^[a-zA-Z0-9]+$",
+      "path": "/api/v1/data",
+      "active": true
+    },
+    {
+      "id": 5678,
+      "rule_id": 1302,
+      "reason": "Allow HTML in specific endpoint",
+      "match_zone": "body",
+      "match_pattern": "<script>",
+      "path": "/api/v1/render",
+      "active": true
+    }
+  ]
+}
+```
+
+### Creating an exception
+
+To create a new exception for a WAF Rule Set:
+
+```bash
+curl --request POST \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "rule_id": 1000,
+    "reason": "Allow legitimate API traffic with SQL-like patterns",
+    "match_zone": "query_string",
+    "match_pattern": "^[a-zA-Z0-9\\s]+$",
+    "path": "/api/v1/search",
+    "active": true
+  }'
+```
+
+### Retrieving a specific exception
+
+To get details of a specific exception:
+
+```bash
+curl --request GET \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id} \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]'
+```
+
+### Updating an exception
+
+To update all fields of an existing exception:
+
+```bash
+curl --request PUT \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id} \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "rule_id": 1000,
+    "reason": "Updated reason for the exception",
+    "match_zone": "query_string",
+    "match_pattern": "^[a-zA-Z0-9\\s\\-]+$",
+    "path": "/api/v1/search",
+    "active": true
+  }'
+```
+
+### Partially updating an exception
+
+To update specific fields without modifying the entire exception:
+
+```bash
+curl --request PATCH \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id} \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "active": false,
+    "reason": "Temporarily disabled for investigation"
+  }'
+```
+
+### Deleting an exception
+
+To delete an exception:
+
+```bash
+curl --request DELETE \
+  --url https://api.azion.com/v4/edge_firewall/wafs/{waf_id}/exceptions/{exception_id} \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token [TOKEN VALUE]'
+```
+
+### Exception object fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Unique identifier of the exception (read-only) |
+| `rule_id` | integer | The WAF internal rule ID to create an exception for. See the [WAF internal rules table](#waf-internal-rules) for available IDs |
+| `reason` | string | A description explaining why this exception was created |
+| `match_zone` | string | The part of the request to match against. See [Match Zone options](/en/documentation/products/secure/firewall/web-application-firewall/#match-zone-dropdown-options) |
+| `match_pattern` | string | The pattern to match in the specified zone |
+| `path` | string | The URL path where the exception applies |
+| `active` | boolean | Whether the exception is active (`true`) or inactive (`false`) |
+
+:::tip
+Use the API to automate WAF calibration workflows. For example, you can create a script that analyzes WAF Tuning data and automatically creates exceptions for verified false positives, or integrate exception management into your CI/CD pipeline to deploy security configurations alongside your application.
+:::
 | 1400    | Possible trick to evade protection: UTF7/8 encoding `&#` found in `Body`, `Path`, `Query String` or `Cookies`.                             |
 | 1401    | Possible trick to evade protection: M$ encoding `%U` found in `Body`, `Path`, `Query String` or `Cookies`.                                 |
 | 1500    | Possible File Upload attempt: `asp/php` or `.ph`, `.asp`, `.ht` found in filename in a multipart POST containing a file.                   |

src/content/docs/en/pages/main-menu/reference/secure/edge-firewall/web-application-firewall/web-application-firewall.mdx

@@ -118,7 +118,11 @@ By clicking the **Apply filter** button, a list of **Possible Attacks** will be
 
 ## Allowed Rules
 
-This tab allows you to create, edit, and delete *Allowed Rules*.
+This tab allows you to create, edit, and delete *Allowed Rules* (also referred to as **Exceptions** in the API).
+
+:::note
+**Exceptions** is the terminology used in the Azion API. In the Console interface, you'll see **Allowed Rules**. Both terms refer to the same functionality.
+:::
 
 The Allowed Rules are composed of the fields:
 
@@ -162,6 +166,17 @@ Options starting with **Specific** require you to provide a value in the **Name*
 The `Last Editor` and `Last Modified` fields are only available through the [API](https://api.azion.com).
 :::
 
+### Managing Exceptions via API
+
+You can manage Allowed Rules (Exceptions) programmatically using the Azion API. This enables you to:
+
+- Automate exception creation based on WAF Tuning analysis
+- Integrate WAF calibration into CI/CD pipelines
+- Build custom tools for managing security configurations
+- Bulk update or deactivate exceptions across multiple WAF Rule Sets
+
+For complete API specifications and examples, see the [WAF Exceptions documentation](/en/documentation/products/secure/firewall/web-application-firewall/custom-allowed-rules/#managing-exceptions-via-api) and the [Azion API reference](https://api.azion.com/v4#/operations/list_waf_exceptions).
+
 ---
 
 ## Limits