Update configuration.md with bf section (#115)

ohad-perets · web-flow · commit f3ab3edfded1 · 2025-01-27T15:46:17.000Z
add brute force configuration
diff --git a/content/nap-waf/v5/configuration-guide/configuration.md b/content/nap-waf/v5/configuration-guide/configuration.md
@@ -37,6 +37,7 @@ For more information on the NGINX App Protect WAF security features, see [NGINX
 |[XFF headers & trust](#xff-headers-and-trust) | Disabled by default. User can enable it and optionally add a list of custom XFF headers. |
 |[gRPC Protection](#grpc-protection-for-unary-traffic) | gRPC content profile detects malformed content, parses well-formed content, and extracts the text fields for detecting attack signatures and disallowed meta-characters. In addition, it enforces size restrictions and prohibition of unknown fields. The Interface Definition Language (IDL) files for the gRPC API must be attached to the profile. gRPC protection can be on [unary](#grpc-protection-for-unary-traffic) or [bidirectional](#grpc-protection-for-bidirectional-streaming) traffic.|
 |[Secure Traffic Between NGINX and App Protect Enforcer using mTLS](#secure-traffic-between-nginx-and-app-protect-enforcer-using-mtls) | Disabled by default. You can manually configure mTLS to secure the traffic between NGINX and App Protect Enforcer.|
+|[Brute Force Attack Preventions](#brute-force-attack-preventions) | Configure brute-force-attack-preventions parameters to secured areas of a web application from brute force attacks.|
 
 ### Disallowed File Types
 
@@ -788,6 +789,118 @@ To enable mTLS in NGINX, you need to perform the following steps:
 
     Refer to the example for mTLS deployment in the admin guide, whether you're using [Docker]({{< relref "/nap-waf/v5/admin-guide/deploy-on-docker.md#docker-compose-file-with-mtls" >}}) or [Kubernetes]({{< relref "/nap-waf/v5/admin-guide/deploy-on-kubernetes.md#mtls-deployment" >}}).
     
+## Brute Force Attack Preventions
+
+### Overview
+
+Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive, 
+systematic, username/password combinations to discover legitimate authentication credentials. 
+To prevent brute force attacks, WAF tracks the number of failed attempts to reach login pages 
+with enforced brute force protection. When brute force patterns are detected, 
+the WAF policy considers it to be an attack if the failed logon rate increased significantly or 
+if failed logins reached a maximum threshold.
+
+### Brute force policy example
+
+```json
+{
+    "policy": {
+        "name": "BruteForcePolicy",
+        "template": {
+            "name": "POLICY_TEMPLATE_NGINX_BASE"
+        },
+        "applicationLanguage": "utf-8",
+        "enforcementMode": "blocking",
+        "brute-force-attack-preventions" : [
+            {
+               "bruteForceProtectionForAllLoginPages" : true,
+               "detectionCriteria" : {
+                  "action" : "alarm",
+                  "detectDistributedBruteForceAttack" : true,
+                  "failedLoginAttemptsRateReached" : 100
+               },
+               "loginAttemptsFromTheSameIp" : {
+                  "action" : "alarm",
+                  "enabled" : true,
+                  "threshold" : 20
+               },
+               "loginAttemptsFromTheSameUser" : {
+                  "action" : "alarm",
+                  "enabled" : true,
+                  "threshold" : 3
+               },
+               "measurementPeriod" : 900,
+               "preventionDuration" : "3600",
+               "reEnableLoginAfter" : 3600,
+               "sourceBasedProtectionDetectionPeriod" : 3600
+            }
+        ]
+    }
+}
+
+```
+### brute-force-attack-preventions fields description
+
+    bruteForceProtectionForAllLoginPages:
+          When enabled, enables Brute Force Protection for all configured login URLs.
+          When disabled, only brute force configurations for specific login pages are applied in case they exist.
+
+    detectionCriteria:
+          Specifies configuration for detecting distributed brute force attacks.
+        action:
+            Specifies action that is applied when the defined thresholds ( failedLoginAttemptsRateReached) is reached.
+            - **alarm**: The system will log the login attempt.
+
+        detectDistributedBruteForceAttack:
+            When enabled, the system detects distributed brute force attacks.
+
+        failedLoginAttemptsRateReached:
+            After configured threshold (number of failed login attempts within measurementPeriod) defined action will be applied for the next login attempt.           
+
+    loginAttemptsFromTheSameIp:
+          Specifies configuration for detecting brute force attacks from IP Address.
+
+        action:
+            Specifies action that is applied when defined threshold is reached.
+            - **alarm**: The system will log the login attempt.
+            - **alarm-and-blocking-page**: The system will log the login attempt, block the request and send the Blocking page.
+            - **alarm-and-drop**: The system will log the login attempt and reset the TCP connection.
+
+        enabled:
+            When enabled, the system counts failed login attempts from IP Address.
+
+        threshold:
+            After configured threshold (number of failed login attempts from IP Address) defined action will be applied for the next login attempt.
+
+    loginAttemptsFromTheSameUser:
+          Specifies configuration for detecting brute force attacks for Username.
+
+        action:
+            Specifies action that is applied when defined threshold is reached.
+            - **alarm**: The system will log the login attempt.
+
+        enabled:
+            When enabled, the system counts failed login attempts for each Username.
+
+        threshold:
+            After configured threshold (number of failed login attempts for each Username) defined action will be applied for the next login attempt.
+
+    measurementPeriod:
+          Defines detection period (measured in seconds) for distributed brute force attacks.
+
+    preventionDuration:
+          Defines prevention period (measured in seconds) for distributed brute force attacks.
+
+    reEnableLoginAfter:
+          Defines prevention period (measured in seconds) for source-based brute force attacks.
+
+    sourceBasedProtectionDetectionPeriod:
+          Defines detection period (measured in seconds) for source-based brute force attacks.
+
+    url:
+          Reference to the URL used in login URL configuration (policy/login-pages). This login URL is protected by Brute Force Protection feature.
+
+
 ## Custom Dimensions Log Entries
 
 ### Overview
@@ -931,11 +1044,7 @@ In the cases where decompression fails,  NGINX App Protect WAF will continue wit
 
 ---
 
-## Converter Tools
-
-NGINX App Protect WAF includes a number of tools that can be used to facilitate the process of porting existing resources or configuration files from the BIG-IP for use in the NGINX App Protect WAF environment. Note that these tools are available in the compiler package, and do not require a full installation of NGINX App Protect WAF or NGINX Plus.
-
-### Policy Converter
+## Policy Converter
 
 The NGINX App Protect WAF v5 Policy Converter tool `/opt/app_protect/bin/convert-policy` is used to convert XML policies to JSON format. The converted JSON policy is based on the NGINX App Protect WAF policy base template and contains the minimal differences to it in JSON declarative policy format.
 
@@ -947,7 +1056,7 @@ Using the tool:
 /opt/app_protect/bin/convert-policy 
 ```
 
-#### Convert Policy using Command Line Interface (CLI Usage)
+### Convert Policy using Command Line Interface (CLI Usage)
 
 The input policy can also be converted using convert-policy as a CLI tool from within NGINX App Protect WAF Converter container by using the following commands:
 
@@ -961,7 +1070,7 @@ docker run -it --rm \
   --full-export
 ```
 
-#### Command Line Options
+### Command Line Options
 
 {{<bootstrap-table "table table-striped table-bordered table-sm table-responsive">}}
 |Field Name   | Notes | 
@@ -973,173 +1082,6 @@ docker run -it --rm \
 | --dos-profile | Filename of JSON DoS Profile (pre-converted to JSON from tmsh syntax) |
 | --full-export | If specified, the full policy with all entities will be exported. Otherwise, only entities that differ from the template will be included.<br> Default for the CLI is not specific (only differing entities). <br> Default for the REST endpoint above is "--full-export" (you can not override this).|{{</bootstrap-table>}}
 
-### User Defined Signatures Converter
-
-The User Defined Signatures Converter tool `/opt/app_protect/bin/convert-signatures` takes a User Defined Signatures XML file as input and exports the content as a JSON file suitable for use in an NGINX App Protect WAF environment.
-
-The tool can optionally accept a tag argument as an input. Otherwise, the default tag value `user-defined-signatures` is assigned to the exported JSON file.
-
-Note that the User Defined signatures XML file can be obtained by exporting the signatures from a BIG-IP device.
-
-Using the tool:
-```shell
-/opt/app_protect/bin/convert-signatures
-```
-
-Output:
-```shell
-USAGE:
-    /opt/app_protect/bin/convert-signatures
-
-Required arguments:
-    --outfile|o='/path/to/signatures.json'
-        File name to write JSON format export
-        Can also be set via an environment variable: EXPORT_FILE
-    --infile|i='/path/to/signatures.xml'
-        Advanced WAF/ASM User Defined Signatures file to Convert
-        Can also be set via an environment variable: IMPORT_FILE
-
-Optional arguments:
-    --tag|t='mytag'
-        Signature Tag to associate with User Defined Signatures.
-        If no tag is specified in the XML file, a default tag of 'user-defined-signatures' will be assigned.
-        Can also be set via an environment variable: TAG
-    --format|f='json'
-        Desired output format for signature file. Default 'json'
-        Supported formats: 'json'
-
-Optionally, using --help will issue this help message.
-```
-
-Example of generating a user defined signature JSON file (with default tag):
-```shell
-docker run -v `pwd`:`pwd` -w `pwd` --entrypoint /opt/app_protect/bin/convert-signatures docker_img:latest -i /path/to/signatures.xml -o /path/to/signatures.json | jq
-```
-
-Output:
-```json
-{
-    "filename": "/path/to/signatures.json",
-    "file_size": 1602,
-    "completed_successfully": true
-}
-```
-
-Example of the contents of the output file (displayed and piped into `jq`):
-```json
-{
-    "tag": "user-defined-signatures",
-    "signatures": [
-        {
-            "accuracy": "high",
-            "risk": "high",
-            "systems": [],
-            "rule": "content:\"header1\"; nocase;",
-            "description": "",
-            "signatureType": "request",
-            "signatureId": "300000000",
-            "revision": "1",
-            "lastUpdateMicros": 1731425468000000,
-            "name": "sig_1_header",
-            "attackType": {
-                "name": "Abuse of Functionality"
-            }
-        },
-        {
-            "signatureId": "300000002",
-            "signatureType": "request",
-            "attackType": {
-                "name": "Cross Site Scripting (XSS)"
-            },
-            "name": "sig_3_uri",
-            "lastUpdateMicros": 1731425631000000,
-            "revision": "1",
-            "risk": "high",
-            "accuracy": "high",
-            "description": "",
-            "rule": "uricontent:\"<script>\"; nocase;",
-            "systems": [
-                {
-                    "name": "Nginx"
-                }
-            ]
-        },
-        {
-            "name": "sig_2_param",
-            "attackType": {
-                "name": "Abuse of Functionality"
-            },
-            "lastUpdateMicros": 1731425549000000,
-            "revision": "1",
-            "signatureId": "300000001",
-            "signatureType": "request",
-            "description": "",
-            "rule": "valuecontent:!\"param\"; nocase; httponly; norm;",
-            "systems": [],
-            "accuracy": "high",
-            "risk": "high"
-        },
-        {
-            "systems": [
-                {
-                    "name": "Apache"
-                },
-                {
-                    "name": "Unix/Linux"
-                },
-                {
-                    "name": "Proxy Servers"
-                },
-                {
-                    "name": "Django"
-                }
-            ],
-            "description": "",
-            "rule": "valuecontent:\"json123\"; nocase; jsononly; norm;",
-            "risk": "high",
-            "accuracy": "high",
-            "lastUpdateMicros": 1731425782000000,
-            "revision": "1",
-            "attackType": {
-                "name": "Server-Side Request Forgery (SSRF)"
-            },
-            "name": "sig_5_",
-            "signatureType": "request",
-            "signatureId": "300000004"
-        },
-        {
-            "description": "",
-            "rule": "uricontent:\"etc\"; nocase;",
-            "systems": [
-                {
-                    "name": "Microsoft Windows"
-                },
-                {
-                    "name": "Unix/Linux"
-                }
-            ],
-            "accuracy": "high",
-            "risk": "high",
-            "name": "sig_4_",
-            "attackType": {
-                "name": "Path Traversal"
-            },
-            "lastUpdateMicros": 1731425708000000,
-            "revision": "1",
-            "signatureId": "300000003",
-            "signatureType": "request"
-        }
-    ]
-}
-```
-
-Example of generating a user defined signature JSON file (with custom tag):
-```shell
-docker run -v `pwd`:`pwd` -w `pwd` --entrypoint /opt/app_protect/bin/convert-signatures docker_img:latest -i /path/to/signatures.xml -o /path/to/signatures.json --tag "MyTag" | jq
-```
-
-Note that if the script is run without the required switches and their corresponding arguments, it will display the help message.
-
 ---
 
 ## Security Logs
