Skip to content

fix: brute force docs #161

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 21 commits into from
Feb 4, 2025
Merged

fix: brute force docs #161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
8954f5e
fix: gofmt
ohad-perets Feb 3, 2025
63ac437
fix: split configuration
ohad-perets Feb 3, 2025
477554f
fix: indent
ohad-perets Feb 3, 2025
3c65764
fix: Beni's comments
ohad-perets Feb 3, 2025
98e356a
fix: more comments
ohad-perets Feb 4, 2025
b18d995
fix: more comments
ohad-perets Feb 4, 2025
5d90cb5
fix: remove doc and add links to declar
ohad-perets Feb 4, 2025
554e5a1
fix: remove doc and add links to declar
ohad-perets Feb 4, 2025
c039749
fix: brokenlink
ohad-perets Feb 4, 2025
2e5c9e4
fix: remove loginpage expla
ohad-perets Feb 4, 2025
f3fec4e
fix: also for v5
ohad-perets Feb 4, 2025
24c6eaf
fix: add login expl
ohad-perets Feb 4, 2025
0f119de
Merge branch 'main' into brute_force_doc
ohad-perets Feb 4, 2025
141c13d
fix: typo
ohad-perets Feb 4, 2025
133ee64
Update content/nap-waf/v4/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
f45c865
Update content/nap-waf/v4/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
fb62621
Update content/nap-waf/v4/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
eb303cf
Update content/nap-waf/v5/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
817f672
Update content/nap-waf/v5/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
45b7499
Update content/nap-waf/v5/configuration-guide/configuration.md
ohad-perets Feb 4, 2025
2d688da
Merge branch 'main' into brute_force_doc
ADubhlaoich Feb 4, 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
84 changes: 3 additions & 81 deletions content/includes/nap-waf/policy.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -803,107 +803,37 @@ <h2 id="policy/brute-force-attack-preventions">brute-force-attack-preventions</h
<td></td>
</tr>
<tr class="even">
<td><a href="#policy/brute-force-attack-preventions/detectionCriteria">detectionCriteria</a></td>
<td>object</td>
<td>Specifies configuration for detecting distributed brute force attacks.</td>
<td></td>
</tr>
<tr class="odd">
<td><a href="#policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginAttemptsFromTheSameIp</a></td>
<td>object</td>
<td>Specifies configuration for detecting brute force attacks from IP Address.</td>
<td></td>
</tr>
<tr class="even">
<tr class="odd">
<td><a href="#policy/brute-force-attack-preventions/loginAttemptsFromTheSameUser">loginAttemptsFromTheSameUser</a></td>
<td>object</td>
<td>Specifies configuration for detecting brute force attacks for Username.</td>
<td></td>
</tr>
<tr class="odd">
<td><code>measurementPeriod</code></td>
<td>integer minimum: 60 maximum: 90000</td>
<td>Defines detection period (measured in seconds) for distributed brute force attacks.</td>
<td></td>
</tr>
<tr class="even">
<td><code>preventionDuration</code></td>
<td><ul>
<li>integer minimum: 60 maximum: 90000</li>
<li>string</li>
</ul></td>
<td>Defines prevention period (measured in seconds) for distributed brute force attacks.</td>
<td><ul>
<li>Integer values</li>
<li>"unlimited"</li>
</ul></td>
</tr>
<tr class="odd">
<td><code>reEnableLoginAfter</code></td>
<td>integer minimum: 60 maximum: 90000</td>
<td>Defines prevention period (measured in seconds) for source-based brute force attacks.</td>
<td></td>
</tr>
<tr class="even">
<tr class="odd">
<td><code>sourceBasedProtectionDetectionPeriod</code></td>
<td>integer minimum: 60 maximum: 90000</td>
<td>Defines detection period (measured in seconds) for source-based brute force attacks.</td>
<td></td>
</tr>
<tr class="odd">
<tr class="even">
<td><a href="#policy/urls">url</a></td>
<td>object</td>
<td>Reference to the URL used in login URL configuration (policy/login-pages). This login URL is protected by Brute Force Protection feature.</td>
<td></td>
</tr>
</tbody>
</table>
<h3 id="policy/brute-force-attack-preventions/detectionCriteria">detectionCriteria</h3>
<table>
<colgroup>
<col style="width: 29%" />
<col style="width: 5%" />
<col style="width: 47%" />
<col style="width: 17%" />
</colgroup>
<thead>
<tr class="header">
<th>Field Name</th>
<th>Type</th>
<th>Description</th>
<th>Allowed Values</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p><code>action</code></p></td>
<td><p>string</p></td>
<td><p>Specifies action that is applied when one of the defined thresholds (credentialsStuffingMatchesReached, failedLoginAttemptsRateReached) is reached.</p>
<blockquote>
<ul>
<li><strong>alarm</strong>: The system will log the login attempt.</li>
<li><strong>alarm-and-client-side-integrity</strong>: The system determines whether the client is a legal browser or a bot by sending a page containing JavaScript code and waiting for a response. Legal browsers are able to execute JavaScript and produce a valid response, whereas bots cannot. A login attempt is logged if the client successfully passes the Client Side Integrity challenge.</li>
</ul>
</blockquote></td>
<td><ul>
<li>alarm</li>
<li>alarm-and-client-side-integrity</li>
</ul></td>
</tr>
<tr class="even">
<td><code>credentialsStuffingMatchesReached</code></td>
<td>integer minimum: 1 maximum: 10000</td>
<td>After configured threshold (number of detected login attempts that match known leaked credentials library) defined action will be applied for the next login attempt.</td>
<td></td>
</tr>
<tr class="odd">
<td><code>failedLoginAttemptsRateReached</code></td>
<td>integer minimum: 1 maximum: 10000</td>
<td>After configured threshold (number of failed login attempts within measurementPeriod) defined action will be applied for the next login attempt.</td>
<td></td>
</tr>
</tbody>
</table>
<h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginAttemptsFromTheSameIp</h3>
<table>
<colgroup>
Expand All @@ -929,17 +859,11 @@ <h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginA
<ul>
<li><strong>alarm</strong>: The system will log the login attempt.</li>
<li><strong>alarm-and-blocking-page</strong>: The system will log the login attempt, block the request and send the Blocking page.</li>
<li><strong>alarm-and-client-side-integrity</strong>: The system determines whether the client is a legal browser or a bot by sending a page containing JavaScript code and waiting for a response. Legal browsers are able to execute JavaScript and produce a valid response, whereas bots cannot. A login attempt is logged if the client successfully passes the Client Side Integrity challenge.</li>
<li><strong>alarm-and-drop</strong>: The system will log the login attempt and reset the TCP connection.</li>
<li><strong>alarm-and-honeypot-page</strong>: The system will log the login attempt, block the request and send the Honeypot page. The Honeypot page is used for attacker deception. The page should look like an application failed login page. Unlike with the Blocking page, when the Honeypot page is sent an attacker is not able to distinguish a failed login response from a mitigation. As a result, the attacker will not change identity (Source IP or Device ID) and the brute force attack will be rendered ineffective. The Honeypot page is recommended when mitigation is request blocking.</li>
</ul>
</blockquote></td>
<td><ul>
<li>alarm</li>
<li>alarm-and-blocking-page</li>
<li>alarm-and-client-side-integrity</li>
<li>alarm-and-drop</li>
<li>alarm-and-honeypot-page</li>
</ul></td>
</tr>
<tr class="even">
Expand Down Expand Up @@ -980,12 +904,10 @@ <h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameUser">logi
<blockquote>
<ul>
<li><strong>alarm</strong>: The system will log the login attempt.</li>
<li><strong>alarm-and-client-side-integrity</strong>: The system determines whether the client is a legal browser or a bot by sending a page containing JavaScript code and waiting for a response. Legal browsers are able to execute JavaScript and produce a valid response, whereas bots cannot. A login attempt is logged if the client successfully passes the Client Side Integrity challenge.</li>
</ul>
</blockquote></td>
<td><ul>
<li>alarm</li>
<li>alarm-and-client-side-integrity</li>
</ul></td>
</tr>
<tr class="even">
Expand Down
81 changes: 70 additions & 11 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 @@ -655,15 +655,43 @@ claims['address'] = "{ \"address\": { .... } }" # JSON structs can be accessed u

### Overview

Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in to --> into

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.
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"...and the number of failed login attempts per each one of them. Once the number of attempts crosses a configured maximum threshold, a brute force attack is assumed. (remove "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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace "When brute force patterns...IP address" with:
"The detected brute force attack will trigger an alarm, that is, a violation reported in the security logs and may also block any further attempt to login, coming from the IP address that exceeded the login attempt threshold. Note that if it was the username that crossed the threshold then it will not be possible to block because you would not like to lock the legitimate username owner out of his account".

To enable brute force protection, at least one login page must be created.

---

### Login page policy 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
"login-pages": [
{
"accessValidation" : {
"responseContains": "Success"
},
"authenticationType": "form",
"url" : {
"method" : "*",
"name" : "/html_login",
"protocol" : "http",
"type" : "explicit"
},
"usernameParameterName": "username",
"passwordParameterName": "password"
}
]
```

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

---
### Brute force policy example

Example1: A single brute force configuration is applied universally to all login pages.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add: "If you configured more than one login page, then the attempts of the same source IP address or username across all the login pages are counted".

```json
{
"policy": {
Expand All @@ -676,10 +704,6 @@ if failed logins reached a maximum threshold.
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : true,
"detectionCriteria" : {
"action" : "alarm",
"failedLoginAttemptsRateReached" : 100
},
"loginAttemptsFromTheSameIp" : {
"action" : "alarm",
"enabled" : true,
Expand All @@ -690,16 +714,51 @@ if failed logins reached a maximum threshold.
"enabled" : true,
"threshold" : 3
},
"measurementPeriod" : 900,
"preventionDuration" : "3600",
"reEnableLoginAfter" : 3600,
"sourceBasedProtectionDetectionPeriod" : 3600
}
]
}
}
```

Example2: Different brute force configurations can be defined for individual login pages.
```json
{
"policy": {
"name": "BruteForcePolicySpec",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"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]({{< relref "/nap-waf/v4/declarative-policy/policy/#policy/brute-force-attack-preventions" >}}). {{< /note >}}

## Custom Dimensions Log Entries

Expand Down
85 changes: 73 additions & 12 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 @@ -791,15 +791,46 @@ To enable mTLS in NGINX, you need to perform the following steps:

## Brute Force Attack Preventions

Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
### 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.
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.

---

### Login page policy 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
"login-pages": [
{
"accessValidation" : {
"responseContains": "Success"
},
"authenticationType": "form",
"url" : {
"method" : "*",
"name" : "/html_login",
"protocol" : "http",
"type" : "explicit"
},
"usernameParameterName": "username",
"passwordParameterName": "password"
}
]
```

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

---

### Brute force policy example

Example1: A single brute force configuration is applied universally to all login pages.
```json
{
"policy": {
Expand All @@ -812,11 +843,6 @@ if failed logins reached a maximum threshold.
"brute-force-attack-preventions" : [
{
"bruteForceProtectionForAllLoginPages" : true,
"detectionCriteria" : {
"action" : "alarm",
"detectDistributedBruteForceAttack" : true,
"failedLoginAttemptsRateReached" : 100
},
"loginAttemptsFromTheSameIp" : {
"action" : "alarm",
"enabled" : true,
Expand All @@ -827,16 +853,51 @@ if failed logins reached a maximum threshold.
"enabled" : true,
"threshold" : 3
},
"measurementPeriod" : 900,
"preventionDuration" : "3600",
"reEnableLoginAfter" : 3600,
"sourceBasedProtectionDetectionPeriod" : 3600
}
]
}
}
```

Example2: Different brute force configurations can be defined for individual login pages.
```json
{
"policy": {
"name": "BruteForcePolicySpec",
"template": {
"name": "POLICY_TEMPLATE_NGINX_BASE"
},
"applicationLanguage": "utf-8",
"enforcementMode": "blocking",
"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]({{< relref "/nap-waf/v5/declarative-policy/policy/#policy/brute-force-attack-preventions" >}}). {{< /note >}}

## Custom Dimensions Log Entries

Expand Down