Skip to content

Commit 58bff0a

Browse files
ohad-peretsADubhlaoich
ohad-perets
and
ADubhlaoich
authored
feat: Update NAP Brute Force documentation
Co-authored-by: Alan Dooley <a.dooley@f5.com>
1 parent 4ba7778 commit 58bff0a

File tree

3 files changed

+146
-104
lines changed

3 files changed

+146
-104
lines changed

‎content/includes/nap-waf/policy.html

Lines changed: 3 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -803,107 +803,37 @@ <h2 id="policy/brute-force-attack-preventions">brute-force-attack-preventions</h
803803
<td></td>
804804
</tr>
805805
<tr class="even">
806-
<td><a href="#policy/brute-force-attack-preventions/detectionCriteria">detectionCriteria</a></td>
807-
<td>object</td>
808-
<td>Specifies configuration for detecting distributed brute force attacks.</td>
809-
<td></td>
810-
</tr>
811-
<tr class="odd">
812806
<td><a href="#policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginAttemptsFromTheSameIp</a></td>
813807
<td>object</td>
814808
<td>Specifies configuration for detecting brute force attacks from IP Address.</td>
815809
<td></td>
816810
</tr>
817-
<tr class="even">
811+
<tr class="odd">
818812
<td><a href="#policy/brute-force-attack-preventions/loginAttemptsFromTheSameUser">loginAttemptsFromTheSameUser</a></td>
819813
<td>object</td>
820814
<td>Specifies configuration for detecting brute force attacks for Username.</td>
821815
<td></td>
822816
</tr>
823-
<tr class="odd">
824-
<td><code>measurementPeriod</code></td>
825-
<td>integer minimum: 60 maximum: 90000</td>
826-
<td>Defines detection period (measured in seconds) for distributed brute force attacks.</td>
827-
<td></td>
828-
</tr>
829817
<tr class="even">
830-
<td><code>preventionDuration</code></td>
831-
<td><ul>
832-
<li>integer minimum: 60 maximum: 90000</li>
833-
<li>string</li>
834-
</ul></td>
835-
<td>Defines prevention period (measured in seconds) for distributed brute force attacks.</td>
836-
<td><ul>
837-
<li>Integer values</li>
838-
<li>"unlimited"</li>
839-
</ul></td>
840-
</tr>
841-
<tr class="odd">
842818
<td><code>reEnableLoginAfter</code></td>
843819
<td>integer minimum: 60 maximum: 90000</td>
844820
<td>Defines prevention period (measured in seconds) for source-based brute force attacks.</td>
845821
<td></td>
846822
</tr>
847-
<tr class="even">
823+
<tr class="odd">
848824
<td><code>sourceBasedProtectionDetectionPeriod</code></td>
849825
<td>integer minimum: 60 maximum: 90000</td>
850826
<td>Defines detection period (measured in seconds) for source-based brute force attacks.</td>
851827
<td></td>
852828
</tr>
853-
<tr class="odd">
829+
<tr class="even">
854830
<td><a href="#policy/urls">url</a></td>
855831
<td>object</td>
856832
<td>Reference to the URL used in login URL configuration (policy/login-pages). This login URL is protected by Brute Force Protection feature.</td>
857833
<td></td>
858834
</tr>
859835
</tbody>
860836
</table>
861-
<h3 id="policy/brute-force-attack-preventions/detectionCriteria">detectionCriteria</h3>
862-
<table>
863-
<colgroup>
864-
<col style="width: 29%" />
865-
<col style="width: 5%" />
866-
<col style="width: 47%" />
867-
<col style="width: 17%" />
868-
</colgroup>
869-
<thead>
870-
<tr class="header">
871-
<th>Field Name</th>
872-
<th>Type</th>
873-
<th>Description</th>
874-
<th>Allowed Values</th>
875-
</tr>
876-
</thead>
877-
<tbody>
878-
<tr class="odd">
879-
<td><p><code>action</code></p></td>
880-
<td><p>string</p></td>
881-
<td><p>Specifies action that is applied when one of the defined thresholds (credentialsStuffingMatchesReached, failedLoginAttemptsRateReached) is reached.</p>
882-
<blockquote>
883-
<ul>
884-
<li><strong>alarm</strong>: The system will log the login attempt.</li>
885-
<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>
886-
</ul>
887-
</blockquote></td>
888-
<td><ul>
889-
<li>alarm</li>
890-
<li>alarm-and-client-side-integrity</li>
891-
</ul></td>
892-
</tr>
893-
<tr class="even">
894-
<td><code>credentialsStuffingMatchesReached</code></td>
895-
<td>integer minimum: 1 maximum: 10000</td>
896-
<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>
897-
<td></td>
898-
</tr>
899-
<tr class="odd">
900-
<td><code>failedLoginAttemptsRateReached</code></td>
901-
<td>integer minimum: 1 maximum: 10000</td>
902-
<td>After configured threshold (number of failed login attempts within measurementPeriod) defined action will be applied for the next login attempt.</td>
903-
<td></td>
904-
</tr>
905-
</tbody>
906-
</table>
907837
<h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginAttemptsFromTheSameIp</h3>
908838
<table>
909839
<colgroup>
@@ -929,17 +859,11 @@ <h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameIp">loginA
929859
<ul>
930860
<li><strong>alarm</strong>: The system will log the login attempt.</li>
931861
<li><strong>alarm-and-blocking-page</strong>: The system will log the login attempt, block the request and send the Blocking page.</li>
932-
<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>
933-
<li><strong>alarm-and-drop</strong>: The system will log the login attempt and reset the TCP connection.</li>
934-
<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>
935862
</ul>
936863
</blockquote></td>
937864
<td><ul>
938865
<li>alarm</li>
939866
<li>alarm-and-blocking-page</li>
940-
<li>alarm-and-client-side-integrity</li>
941-
<li>alarm-and-drop</li>
942-
<li>alarm-and-honeypot-page</li>
943867
</ul></td>
944868
</tr>
945869
<tr class="even">
@@ -980,12 +904,10 @@ <h3 id="policy/brute-force-attack-preventions/loginAttemptsFromTheSameUser">logi
980904
<blockquote>
981905
<ul>
982906
<li><strong>alarm</strong>: The system will log the login attempt.</li>
983-
<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>
984907
</ul>
985908
</blockquote></td>
986909
<td><ul>
987910
<li>alarm</li>
988-
<li>alarm-and-client-side-integrity</li>
989911
</ul></td>
990912
</tr>
991913
<tr class="even">

‎content/nap-waf/v4/configuration-guide/configuration.md

Lines changed: 70 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -655,15 +655,43 @@ claims['address'] = "{ \"address\": { .... } }" # JSON structs can be accessed u
655655

656656
### Overview
657657

658-
Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
658+
Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
659659
systematic, username/password combinations to discover legitimate authentication credentials.
660-
To prevent brute force attacks, WAF tracks the number of failed attempts to reach login pages
661-
with enforced brute force protection. When brute force patterns are detected,
662-
the WAF policy considers it to be an attack if the failed logon rate increased significantly or
663-
if failed logins reached a maximum threshold.
660+
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
661+
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
662+
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
663+
To enable brute force protection, at least one login page must be created.
664664

665+
---
666+
667+
### Login page policy example
668+
669+
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)
670+
```json
671+
"login-pages": [
672+
{
673+
"accessValidation" : {
674+
"responseContains": "Success"
675+
},
676+
"authenticationType": "form",
677+
"url" : {
678+
"method" : "*",
679+
"name" : "/html_login",
680+
"protocol" : "http",
681+
"type" : "explicit"
682+
},
683+
"usernameParameterName": "username",
684+
"passwordParameterName": "password"
685+
}
686+
]
687+
```
688+
689+
{{< 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 >}}
690+
691+
---
665692
### Brute force policy example
666693

694+
Example1: A single brute force configuration is applied universally to all login pages.
667695
```json
668696
{
669697
"policy": {
@@ -676,10 +704,6 @@ if failed logins reached a maximum threshold.
676704
"brute-force-attack-preventions" : [
677705
{
678706
"bruteForceProtectionForAllLoginPages" : true,
679-
"detectionCriteria" : {
680-
"action" : "alarm",
681-
"failedLoginAttemptsRateReached" : 100
682-
},
683707
"loginAttemptsFromTheSameIp" : {
684708
"action" : "alarm",
685709
"enabled" : true,
@@ -690,16 +714,51 @@ if failed logins reached a maximum threshold.
690714
"enabled" : true,
691715
"threshold" : 3
692716
},
693-
"measurementPeriod" : 900,
694-
"preventionDuration" : "3600",
695717
"reEnableLoginAfter" : 3600,
696718
"sourceBasedProtectionDetectionPeriod" : 3600
697719
}
698720
]
699721
}
700722
}
723+
```
701724

725+
Example2: Different brute force configurations can be defined for individual login pages.
726+
```json
727+
{
728+
"policy": {
729+
"name": "BruteForcePolicySpec",
730+
"template": {
731+
"name": "POLICY_TEMPLATE_NGINX_BASE"
732+
},
733+
"applicationLanguage": "utf-8",
734+
"enforcementMode": "blocking",
735+
"brute-force-attack-preventions" : [
736+
{
737+
"bruteForceProtectionForAllLoginPages" : false,
738+
"loginAttemptsFromTheSameIp" : {
739+
"action" : "alarm",
740+
"enabled" : true,
741+
"threshold" : 20
742+
},
743+
"loginAttemptsFromTheSameUser" : {
744+
"action" : "alarm",
745+
"enabled" : true,
746+
"threshold" : 3
747+
},
748+
"reEnableLoginAfter" : 3600,
749+
"sourceBasedProtectionDetectionPeriod" : 3600,
750+
"url": {
751+
"method": "*",
752+
"name": "/html_login",
753+
"protocol": "http"
754+
}
755+
}
756+
],
757+
758+
}
759+
}
702760
```
761+
{{< 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 >}}
703762

704763
## Custom Dimensions Log Entries
705764

‎content/nap-waf/v5/configuration-guide/configuration.md

Lines changed: 73 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -791,15 +791,46 @@ To enable mTLS in NGINX, you need to perform the following steps:
791791

792792
## Brute Force Attack Preventions
793793

794-
Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
794+
### Overview
795+
796+
Brute force attacks are attempts to break in to secured areas of a web application by trying exhaustive,
795797
systematic, username/password combinations to discover legitimate authentication credentials.
796-
To prevent brute force attacks, WAF tracks the number of failed attempts to reach login pages
797-
with enforced brute force protection. When brute force patterns are detected,
798-
the WAF policy considers it to be an attack if the failed logon rate increased significantly or
799-
if failed logins reached a maximum threshold.
798+
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
799+
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
800+
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
801+
To enable brute force protection, at least one login page must be created.
802+
803+
---
804+
805+
### Login page policy example
806+
807+
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)
808+
```json
809+
"login-pages": [
810+
{
811+
"accessValidation" : {
812+
"responseContains": "Success"
813+
},
814+
"authenticationType": "form",
815+
"url" : {
816+
"method" : "*",
817+
"name" : "/html_login",
818+
"protocol" : "http",
819+
"type" : "explicit"
820+
},
821+
"usernameParameterName": "username",
822+
"passwordParameterName": "password"
823+
}
824+
]
825+
```
826+
827+
{{< 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 >}}
828+
829+
---
800830

801831
### Brute force policy example
802832

833+
Example1: A single brute force configuration is applied universally to all login pages.
803834
```json
804835
{
805836
"policy": {
@@ -812,11 +843,6 @@ if failed logins reached a maximum threshold.
812843
"brute-force-attack-preventions" : [
813844
{
814845
"bruteForceProtectionForAllLoginPages" : true,
815-
"detectionCriteria" : {
816-
"action" : "alarm",
817-
"detectDistributedBruteForceAttack" : true,
818-
"failedLoginAttemptsRateReached" : 100
819-
},
820846
"loginAttemptsFromTheSameIp" : {
821847
"action" : "alarm",
822848
"enabled" : true,
@@ -827,16 +853,51 @@ if failed logins reached a maximum threshold.
827853
"enabled" : true,
828854
"threshold" : 3
829855
},
830-
"measurementPeriod" : 900,
831-
"preventionDuration" : "3600",
832856
"reEnableLoginAfter" : 3600,
833857
"sourceBasedProtectionDetectionPeriod" : 3600
834858
}
835859
]
836860
}
837861
}
862+
```
838863

864+
Example2: Different brute force configurations can be defined for individual login pages.
865+
```json
866+
{
867+
"policy": {
868+
"name": "BruteForcePolicySpec",
869+
"template": {
870+
"name": "POLICY_TEMPLATE_NGINX_BASE"
871+
},
872+
"applicationLanguage": "utf-8",
873+
"enforcementMode": "blocking",
874+
"brute-force-attack-preventions" : [
875+
{
876+
"bruteForceProtectionForAllLoginPages" : false,
877+
"loginAttemptsFromTheSameIp" : {
878+
"action" : "alarm",
879+
"enabled" : true,
880+
"threshold" : 20
881+
},
882+
"loginAttemptsFromTheSameUser" : {
883+
"action" : "alarm",
884+
"enabled" : true,
885+
"threshold" : 3
886+
},
887+
"reEnableLoginAfter" : 3600,
888+
"sourceBasedProtectionDetectionPeriod" : 3600,
889+
"url": {
890+
"method": "*",
891+
"name": "/html_login",
892+
"protocol": "http"
893+
}
894+
}
895+
],
896+
897+
}
898+
}
839899
```
900+
{{< 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 >}}
840901

841902
## Custom Dimensions Log Entries
842903

0 commit comments

Comments
 (0)