feat: add IP intelligence (new) (#622)

Author: mouraddmeiri

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

@@ -2,11 +2,11 @@
 
 
 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` needs to 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.
+- 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 required `block` and `alarm` values to the violation.
+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.
 
@@ -99,6 +99,7 @@ An example policy where both elements are enabled, and all the IP intelligence c
     }
 }
 ```
+
 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:

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

content/nap-waf/v4/admin-guide/install.md

@@ -1079,7 +1079,7 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \
 # Only use if you want to install and use the IP intelligence feature:
 RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \
     --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \
-    apk update && apk app-protect-ip-intelligence
+    apk update && apk add app-protect-ip-intelligence
 
 # Forward request logs to Docker log collector:
 RUN ln -sf /dev/stdout /var/log/nginx/access.log \
@@ -1743,7 +1743,7 @@ On a host with access to the NGINX App Protect WAF repository:
     yum install --downloadonly --downloaddir=/etc/packages/ app-protect
     ```
 
-Only use if you want to install and use the IP intelligence feature:
+    Only use if you want to install and use the IP intelligence feature:
 
     ```shell
     yum install --downloadonly --downloaddir=/etc/packages/ app-protect-ip-intelligence
@@ -1777,7 +1777,7 @@ On an offline host:
     yum -y install app-protect
     ```
 
-Only use if you want to install and use the IP intelligence feature:
+    Only use if you want to install and use the IP intelligence feature:
 
     ```shell
     yum -y install app-protect-ip-intelligence
@@ -1797,7 +1797,8 @@ On a host with access to the NGINX App Protect WAF repository:
     apt-get update
     for i in $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances app-protect | grep "^\w" | sort -u); do apt-get download $i 2>>errors.txt; done
     ```
-Only use if you want to install and use the IP intelligence feature:
+    
+    Only use if you want to install and use the IP intelligence feature:
 
     ```shell
     cd /etc/packages/
@@ -1818,7 +1819,8 @@ On an offline host:
     apt-get update
     apt-get install -y app-protect
     ```
-Only use if you want to install and use the IP intelligence feature:
+    
+    Only use if you want to install and use the IP intelligence feature:
 
     ```shell
     apt-get install -y app-protect-ip-intelligence

content/nap-waf/v5/admin-guide/deploy-on-docker.md

@@ -346,6 +346,11 @@ volumes:
 ```
 
 
+### Docker Compose File with IP Intelligence
+
+{{< include "nap-waf/ip-intelligence.md" >}}
+
+
 ### Docker Compose File with mTLS
 
 To secure traffic between NGINX and App Protect Enforcer using mTLS, create a `docker-compose.yml` with the following configuration:
@@ -665,6 +670,11 @@ volumes:
   app_protect_config:
   app_protect_etc_config:
 ```
+
+#### Docker Compose File with IP Intelligence
+
+{{< include "nap-waf/ip-intelligence.md" >}}
+
 ### Start Deployment
 
 1. To start the NGINX and WAF services, navigate to the directory that contains the `docker-compose.yml` file and run:

content/nap-waf/v5/admin-guide/install.md

@@ -294,6 +294,10 @@ networks:
 In some operating systems, security mechanisms like **SELinux** or **AppArmor** are enabled by default, potentially blocking necessary file access for the `nginx` process and `waf-config-mgr` and `waf-enforcer` containers. To ensure NGINX App Protect WAF v5 operates smoothly without compromising security, consider setting up a custom SELinux policy or AppArmor profile. For short-term troubleshooting, you may use `permissive` (SELinux) or `complain` (AppArmor) mode to avoid these restrictions, but keep in mind that this lowers security and isn't advised for prolonged use.
 {{< /note >}}
 
+### Docker Compose File with IP Intelligence
+
+{{< include "nap-waf/ip-intelligence.md" >}}
+
 ## Start the Deployment
 
 1. To start the WAF services, navigate to the directory that contains the `docker-compose.yml` file and run:
@@ -897,18 +901,25 @@ docker pull private-registry.nginx.com/nap/waf-enforcer:5.2.0
 docker pull private-registry.nginx.com/nap/waf-config-mgr:5.2.0
 ```
 
+If IP Intelligence feature is to be used on the deployment, download the `waf-ip-intelligence` as well:
+
+```shell
+docker pull private-registry.nginx.com/nap/waf-ip-intelligence:5.2.0
+```
+
 #### Saving and Transferring Images
 
-1. Save the `waf-enforcer` docker image:
+1. Save the `waf-enforcer` and `waf-config-mgr` docker images:
 
     ```shell
     docker save -o waf-enforcer.tar waf-enforcer:5.2.0
+    docker save -o waf-config-mgr.tar waf-config-mgr:5.2.0
     ```
 
-2. Save the `waf-config-mgr` docker image:
+2. If IP Intelligence feature is to be used on the deployment, save the `waf-ip-intelligence` docker image:
 
     ```shell
-    docker save -o waf-config-mgr.tar waf-config-mgr:5.2.0
+    docker save -o waf-ip-intelligence.tar waf-ip-intelligence:5.2.0
     ```
 
 3. Transfer the tar files from the online machine to the offline/air-gapped machine:
@@ -920,6 +931,12 @@ docker pull private-registry.nginx.com/nap/waf-config-mgr:5.2.0
     docker load -i waf-config-mgr.tar
     ```
 
+5. If IP Intelligence feature is to be used on the deployment, on the offline machine load the docker images:
+
+    ```shell
+    docker load -i waf-ip-intelligence.tar
+    ```
+
 #### Docker Compose File
 
 Create a `docker-compose.yml` with the following configuration on the offline machine:
@@ -963,6 +980,10 @@ networks:
 In some operating systems, security mechanisms like **SELinux** or **AppArmor** are enabled by default, potentially blocking necessary file access for the `nginx` process and `waf-config-mgr` and `waf-enforcer` containers. To ensure NGINX App Protect WAF v5 operates smoothly without compromising security, consider setting up a custom SELinux policy or AppArmor profile. For short-term troubleshooting, you may use `permissive` (SELinux) or `complain` (AppArmor) mode to avoid these restrictions, but keep in mind that this lowers security and isn't advised for prolonged use.
 {{< /note >}}
 
+#### Docker Compose File with IP Intelligence
+
+{{< include "nap-waf/ip-intelligence.md" >}}
+
 ### Start the Deployment
 
 1. To start the WAF services, navigate to the directory that contains the `docker-compose.yml` file and run: