Skip to content

Patch 1 to nap-release-5.7 brute-force and login-pages documentation improvement #609

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 3 commits into from
May 28, 2025
Merged

Patch 1 to nap-release-5.7 brute-force and login-pages documentation improvement #609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
951f918
Update configuration.md brute-force and login-pages
kudriavitsky May 27, 2025
ceef3f4
Update configuration.md
kudriavitsky May 27, 2025
d87d893
Update configuration.md v5
kudriavitsky May 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
103 changes: 78 additions & 25 deletions content/nap-waf/v4/configuration-guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ When configuring NGINX App Protect WAF, `app_protect_enable` should always be en
|[Deny and Allow IP lists](#deny-and-allow-ip-lists) | Manually define denied & allowed IP addresses as well as IP addresses to never log. |
|[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.|
|[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.|}
|[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.|
|[IP Groups](#ip-address-lists) | Configure IP Groups feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.|

### Disallowed File Types
{{< include "nap-waf/config/common/disallowed-file-types.md" >}}
Expand Down Expand Up @@ -669,12 +670,23 @@ systematic, username/password combinations to discover legitimate authentication
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
To enable brute force protection, at least one login page must be created.
The login page entity is created separately and is not included in the brute force configuration block.
In order to create a brute force configuration for a specific URL in Nginx App Protect you must first create a User-Defined URL, then a Login Page and finally define the URL element in the Brute Force configuration section.

---
### The User-Defined URL example

### Login page policy example
```json
"urls": [
{
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
}
],
```

### Login pages example

A login page specifies the login URL that users must pass through to get authenticated. The configuration of a login URL includes the URL itself, the username and passwords parameters and the validation criteria (how we know that a login was successful or failed)
```json
Expand All @@ -699,18 +711,10 @@ A login page specifies the login URL that users must pass through to get authent
{{< note >}} For further configuration details, see NGINX App Protect WAF Declarative Policy Guide [Declarative Policy guide]({{< ref "/nap-waf/v4/declarative-policy/policy/#policy/login-pages" >}}). {{< /note >}}

---
### Brute force policy example
### Brute force prevention example

Example1: A single brute force configuration is applied universally to all login pages.
```json
{
"policy": {
"name": "BruteForcePolicy",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : true,
Expand All @@ -728,21 +732,11 @@ Example1: A single brute force configuration is applied universally to all login
"sourceBasedProtectionDetectionPeriod" : 3600
}
]
}
}
```

Example2: Different brute force configurations can be defined for individual login pages,
with each configuration referencing a specific login page.
```json
{
"policy": {
"name": "BruteForcePolicySpec",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : false,
Expand All @@ -762,13 +756,72 @@ Example2: Different brute force configurations can be defined for individual log
"method": "*",
"name": "/html_login",
"protocol": "http"
}
}
}
],
```

}
The following example adds all three of the pieces for a complete example policy.

```json
{
"policy": {
"name": "BruteForcePolicy",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"urls": [
{
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
}
],
"login-pages": [
{
"accessValidation": {
"responseContains": "Success"
},
"authenticationType": "form",
"url": {
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
},
"usernameParameterName": "username",
"passwordParameterName": "password"
}
],
"brute-force-attack-preventions": [
{
"bruteForceProtectionForAllLoginPages": false,
"loginAttemptsFromTheSameIp": {
"action": "alarm",
"enabled": true,
"threshold": 20
},
"loginAttemptsFromTheSameUser": {
"action": "alarm",
"enabled": true,
"threshold": 3
},
"reEnableLoginAfter": 3600,
"sourceBasedProtectionDetectionPeriod": 3600,
"url": {
"method": "*",
"name": "/html_login",
"protocol": "http"
}
}
]
}
}
```

{{< note >}} For further configuration details, see NGINX App Protect WAF Declarative Policy Guide [Declarative Policy guide]({{< ref "/nap-waf/v4/declarative-policy/policy/#policy/brute-force-attack-preventions" >}}). {{< /note >}}

## Custom Dimensions Log Entries
Expand Down
104 changes: 79 additions & 25 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 @@ -38,6 +38,7 @@ For more information on the NGINX App Protect WAF security features, see [NGINX
|[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.|
|[IP Groups](#ip-address-lists) | Configure IP Groups feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.|

### Disallowed File Types

Expand Down Expand Up @@ -808,12 +809,25 @@ systematic, username/password combinations to discover legitimate authentication
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
To enable brute force protection, at least one login page must be created.
The login page entity is created separately and is not included in the brute force configuration block
In order to create a brute force configuration for a specific URL in Nginx App Protect you must first create a User-Defined URL, then a Login Page and finally define the URL element in the Brute Force configuration section.


---

### Login page policy example
### The User-Defined URL example

```json
"urls": [
{
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
}
],
```

### Login pages example

A login page specifies the login URL that users must pass through to get authenticated. The configuration of a login URL includes the URL itself, the username and passwords parameters and the validation criteria (how we know that a login was successful or failed)
```json
Expand All @@ -839,18 +853,10 @@ A login page specifies the login URL that users must pass through to get authent

---

### Brute force policy example
### Brute force prevention example

Example1: A single brute force configuration is applied universally to all login pages.
```json
{
"policy": {
"name": "BruteForcePolicy",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : true,
Expand All @@ -868,21 +874,11 @@ Example1: A single brute force configuration is applied universally to all login
"sourceBasedProtectionDetectionPeriod" : 3600
}
]
}
}
```

Example2: Different brute force configurations can be defined for individual login pages,
with each configuration referencing a specific login page.
```json
{
"policy": {
"name": "BruteForcePolicySpec",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : false,
Expand All @@ -902,13 +898,71 @@ Example2: Different brute force configurations can be defined for individual log
"method": "*",
"name": "/html_login",
"protocol": "http"
}
}
}
],
]
```

}
The following example adds all three of the pieces for a complete example policy.
```json
{
"policy": {
"name": "BruteForcePolicy",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"urls": [
{
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
}
],
"login-pages": [
{
"accessValidation": {
"responseContains": "Success"
},
"authenticationType": "form",
"url": {
"method": "*",
"name": "/html_login",
"protocol": "http",
"type": "explicit"
},
"usernameParameterName": "username",
"passwordParameterName": "password"
}
],
"brute-force-attack-preventions": [
{
"bruteForceProtectionForAllLoginPages": false,
"loginAttemptsFromTheSameIp": {
"action": "alarm",
"enabled": true,
"threshold": 20
},
"loginAttemptsFromTheSameUser": {
"action": "alarm",
"enabled": true,
"threshold": 3
},
"reEnableLoginAfter": 3600,
"sourceBasedProtectionDetectionPeriod": 3600,
"url": {
"method": "*",
"name": "/html_login",
"protocol": "http"
}
}
]
}
}
```

{{< note >}} For further configuration details, see NGINX App Protect WAF Declarative Policy Guide [Declarative Policy guide]({{< ref "/nap-waf/v5/declarative-policy/policy/#policy/brute-force-attack-preventions" >}}). {{< /note >}}

## Custom Dimensions Log Entries
Expand Down