From 0da06733fa561c4e8733346ac2433f6c6da84f23 Mon Sep 17 00:00:00 2001 From: ohad-perets <126083286+ohad-perets@users.noreply.github.com> Date: Mon, 27 Jan 2025 16:11:55 +0200 Subject: [PATCH 1/2] Update configuration.md with bf section add brute force configuration --- .../v5/configuration-guide/configuration.md | 295 +++++++----------- 1 file changed, 121 insertions(+), 174 deletions(-) diff --git a/content/nap-waf/v5/configuration-guide/configuration.md b/content/nap-waf/v5/configuration-guide/configuration.md index e6b8ed194..6530a746c 100644 --- 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,123 @@ 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 Prevention + +### 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 +1049,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 +1061,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 +1075,7 @@ docker run -it --rm \ --full-export ``` -#### Command Line Options +### Command Line Options {{}} |Field Name | Notes | @@ -973,173 +1087,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.
Default for the CLI is not specific (only differing entities).
Default for the REST endpoint above is "--full-export" (you can not override this).|{{}} -### 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:\"