Skip to content

Update configuration.md with bf section #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 27, 2025
Merged

Update configuration.md with bf section #115

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0da0673
Update configuration.md with bf section
ohad-perets Jan 27, 2025
1812046
Update configuration.md
ohad-perets Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 116 additions & 174 deletions content/nap-waf/v5/configuration-guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -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 |
Expand All @@ -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
Expand Down