NGINX App Protect 5.7 / 4.15 Release

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 |
+
+
+

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"
+      }
+    ]
+}
+```

content/includes/nap-waf/config/common/ip-intelligence-conf.md

@@ -0,0 +1,119 @@
+
+
+
+As of NAP version 4.15.0 (for NAP V4 deployments), and NAP version 5.7.0 (for NAP V5 deployments), NGINX App Protect WAF includes a new feature named IP Intelligence. This features allows customizing the enforcement based on the source IP of the request to limit access from IP addresses with questionable reputation. Please note that:
+- The IP intelligence feature is **disabled** by default and needs to be explicitly enabled and configured in the policy.
+- The package `app-protect-ip-intelligence` must be installed (for NAP V4 deployments), or the IP Intelligence image deployed (for NAP V5 deployments), before configuring and using the feature. This package installs the client that downloads and updates the database required for enforcing IP Intelligence.
+
+After installing the package or image, enable the feature in the following two places in the policy:
+1. By enabling the corresponding violation in the violation list: `"name": "VIOL_MALICIOUS_IP"` and assigning the appropriate `block` and `alarm` values to the violation.
+
+2. By enabling the featue in the corresponding IP Intelligence JSON section: `"ip-intelligence": {"enabled": true}` and define actions for the IP Intelligence categories listed below.
+
+An example policy where both elements are enabled, and all the IP intelligence categories are configured to `block` and `alarm` can be found here:
+
+```json
+{
+    "policy": {
+        "name": "ip_intelligency_policy",
+        "template": {
+            "name": "POLICY_TEMPLATE_NGINX_BASE"
+        },
+        "applicationLanguage": "utf-8",
+        "caseInsensitive": false,
+        "enforcementMode": "blocking",
+        "blocking-settings": {
+            "violations": [
+                {
+                    "name": "VIOL_MALICIOUS_IP",
+                    "alarm": true,
+                    "block": true
+                }
+            ]
+        },
+        "ip-intelligence": {
+            "enabled": true,
+            "ipIntelligenceCategories": [
+                {
+                    "category": "Anonymous Proxy",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "BotNets",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Cloud-based Services",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Denial of Service",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Infected Sources",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Mobile Threats",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Phishing Proxies",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Scanners",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Spam Sources",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Tor Proxies",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Web Attacks",
+                    "alarm": true,
+                    "block": true
+                },
+                {
+                    "category": "Windows Exploits",
+                    "alarm": true,
+                    "block": true
+                }
+            ]
+        }
+    }
+}
+```
+
+This policy will basically block `"block": true` all IP addresses that are part of any threat category and add a log entry `"alarm": true` for the transaction.
+
+The IP address database is managed by an external provider and is constantly updated (every 1 minute by default). The database also categorizes IP addresses into one or more threat categories. These are the same categories that can be configured individually in the IP intelligence section:
+- Anonymous Proxy
+- BotNets
+- Cloud-based Services
+- Denial of Service
+- Infected Sources
+- Mobile Threats
+- Phishing Proxies
+- Scanners
+- Spam Sources
+- Tor Proxies
+- Web Attacks
+- Windows Exploits
+
+Note that since the IP address database is constantly updated, IP address enforcement is also expected to change. IP Addresses may be added, removed, or moved from one category to another based on the reported activity of the IP address.

content/includes/nap-waf/ip-intelligence.md

@@ -0,0 +1,67 @@
+If the deployment intends to use the IP intelligence Feature (avaiable from version 5.7.0), then the IP intelligence container needs to be added to the deployment in the docker compose file.
+
+Modify the original `docker-compose.yml` file to include the additional IP Intelligence container:
+
+```yaml
+services:
+  waf-enforcer:
+    container_name: waf-enforcer
+    image: private-registry.nginx.com/nap/waf-enforcer:5.7.0
+    environment:
+      - ENFORCER_PORT=50000
+    ports:
+      - "50000:50000"
+    volumes:
+      - /opt/app_protect/bd_config:/opt/app_protect/bd_config
+      - /var/IpRep:/var/IpRep
+    networks:
+      - waf_network
+    restart: always
+    user: "101:101"
+    depends_on:
+      - waf-ip-intelligence
+
+  waf-config-mgr:
+    container_name: waf-config-mgr
+    image: private-registry.nginx.com/nap/waf-config-mgr:5.7.0
+    volumes:
+      - /opt/app_protect/bd_config:/opt/app_protect/bd_config
+      - /opt/app_protect/config:/opt/app_protect/config
+      - /etc/app_protect/conf:/etc/app_protect/conf
+    restart: always
+    user: "101:101"
+    network_mode: none
+    depends_on:
+      waf-enforcer:
+        condition: service_started
+
+  waf-ip-intelligence:
+    container_name: waf-ip-intelligence
+    image: private-registry.nginx.com/nap/waf-ip-intelligence:5.7.0
+    volumes:
+      - /var/IpRep:/var/IpRep
+    networks:
+      - waf_network
+    restart: always
+    user: "101:101"
+
+networks:
+  waf_network:
+    driver: bridge
+```
+
+Notes:
+- Replace `waf-config-mgr`, `waf-enforcer` and `waf-ip-intelligence` tags with the actual release version tag you are deploying. We are using version 5.7.0 for this example deployment.
+- By default, the containers `waf-config-mgr`, `waf-enforcer` and `waf-ip-intelligence` operate with the user and group IDs set to 101:101. Ensure that the folders and files are accessible to these IDs.
+
+Before creating the deployment in docker compose, create the required directories:
+
+```shell
+sudo mkdir -p /opt/app_protect/config /opt/app_protect/bd_config /var/IpRep
+```
+
+Then set correct ownership:
+
+```shell
+sudo chown -R 101:101 /opt/app_protect/ /var/IpRep
+```