diff --git a/content/includes/nap-waf/config/common/ip-groups-override-rules.md b/content/includes/nap-waf/config/common/ip-groups-override-rules.md
new file mode 100644
index 000000000..3ec4d47a1
--- /dev/null
+++ b/content/includes/nap-waf/config/common/ip-groups-override-rules.md
@@ -0,0 +1,70 @@
+#### IP-Groups feature as part of Override Rules feature.
+
+The Override Rules feature allows you to modify original or parent policy settings.
+
+Rules are defined using specific conditions, which can include an IP group based on the declarative policy JSON schema.
+
+When triggered, the rule is applied to the _clientIp_ attribute using the _matches_ function.
+
+'clientIp.matches(ipAddressLists["standalone"])'
+
+Here is a policy example:
+
+```json
+{
+ "policy": {
+ "name": "ip_group_override_rule",
+ "template": {
+ "name": "POLICY_TEMPLATE_NGINX_BASE"
+ },
+ "applicationLanguage": "utf-8",
+ "caseInsensitive": false,
+ "enforcementMode": "blocking",
+ "ip-address-lists": [
+ {
+ "name": "standalone",
+ "description": "This is my list of IP addresses",
+ "ipAddresses": [
+ {
+ "ipAddress": "6.5.3.3/32"
+ },
+ {
+ "ipAddress": "6.5.4.2"
+ }
+ ]
+ }
+ ],
+ "override-rules": [
+ {
+ "name": "myFirstRule",
+ "condition": "clientIp.matches(ipAddressLists['standalone'])",
+ "actionType": "violation",
+ "violation": {
+ "block": true,
+ "alarm": true,
+ "attackType": {
+ "name": "Forceful Browsing"
+ },
+ "description": "Attempt to access from clientIp",
+ "rating": 4
+ }
+ }
+ ],
+ }
+}
+```
+
+The previous example policy contains an IP group with the name "standalone", used for the override rule condition "clientIp.matches(ipAddressLists['standalone'])".
+The condition means that the rule enforcement is applied when clientIp is matched to one of ipAddresses in ipAddressList with name "standalone".
+The value used for the override condition must exist and exactly match the name in "ip-address-lists".
+
+#### Possible errors
+
+| Error text | Input | Explanation |
+| -----------| ------------- | ------------ |
+| _Invalid field invalidList_ | _clientIp.matches(invalidList['standalone']);_ | An incorrect keyword was used instead of _ipAddressLists_ |
+| _Invalid value empty string_ | _clientIp.matches(ipAddressLists['']_ | An empty name was provided |
+| _Failed to compile policy - 'ipGroupOverridePolicy'_ | _uri.matches(ipAddressLists['standalone']);_ | Used _ipAddressLists_ without the _clientIP_ attribute |
+
+
+
diff --git a/content/includes/nap-waf/config/common/ip-groups-overview.md b/content/includes/nap-waf/config/common/ip-groups-overview.md
new file mode 100644
index 000000000..635cd4c67
--- /dev/null
+++ b/content/includes/nap-waf/config/common/ip-groups-overview.md
@@ -0,0 +1,86 @@
+IP groups is a feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.
+
+This allows you to control unique policy settings for incoming requests based on specific IP addresses.
+
+Each IP Group contains a unique name, enforcement type (_always_, _never_ and _policy-default_), and list of IP addresses.
+
+
+An example of a declarative policy using IP Groups configuration:
+
+```json
+{
+ "policy": {
+ "name": "IpGroups_policy",
+ "template": {
+ "name": "POLICY_TEMPLATE_NGINX_BASE"
+ },
+ "applicationLanguage": "utf-8",
+ "caseInsensitive": false,
+ "enforcementMode": "blocking",
+ "ip-address-lists": [
+ {
+ "name": "Standalone",
+ "description": "Optional Description",
+ "blockRequests": "policy-default",
+ "setGeolocation": "IN",
+ "ipAddresses": [
+ {
+ "ipAddress": "1.2.3.4/32"
+ },
+ {
+ "ipAddress": "1111:fc00:0:112::2"
+ }
+ ]
+ }
+ ]
+ }
+}
+
+```
+The example with IP-Group definition in external file external_ip_groups.json:
+
+```json
+{
+ "policy": {
+ "name": "IpGroups_policy2",
+ "template": {
+ "name": "POLICY_TEMPLATE_NGINX_BASE"
+ },
+ "applicationLanguage": "utf-8",
+ "caseInsensitive": false,
+ "enforcementMode": "blocking",
+ "ip-address-lists": [
+ {
+ "name": "external_ip_groups",
+ "description": "Optional Description",
+ "blockRequests": "always",
+ "setGeolocation": "IL",
+ "ipAddresses": [
+ {
+ "ipAddress": "31.8.194.27"
+ }
+ ],
+ "$ref": "file:///tmp/policy/external_ip_groups.json"
+ }
+ ]
+ }
+}
+```
+Example of the file external_ip_groups.json
+
+```json
+{
+ "name": "External Ip Groups List",
+ "description": "Optional Description",
+ "blockRequests": "always",
+ "setGeolocation": "IR",
+ "ipAddresses": [
+ {
+ "ipAddress": "66.51.41.21"
+ },
+ {
+ "ipAddress": "66.52.42.22"
+ }
+ ]
+}
+```
diff --git a/content/nap-waf/v4/configuration-guide/configuration.md b/content/nap-waf/v4/configuration-guide/configuration.md
index 025870d05..1514a31bf 100644
--- a/content/nap-waf/v4/configuration-guide/configuration.md
+++ b/content/nap-waf/v4/configuration-guide/configuration.md
@@ -39,6 +39,7 @@ When configuring NGINX App Protect WAF, `app_protect_enable` should always be en
|[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.|}
+|[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" >}}
@@ -478,6 +479,15 @@ For the full reference of Override Rules condition syntax and usage see the NGIN
{{< include "nap-waf/config/common/geolocation-override-rules.md" >}}
+## IP Groups
+
+### Overview
+
+{{< include "nap-waf/config/common/ip-groups-overview.md" >}}
+
+### IP Groups in Policy Override Rules Conditions
+
+{{< include "nap-waf/config/common/ip-groups-override-rules.md" >}}
## JSON Web Token Protection
@@ -660,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
+
+```json
+"urls": [
+ {
+ "method": "*",
+ "name": "/html_login",
+ "protocol": "http",
+ "type": "explicit"
+ }
+ ],
+```
-### Login page policy example
+### Login page 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
@@ -690,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 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,
@@ -719,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,
@@ -753,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
diff --git a/content/nap-waf/v5/configuration-guide/configuration.md b/content/nap-waf/v5/configuration-guide/configuration.md
index a17322367..80d5dfe7c 100644
--- a/content/nap-waf/v5/configuration-guide/configuration.md
+++ b/content/nap-waf/v5/configuration-guide/configuration.md
@@ -475,6 +475,16 @@ For the full reference of Override Rules condition syntax and usage see the NGIN
{{< include "nap-waf/config/common/geolocation-override-rules.md" >}}
+## IP Groups
+
+### Overview
+
+{{< include "nap-waf/config/common/ip-groups-overview.md" >}}
+
+### IP Groups in Policy Override Rules Conditions
+
+{{< include "nap-waf/config/common/ip-groups-override-rules.md" >}}
+
## JSON Web Token Protection
### Overview
@@ -798,12 +808,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
+
+```json
+"urls": [
+ {
+ "method": "*",
+ "name": "/html_login",
+ "protocol": "http",
+ "type": "explicit"
+ }
+ ],
+```
-### Login page policy example
+### Login page 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
@@ -829,18 +850,10 @@ A login page specifies the login URL that users must pass through to get authent
---
-### Brute force policy example
+### Brute force 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,
@@ -858,21 +871,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,
@@ -892,13 +895,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