Skip to content

Commit c898f90

Browse files
kudriavitskykudriavitsky
authored
feat: Improve NAP-WAF brute force and login-pages documentation (#609)
1 parent 4f69882 commit c898f90

File tree

2 files changed

+157
-50
lines changed

2 files changed

+157
-50
lines changed

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

Lines changed: 78 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ When configuring NGINX App Protect WAF, `app_protect_enable` should always be en
3838
|[Deny and Allow IP lists](#deny-and-allow-ip-lists) | Manually define denied & allowed IP addresses as well as IP addresses to never log. |
3939
|[XFF headers & trust](#xff-headers-and-trust) | Disabled by default. User can enable it and optionally add a list of custom XFF headers. |
4040
|[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.|
41-
|[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.|}
41+
|[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.|
42+
|[IP Groups](#ip-address-lists) | Configure IP Groups feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.|
4243

4344
### Disallowed File Types
4445
{{< include "nap-waf/config/common/disallowed-file-types.md" >}}
@@ -673,12 +674,23 @@ systematic, username/password combinations to discover legitimate authentication
673674
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
674675
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
675676
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
676-
To enable brute force protection, at least one login page must be created.
677-
The login page entity is created separately and is not included in the brute force configuration block.
677+
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.
678678

679679
---
680+
### The User-Defined URL example
680681

681-
### Login page policy example
682+
```json
683+
"urls": [
684+
{
685+
"method": "*",
686+
"name": "/html_login",
687+
"protocol": "http",
688+
"type": "explicit"
689+
}
690+
],
691+
```
692+
693+
### Login pages example
682694

683695
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)
684696
```json
@@ -703,18 +715,10 @@ A login page specifies the login URL that users must pass through to get authent
703715
{{< 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 >}}
704716

705717
---
706-
### Brute force policy example
718+
### Brute force prevention example
707719

708720
Example1: A single brute force configuration is applied universally to all login pages.
709721
```json
710-
{
711-
"policy": {
712-
"name": "BruteForcePolicy",
713-
"template": {
714-
"name": "POLICY_TEMPLATE_NGINX_BASE"
715-
},
716-
"applicationLanguage": "utf-8",
717-
"enforcementMode": "blocking",
718722
"brute-force-attack-preventions" : [
719723
{
720724
"bruteForceProtectionForAllLoginPages" : true,
@@ -732,21 +736,11 @@ Example1: A single brute force configuration is applied universally to all login
732736
"sourceBasedProtectionDetectionPeriod" : 3600
733737
}
734738
]
735-
}
736-
}
737739
```
738740

739741
Example2: Different brute force configurations can be defined for individual login pages,
740742
with each configuration referencing a specific login page.
741743
```json
742-
{
743-
"policy": {
744-
"name": "BruteForcePolicySpec",
745-
"template": {
746-
"name": "POLICY_TEMPLATE_NGINX_BASE"
747-
},
748-
"applicationLanguage": "utf-8",
749-
"enforcementMode": "blocking",
750744
"brute-force-attack-preventions" : [
751745
{
752746
"bruteForceProtectionForAllLoginPages" : false,
@@ -766,13 +760,72 @@ Example2: Different brute force configurations can be defined for individual log
766760
"method": "*",
767761
"name": "/html_login",
768762
"protocol": "http"
769-
}
763+
}
770764
}
771765
],
766+
```
772767

773-
}
768+
The following example adds all three of the pieces for a complete example policy.
769+
770+
```json
771+
{
772+
"policy": {
773+
"name": "BruteForcePolicy",
774+
"template": {
775+
"name": "POLICY_TEMPLATE_NGINX_BASE"
776+
},
777+
"applicationLanguage": "utf-8",
778+
"enforcementMode": "blocking",
779+
"urls": [
780+
{
781+
"method": "*",
782+
"name": "/html_login",
783+
"protocol": "http",
784+
"type": "explicit"
785+
}
786+
],
787+
"login-pages": [
788+
{
789+
"accessValidation": {
790+
"responseContains": "Success"
791+
},
792+
"authenticationType": "form",
793+
"url": {
794+
"method": "*",
795+
"name": "/html_login",
796+
"protocol": "http",
797+
"type": "explicit"
798+
},
799+
"usernameParameterName": "username",
800+
"passwordParameterName": "password"
801+
}
802+
],
803+
"brute-force-attack-preventions": [
804+
{
805+
"bruteForceProtectionForAllLoginPages": false,
806+
"loginAttemptsFromTheSameIp": {
807+
"action": "alarm",
808+
"enabled": true,
809+
"threshold": 20
810+
},
811+
"loginAttemptsFromTheSameUser": {
812+
"action": "alarm",
813+
"enabled": true,
814+
"threshold": 3
815+
},
816+
"reEnableLoginAfter": 3600,
817+
"sourceBasedProtectionDetectionPeriod": 3600,
818+
"url": {
819+
"method": "*",
820+
"name": "/html_login",
821+
"protocol": "http"
822+
}
823+
}
824+
]
825+
}
774826
}
775827
```
828+
776829
{{< 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 >}}
777830

778831
## Custom Dimensions Log Entries

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

Lines changed: 79 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ For more information on the NGINX App Protect WAF security features, see [NGINX
3838
|[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.|
3939
|[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.|
4040
|[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.|
41+
|[IP Groups](#ip-address-lists) | Configure IP Groups feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.|
4142

4243
### Disallowed File Types
4344

@@ -812,12 +813,25 @@ systematic, username/password combinations to discover legitimate authentication
812813
To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold.
813814
When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed
814815
login attempts reached a maximum threshold for a specific username or coming from a specific IP address.
815-
To enable brute force protection, at least one login page must be created.
816-
The login page entity is created separately and is not included in the brute force configuration block
816+
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.
817+
817818

818819
---
819820

820-
### Login page policy example
821+
### The User-Defined URL example
822+
823+
```json
824+
"urls": [
825+
{
826+
"method": "*",
827+
"name": "/html_login",
828+
"protocol": "http",
829+
"type": "explicit"
830+
}
831+
],
832+
```
833+
834+
### Login pages example
821835

822836
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)
823837
```json
@@ -843,18 +857,10 @@ A login page specifies the login URL that users must pass through to get authent
843857

844858
---
845859

846-
### Brute force policy example
860+
### Brute force prevention example
847861

848862
Example1: A single brute force configuration is applied universally to all login pages.
849863
```json
850-
{
851-
"policy": {
852-
"name": "BruteForcePolicy",
853-
"template": {
854-
"name": "POLICY_TEMPLATE_NGINX_BASE"
855-
},
856-
"applicationLanguage": "utf-8",
857-
"enforcementMode": "blocking",
858864
"brute-force-attack-preventions" : [
859865
{
860866
"bruteForceProtectionForAllLoginPages" : true,
@@ -872,21 +878,11 @@ Example1: A single brute force configuration is applied universally to all login
872878
"sourceBasedProtectionDetectionPeriod" : 3600
873879
}
874880
]
875-
}
876-
}
877881
```
878882

879883
Example2: Different brute force configurations can be defined for individual login pages,
880884
with each configuration referencing a specific login page.
881885
```json
882-
{
883-
"policy": {
884-
"name": "BruteForcePolicySpec",
885-
"template": {
886-
"name": "POLICY_TEMPLATE_NGINX_BASE"
887-
},
888-
"applicationLanguage": "utf-8",
889-
"enforcementMode": "blocking",
890886
"brute-force-attack-preventions" : [
891887
{
892888
"bruteForceProtectionForAllLoginPages" : false,
@@ -906,13 +902,71 @@ Example2: Different brute force configurations can be defined for individual log
906902
"method": "*",
907903
"name": "/html_login",
908904
"protocol": "http"
909-
}
905+
}
910906
}
911-
],
907+
]
908+
```
912909

913-
}
910+
The following example adds all three of the pieces for a complete example policy.
911+
```json
912+
{
913+
"policy": {
914+
"name": "BruteForcePolicy",
915+
"template": {
916+
"name": "POLICY_TEMPLATE_NGINX_BASE"
917+
},
918+
"applicationLanguage": "utf-8",
919+
"enforcementMode": "blocking",
920+
"urls": [
921+
{
922+
"method": "*",
923+
"name": "/html_login",
924+
"protocol": "http",
925+
"type": "explicit"
926+
}
927+
],
928+
"login-pages": [
929+
{
930+
"accessValidation": {
931+
"responseContains": "Success"
932+
},
933+
"authenticationType": "form",
934+
"url": {
935+
"method": "*",
936+
"name": "/html_login",
937+
"protocol": "http",
938+
"type": "explicit"
939+
},
940+
"usernameParameterName": "username",
941+
"passwordParameterName": "password"
942+
}
943+
],
944+
"brute-force-attack-preventions": [
945+
{
946+
"bruteForceProtectionForAllLoginPages": false,
947+
"loginAttemptsFromTheSameIp": {
948+
"action": "alarm",
949+
"enabled": true,
950+
"threshold": 20
951+
},
952+
"loginAttemptsFromTheSameUser": {
953+
"action": "alarm",
954+
"enabled": true,
955+
"threshold": 3
956+
},
957+
"reEnableLoginAfter": 3600,
958+
"sourceBasedProtectionDetectionPeriod": 3600,
959+
"url": {
960+
"method": "*",
961+
"name": "/html_login",
962+
"protocol": "http"
963+
}
964+
}
965+
]
966+
}
914967
}
915968
```
969+
916970
{{< 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 >}}
917971

918972
## Custom Dimensions Log Entries

0 commit comments

Comments
 (0)