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