NGINX App Protect WAF refactor

.github/CODEOWNERS

@@ -22,7 +22,7 @@
 # NGINX Agent
 content/nginx/nms/agent/*   @nginx/nginx-agent 
 
-# NGINX App Protect DoS
+# F5 DoS for NGINX
 content/nap-dos/*           @nginx/dos-docs-approvers
 
 # NGINX App Protect WAF

_banners/waf-oss-usage.md

@@ -0,0 +1,7 @@
+{{< banner "warning" "NGINX Open Source availability" >}}
+
+The guidance in this section is **only** applicable to F5 WAF for NGINX v5.
+
+For NGINX v4, you must use an [NGINX Plus]({{< ref "/waf/install/plus" >}}) deployment.
+
+{{< /banner >}}

cloudcannon.config.yml

@@ -88,8 +88,8 @@ collections_config:
   nap_dos:
     path: content/nap-dos
     output: true
-    name: NGINX App Protect DoS
-    description: Documentation for NGINX App Protect DoS
+    name: F5 DoS for NGINX
+    description: Documentation for F5 DoS for NGINX
     parse_branch_index: false
     icon: notes
     preview:

content/includes/nic/configuration/security.md

@@ -34,7 +34,7 @@ By default, the ServiceAccount has access to all Secret resources in the cluster
 ### Configure root filesystem as read-only
 
 {{< call-out "caution"  >}}
- This feature is compatible with [NGINX App Protect WAFv5](https://docs.nginx.com/nginx-app-protect-waf/v5/). It is not compatible with [NGINX App Protect WAFv4](https://docs.nginx.com/nginx-app-protect-waf/v4/) or [NGINX App Protect DoS](https://docs.nginx.com/nginx-app-protect-dos/).
+ This feature is compatible with [NGINX App Protect WAFv5](https://docs.nginx.com/nginx-app-protect-waf/v5/). It is not compatible with [NGINX App Protect WAFv4](https://docs.nginx.com/nginx-app-protect-waf/v4/) or [F5 DoS for NGINX](https://docs.nginx.com/nginx-app-protect-dos/).
 {{< /call-out >}}
 
 NGINX Ingress Controller is designed to be resilient against attacks in various ways, such as running the service as non-root to avoid changes to files. We recommend setting filesystems on all containers to read-only, this includes `nginx-ingress-controller`, though also includes `waf-enforcer` and `waf-config-mgr` when NGINX App Protect WAFv5 is in use.  This is so that the attack surface is further reduced by limiting changes to binaries and libraries.

content/includes/nic/rbac/set-up-rbac.md

@@ -18,15 +18,15 @@ nd-docs: DOCS-1468
 
 <br>
 
-If you're planning to use NGINX App Protect or NGINX App Protect DoS, additional roles and bindings are needed.
+If you're planning to use NGINX App Protect or F5 DoS for NGINX, additional roles and bindings are needed.
 
 1. (NGINX App Protect only) Create the *App Protect* role and binding:
 
     ```shell
     kubectl apply -f deployments/rbac/ap-rbac.yaml
     ```
 
-2. (NGINX App Protect DoS only) Create the *App Protect DoS* role and binding:
+2. (F5 DoS for NGINX only) Create the *App Protect DoS* role and binding:
 
     ```shell
     kubectl apply -f deployments/rbac/apdos-rbac.yaml

content/includes/waf/install-next-steps.md

@@ -0,0 +1,10 @@
+---
+nd-docs:
+---
+
+Once you have successfully installed F5 WAF for NGINX, there are some topics you may want to follow afterwards:
+
+- [Configure policies]({{< ref "/waf/policies/configuration.md" >}}), to begin customizing your deployment
+- [IP intelligence]({{< ref "/waf/policies/ip-intelligence.md">}}), for the extra steps to enable the IP intelligence feature
+- [Converter tools]({{< ref "/waf/tools/converters.md" >}}), to convert existing resources from a BIG-IP environment
+- [Changelog]({{< ref "/waf/changelog.md" >}}), to view information from the latest releases

content/includes/waf/install-post-checks.md

@@ -0,0 +1,61 @@
+---
+nd-docs:
+---
+
+Use the following steps to ensure that F5 WAF for NGINX enforcement is operational.
+
+Check that the three processes for F5 WAF for NGINX are running using `ps aux`:
+
+- _bd-socket-plugin_
+- _nginx: master process_
+- _nginx: worker process_
+
+```shell
+USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
+root         8  1.3  2.4 3486948 399092 ?      Sl   09:11   0:02 /usr/share/ts/bin/bd-socket-plugin tmm_count 4 proc_cpuinfo_cpu_mhz 2000000 total_xml_memory 307200000 total_umu_max_size 3129344 sys_max_account_id 1024 no_static_config
+root        14  0.0  0.1  71060 26680 ?        S    09:11   0:00 nginx: master process /usr/sbin/nginx -c /tmp/policy/test_nginx.conf -g daemon off;
+root        26  0.0  0.3  99236 52092 ?        S    09:12   0:00 nginx: worker process
+root        28  0.0  0.0  11788  2920 pts/0    Ss   09:12   0:00 bash
+root        43  0.0  0.0  47460  3412 pts/0    R+   09:14   0:00 ps aux
+```
+
+Verify there are no errors in the file `/var/log/nginx/error.log` and that the policy compiled successfully:
+
+```none
+2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_start", "configSetFile": "/opt/f5waf/config/config_set.json" }
+2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT policy 'app_protect_default_policy' from: /etc/app_protect/conf/NginxDefaultPolicy.json compiled successfully
+2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_success", "software_version": "1.1.1", "attack_signatures_package":{"revision_datetime":"2019-07-16T12:21:31Z"},"completed_successfully":true}
+2020/05/10 13:21:04 [notice] 402#402: using the "epoll" event method
+2020/05/10 13:21:04 [notice] 402#402: nginx/1.17.6 (nginx-plus-r20)
+2020/05/10 13:21:04 [notice] 402#402: built by gcc 4.8.5 20150623 (Red Hat 4.8.5-36) (GCC)
+2020/05/10 13:21:04 [notice] 402#402: OS: Linux 3.10.0-957.27.2.el7.x86_64
+2020/05/10 13:21:04 [notice] 402#402: getrlimit(RLIMIT_NOFILE): 1048576:1048576
+2020/05/10 13:21:04 [notice] 406#406: start worker processes
+2020/05/10 13:21:04 [notice] 406#406: start worker process 407
+```
+
+Check that sending an attack signature in a request returns a response block page containing a support ID:
+
+```shell
+Request:
+http://10.240.185.211/?a=<script>
+
+Response:
+The requested URL was rejected. Please consult with your administrator.
+
+Your support ID is: 9847191526422998597
+
+[Go Back]
+```
+
+If your policy includes JSON/XML profiles, check `/var/log/app_protect/bd-socket-plugin.log` for possible errors:
+
+```shell
+grep '|ERR' /var/log/app_protect/bd-socket-plugin.log
+```
+
+Verify that Enforcement functionality is working by checking the following request is rejected:
+
+```shell
+curl "localhost/<script>"
+```

content/includes/waf/install-services-compose.md

@@ -0,0 +1,54 @@
+---
+nd-docs:
+---
+
+Create a _docker-compose.yml_ file with the following contents in your host environment, replacing image tags as appropriate:
+
+```yaml
+services:
+  waf-enforcer:
+    container_name: waf-enforcer
+    image: waf-enforcer:5.2.0
+    environment:
+      - ENFORCER_PORT=50000
+    ports:
+      - "50000:50000"
+    volumes:
+      - /opt/app_protect/bd_config:/opt/app_protect/bd_config
+    networks:
+      - waf_network
+    restart: always
+
+  waf-config-mgr:
+    container_name: waf-config-mgr
+    image: waf-config-mgr:5.2.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
+    network_mode: none
+    depends_on:
+      waf-enforcer:
+        condition: service_started
+
+networks:
+  waf_network:
+    driver: bridge
+```
+
+{{< call-out "caution" >}}
+
+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 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 this is inadvisable for prolonged use.
+
+{{< /call-out >}}
+
+To start the F5 WAF for NGINX services, use `docker compose up` in the same folder as the _docker-compose.yml_ file:
+
+```shell
+sudo docker compose up -d
+```

content/includes/waf/install-services-docker.md

@@ -0,0 +1,25 @@
+---
+nd-docs:
+---
+
+{{< call-out "warning" >}}
+
+This section **only** applies to V5 packages. 
+
+Skip to [Post-installation checks](#post-installation-checks) if you're using a V4 package.
+
+{{< /call-out>}}
+
+F5 WAF for NGINX uses Docker containers for its services when installed with a V5 package, which requires some extra set-up steps.
+
+First, create new directories for the services:
+
+```shell
+sudo mkdir -p /opt/app_protect/config /opt/app_protect/bd_config
+```
+
+Then assign new owners, with `101:101` as the default UID/GID
+
+```shell
+sudo chown -R 101:101 /opt/app_protect/
+```

content/includes/waf/install-services-images.md

@@ -0,0 +1,12 @@
+---
+nd-docs:
+---
+
+Download the `waf-enforcer` and `waf-config-mgr` images. 
+
+Replace `5.2.0` with the release version you are deploying.
+
+```shell
+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
+```

content/includes/waf/install-services-registry.md

@@ -0,0 +1,11 @@
+---
+nd-docs:
+---
+
+Create a directory and copy your certificate and key to this directory:
+
+```shell
+mkdir -p /etc/docker/certs.d/private-registry.nginx.com
+cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
+cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
+```

content/includes/waf/install-update-configuration.md

@@ -0,0 +1,127 @@
+---
+nd-docs:
+---
+
+Once you have installed F5 WAF for NGINX, you must load it as a module in the main context of your NGINX configuration.
+
+```nginx
+load_module modules/ngx_http_app_protect_module.so;
+```
+
+The Enforcer address must be added at the _http_ context:
+
+```nginx
+app_protect_enforcer_address 127.0.0.1:50000;
+```
+
+And finally, F5 WAF for NGINX can enabled on a _http_, _server_ or _location_ context:
+
+```nginx
+app_protect_enable on;
+```
+
+{{< call-out "warning" >}}
+
+You should only enable F5 WAF for NGINX on _proxy_pass_ and _grpc_pass_ locations.
+
+{{< /call-out >}}
+
+Here are two examples of how these additions could look in configuration files:
+
+{{<tabs name="example-configuration-files">}}
+
+{{% tab name="nginx.conf" %}}
+
+`/etc/nginx/nginx.conf`
+
+```nginx
+user  nginx;
+worker_processes  auto;
+
+# NGINX App Protect WAF
+load_module modules/ngx_http_app_protect_module.so;
+
+error_log  /var/log/nginx/error.log notice;
+pid        /var/run/nginx.pid;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log  /var/log/nginx/access.log  main;
+
+    sendfile        on;
+    #tcp_nopush     on;
+
+    keepalive_timeout  65;
+
+    #gzip  on;
+
+    # NGINX App Protect WAF
+    app_protect_enforcer_address 127.0.0.1:50000;
+
+    include /etc/nginx/conf.d/*.conf;
+}
+```
+
+
+{{% /tab %}}
+
+{{% tab name="default.conf" %}}
+
+`/etc/nginx/conf.d/default.conf`
+
+```nginx
+server {
+    listen 80;
+    server_name domain.com;
+
+    proxy_http_version 1.1;
+
+    location / {
+
+        # NGINX App Protect WAF
+        app_protect_enable on;
+
+        client_max_body_size 0;
+        default_type text/html;
+        proxy_pass http://127.0.0.1:8080/;
+    }
+}
+
+server {
+    listen 8080;
+    server_name localhost;
+
+    location / {
+        root /usr/share/nginx/html;
+        index index.html index.htm;
+    }
+
+    # redirect server error pages to the static page /50x.html
+    #
+    error_page 500 502 503 504 /50x.html;
+    location = /50x.html {
+        root /usr/share/nginx/html;
+    }
+}
+```
+
+{{% /tab %}}
+
+{{< /tabs >}}
+
+Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment:
+
+- `nginx -s reload`
+- `sudo systemctl reload nginx`
+
+If you are using a V4 package, you have finished installing F5 WAF for NGINX and can look at [Post-installation checks](#post-installation-checks).