From 562683e811e7e4086c97be92e8de5ba2e77b6e10 Mon Sep 17 00:00:00 2001 From: Travis Martin <33876974+travisamartin@users.noreply.github.com> Date: Fri, 7 Nov 2025 10:09:23 -0800 Subject: [PATCH] Internal/nim release 2.21.0 (#272) * updated docs for bot signatures * edits from tech review * Reorganized the NIM WAF docs * moved files to subdirs and fixed links * Renamed NGINX App Protect to F5 WAF for NGINX in the NIM docs * made separate topics for security policies and fixed links * broke up the manage waf security policies doc into separate topics * deleted manage-waf-security-policies.md file * cleaned up waf policy doc titles * created include for F5 WAF compiler compatibility * edits to waf compiler heading levels * updates to NIM WAF docs * changed weight of Add signature sets and exceptions * edits to NIM WAF front matter * edits to NAP WAF topic titles * edits * fixes URL in front-matter metadata * edits * edits * Deleted file that was inadvertently added * edits * edits per tech review * edits * edits * edits * added release notes and known issues for NIM 2.21.0. * edits * edits * edits to NIM WAF version requirements * edits * edits per tech review * fixed url path in nim index files * edit per tech review * fixed bullet indenting * added known issue for 46754 * changed bash codeblocks to shell * fixed broken links * fixed url path for security monitoring * bumped NIM NAP WAF support table for 2.21.0 * fixed link * added release note for 46726 --- .../agent/installation/install-agent-api.md | 2 +- .../auth/basic-auth-api-requests.md | 4 +- .../set-mode-of-operation-disconnected.md | 2 +- .../nim/docker/docker-registry-login.md | 2 +- .../includes/nim/how-to-access-api-docs.md | 8 +- content/includes/nim/how-to-access-nim-api.md | 4 +- .../nim/kubernetes/access-webui-helm.md | 2 +- ...ty-monitoring-attack-signature-database.md | 26 + .../trust-proxy-ca-certificates.md | 2 +- .../nim/tech-specs/nim-app-protect-support.md | 13 +- .../includes/nim/uninstall/uninstall-nim.md | 4 +- .../nim/waf/nim-waf-before-you-begin.md | 22 + .../restart-nms-integrations.md | 2 +- .../includes/nim/waf/upload-cert-and-key.md | 80 + ...f5-waf-for-nginx-compiler-compatibility.md | 31 + content/nginx-one/_index.md | 2 +- content/nginx-one/changelog.md | 15 +- .../_index.md | 0 .../add-signature-sets.md | 4 +- .../configure-policy.md | 0 .../cookies-params-urls.md | 19 +- .../deploy-policy.md | 0 .../overview.md | 8 +- .../review-policy.md | 0 .../security-policy-api.md | 0 .../waf-policy-matching-types.md | 0 .../compile-waf-policies.md | 4 +- content/nic/releases.md | 2 +- .../nim/admin-guide/authentication/_index.md | 2 +- .../authentication/oidc/keycloak-setup.md | 16 +- .../oidc/microsoft-entra-automation.md | 4 +- .../maintenance/sqlite-installation.md | 8 +- content/nim/admin-guide/rbac/_index.md | 2 +- .../rbac/manage-resource-groups.md | 6 +- ...y-nginx-instance-manager-docker-compose.md | 4 +- content/nim/deploy/vm-bare-metal/install.md | 14 +- .../add-license-disconnected-deployment.md | 20 +- .../offline-install-guide-manual.md | 18 +- .../report-usage-disconnected-deployment.md | 16 +- content/nim/fundamentals/tech-specs.md | 22 +- .../manage-waf-security-policies.md | 744 ---------- .../security-monitoring/_index.md | 5 - .../security-monitoring/update-signatures.md | 45 - .../setup-waf-config-management.md | 1281 ----------------- content/nim/nginx-instances/add-tags.md | 2 +- .../nginx-instances/manage-certificates.md | 14 +- .../nginx-instances/manage-instance-groups.md | 10 +- content/nim/nginx-instances/scan-instances.md | 6 +- content/nim/releases/known-issues.md | 81 +- content/nim/releases/release-notes.md | 116 +- content/nim/security-monitoring/_index.md | 5 + ...ccess-to-security-monitoring-dashboards.md | 0 .../set-up-app-protect-instances.md | 26 +- .../security-monitoring/troubleshooting.md | 2 +- .../security-monitoring/update-geo-db.md | 6 +- .../security-monitoring/update-signatures.md | 28 + content/nim/support/contact-support.md | 6 +- content/nim/support/k8s-support-package.md | 4 +- content/nim/support/support-package.md | 4 +- .../configure-forward-proxy.md | 6 +- .../system-configuration/configure-gateway.md | 8 +- .../system-configuration/configure-selinux.md | 14 +- .../system-configuration/configure-vault.md | 20 +- content/nim/troubleshooting.md | 12 +- .../_index.md | 2 +- .../waf-integration/configuration/_index.md | 39 + .../compiler-resource-pruning.md | 63 + .../install-waf-compiler/_index.md | 6 + .../automatic-download.md | 50 + .../download-from-myf5.md | 48 + .../install-disconnected.md | 213 +++ .../install-waf-compiler/install.md | 142 ++ .../manage-waf-configurations/_index.md | 8 + .../add-configuration.md | 36 + .../edit-waf-configuration.md | 153 ++ .../onboard-custom-security-policies.md | 63 + .../verify-configuration.md | 29 + .../configuration/onboard-instances/_index.md | 6 + .../configure-docker-compose.md | 79 + .../configure-nginx-agent.md | 57 + .../onboard-instances/install-nginx-agent.md | 24 + .../onboard-instances/verify-installation.md | 82 ++ .../setup-signatures-and-threats/_index.md | 38 + .../automatic-download.md | 50 + .../manual-update.md | 170 +++ ...update-security-monitoring-signature-db.md | 15 + .../configuration/troubleshooting.md | 142 ++ .../overview.md} | 25 +- .../policies-and-logs/_index.md | 65 + .../policies-and-logs/bundles/_index.md | 6 + .../bundles/create-bundle.md | 168 +++ .../bundles/download-bundle.md | 80 + .../policies-and-logs/bundles/list-bundles.md | 118 ++ .../policies-and-logs/log-profiles/_index.md | 6 + .../log-profiles/create-log-profile.md | 69 + .../log-profiles/delete-log-profile.md | 37 + .../log-profiles/update-log-profile.md | 58 + .../policies-and-logs/policies/_index.md | 6 + .../policies/add-signature-sets.md | 127 ++ .../policies/cookies-parameters-urls.md | 182 +++ .../policies/create-policy.md | 137 ++ .../policies/delete-policy.md | 57 + .../policies/review-policy.md | 38 + .../policies/update-policy.md | 75 + .../policies/waf-policy-matching-types.md | 41 + .../policies-and-logs/publish/_index.md | 6 + .../publish/check-publication-status.md | 92 ++ .../publish/publish-to-instances.md | 99 ++ 108 files changed, 3560 insertions(+), 2282 deletions(-) create mode 100644 content/includes/nim/security-monitoring/update-security-monitoring-attack-signature-database.md create mode 100644 content/includes/nim/waf/nim-waf-before-you-begin.md rename content/includes/nim/{nap-waf => waf}/restart-nms-integrations.md (62%) create mode 100644 content/includes/nim/waf/upload-cert-and-key.md create mode 100644 content/includes/waf/f5-waf-for-nginx-compiler-compatibility.md rename content/nginx-one/{nap-integration => waf-integration}/_index.md (100%) rename content/nginx-one/{nap-integration => waf-integration}/add-signature-sets.md (97%) rename content/nginx-one/{nap-integration => waf-integration}/configure-policy.md (100%) rename content/nginx-one/{nap-integration => waf-integration}/cookies-params-urls.md (95%) rename content/nginx-one/{nap-integration => waf-integration}/deploy-policy.md (100%) rename content/nginx-one/{nap-integration => waf-integration}/overview.md (90%) rename content/nginx-one/{nap-integration => waf-integration}/review-policy.md (100%) rename content/nginx-one/{nap-integration => waf-integration}/security-policy-api.md (100%) rename content/nginx-one/{nap-integration => waf-integration}/waf-policy-matching-types.md (100%) delete mode 100644 content/nim/nginx-app-protect/manage-waf-security-policies.md delete mode 100644 content/nim/nginx-app-protect/security-monitoring/_index.md delete mode 100644 content/nim/nginx-app-protect/security-monitoring/update-signatures.md delete mode 100644 content/nim/nginx-app-protect/setup-waf-config-management.md create mode 100644 content/nim/security-monitoring/_index.md rename content/nim/{nginx-app-protect => }/security-monitoring/give-access-to-security-monitoring-dashboards.md (100%) rename content/nim/{nginx-app-protect => }/security-monitoring/set-up-app-protect-instances.md (88%) rename content/nim/{nginx-app-protect => }/security-monitoring/troubleshooting.md (81%) rename content/nim/{nginx-app-protect => }/security-monitoring/update-geo-db.md (92%) create mode 100644 content/nim/security-monitoring/update-signatures.md rename content/nim/{nginx-app-protect => waf-integration}/_index.md (52%) create mode 100644 content/nim/waf-integration/configuration/_index.md create mode 100644 content/nim/waf-integration/configuration/compiler-resource-pruning.md create mode 100644 content/nim/waf-integration/configuration/install-waf-compiler/_index.md create mode 100644 content/nim/waf-integration/configuration/install-waf-compiler/automatic-download.md create mode 100644 content/nim/waf-integration/configuration/install-waf-compiler/download-from-myf5.md create mode 100644 content/nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md create mode 100644 content/nim/waf-integration/configuration/install-waf-compiler/install.md create mode 100644 content/nim/waf-integration/configuration/manage-waf-configurations/_index.md create mode 100644 content/nim/waf-integration/configuration/manage-waf-configurations/add-configuration.md create mode 100644 content/nim/waf-integration/configuration/manage-waf-configurations/edit-waf-configuration.md create mode 100644 content/nim/waf-integration/configuration/manage-waf-configurations/onboard-custom-security-policies.md create mode 100644 content/nim/waf-integration/configuration/manage-waf-configurations/verify-configuration.md create mode 100644 content/nim/waf-integration/configuration/onboard-instances/_index.md create mode 100644 content/nim/waf-integration/configuration/onboard-instances/configure-docker-compose.md create mode 100644 content/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md create mode 100644 content/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md create mode 100644 content/nim/waf-integration/configuration/onboard-instances/verify-installation.md create mode 100644 content/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md create mode 100644 content/nim/waf-integration/configuration/setup-signatures-and-threats/automatic-download.md create mode 100644 content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md create mode 100644 content/nim/waf-integration/configuration/setup-signatures-and-threats/update-security-monitoring-signature-db.md create mode 100644 content/nim/waf-integration/configuration/troubleshooting.md rename content/nim/{nginx-app-protect/overview-nap-waf-config-management.md => waf-integration/overview.md} (70%) create mode 100644 content/nim/waf-integration/policies-and-logs/_index.md create mode 100644 content/nim/waf-integration/policies-and-logs/bundles/_index.md create mode 100644 content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md create mode 100644 content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md create mode 100644 content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md create mode 100644 content/nim/waf-integration/policies-and-logs/log-profiles/_index.md create mode 100644 content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md create mode 100644 content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md create mode 100644 content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/_index.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/cookies-parameters-urls.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/create-policy.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/delete-policy.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/review-policy.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/update-policy.md create mode 100644 content/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md create mode 100644 content/nim/waf-integration/policies-and-logs/publish/_index.md create mode 100644 content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md create mode 100644 content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 4e2909146..4efe97be5 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,7 +1,7 @@ --- nd-docs: DOCS-1031 files: - - content/nim/nginx-app-protect/setup-waf-config-management.md + - content/nim/waf-integration/configuration/setup-waf-config-management.md --- {{< call-out "note" >}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{< /call-out >}} diff --git a/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md b/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md index fd850214f..b24d88392 100644 --- a/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md +++ b/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md @@ -4,13 +4,13 @@ nd-docs: DOCS-1295 To use basic authentication for API requests, include your base64-encoded credentials as a "Basic" token in the "Authorization" header. To create the base64-encoded credentials, run the following command: -```bash +```shell echo -n : | base64 ``` Once you've generated the credentials, you can include them in your API request. Here's how to do it with `curl`: -```bash +```shell curl -X GET "https:///api/platform//systems" -H "Authorization: Basic " ``` diff --git a/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md b/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md index 066afb1b8..809029ed0 100644 --- a/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md +++ b/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md @@ -12,6 +12,6 @@ nd-docs: "DOCS-1663" 2. Restart NGINX Instance Manager: - ``` bash + ```shell sudo systemctl restart nms ``` diff --git a/content/includes/nim/docker/docker-registry-login.md b/content/includes/nim/docker/docker-registry-login.md index 961380426..b5e16a39f 100644 --- a/content/includes/nim/docker/docker-registry-login.md +++ b/content/includes/nim/docker/docker-registry-login.md @@ -12,7 +12,7 @@ nd-docs: "DOCS-1666" 2. Log in to the Docker registry using the contents of the JSON Web Token file: - ```bash + ```shell docker login private-registry.nginx.com --username= --password=none ``` diff --git a/content/includes/nim/how-to-access-api-docs.md b/content/includes/nim/how-to-access-api-docs.md index 4375880e2..cb77766d9 100644 --- a/content/includes/nim/how-to-access-api-docs.md +++ b/content/includes/nim/how-to-access-api-docs.md @@ -2,8 +2,8 @@ nd-docs: DOCS-991 --- -You can access the NGINX Instance Manager API documentation from the web interface: +Access the NGINX Instance Manager API documentation from the web interface: -1. Log in to the FQDN of your NGINX Instance Manager host. -2. Select **API Documentation** from the Launchpad menu. -3. On the left menu, select **NIM and Platform API**. +1. Go to the FQDN of your NGINX Instance Manager host and log in. +2. From the Launchpad menu, select **API Documentation**. +3. In the left menu, choose **NIM and Platform API**. diff --git a/content/includes/nim/how-to-access-nim-api.md b/content/includes/nim/how-to-access-nim-api.md index 66cea5c68..c4426031b 100644 --- a/content/includes/nim/how-to-access-nim-api.md +++ b/content/includes/nim/how-to-access-nim-api.md @@ -2,4 +2,6 @@ nd-docs: DOCS-1050 --- -You can use tools like `curl` or [Postman](https://www.postman.com) to interact with the NGINX Instance Manager REST API. The API URL is `https:///api/[nim|platform]/`, and each request requires authentication. For more details on authentication options, see the [API Overview]({{< ref "/nim/fundamentals/api-overview.md" >}}). +Use tools such as `curl` or [Postman](https://www.postman.com) to send requests to the NGINX Instance Manager REST API. +The API base URL is `https:///api/[nim|platform]/`. +All requests require authentication. For details on authentication methods, see the [API overview]({{< ref "/nim/fundamentals/api-overview.md" >}}). diff --git a/content/includes/nim/kubernetes/access-webui-helm.md b/content/includes/nim/kubernetes/access-webui-helm.md index 76e22288e..b95ec65c7 100644 --- a/content/includes/nim/kubernetes/access-webui-helm.md +++ b/content/includes/nim/kubernetes/access-webui-helm.md @@ -6,7 +6,7 @@ You can access the NGINX Instance Manager web interface using the external IP ad 1. To look up the external IP address for the API Gateway, run the following command: - ```bash + ```shell kubectl -n nim get svc apigw ``` diff --git a/content/includes/nim/security-monitoring/update-security-monitoring-attack-signature-database.md b/content/includes/nim/security-monitoring/update-security-monitoring-attack-signature-database.md new file mode 100644 index 000000000..20002d9c0 --- /dev/null +++ b/content/includes/nim/security-monitoring/update-security-monitoring-attack-signature-database.md @@ -0,0 +1,26 @@ +--- +docs: +files: + - /nim/security-monitoring/update-signatures.md +--- + +1. Open an SSH connection to the data plane host and log in. +1. Generate a Signature Report file using the [Attack Signature Report Tool]({{< ref "/waf/configure/converters.md#attack-signature-report-tool" >}}). Save the file as `signature-report.json`: + + ```shell + sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json + ``` + +1. Open an SSH connection to the management plane host and log in. +1. Copy the `signature-report.json` file to the NGINX Instance Manager control plane at `/usr/share/nms/sigdb/`: + + ```shell + sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json + ``` + +1. Restart the NGINX Instance Manager services to apply the update: + + ```shell + sudo systemctl restart nms-ingestion + sudo systemctl restart nms-core + ``` \ No newline at end of file diff --git a/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md b/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md index 9113bd901..88bdd7bce 100644 --- a/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md +++ b/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md @@ -6,7 +6,7 @@ - **Debian/Ubuntu**: - ```bash + ```shell sudo update-ca-certificates ``` diff --git a/content/includes/nim/tech-specs/nim-app-protect-support.md b/content/includes/nim/tech-specs/nim-app-protect-support.md index 5bf972e0b..151449219 100644 --- a/content/includes/nim/tech-specs/nim-app-protect-support.md +++ b/content/includes/nim/tech-specs/nim-app-protect-support.md @@ -2,13 +2,13 @@ nd-docs: DOCS-1068 --- -NGINX Instance Manager supports the following versions of [F5 WAF for NGINX](https://docs.nginx.com/nginx-app-protect/): +NGINX Instance Manager supports the following versions of [F5 WAF for NGINX](https://docs.nginx.com/waf/): -{{}} +{{< table >}} -| NGINX Instance Manager | F5 WAF for NGINX | -|------------------------|------------------------------------| -| 2.17.0–2.20.0 | Release 4.8.0–4.16.0, 5.1.0–5.9.0 | +| NGINX Instance Manager | F5 WAF for NGINX | +| ---------------------- | --------------------------------- | +| 2.17.0–2.21.0 | Release 4.8.0–4.16.0, 5.1.0–5.9.0 | | 2.15.1–2.16.0 | Release 4.8.0–4.10.0 | | 2.14.1–2.15.0 | Release 4.4.0–4.7.0 | | 2.13.0–2.14.0 | Release 4.3.0–4.5.0 | @@ -20,5 +20,4 @@ NGINX Instance Manager supports the following versions of [F5 WAF for NGINX](htt | 2.7.0 | Release 3.12.2–4.0.0 | | 2.6.0 | Release 3.12.2 | -{{}} - +{{}} diff --git a/content/includes/nim/uninstall/uninstall-nim.md b/content/includes/nim/uninstall/uninstall-nim.md index e902719ac..0b5993e83 100644 --- a/content/includes/nim/uninstall/uninstall-nim.md +++ b/content/includes/nim/uninstall/uninstall-nim.md @@ -5,7 +5,7 @@ Follow the steps below to uninstall NGINX Instance Manager and ClickHouse. - **For CentOS, RHEL, and RPM-based distributions:** - ```bash + ```shell sudo yum remove -y nms-* sudo systemctl stop clickhouse-server sudo yum remove -y clickhouse-server @@ -13,7 +13,7 @@ Follow the steps below to uninstall NGINX Instance Manager and ClickHouse. - **For Debian, Ubuntu, and Deb-based distributions:** - ``` bash + ```shell sudo apt-get remove -y nms-* sudo systemctl stop clickhouse-server sudo apt-get remove -y clickhouse-server diff --git a/content/includes/nim/waf/nim-waf-before-you-begin.md b/content/includes/nim/waf/nim-waf-before-you-begin.md new file mode 100644 index 000000000..742260d4b --- /dev/null +++ b/content/includes/nim/waf/nim-waf-before-you-begin.md @@ -0,0 +1,22 @@ +--- +docs: +files: + - content/nim/waf-integration/configuration/_index.md + - content/nim/waf-integration/configuration/install-waf-compiler/install.md + - content/nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md +--- + +Make sure you’ve completed the following tasks: + +- You have one or more [F5 WAF for NGINX]({{< ref "/waf/" >}}) instances running. + For supported versions, see [Support for F5 WAF for NGINX]({{< ref "/nim/fundamentals/tech-specs.md#f5-waf" >}}). + + {{< call-out "note" >}} + If you plan to use configuration management and Security Monitoring, follow the steps in the [setup guide]({{< ref "/nim/security-monitoring/set-up-app-protect-instances.md" >}}) before continuing. + {{< /call-out >}} + +- NGINX Instance Manager is [installed]({{< ref "/nim/deploy/vm-bare-metal/_index.md" >}}), licensed, and running. + + The latest version of NGINX Instance Manager is recommended to ensure full compatibility and access to the newest features. + + If you have a subscription for F5 WAF for NGINX, you can find your license in the subscription details section of [MyF5](https://my.f5.com). \ No newline at end of file diff --git a/content/includes/nim/nap-waf/restart-nms-integrations.md b/content/includes/nim/waf/restart-nms-integrations.md similarity index 62% rename from content/includes/nim/nap-waf/restart-nms-integrations.md rename to content/includes/nim/waf/restart-nms-integrations.md index e0e0a7f64..f761f114b 100644 --- a/content/includes/nim/nap-waf/restart-nms-integrations.md +++ b/content/includes/nim/waf/restart-nms-integrations.md @@ -1,7 +1,7 @@ --- nd-docs: DOCS-000 files: - - content/nim/nginx-app-protect/setup-waf-config-management.md + - content/nim/waf-integration/configuration/setup-waf-config-management.md --- Restart the `nms-integrations` service: diff --git a/content/includes/nim/waf/upload-cert-and-key.md b/content/includes/nim/waf/upload-cert-and-key.md new file mode 100644 index 000000000..82f3d24ea --- /dev/null +++ b/content/includes/nim/waf/upload-cert-and-key.md @@ -0,0 +1,80 @@ +--- +doc: +files: + - content/nim/waf-integration/configuration/setup-signatures-and-threats/automatic-download.md +--- + +Follow these steps to get and upload the certificate and key: + +1. Log in to [MyF5](https://account.f5.com/myf5). +1. Go to **My Products and Plans > Subscriptions**. +1. Download these files from your F5 WAF for NGINX subscription: + - `nginx-repo.crt` (certificate) + - `nginx-repo.key` (private key) +1. Create a JSON file that contains both files. Replace each newline (`\n`) in the certificate and key with a literal `\n` so the formatting is correct inside the JSON file. + + **Example request:** + + ```json + { + "name": "nginx-repo", + "nginxResourceType": "NginxRepo", + "certPEMDetails": { + "caCerts": [], + "password": "", + "privateKey": "-----BEGIN PRIVATE KEY-----\n[content snipped]\n-----END PRIVATE KEY-----\n", + "publicCert": "-----BEGIN CERTIFICATE-----\n[content snipped]\n-----END CERTIFICATE-----", + "type": "PEM" + } + } + ``` + +1. Upload the file to NGINX Instance Manager using the REST API: + + ```shell + curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/certs' --header "Authorization: Bearer " --header "Content-Type: application/json" -d @nginx-repo-certs.json + ``` + +1. If successful, you’ll see a response similar to this: + + **Example response:** + + ```json + { + "certAssignmentDetails": [], + "certMetadata": [ + { + "authorityKeyIdentifier": "", + "commonName": "", + "expired": false, + "expiry": 59789838, + "issuer": "C=US, ST=Washington, L=Seattle, Inc., O=F5 Networks\\, OU=Certificate Authority, CN=F5 PRD Issuing Certificate Authority TEEM V1", + "publicKeyType": "RSA (2048 bit)", + "serialNumber": "", + "signatureAlgorithm": "SHA256-RSA", + "subject": "CN=", + "subjectAlternativeName": "", + "subjectKeyIdentifier": "", + "thumbprint": "", + "thumbprintAlgorithm": "SHA256-RSA", + "validFrom": "2021-12-21T16:57:55Z", + "validTo": "2024-12-20T00:00:00Z", + "version": 3 + } + ], + "certPEMDetails": { + "caCerts": [], + "password": "**********", + "privateKey": "**********", + "publicCert": "[content snipped]", + "type": "PEM" + }, + "created": "2023-01-27T23:42:41.587760092Z", + "modified": "2023-01-27T23:42:41.587760092Z", + "name": "nginx-repo", + "serialNumber": "", + "uid": "d08d9f54-58dd-447a-a71d-6fa5aa0d880c", + "validFrom": "2021-12-21T16:57:55Z", + "validTo": "2024-12-20T00:00:00Z" + } + ``` diff --git a/content/includes/waf/f5-waf-for-nginx-compiler-compatibility.md b/content/includes/waf/f5-waf-for-nginx-compiler-compatibility.md new file mode 100644 index 000000000..dccab021b --- /dev/null +++ b/content/includes/waf/f5-waf-for-nginx-compiler-compatibility.md @@ -0,0 +1,31 @@ +--- +docs: +files: + - /nim/waf-integration/configuration/install-waf-compiler/install.md + - /nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md +--- + +{{}} + +| F5 WAF for NGINX version | WAF compiler version | +|---------------------------|----------------------------| +| 5.9.0 | nms-nap-compiler-v5.527.0 | +| 5.8.0 | nms-nap-compiler-v5.498.0 | +| 5.7.0 | nms-nap-compiler-v5.442.0 | +| 5.6.0 | nms-nap-compiler-v5.342.0 | +| 5.5.0 | nms-nap-compiler-v5.264.0 | +| 5.4.0 | nms-nap-compiler-v5.210.0 | +| 5.3.0 | nms-nap-compiler-v5.144.0 | +| 5.2.0 | nms-nap-compiler-v5.48.0 | +| 5.1.0 | nms-nap-compiler-v5.17.0 | +| 4.16.0 | nms-nap-compiler-v5.498.0 | +| 4.15.0 | nms-nap-compiler-v5.442.0 | +| 4.14.0 | nms-nap-compiler-v5.342.0 | +| 4.13.0 | nms-nap-compiler-v5.264.0 | +| 4.12.0 | nms-nap-compiler-v5.210.0 | +| 4.11.0 | nms-nap-compiler-v5.144.0 | +| 4.10.0 | nms-nap-compiler-v5.48.0 | +| 4.9.0 | nms-nap-compiler-v5.17.0 | +| 4.8.1 | nms-nap-compiler-v4.815.0 | + +{{}} \ No newline at end of file diff --git a/content/nginx-one/_index.md b/content/nginx-one/_index.md index e4b65f795..3c12f1716 100644 --- a/content/nginx-one/_index.md +++ b/content/nginx-one/_index.md @@ -54,7 +54,7 @@ F5 NGINX One Console makes it easy to manage NGINX instances across locations an ### More information {{}} - {{}} + {{}} Set up security policies by instance and group {{}} {{}} diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index 32f281695..9c1e8163b 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -26,14 +26,13 @@ You can now graph any two metrics simultaneously on one chart within the Metrics ### Expanded features for configuring NGINX security policies with F5 WAF You can now configure the following for F5 WAF policies directly in the NGINX One Console: +- [Signature Sets]({{< ref "/nginx-one/waf-integration/add-signature-sets.md" >}}) +- [Signature Exceptions]({{< ref "/nginx-one/waf-integration/add-signature-sets.md#exceptions" >}}) +- [Parameters]({{< ref "/nginx-one/waf-integration/cookies-params-urls.md#add-parameters" >}}) +- [URLs]({{< ref "/nginx-one/waf-integration/cookies-params-urls.md#add-urls" >}}) +- [Cookies]({{< ref "/nginx-one/waf-integration/cookies-params-urls.md#add-cookies" >}}) -- [Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md" >}}) -- [Signature Exceptions]({{< ref "/nginx-one/nap-integration/add-signature-sets.md#exceptions" >}}) -- [Parameters]({{< ref "/nginx-one/nap-integration/cookies-params-urls.md#add-parameters" >}}) -- [URLs]({{< ref "/nginx-one/nap-integration/cookies-params-urls.md#add-urls" >}}) -- [Cookies]({{< ref "/nginx-one/nap-integration/cookies-params-urls.md#add-cookies" >}}) - -For more details, see the [F5 WAF Integration Guide ]({{< ref "/nginx-one/nap-integration/" >}}). +For more details, see the [F5 WAF Integration Guide ]({{< ref "/nginx-one/waf-integration/" >}}). ## October 2, 2025 @@ -53,7 +52,7 @@ See the [Getting Started Guide]({{< ref "/nginx-one/getting-started.md#install-n ### Set up F5 WAF for NGINX security policies -You can now incorporate [F5 WAF for NGINX]({{< ref "/waf/" >}}) in NGINX One Console UI. For details, see [Secure with F5 WAF for NGINX]({{< ref "/nginx-one/nap-integration/" >}}). +You can now incorporate [F5 WAF for NGINX]({{< ref "/waf/" >}}) in NGINX One Console UI. For details, see [Secure with F5 WAF for NGINX]({{< ref "/nginx-one/waf-integration/" >}}). In NGINX One Console, you can: diff --git a/content/nginx-one/nap-integration/_index.md b/content/nginx-one/waf-integration/_index.md similarity index 100% rename from content/nginx-one/nap-integration/_index.md rename to content/nginx-one/waf-integration/_index.md diff --git a/content/nginx-one/nap-integration/add-signature-sets.md b/content/nginx-one/waf-integration/add-signature-sets.md similarity index 97% rename from content/nginx-one/nap-integration/add-signature-sets.md rename to content/nginx-one/waf-integration/add-signature-sets.md index b56ff66b8..f892d5613 100644 --- a/content/nginx-one/nap-integration/add-signature-sets.md +++ b/content/nginx-one/waf-integration/add-signature-sets.md @@ -123,10 +123,10 @@ After configuring signature sets and exceptions: 1. Select **Add Policy**. The policy JSON will be updated with your changes. 1. Your policy will appear in the list under the name you provided. -1. You can then [deploy]({{< ref "/nginx-one/nap-integration/deploy-policy.md/" >}}) the policy to either: +1. You can then [deploy]({{< ref "/nginx-one/waf-integration/deploy-policy.md/" >}}) the policy to either: - An instance - A Config Sync Group -From NGINX One Console, you can [review and modify]({{< ref "/nginx-one/nap-integration/review-policy.md/" >}}) your saved policies at any time by selecting **App Protect > Policies**. +From NGINX One Console, you can [review and modify]({{< ref "/nginx-one/waf-integration/review-policy.md/" >}}) your saved policies at any time by selecting **App Protect > Policies**. For a complete list of available signature sets and detailed information about attack signatures, see the [Attack Signatures]({{< ref "/waf/policies/attack-signatures.md" >}}) documentation. diff --git a/content/nginx-one/nap-integration/configure-policy.md b/content/nginx-one/waf-integration/configure-policy.md similarity index 100% rename from content/nginx-one/nap-integration/configure-policy.md rename to content/nginx-one/waf-integration/configure-policy.md diff --git a/content/nginx-one/nap-integration/cookies-params-urls.md b/content/nginx-one/waf-integration/cookies-params-urls.md similarity index 95% rename from content/nginx-one/nap-integration/cookies-params-urls.md rename to content/nginx-one/waf-integration/cookies-params-urls.md index e4b89e47a..efabf4d9f 100644 --- a/content/nginx-one/nap-integration/cookies-params-urls.md +++ b/content/nginx-one/waf-integration/cookies-params-urls.md @@ -6,14 +6,14 @@ nd-content-type: how-to nd-product: NGINX One Console --- -# Add cookies +## Add cookies Cookie protections can be configured and managed directly within the policy editor by selecting the **Cookies** option. ## Cookie properties and types Each cookie configuration includes: -- `Cookie Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. +- `Cookie Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/waf-integration/waf-policy-matching-types.md" >}}) section. - `Cookie Name`: The name of the cookie to be monitored or protected - `Enforcement Type`: - **Allow**: Specifies that this cookie may be changed by the client. The cookie is not protected from modification @@ -33,6 +33,7 @@ Select **Edit Configuration** to configure cookie violations. The following viol - `VIOL_COOKIE_MODIFIED`: Triggered when domain cookies have been tampered with For each violation type, you can: + - Set the enforcement action - Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings @@ -54,7 +55,7 @@ See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-vi 1. Optional: Configure Attack Signatures - If enabled, you can overwrite attack signatures for this specific cookie - - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) + - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/waf-integration/add-signature-sets.md/" >}}) 1. Select **Add Cookie** to save your configuration @@ -65,7 +66,8 @@ Parameter protections can be configured and managed directly within the policy e ## Parameter properties and types Each parameter configuration includes: -- `Parameter Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. + +- `Parameter Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/waf-integration/waf-policy-matching-types.md" >}}) section. - `Parameter Name`: The name of the parameter - `Location`: Where the parameter is expected (URL query string, POST data, etc.) - `Value Type`: The expected type of the parameter value (e.g., alpha-numeric, integer, email) @@ -94,6 +96,7 @@ Select **Edit Configuration** to configure parameter violations. The following v - `VIOL_PARAMETER_VALUE_REGEXP`: Triggered when parameter value doesn't match required pattern For each violation type, you can: + - Set the enforcement action - Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings @@ -125,18 +128,18 @@ See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-vi 1. Optional: Configure Attack Signatures - If enabled, you can overwrite attack signatures for this specific parameter - - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) + - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/waf-integration/add-signature-sets.md/" >}}) 1. Select **Add Parameter** to save your configuration -# Add URLs +## Add URLs URL protections can be configured and managed directly within the policy editor by selecting the **URLs** option. ## URL properties and types Each URL configuration includes: -- `URL Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. +- `URL Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/waf-integration/waf-policy-matching-types.md" >}}) section. - `Method`: Specifies the HTTP method(s) for the URL (`GET`, `POST`, `PUT`, etc.) - `Protocol`: The protocol for the URL (`HTTP`/`HTTPS`) - `Enforcement Type`: @@ -192,6 +195,6 @@ See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-vi 1. **Optional**: Configure Attack Signatures - If enabled, you can overwrite attack signatures for this specific URL - - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) + - For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/waf-integration/add-signature-sets.md/" >}}) 1. Select **Add URL** to save your configuration diff --git a/content/nginx-one/nap-integration/deploy-policy.md b/content/nginx-one/waf-integration/deploy-policy.md similarity index 100% rename from content/nginx-one/nap-integration/deploy-policy.md rename to content/nginx-one/waf-integration/deploy-policy.md diff --git a/content/nginx-one/nap-integration/overview.md b/content/nginx-one/waf-integration/overview.md similarity index 90% rename from content/nginx-one/nap-integration/overview.md rename to content/nginx-one/waf-integration/overview.md index 376dbbfe9..ae695aeea 100644 --- a/content/nginx-one/nap-integration/overview.md +++ b/content/nginx-one/waf-integration/overview.md @@ -21,11 +21,11 @@ Once you've connected to the NGINX One Console, select **App Protect > Policies* Through the NGINX One Console UI, you can: -- [Add and configure a policy]({{< ref "/nginx-one/nap-integration/configure-policy.md/" >}}) -- [Review existing policies]({{< ref "/nginx-one/nap-integration/review-policy.md/" >}}) -- [Deploy policies]({{< ref "/nginx-one/nap-integration/deploy-policy.md/" >}}) on instances and Config Sync Groups +- [Add and configure a policy]({{< ref "/nginx-one/waf-integration/configure-policy.md/" >}}) +- [Review existing policies]({{< ref "/nginx-one/waf-integration/review-policy.md/" >}}) +- [Deploy policies]({{< ref "/nginx-one/waf-integration/deploy-policy.md/" >}}) on instances and Config Sync Groups -You can also set up policies through the [NGINX One Console API]({{< ref "/nginx-one/nap-integration/security-policy-api.md/" >}}). +You can also set up policies through the [NGINX One Console API]({{< ref "/nginx-one/waf-integration/security-policy-api.md/" >}}). ## Set up F5 WAF for NGINX diff --git a/content/nginx-one/nap-integration/review-policy.md b/content/nginx-one/waf-integration/review-policy.md similarity index 100% rename from content/nginx-one/nap-integration/review-policy.md rename to content/nginx-one/waf-integration/review-policy.md diff --git a/content/nginx-one/nap-integration/security-policy-api.md b/content/nginx-one/waf-integration/security-policy-api.md similarity index 100% rename from content/nginx-one/nap-integration/security-policy-api.md rename to content/nginx-one/waf-integration/security-policy-api.md diff --git a/content/nginx-one/nap-integration/waf-policy-matching-types.md b/content/nginx-one/waf-integration/waf-policy-matching-types.md similarity index 100% rename from content/nginx-one/nap-integration/waf-policy-matching-types.md rename to content/nginx-one/waf-integration/waf-policy-matching-types.md diff --git a/content/nic/installation/integrations/app-protect-waf-v5/compile-waf-policies.md b/content/nic/installation/integrations/app-protect-waf-v5/compile-waf-policies.md index fdb8b7233..a1ce767ce 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/compile-waf-policies.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/compile-waf-policies.md @@ -32,7 +32,7 @@ The following steps describe how to use the NGINX Instance Manager API to create {{< call-out "tip" >}} You can skip this step if you intend to use an existing security policy. {{< /call-out >}} -Create a [new security policy]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md#create-security-policy" >}}) using the API: this will require the use of a tool such as [`curl`](https://curl.se/) or [Postman](https://www.postman.com/) +Create a [new security policy]({{< ref "/nim/waf-integration/policies-and-logs/policies/create-policy.md" >}}) using the API: this will require the use of a tool such as [`curl`](https://curl.se/) or [Postman](https://www.postman.com/) Create the file `simple-policy.json` with the contents below: @@ -92,7 +92,7 @@ It is one of two unique IDs we will use to download the bundle: it will be refer ## Create a new security bundle -Once you have created (Or selected) a security policy, [create a security bundle]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md#create-security-policy-bundles" >}}) using the API. The version in the bundle you create **must** match the WAF compiler version you intend to use. +Once you have created (Or selected) a security policy, [create a security bundle]({{< ref "/nim/waf-integration/policies-and-logs/bundles/create-bundle.md" >}}) using the API. The version in the bundle you create **must** match the WAF compiler version you intend to use. You can check which version is installed in NGINX Instance Manager by checking the operating system packages. If the wrong version is noted in the JSON payload, you will receive an error similar to below: diff --git a/content/nic/releases.md b/content/nic/releases.md index 24db3cb59..54e6f4a8d 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -524,7 +524,7 @@ versions: 1.25-1.30. 25 Jun 2024 Added support for the latest generation of NGINX App Protect Web Application Firewall, v5. NGINX Ingress Controller will continue to support the NGINX App Protect v4 family to allow customers to implement new Policy Bundle workflow at their own pace. -F5 WAF for NGINX v5 does not accept the JSON based policies, instead requiring users to compile a Policy Bundle outside of the NGINX Ingress Controller pod. Policy bundles contain a combination of custom Policy, signatures, and campaigns. Bundles can be compiled using either the F5 WAF for NGINX [compiler]({{< ref "/waf/configure/compiler.md" >}}), or [NGINX Instance Manager]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md#list-security-policy-bundles" >}}). Read more in the [F5 WAF for NGINX V5]({{< ref "/nic/installation/integrations/app-protect-waf-v5/" >}}) topic. +F5 WAF for NGINX v5 does not accept the JSON based policies, instead requiring users to compile a Policy Bundle outside of the NGINX Ingress Controller pod. Policy bundles contain a combination of custom Policy, signatures, and campaigns. Bundles can be compiled using either the F5 WAF for NGINX [compiler]({{< ref "/waf/configure/compiler.md" >}}), or [NGINX Instance Manager]({{< ref "/nim/waf-integration/policies-and-logs/bundles/list-bundles.md" >}}). Read more in the [F5 WAF for NGINX V5]({{< ref "/nic/installation/integrations/app-protect-waf-v5/" >}}) topic. With this release, NGINX Ingress Controller is implementing a new image maintenance policy. Container images for subscribed users will be updated on a regular basis in-between releases to reduce the CVE vulnerabilities. Customers can observe the 3.6.x tag when listing images in the registry and select the latest image to update to for the current release. diff --git a/content/nim/admin-guide/authentication/_index.md b/content/nim/admin-guide/authentication/_index.md index 021e30b44..8eeb953b2 100644 --- a/content/nim/admin-guide/authentication/_index.md +++ b/content/nim/admin-guide/authentication/_index.md @@ -1,6 +1,6 @@ --- title: Authentication weight: 100 -url: /nginx-management-suite/admin-guide/authentication/ +url: /nginx-instance-manager/admin-guide/authentication/ --- diff --git a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md index 2a1e971d6..4391a2d9e 100644 --- a/content/nim/admin-guide/authentication/oidc/keycloak-setup.md +++ b/content/nim/admin-guide/authentication/oidc/keycloak-setup.md @@ -118,7 +118,7 @@ To set the Keycloak secret as an environment variable: 1. Open an SSH connection to your NGINX Instance Manager host and log in. 2. Run the following command, replacing `` with the secret value you copied: - ```bash + ```shell export KEYCLOAK_SECRET= ``` @@ -130,7 +130,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - **For Keycloak versions earlier than 18.x**: - ```bash + ```shell # Either the FQDN or the IP address is suitable for these environment variables. export KEYCLOAK_IP="" export NIM_IP="" @@ -147,7 +147,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - **For Keycloak versions 18.x and later**: - ```bash + ```shell # Either the FQDN or the IP address is suitable for these environment variables. export KEYCLOAK_IP="" export NIM_IP="" @@ -172,14 +172,14 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - Back up the original configuration files: - ```bash + ```shell sudo cp /etc/nms/nginx/oidc/openid_configuration.conf ~/openid_configuration.conf.orig sudo cp /etc/nginx/conf.d/nms-http.conf ~/nms-http.conf.orig ``` - Copy the OpenID configuration for NGINX to `/tmp` so you can replace the necessary values: - ```bash + ```shell sudo cp /etc/nms/nginx/oidc/openid_configuration.conf /tmp/openid_configuration.conf sudo sed -i'.bak' \ -e "s%OIDC_CLIENT_ID%${KEYCLOAK_CLIENT_ID}%" \ @@ -209,7 +209,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - Copy the `nms-http.conf` file to `/tmp` to replace the necessary values: - ```bash + ```shell sudo cp /etc/nginx/conf.d/nms-http.conf /tmp/nms-http.conf ``` @@ -263,7 +263,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the - Copy the modified configuration files back to their original locations: - ```bash + ```shell sudo cp /tmp/nms-http.conf /etc/nginx/conf.d/nms-http.conf sudo cp /tmp/openid_configuration.conf /etc/nms/nginx/oidc/openid_configuration.conf ``` @@ -275,7 +275,7 @@ To configure NGINX Instance Manager with the necessary OIDC settings, follow the To revert to Basic Auth for troubleshooting authentication issues, run: -```bash +```shell sudo cp ~/openid_configuration.conf.orig /etc/nms/nginx/oidc/openid_configuration.conf sudo cp ~/nms-http.conf.orig /etc/nginx/conf.d/nms-http.conf sudo nginx -s reload diff --git a/content/nim/admin-guide/authentication/oidc/microsoft-entra-automation.md b/content/nim/admin-guide/authentication/oidc/microsoft-entra-automation.md index 41484ccaf..2446c5cff 100644 --- a/content/nim/admin-guide/authentication/oidc/microsoft-entra-automation.md +++ b/content/nim/admin-guide/authentication/oidc/microsoft-entra-automation.md @@ -108,7 +108,7 @@ Additionally, complete the following steps: 1. Send a `POST` request to the Microsoft Entra token endpoint: - ```bash + ```shell https://login.microsoftonline.com//oauth2/v2.0/token ``` @@ -160,7 +160,7 @@ Additionally, complete the following steps: To access the NGINX Management Suite API using the access token, send the token in the `Authorization` header of the request as a Bearer token. For example, using `curl`: -```bash +```shell curl -v -k --header "Authorization: Bearer " https:///api/platform/v1/userinfo ``` diff --git a/content/nim/admin-guide/maintenance/sqlite-installation.md b/content/nim/admin-guide/maintenance/sqlite-installation.md index 683ab4ffe..fde332b16 100644 --- a/content/nim/admin-guide/maintenance/sqlite-installation.md +++ b/content/nim/admin-guide/maintenance/sqlite-installation.md @@ -16,13 +16,13 @@ To install SQLite on your system, run the appropriate command(s) for your Linux #### For RHEL and RPM-based distributions (excluding CentOS 7, Amazon Linux 2, and Oracle Linux 7): -```bash +```shell sudo yum install -y sqlite ``` #### For CentOS 7, Amazon Linux 2, and Oracle Linux 7: -```bash +```shell sudo su yum install -y gcc \ make \ @@ -50,14 +50,14 @@ To install SQLite on your system, run the appropriate command(s) for your Linux #### For Debian, Ubuntu, and Deb-based distributions (excluding Debian (buster/sid) and Ubuntu 18.04): -```bash +```shell sudo apt-get update sudo apt-get install -y sqlite3 ``` #### For Debian (buster/sid) and Ubuntu 18.04: -```bash +```shell sudo su apt-get install -y gcc \ make \ diff --git a/content/nim/admin-guide/rbac/_index.md b/content/nim/admin-guide/rbac/_index.md index cc8b07c0f..f211d9b69 100644 --- a/content/nim/admin-guide/rbac/_index.md +++ b/content/nim/admin-guide/rbac/_index.md @@ -1,6 +1,6 @@ --- title: RBAC weight: 200 -url: /nginx-management-suite/admin-guide/rbac/ +url: /nginx-instance-manager/admin-guide/rbac/ --- diff --git a/content/nim/admin-guide/rbac/manage-resource-groups.md b/content/nim/admin-guide/rbac/manage-resource-groups.md index 99dfed1ea..65e884495 100644 --- a/content/nim/admin-guide/rbac/manage-resource-groups.md +++ b/content/nim/admin-guide/rbac/manage-resource-groups.md @@ -165,7 +165,7 @@ To remove a resource from a resource group via the REST API, send an HTTP `DELET ##### Example request -```bash +```shell DELETE https:///api/platform/v1/resource-groups/{resourceGroupUid}/resources/{resourceUid}?moduleName=Instance Manager ``` @@ -193,7 +193,7 @@ To delete a resource group via the REST API, send an HTTP `DELETE` request. ##### Example request -```bash +```shell DELETE https:///api/platform/v1/resource-groups/{resourceGroupUid} ``` @@ -227,7 +227,7 @@ To retrieve a list of resource groups with resource details: ##### Example request (showing resource details) -```bash +```shell GET https:///api/platform/v1/resource-groups?showDetails=true ``` diff --git a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md b/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md index 2936ccce1..9d6753813 100644 --- a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md +++ b/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md @@ -17,7 +17,7 @@ You can deploy it in two ways: - **Standard mode** includes full metrics and dashboards. This setup runs ClickHouse in a separate container. - **Lightweight mode** (new in 2.20.0) skips ClickHouse entirely. It’s ideal if you don’t need monitoring data or want a simpler setup. This reduces system requirements and avoids the work of managing a metrics database. You can add ClickHouse later if your needs change. -Both modes use a pre-built Docker image that includes NGINX Instance Manager, Security Monitoring, and the latest NGINX App Protect compilers. +Both modes use a pre-built Docker image that includes NGINX Instance Manager, Security Monitoring, and the latest F5 WAF for NGINX compilers. If you use the standard setup, ClickHouse runs in its own container. This helps with fault tolerance and keeps data separate. You can also use persistent storage. @@ -48,7 +48,7 @@ Your system needs enough resources to run NGINX Instance Manager based on the mo | Standard | 4 | 4 GB | Yes | | Lightweight | (Lower) | (Lower)| No | -Standard mode requires a minimum of 4 CPU cores and 4 GB of memory. This setup includes ClickHouse, which handles metrics and dashboards. Depending on your NGINX footprint, you may need more resources, especially for environments with many configuration files or NGINX App Protect enabled. +Standard mode requires a minimum of 4 CPU cores and 4 GB of memory. This setup includes ClickHouse, which handles metrics and dashboards. Depending on your NGINX footprint, you may need more resources, especially for environments with many configuration files or F5 WAF for NGINX enabled. Lightweight mode removes ClickHouse, which lowers memory and CPU usage. While there’s no official minimum, users with basic instance management needs may see success with fewer resources. Test in your environment before committing to a smaller footprint. diff --git a/content/nim/deploy/vm-bare-metal/install.md b/content/nim/deploy/vm-bare-metal/install.md index f06b29897..ffe5955e4 100644 --- a/content/nim/deploy/vm-bare-metal/install.md +++ b/content/nim/deploy/vm-bare-metal/install.md @@ -241,13 +241,13 @@ bash install-nim-bundle.sh -r 1. To upgrade to the latest version of the NGINX Instance Manager, run the following command: - ```bash + ```shell sudo yum update -y nms-instance-manager --allowerasing ``` 1. To upgrade to the latest version of Clickhouse, run the following command: - ```bash + ```shell sudo yum update -y clickhouse-server clickhouse-client ``` @@ -257,14 +257,14 @@ bash install-nim-bundle.sh -r 1. To upgrade to the latest version of the NGINX Instance Manager, run the following commands: - ```bash + ```shell sudo apt-get update sudo apt-get install -y --only-upgrade nms-instance-manager ``` 1. To upgrade to the latest version of ClickHouse, run the following commands: - ```bash + ```shell sudo apt-get update sudo apt-get install -y --only-upgrade clickhouse-server clickhouse-client ``` @@ -274,7 +274,7 @@ bash install-nim-bundle.sh -r 2. Restart the NGINX Instance Manager platform services: - ```bash + ```shell sudo systemctl restart nms ``` @@ -282,13 +282,13 @@ bash install-nim-bundle.sh -r 3. Restart the NGINX web server: - ```bash + ```shell sudo systemctl restart nginx ``` 4. Restart the Clickhouse server: - ```bash + ```shell sudo systemctl restart clickhouse-server ``` diff --git a/content/nim/disconnected/add-license-disconnected-deployment.md b/content/nim/disconnected/add-license-disconnected-deployment.md index 8434babf7..f845ad036 100644 --- a/content/nim/disconnected/add-license-disconnected-deployment.md +++ b/content/nim/disconnected/add-license-disconnected-deployment.md @@ -40,13 +40,13 @@ To add a license and submit the initial usage report in a disconnected environme 1. {{}}[Download license_usage_offline.sh](/scripts/license_usage_offline.sh). 1. Run the following command to allow the script to run: - ```bash + ```shell chmod +x /license_usage_offline.sh ``` 1. Run the script. Replace each placeholder with your specific values: - ``` bash + ```shell ./license_usage_offline.sh \ -j .jwt \ -i \ @@ -75,7 +75,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Add the license to NGINX Instance Manager**: - ``` bash + ```shell curl -k --location 'https:///api/platform/v1/license?telemetry=true' \ --header 'Origin: https://' \ --header 'Referer: https:///ui/settings/license' \ @@ -95,7 +95,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and Use this command to check the current license status. Look for `INITIALIZE_ACTIVATION_COMPLETE` or `CONFIG_REPORT_READY` in the status field. Poll periodically if necessary. - ```bash + ```shell curl -k "https:///api/platform/v1/license" \ --header "accept: application/json" \ --header "authorization: Basic " \ @@ -106,7 +106,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and This step ensures that the license configuration is fully applied. - ```bash + ```shell curl -k --location --request PUT "https:///api/platform/v1/license?telemetry=true" \ --header "Origin: https://" \ --header "Referer: https:///ui/settings/license" \ @@ -136,7 +136,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Download the initial usage report**: - ```bash + ```shell curl -k --location 'https:///api/platform/v1/report/download?format=zip&reportType=initial' \ --header 'accept: */*' \ --header 'Authorization: Basic ' \ @@ -145,7 +145,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Submit the usage report to F5 for verification**: - ```bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" \ --form 'file=@".zip"' @@ -165,14 +165,14 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and Replace `` with your specific ID from the previous response. - ``` bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk/status/' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" ``` 3. **Download the usage acknowledgement from F5**: - ``` bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk/download/' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" \ --output .zip @@ -180,7 +180,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 4. **Upload the usage acknowledgement to NGINX Instance Manager**: - ``` bash + ```shell curl -k --location 'https:///api/platform/v1/report/upload' \ --header 'Authorization: Basic ' \ --form 'file=@".zip"' diff --git a/content/nim/disconnected/offline-install-guide-manual.md b/content/nim/disconnected/offline-install-guide-manual.md index ce3647e35..900a3a67e 100644 --- a/content/nim/disconnected/offline-install-guide-manual.md +++ b/content/nim/disconnected/offline-install-guide-manual.md @@ -81,14 +81,14 @@ To download external dependencies: - **For RHEL and RPM-Based systems**: - ```bash + ```shell tar -kzxvf nms-dependencies-.tar.gz sudo rpm -ivh *.rpm ``` - **For Debian, Ubuntu, Deb-based systems**: - ```bash + ```shell tar -kzxvf nms-dependencies-.tar.gz sudo dpkg -i ./*.deb ``` @@ -107,19 +107,19 @@ The administrator username (default: **admin**) and the generated password are d - **For RHEL and RPM-based systems**: - ```bash + ```shell sudo rpm -ivh --nosignature /home//nms-instance-manager_.x86_64.rpm ``` - **For Debian, Ubuntu, Deb-based systems**: - ```bash + ```shell sudo apt-get -y install -f /home//nms-instance-manager__amd64.deb ``` 3. Enable and start NGINX Instance Manager services: - ```bash + ```shell sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now ``` @@ -127,7 +127,7 @@ The administrator username (default: **admin**) and the generated password are d 4. Restart the NGINX web server: - ```bash + ```shell sudo systemctl restart nginx ``` @@ -167,7 +167,7 @@ To upgrade NGINX Instance Manager to a newer version: 2. Upgrade the package: - **For RHEL and RPM-based systems**: - ``` bash + ```shell sudo rpm -Uvh --nosignature /home/user/nms-instance-manager_.x86_64.rpm sudo systemctl restart nms sudo systemctl restart nginx @@ -175,7 +175,7 @@ To upgrade NGINX Instance Manager to a newer version: - **For Debian, Ubuntu, Deb-based systems**: - ```bash + ```shell sudo apt-get -y install -f /home/user/nms-instance-manager__amd64.deb sudo systemctl restart nms sudo systemctl restart nginx @@ -191,7 +191,7 @@ To upgrade NGINX Instance Manager to a newer version: To manually update the CVE list in an air-gapped environment, follow these steps to download and overwrite the `cve.xml` file in the `/usr/share/nms` directory and restart the Data Plane Manager service: -```bash +```shell sudo chmod 777 /usr/share/nms/cve.xml && \ sudo curl -s http://hg.nginx.org/nginx.org/raw-file/tip/xml/en/security_advisories.xml > /usr/share/nms/cve.xml && \ sudo chmod 644 /usr/share/nms/cve.xml && \ diff --git a/content/nim/disconnected/report-usage-disconnected-deployment.md b/content/nim/disconnected/report-usage-disconnected-deployment.md index 96ac83234..820483225 100644 --- a/content/nim/disconnected/report-usage-disconnected-deployment.md +++ b/content/nim/disconnected/report-usage-disconnected-deployment.md @@ -50,13 +50,13 @@ To submit a usage report in a disconnected environment, use the provided `licens 1. {{}}[Download license_usage_offline.sh](/scripts/license_usage_offline.sh). 1. Run the following command to allow the script to run: - ```bash + ```shell chmod +x /license_usage_offline.sh ``` 1. Run the script. Replace each placeholder with your specific values: - ``` bash + ```shell ./license_usage_offline.sh \ -j .jwt \ -i \ @@ -84,7 +84,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Prepare the usage report**: - ```bash + ```shell curl -k --location 'https:///api/platform/v1/report/download?format=zip&reportType=telemetry&telemetryAction=prepare' \ --header 'accept: application/json' \ --header 'authorization: Basic ' \ @@ -93,7 +93,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Download the usage report from NGINX Instance Manager**: - ```bash + ```shell curl -k --location 'https:///api/platform/v1/report/download?format=zip&reportType=telemetry&telemetryAction=download' \ --header 'accept: */*' \ --header 'authorization: Basic ' \ @@ -102,7 +102,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Submit the usage report to F5 for verification**: - ```bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" \ --form 'file=@".zip"' @@ -122,14 +122,14 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and Replace `` with your specific ID from the previous response. - ```bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk/status/' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" ``` 1. **Download the usage acknowledgement from F5**: - ```bash + ```shell curl --location 'https://product.apis.f5.com/ee/v1/entitlements/telemetry/bulk/download/' \ --header "Authorization: Bearer $(cat /path/to/jwt-file)" \ --output .zip @@ -137,7 +137,7 @@ Run these `curl` commands on a system that can access NGINX Instance Manager and 1. **Upload the usage acknowledgement to NGINX Instance Manager**: - ```bash + ```shell curl -k --location 'https:///api/platform/v1/report/upload' \ --header 'Authorization: Basic ' \ --form 'file=@".zip"' diff --git a/content/nim/fundamentals/tech-specs.md b/content/nim/fundamentals/tech-specs.md index 1125c04d6..9f0cb9a65 100644 --- a/content/nim/fundamentals/tech-specs.md +++ b/content/nim/fundamentals/tech-specs.md @@ -30,11 +30,11 @@ You can deploy NGINX Instance Manager in the following environments: ## Sizing recommendations for Managing NGINX Instances {#system-sizing} -The following recommendations provide the minimum guidelines for NGINX Instance Manager. These guidelines ensure adequate performance, but for optimal results, we strongly recommend using solid-state drives (SSDs) for storage. If you set up [deployments with NGINX App Protect](#system-sizing-app-protect), you may need additional memory and CPU. +The following recommendations provide the minimum guidelines for NGINX Instance Manager. These guidelines ensure adequate performance, but for optimal results, we strongly recommend using solid-state drives (SSDs) for storage. If you set up [deployments with F5 WAF for NGINX](#system-sizing-app-protect), you may need additional memory and CPU. ### Standard NGINX configuration deployments -This section outlines the recommendations for NGINX Instance Manager deployments with data plane instances using standard configurations, without NGINX App Protect. **Standard configurations** typically support up to **40 upstream servers** with associated location and server blocks, and up to **350 certificates**. This is ideal for medium-sized environments or applications with moderate traffic. +This section outlines the recommendations for NGINX Instance Manager deployments with data plane instances using standard configurations, without F5 WAF for NGINX. **Standard configurations** typically support up to **40 upstream servers** with associated location and server blocks, and up to **350 certificates**. This is ideal for medium-sized environments or applications with moderate traffic. We recommend using SSDs to enhance storage performance. @@ -50,7 +50,7 @@ These values represent the minimum resources needed for deployments that fall un ### Large NGINX configuration deployments -For environments requiring more resources, **large configurations** are suitable. These configurations can support up to **300 upstream servers** and are designed for enterprise environments or applications handling high traffic and complex configurations, without NGINX App Protect. +For environments requiring more resources, **large configurations** are suitable. These configurations can support up to **300 upstream servers** and are designed for enterprise environments or applications handling high traffic and complex configurations, without F5 WAF for NGINX. {{< bootstrap-table "table table-striped table-bordered" >}} | Number of Data Plane Instances | CPU | Memory | Network | Storage | @@ -59,9 +59,9 @@ For environments requiring more resources, **large configurations** are suitable | 250 | 4 vCPU | 8 GB RAM | 1 GbE NIC | 2 TB | {{}} -### NGINX configuration deployments with NGINX App Protect {#system-sizing-app-protect} +### NGINX configuration deployments with F5 WAF for NGINX {#system-sizing-app-protect} -If using NGINX App Protect features in NGINX Instance Manager, this requires additional CPU and Memory for policy compilation and security monitoring features. At a minimum, 8gb Memory and 4 CPUs are required for a standard NGINX App Protect use case (under 20 NGINX Plus instances). The requirements are heavily dependent on the number of policies being managed, the frequency of updates and the number of events being that occur in the security monitoring feature. +If using F5 WAF for NGINX features in NGINX Instance Manager, this requires additional CPU and Memory for policy compilation and security monitoring features. At a minimum, 8gb Memory and 4 CPUs are required for a standard F5 WAF for NGINX use case (under 20 NGINX Plus instances). The requirements are heavily dependent on the number of policies being managed, the frequency of updates and the number of events being that occur in the security monitoring feature. ### Lightweight mode {#lightweight-mode} @@ -84,7 +84,7 @@ When used only for licensing and usage reporting, NGINX Instance Manager has min | Number of Data Plane Instances | CPU | Memory | Network | Storage | |--------------------------------|--------|----------|-----------|---------| | n/a | 2 vCPU | 4 GB RAM | 1 GbE NIC | 20 GB | -{{}} +{{< /bootstrap-table >}} ### Sizing benchmarks for storage @@ -99,6 +99,7 @@ The following benchmarks focus on **disk storage** requirements for NGINX Instan The table below provides storage estimates for **NGINX Plus** based on configuration size, number of instances, and a 14-day data retention period. Larger configurations and longer retention periods will require proportionally more storage. {{}} + | Config Size | Instances | Retention (days) | Estimated Disk Usage (NGINX Plus) | |---------------------|-----------|------------------|-----------------------------------| | **Small Size** | 10 | 14 | 5 GiB | @@ -113,9 +114,10 @@ The table below provides storage estimates for **NGINX Plus** based on configura | | 50 | 14 | 426 GiB | | | 100 | 14 | 850 GiB | | | 250 | 14 | 2 TiB | + {{}} -{{< call-out "note" >}}MiB (mebibyte), GiB (gibibyte), and TiB (tebibyte) are units of data storage. MiB equals 1,024^2 (2^20) bytes, GiB equals 1,024^3 (2^30) bytes, and TiB equals 1,024^4 (2^40) bytes. These are often used in computing to represent binary data storage capacities, as opposed to MB (megabyte), GB (gigabyte), and TB (terabyte), which use decimal units.{{< /call-out >}} +{{< call-out "note" "Note" >}}MiB (mebibyte), GiB (gibibyte), and TiB (tebibyte) are units of data storage. MiB equals 1,024^2 (2^20) bytes, GiB equals 1,024^3 (2^30) bytes, and TiB equals 1,024^4 (2^40) bytes. These are often used in computing to represent binary data storage capacities, as opposed to MB (megabyte), GB (gigabyte), and TB (terabyte), which use decimal units.{{< /call-out >}} #### Storage requirements for NGINX OSS @@ -124,12 +126,14 @@ The table below provides storage estimates for **NGINX Plus** based on configura The table below shows the estimated storage requirements for **NGINX OSS**, based on the number of instances and a 14-day retention period. {{}} + | Config Size | Instances | Retention (days) | Estimated Disk Usage (NGINX OSS) | |-----------------------|-----------|------------------|----------------------------------| | **Generic Large Size** | 10 | 14 | 200 MiB | | | 50 | 14 | 850 MiB | | | 100 | 14 | 1.75 GiB | | | 250 | 14 | 4 GiB | + {{}} ## Directory Requirements for NGINX Instance Manager @@ -151,7 +155,7 @@ If you're concerned solely on usage reporting, you do not need NGINX Agent. Requ | Directory path | Content | Recommendation | |-----------------------|-----------------|----------------------------------| | /usr/bin | Stores NIM binaries | 500MB | -| /var/lib/nms/dqlite | Stores DQLite database data| 2GiB without NGINX App Protect; 5GiB with NGINX App Protect enabled and large compiled bundles | +| /var/lib/nms/dqlite | Stores DQLite database data| 2GiB without F5 WAF for NGINX; 5GiB with F5 WAF for NGINX enabled and large compiled bundles | | /var/lib/nms/streaming | Stores NATS streaming messages | 500MiB | | /var/lib/nms/secrets | Stores secrets for LLM license handshakes | 10MiB | | /var/lib/nms/modules | Stores static content like manager.json | 100KiB (12KiB minimum) | @@ -184,7 +188,7 @@ The NGINX Instance Manager web interface works best on the latest versions of th - [Safari](https://support.apple.com/downloads/safari) - [Microsoft Edge](https://www.microsoft.com/en-us/edge) -## Support for F5 WAF for NGINX +## Support for F5 WAF for NGINX {#f5-waf} {{< include "nim/tech-specs/nim-app-protect-support.md" >}} diff --git a/content/nim/nginx-app-protect/manage-waf-security-policies.md b/content/nim/nginx-app-protect/manage-waf-security-policies.md deleted file mode 100644 index 4bb8b4e7e..000000000 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ /dev/null @@ -1,744 +0,0 @@ ---- -title: Manage and deploy WAF policies and log profiles -description: Learn how to use F5 NGINX Instance Manager to manage F5 WAF for NGINX security policies and security log profiles. -weight: 300 -toc: true -nd-content-type: how-to -nd-product: NIM -nd-docs: DOCS-1105 ---- - -## Overview - -F5 NGINX Instance Manager lets you manage F5 WAF for NGINX configurations using either the web interface or REST API. You can edit, update, and deploy security policies, log profiles, attack signatures, and threat campaigns to individual instances or instance groups. - -You can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. The bundle includes all necessary components for a specific F5 WAF for NGINX version. Precompiling the bundle improves performance by avoiding separate compilation of each component during deployment. - -{{< call-out "note" >}} -The following capabilities are available only through the Instance Manager REST API: - -- Update security policies -- Create, read, and update security policy bundles -- Create, read, update, and delete security log profiles -- Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups -{{< /call-out >}} - -## Before you begin - -Before continuing, complete the following steps: - -- [Set up F5 WAF for NGINX configuration management]({{< ref "setup-waf-config-management" >}}) -- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: - - - **Module**: Instance Manager - - **Feature**: Instance Management → `READ` - - **Feature**: Security Policies → `READ`, `CREATE`, `UPDATE`, `DELETE` - -To use policy bundles, you also need to: - -- Have `UPDATE` permissions for each referenced security policy -- [Install the correct `nms-nap-compiler` package]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}) for your F5 WAF for NGINX version -- [Install the required attack signatures and threat campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}) - -### Access the web interface - -To access the web interface, open a browser and go to the fully qualified domain name (FQDN) of your NGINX Instance Manager. Log in, then select **Instance Manager** from the Launchpad. - -### Access the REST API - -{{< include "nim/how-to-access-nim-api.md" >}} - -## Create a security policy {#create-security-policy} - -{{}} - -{{%tab name="web interface"%}} - -To create a security policy using the NGINX Instance Manager web interface: - -1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, select **Create**. -5. On the *Create Policy* page, enter the required information: - - **Name**: Enter a name for the policy. - - **Description**: (Optional) Add a brief description. - - **Enter Policy**: Paste or type the JSON-formatted policy into the editor. The interface automatically validates the JSON. - - For help writing custom policies, see the [F5 WAF for NGINX Declarative Policy guide](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) and the [Policy Authoring and Tuning section](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) in the configuration guide. - -6. Select **Save**. - -{{%/tab%}} - -{{%tab name="API"%}} - -To upload a new security policy using the REST API, send a `POST` request to the Security Policies API endpoint. - -You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. - -| Method | Endpoint | -|--------|--------------------------------------| -| POST | `/api/platform/v1/security/policies` | - -For example: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @ignore-xss-example.json -``` - -{{< details summary="JSON request" >}} - -```json -{ - "metadata": { - "name": "ignore-cross-site-scripting", - "displayName": "Ignore cross-site scripting", - "description": "Ignore cross-site scripting is a security policy that intentionally ignores cross site scripting." - }, - "content": "ewoJInBvbGljeSI6IHsKCQkibmFtZSI6ICJzaW1wbGUtYmxvY2tpbmctcG9saWN5IiwKCQkic2lnbmF0dXJlcyI6IFsKCQkJewoJCQkJInNpZ25hdHVyZUlkIjogMjAwMDAxODM0LAoJCQkJImVuYWJsZWQiOiBmYWxzZQoJCQl9CgkJXSwKCQkidGVtcGxhdGUiOiB7CgkJCSJuYW1lIjogIlBPTElDWV9URU1QTEFURV9OR0lOWF9CQVNFIgoJCX0sCgkJImFwcGxpY2F0aW9uTGFuZ3VhZ2UiOiAidXRmLTgiLAoJCSJlbmZvcmNlbWVudE1vZGUiOiAiYmxvY2tpbmciCgl9Cn0=" -} -``` - -{{< /details >}} - -{{< details summary="JSON response" >}} - -```json -{ - "metadata": { - "created": "2022-04-10T23:19:58.502Z", - "description": "string", - "displayName": "Ignore cross-site scripting", - "modified": "2022-04-12T23:19:58.502Z", - "name": "ignore-cross-site-scripting", - "revisionTimestamp": "2022-04-12T23:19:58.502Z", - "uid": "" - }, - "selfLink": { - "rel": "/api/platform/v1/services/environments/prod" - } -} -``` - -{{< /details >}} - -{{%/tab%}} - -{{}} - -## Update a security policy - -To update a security policy, send a `POST` or `PUT` request to the Security Policies API. - -- Use `POST` with the `isNewRevision=true` parameter to add a new version of an existing policy. -- Use `PUT` with the policy UID to overwrite the existing version. - -| Method | Endpoint | -|--------|---------------------------------------------------------| -| POST | `/api/platform/v1/security/policies?isNewRevision=true` | -| PUT | `/api/platform/v1/security/policies/{system_id_string}` | - -To use `POST`, include the policy metadata and content in your request: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @update-xss-policy.json -``` - -To use PUT, first retrieve the policy’s unique identifier (UID). You can do this by sending a GET request to the policies endpoint: - -```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " -``` - -Then include the UID in your PUT request: - -```shell -curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ - -H "Authorization: Bearer " \ - -H "Content-Type application/json" \ - -d @update-xss-policy.json -``` - -After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. - -## Delete a security policy - -{{}} - -{{%tab name="web interface"%}} - -To delete a security policy using the NGINX Instance Manager web interface: - -1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, find the policy you want to delete. -5. Select the **Actions** menu (**...**) and choose **Delete**. - - -{{%/tab%}} - -{{%tab name="API"%}} - -To delete a security policy using the REST API: - -1. Retrieve the UID for the policy by sending a `GET` request to the policies endpoint: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " - ``` - -2. Send a `DELETE` request using the policy UID: - -| Method | Endpoint | -|--------|------------------------------------------------------------| -| DELETE | `/api/platform/v1/security/policies/{security-policy-uid}` | - -Example: - -```shell -curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ - -H "Authorization: Bearer " -``` - -{{%/tab%}} - -{{}} - -## Create security policy bundles {#create-security-policy-bundles} - -To create a security policy bundle, send a `POST` request to the Security Policy Bundles API. The policies you want to include in the bundle must already exist in NGINX Instance Manager. - -Each bundle includes: - -- A security policy -- Attack signatures -- Threat campaigns -- A version of F5 WAF for NGINX -- Supporting files required to compile and deploy the bundle - -### Required fields - -- `appProtectWAFVersion`: The version of F5 WAF for NGINX to target. -- `policyName`: The name of the policy to include. Must reference an existing policy. -- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. - -If you don’t include `attackSignatureVersionDateTime` or `threatCampaignVersionDateTime`, the latest versions are used by default. You can also set them explicitly by using `"latest"` as the value. - -| Method | Endpoint | -|--------|----------------------------------------------| -| POST | `/api/platform/v1/security/policies/bundles` | - -Example: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @security-policy-bundles.json -``` - -{{< details summary="JSON request" >}} - -```json -{ - "bundles": [{ - "appProtectWAFVersion": "4.457.0", - "policyName": "default-enforcement", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.06.20", - "threatCampaignVersionDateTime": "2023.07.18" - }, - { - "appProtectWAFVersion": "4.279.0", - "policyName": "default-enforcement", - "attackSignatureVersionDateTime": "latest", - "threatCampaignVersionDateTime": "latest" - }, - { - "appProtectWAFVersion": "4.457.0", - "policyName": "ignore-xss" - } - ] -} -``` - -{{< /details >}} - -{{< details summary="JSON response" >}} - -```json -{ - "items": [{ - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.457.0", - "policyName": "default-enforcement", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.06.20", - "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiling", - "message": "" - } - }, - { - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.279.0", - "policyName": "default-enforcement", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.08.10", - "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiling", - "message": "" - } - }, - { - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.457.0", - "policyName": "ignore-xss", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.08.10", - "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiling", - "message": "" - } - } - ] -} -``` - -{{< /details >}} - -## List security policy bundles {#list-security-policy-bundles} - -To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. - -You’ll only see bundles you have `"READ"` permissions for. - -You can use the following query parameters to filter results: - -- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. -- `policyName`: Return only bundles that match this policy name. -- `policyUID`: Return only bundles that match this policy UID. -- `startTime`: Return only bundles modified at or after this time. -- `endTime`: Return only bundles modified before this time. - -If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. - -| Method | Endpoint | -|--------|----------------------------------------------| -| GET | `/api/platform/v1/security/policies/bundles` | - -Example: - -```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ - -H "Authorization: Bearer " -``` - -{{< details summary="JSON response" >}} - -```json -{ - "items": [{ - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.457.0", - "policyName": "default-enforcement", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.06.20", - "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiled", - "message": "" - } - }, - { - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.279.0", - "policyName": "defautl-enforcement", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.08.10", - "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiled", - "message": "" - } - }, - { - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.457.0", - "policyName": "ignore-xss", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.08.10", - "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" - }, - "content": "", - "compilationStatus": { - "status": "compiling", - "message": "" - } - } - ] -} -``` - -{{< /details >}} - -## Get a security policy bundle {#get-security-policy-bundle} - -To retrieve a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. - -You must have `"READ"` permission for the bundle to retrieve it. - -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | - -Example: - -```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ - -H "Authorization: Bearer " -``` - -The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file. - -Example: - -```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ - -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz -``` - -{{< details summary="JSON response" >}} - -```json -{ - "metadata": { - "created": "2023-10-04T23:19:58.502Z", - "modified": "2023-10-04T23:19:58.502Z", - "appProtectWAFVersion": "4.457.0", - "policyUID": "", - "attackSignatureVersionDateTime": "2023.08.10", - "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" - }, - "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", - "compilationStatus": { - "status": "compiled", - "message": "" - } -} -``` - -{{< /details >}} - -## Create a security log profile {#create-security-log-profile} - -To upload a new security log profile, send a `POST` request to the Security Log Profiles API endpoint. - -You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. - -| Method | Endpoint | -|--------|-----------------------------------------| -| POST | `/api/platform/v1/security/logprofiles` | - -Example: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @default-log-example.json -``` - -{{< details summary="JSON request" >}} - -```json -{ - "metadata": { - "name": "default-log-example" - }, - "content": "Cgl7CgkJImZpbHRlciI6IHsKCQkJInJlcXVlc3RfdHlwZSI6ICJpbGxlZ2FsIgoJCX0sCgkJImNvbnRlbnQiOiB7CgkJCSJmb3JtYXQiOiAiZGVmYXVsdCIsCgkJCSJtYXhfcmVxdWVzdF9zaXplIjogImFueSIsCgkJCSJtYXhfbWVzc2FnZV9zaXplIjogIjVrIgoJCX0KCX0=" -} -``` - -{{< /details >}} - -{{< details summary="JSON response" >}} - -```json -{ - "metadata": { - "created": "2023-07-05T22:09:19.634358096Z", - "externalIdType": "", - "modified": "2023-07-05T22:09:19.634358096Z", - "name": "default-log-example", - "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", - "uid": "" - }, - "selfLink": { - "rel": "/api/platform/v1/security/logprofiles/" - } -} -``` - -{{< /details >}} - -## Update a security log profile {#update-security-log-profile} - -To update a security log profile, you can either: - -- Use `POST` with the `isNewRevision=true` parameter to add a new version. -- Use `PUT` with the log profile UID to overwrite the existing version. - -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | -| PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | - -To create a new revision: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @update-default-log.json -``` - -To overwrite an existing security log profile: - -1. Retrieve the profile’s UID: - - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - -H "Content-Type application/json" \ - -d @update-log-profile.json - ``` - -2. Use the UID in your PUT request: - - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @update-log-profile.json - ``` - -After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. - -## Delete a security log profile {#delete-security-log-profile} - -To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. - -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | - - -1. Retrieve the UID: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ - -H "Authorization: Bearer " - ``` - -2. Send the delete request: - - ```shell - curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " - ``` - -## Publish updates to instances {#publish-policy} - -Use the Publish API to push security policies, log profiles, attack signatures, and threat campaigns to NGINX instances or instance groups. - -Call this endpoint *after* you've created or updated the resources you want to deploy. - -| Method | Endpoint | -|--------|-------------------------------------| -| POST | `/api/platform/v1/security/publish` | - -Include the following information in your request, depending on what you're publishing: - -- Instance and instance group UIDs -- Policy UID and name -- Log profile UID and name -- Attack signature library UID and version -- Threat campaign UID and version - -Example: - -```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @publish-request.json -``` - -{{< details summary="JSON request" >}} - -```json -{ - "publications": [ - { - "instances": [ - "" - ], - "instanceGroups": [ - "" - ], - "policyContent": { - "name": "example-policy", - "uid": "" - }, - "logProfileContent": { - "name": "example-log-profile", - "uid": "" - }, - "attackSignatureLibrary": { - "uid": "", - "versionDateTime": "2023.10.02" - }, - "threatCampaign": { - "uid": "", - "versionDateTime": "2023.10.01" - } - } - ] -} -``` - -{{< /details >}} - -{{< details summary="JSON response" >}} - -```json -{ - "deployments": [ - { - "deploymentUID": "ddc781ca-15d6-46c9-86ea-e7bdb91e8dec", - "links": { - "rel": "/api/platform/v1/security/deployments/ddc781ca-15d6-46c9-86ea-e7bdb91e8dec" - }, - "result": "Publish security content request Accepted" - } - ] -} -``` - -{{< /details >}} - -## Check security policy and security log profile publication status {#check-publication-status} - -After publishing updates, you can check deployment status using the NGINX Instance Manager REST API. - -Use the following endpoints to verify whether the configuration updates were successfully deployed to instances or instance groups. - -### Check publication status for a security policy - -To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. - -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | - -Example: - -```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ - -H "Authorization: Bearer " -``` - -In the response, look for the `lastDeploymentDetails` field under instance or `instanceGroup.instances`. - - -### Check publication status for a security log profile - -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | - -Example: - -```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ - -H "Authorization: Bearer " -``` - -The response also contains `lastDeploymentDetails` for each instance or group. - -### Check status for a specific instance - -You can also view the deployment status for a specific instance by providing the system UID and instance UID. - -| Method | Endpoint | -|--------|------------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | - -Example: - -```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ - -H "Authorization: Bearer " -``` - -In the response, look for the `lastDeploymentDetails` field, which shows the deployment status and any related errors. - -### Check deployment result by deployment ID - -When you use the Publish API to [publish security content](#publish-policy), NGINX Instance Manager creates a deployment ID for the request. You can use this ID to check the result of the publication. - -| Method | Endpoint | -|--------|------------------------------------------------------------------| -| GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | - -Example: - -```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ - -H "Authorization: Bearer " -``` - -The response includes the full deployment status, success or failure details, and any compiler error messages. diff --git a/content/nim/nginx-app-protect/security-monitoring/_index.md b/content/nim/nginx-app-protect/security-monitoring/_index.md deleted file mode 100644 index e03c962d2..000000000 --- a/content/nim/nginx-app-protect/security-monitoring/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Security Monitoring -weight: 500 -url: /nginx-instance-manager/nginx-app-protect/security-monitoring/ ---- diff --git a/content/nim/nginx-app-protect/security-monitoring/update-signatures.md b/content/nim/nginx-app-protect/security-monitoring/update-signatures.md deleted file mode 100644 index a16cc0573..000000000 --- a/content/nim/nginx-app-protect/security-monitoring/update-signatures.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Update the Attack Signature Database -weight: 300 -toc: true -type: how-to -product: NIM -nd-docs: DOCS-1109 ---- - -## Overview - -The F5 NGINX Security Monitoring module tracks security violations on F5 WAF for NGINX instances. Its analytics dashboards use a Signature Database to provide details about Attack Signatures, including their name, accuracy, and risk. - -If the Signature Database is outdated and doesn’t match the version used in F5 WAF for NGINX, new signatures may appear without attributes like a name, risk, or accuracy. - -Follow these steps to update the Security Monitoring module with the latest Attack Signature data, ensuring the dashboards display complete and accurate information. - -## Before you begin - -Ensure the following prerequisites are met: - -- F5 WAF for NGINX is configured, and the Security Monitoring dashboard is collecting security violations. - -## Update the Signature Database - -1. Open an SSH connection to the data plane host and log in. -1. Generate a Signature Report file using the [Attack Signature Report Tool]({{< ref "/waf/policies/attack-signatures.md" >}}). Save the file as `signature-report.json`: - - ```shell - sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json - ``` - -1. Open an SSH connection to the management plane host and log in. -1. Copy the `signature-report.json` file to the NGINX Instance Manager control plane at `/usr/share/nms/sigdb/`: - - ```bash - sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json - ``` - -1. Restart the NGINX Instance Manager services to apply the update: - - ```shell - sudo systemctl restart nms-ingestion - sudo systemctl restart nms-core - ``` diff --git a/content/nim/nginx-app-protect/setup-waf-config-management.md b/content/nim/nginx-app-protect/setup-waf-config-management.md deleted file mode 100644 index 3e6f73df3..000000000 --- a/content/nim/nginx-app-protect/setup-waf-config-management.md +++ /dev/null @@ -1,1281 +0,0 @@ ---- -title: Set up WAF configuration management -description: Learn how to set up F5 NGINX Instance Manager to manage F5 WAF for NGINX configurations, including compiler installation, security policy onboarding, and threat update management. -toc: true -weight: 200 -nd-content-type: how-to -nd-product: NIM -nd-docs: DOCS-996 ---- - -## Overview - -F5 NGINX Instance Manager helps you manage your F5 WAF for NGINX configurations, making it easier to stay secure. This guide walks you through how to set up NGINX Instance Manager to configure and manage F5 WAF for NGINX. - -### Before you begin - -Make sure you've completed the following prerequisites before you get started: - -- You have one or more [F5 WAF for NGINX]({{< ref "/waf/" >}}) instances running. For supported versions, see [Support for F5 WAF for NGINX]({{< ref "/nim/fundamentals/tech-specs.md#support-for-nginx-app-protect-waf" >}}). - - {{< call-out "note" >}}If you're using configuration management and Security Monitoring, follow the steps in the [setup guide]({{< ref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md" >}}) to set up your F5 WAF for NGINX instances first.{{< /call-out >}} - -- You're running NGINX Instance Manager v2.6.0 or later. Make sure it's [installed]({{< ref "/nim/deploy/vm-bare-metal/_index.md" >}}), licensed, and running. - - If you have a subscription to F5 WAF for NGINX, you can find your license in the subscription details section of [MyF5](https://my.f5.com). - -### Limitations - -NGINX Instance Manager doesn’t support the following F5 WAF for NGINX features: - -- [Policies with external references]({{< ref "/waf/policies/external-references.md" >}}) -- Custom signatures - -## Install the WAF compiler - -NGINX Instance Manager can use the WAF compiler to precompile security configurations before deploying them to F5 WAF for NGINX instances. Precompiling configurations improves performance and reduces the risk of runtime errors. - -Install the WAF compiler on the NGINX Instance Manager host only if you plan to compile configurations on the management plane. If you’ll compile on the data plane, you can skip this step. - -Each version of F5 WAF for NGINX has a matching WAF compiler version. If you're managing multiple versions, install the corresponding WAF compiler for each one on the NGINX Instance Manager host. - -The WAF compiler installs to the `/opt` directory. Make sure this directory has the correct permissions so the owner can write to it. A permission setting like `0755` is typically sufficient. - -To keep track of instances running the same version, you can create [instance groups]({{< ref "/nim/nginx-instances/manage-instance-groups" >}}). - -For an overview of how the WAF compiler works, see the [Security bundle compilation]({{< ref "/nim/nginx-app-protect/overview-nap-waf-config-management#security-bundle" >}}) topic. - -### WAF compiler and supported F5 WAF for NGINX versions {#nap-waf-compiler-compatibility} - -The table below shows which WAF compiler version to use for each version of F5 WAF for NGINX: - -{{}} - -| F5 WAF for NGINX version | WAF compiler version | -|-------------------------------|----------------------------| -| 5.9.0 | nms-nap-compiler-v5.527.0 | -| 5.8.0 | nms-nap-compiler-v5.498.0 | -| 5.7.0 | nms-nap-compiler-v5.442.0 | -| 5.6.0 | nms-nap-compiler-v5.342.0 | -| 5.5.0 | nms-nap-compiler-v5.264.0 | -| 5.4.0 | nms-nap-compiler-v5.210.0 | -| 5.3.0 | nms-nap-compiler-v5.144.0 | -| 5.2.0 | nms-nap-compiler-v5.48.0 | -| 5.1.0 | nms-nap-compiler-v5.17.0 | -| 4.16.0 | nms-nap-compiler-v5.498.0 | -| 4.15.0 | nms-nap-compiler-v5.442.0 | -| 4.14.0 | nms-nap-compiler-v5.342.0 | -| 4.13.0 | nms-nap-compiler-v5.264.0 | -| 4.12.0 | nms-nap-compiler-v5.210.0 | -| 4.11.0 | nms-nap-compiler-v5.144.0 | -| 4.10.0 | nms-nap-compiler-v5.48.0 | -| 4.9.0 | nms-nap-compiler-v5.17.0 | -| 4.8.1 | nms-nap-compiler-v4.815.0 | -| 4.8.0 | nms-nap-compiler-v4.762.0 | -| 4.7.0 | nms-nap-compiler-v4.641.0 | -| 4.6.0 | nms-nap-compiler-v4.583.0 | -| 4.5.0 | nms-nap-compiler-v4.457.0 | -| 4.4.0 | nms-nap-compiler-v4.402.0 | -| 4.3.0 | nms-nap-compiler-v4.279.0 | -| 4.2.0 | nms-nap-compiler-v4.218.0 | -| 4.1.0 | nms-nap-compiler-v4.100.1 | -| 4.0.0 | nms-nap-compiler-v4.2.0 | -| 3.12.2 | nms-nap-compiler-v3.1088.2 | - -{{}} - -{{< call-out "note" >}} -Beginning with v5.9.0, both the installation packages for virtual machines and those for containers are categorized under the 5.x.x tag. For previous releases, packages designed for installation on virtual machines were released as 4.x.x versions (NAP 4.15.0, NAP 4.16.0, and so on.), while packages meant for installation on containers were provided as 5.x.x versions (NAP 5.7.0, NAP 5.8.0, and so on.). -{{< /call-out >}} - -### Debian or Ubuntu - -To install the WAF compiler on Debian or Ubuntu, run the following command: - -```shell -sudo apt-get install nms-nap-compiler-v5.527.0 -``` - -If you want to install more than one version of the WAF compiler on the same system, append the `--force-overwrite` option to the install command after the first installation: - -```shell -sudo apt-get install nms-nap-compiler-v5.527.0 -o Dpkg::Options::="--force-overwrite" -``` - -{{< include "nim/nap-waf/restart-nms-integrations.md" >}} - -### RHEL 8.1 - -To install the WAF compiler on RHEL 8.1 : - -1. Download the `dependencies.repo` file to the `/etc/yum.repos.d` directory: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo - ``` - -2. Enable the CodeReady Builder repository: - - ```shell - sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms - ``` - -3. Install the WAF compiler: - - ```shell - sudo yum install nms-nap-compiler-v5.527.0 - ``` - -### RHEL 9 - -To install the WAF compiler on RHEL 9: - -1. Download the `dependencies.repo` file to the `/etc/yum.repos.d` directory: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo - ``` - -2. Enable the CodeReady Builder repository: - - ```shell - sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms - ``` - -3. Install the WAF compiler: - - ```shell - sudo yum install nms-nap-compiler-v5.527.0 - ``` - -4. {{< include "nim/nap-waf/restart-nms-integrations.md" >}} - -### Oracle Linux 8.1 - -To install the WAF compiler on Oracle Linux 8.1: - -1. Download the `dependencies.repo` file to the `/etc/yum.repos.d` directory: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo - ``` - -2. Enable the `ol8_codeready_builder` repository: - - ```shell - sudo yum-config-manager --enable ol8_codeready_builder - ``` - -3. Install the WAF compiler: - - ```shell - sudo yum install nms-nap-compiler-v5.527.0 - ``` - -4. {{< include "nim/nap-waf/restart-nms-integrations.md" >}} - -### Download from MyF5 - -If you can’t access the public NGINX repository, you can manually download the WAF compiler from [MyF5](https://my.f5.com/). - -To install the WAF compiler manually: - -1. Log in to [MyF5](https://my.f5.com). -2. Go to **Resources** > **Downloads**. -3. Select the following: - - **Group/Product Family**: **NGINX** - - **Product Line**: **NGINX App Protect** - - Choose a **Product version** that matches your environment - - Select the **Linux distribution**, **version**, and **architecture** -4. Download the appropriate `.deb` or `.rpm` WAF compiler file. -5. Transfer the file to your NGINX Instance Manager host. -6. Install the WAF compiler: - - - **Debian or Ubuntu** - - ```shell - sudo apt-get install -f /path/to/nms-nap-compiler-_focal_amd64.deb - ``` - - To install multiple versions, use: - - ```shell - sudo apt-get install -f /path/to/nms-nap-compiler-_focal_amd64.deb -o Dpkg::Options::="--force-overwrite" - ``` - - - **RHEL, CentOS, or Oracle Linux** - - ```shell - sudo yum install -f /path/to/nms-nap-compiler-_el8.ngx.x86_64.rpm - ``` - -7. {{< include "nim/nap-waf/restart-nms-integrations.md" >}} - -### Automatically download and install new WAF compiler - -After you manually install at least one version of the F5 WAF for NGINX compiler, NGINX Instance Manager can automatically download and install additional versions as needed. - -This typically happens when: - -- A managed instance is upgraded to a new F5 WAF for NGINX version. -- You add a new instance running a different version of F5 WAF for NGINX. - -To enable this automatic download feature, you need to [upload your F5 WAF for NGINX certificate and key](#upload-the-nginx-app-protect-waf-certificate-and-key) to NGINX Instance Manager. This step allows Instance Manager to securely connect to the NGINX package repository and retrieve the necessary files. You only need to upload the certificate and key once. - -If the certificate is missing or invalid, or if NGINX Instance Manager can’t connect to the repository, you’ll see an error like: - -```text -missing the specific compiler, please install it and try again. -``` - -This usually means the certificate and key are missing or incorrect, or that NGINX Instance Manager can’t connect to the NGINX repository. - -Check the log file for errors: - -```text -/var/log/nms/nms.log -``` - -If you see the following message, your certificate and key might be invalid or expired: - -```text -error when creating the nginx repo retriever - NGINX repo certificates not found -``` - -If needed, you can also [install the WAF compiler manually](#install-the-waf-compiler). - -## Install or update the WAF compiler in a disconnected environment - -To install the WAF compiler on a system without internet access, complete these steps: - -- **Step 1:** Generate the WAF compiler package on a system that has internet access. -- **Step 2:** Move the generated package to the offline target system and install it. - -Note : Version of NAP compiler can be referred from the table at the top of this page. -Current latest version 5.527.0 at the point of writing this document is used in below commands. - -{{}} - -{{%tab name="Ubuntu"%}} - -### Install on Ubuntu 24.04, 22.04 - -#### Step 1: On a system with internet access - -Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. - -```shell -sudo apt-get update -y -sudo mkdir -p /etc/ssl/nginx/ -sudo mv nginx-repo.crt /etc/ssl/nginx/ -sudo mv nginx-repo.key /etc/ssl/nginx/ - -wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ - | gpg --dearmor \ - | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null - -printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ -https://pkgs.nginx.com/nms/ubuntu $(lsb_release -cs) nginx-plus\n" | \ -sudo tee /etc/apt/sources.list.d/nms.list - -sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx -mkdir -p compiler && cd compiler -sudo apt-get update - -sudo apt-get download nms-nap-compiler-v5.527.0 -cd ../ -mkdir -p compiler/compiler.deps -sudo apt-get install --download-only --reinstall --yes --print-uris nms-nap-compiler-v5.527.0 | grep ^\' | cut -d\' -f2 | xargs -n 1 wget -P ./compiler/compiler.deps - -tar -czvf compiler.tar.gz compiler/ -``` - -#### Step 2: On the target (offline) system - -Before running the steps, make sure the OS libraries are up to date, especially `glibc`. -Move the `compiler.tar.gz` file from Step 1 to this system. - -```shell -tar -xzvf compiler.tar.gz -sudo dpkg -i ./compiler/compiler.deps/*.deb -sudo dpkg -i ./compiler/*.deb -``` - -{{%/tab%}} - -{{%tab name="Debian"%}} - -### Install on Debian 11 and 12 - -#### Step 1: On a system with internet access - -Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. - -```shell -sudo apt-get update -y -sudo mkdir -p /etc/ssl/nginx/ -sudo mv nginx-repo.crt /etc/ssl/nginx/ -sudo mv nginx-repo.key /etc/ssl/nginx/ - -wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ - | gpg --dearmor \ - | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null - -printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ -https://pkgs.nginx.com/nms/debian $(lsb_release -cs) nginx-plus\n" | \ -sudo tee /etc/apt/sources.list.d/nms.list - -sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx -mkdir -p compiler && cd compiler -sudo apt-get update - -sudo apt-get download nms-nap-compiler-v5.527.0 - -cd ../ -mkdir -p compiler/compiler.deps -sudo apt-get install --download-only --reinstall --yes --print-uris nms-nap-compiler-v5.527.0 | grep ^\' | cut -d\' -f2 | xargs -n 1 wget -P ./compiler/compiler.deps -tar -czvf compiler.tar.gz compiler/ -``` - -#### Step 2: On the target (offline) system - -Before running the steps, make sure the OS libraries are up to date, especially `glibc`. -Move the `compiler.tar.gz` file from Step 1 to this system. - -```shell -tar -xzvf compiler.tar.gz -sudo dpkg -i ./compiler/compiler.deps/*.deb -sudo dpkg -i ./compiler/*.deb -``` - -{{%/tab%}} - -{{%tab name="RHEL9, Oracle-9 "%}} - -### Install on RHEL 9 or Oracle Linux 9 - -#### Step 1: On a system with internet access - -> For RHEL 8, you can skip the `yum-config-manager` line. - -Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. - -```shell -sudo yum update -y -sudo yum install yum-utils -y -sudo mkdir -p /etc/ssl/nginx/ -sudo mv nginx-repo.crt /etc/ssl/nginx/ -sudo mv nginx-repo.key /etc/ssl/nginx/ -sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo -sudo yum-config-manager --disable rhel-9-appstream-rhui-rpms -sudo yum update -y -sudo mkdir -p nms-nap-compiler - -sudo yumdownloader --resolve --destdir=nms-nap-compiler nms-nap-compiler-v5.527.0 -tar -czvf compiler.tar.gz nms-nap-compiler/ -``` - -#### Step 2: On the target (offline) system - -Before running the steps, make sure the OS libraries are up to date, especially `glibc`. -Move the `compiler.tar.gz` file from Step 1 to this system. - -```shell -tar -xzvf compiler.tar.gz -cd nms-nap-compiler -sudo dnf install *.rpm --disablerepo=* -``` - -{{%/tab%}} - -{{%tab name="Redhat-8, Oracle-8"%}} - -### Install on RHEL-8 or Oracle Linux 8 - -#### Step 1: On a system with internet access - -Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. - -```shell -sudo yum update -y -sudo yum install yum-utils tar -y -sudo mkdir -p /etc/ssl/nginx/ -sudo mv nginx-repo.crt /etc/ssl/nginx/ -sudo mv nginx-repo.key /etc/ssl/nginx/ -sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo - -sudo tee /etc/yum.repos.d/centos-vault-powertools.repo << 'EOF' -[centos-vault-powertools] -name=CentOS Vault - PowerTools -baseurl=https://vault.centos.org/centos/8/PowerTools/x86_64/os/ -enabled=1 -gpgcheck=0 -EOF - -sudo yum update -y -sudo mkdir -p nms-nap-compiler - -sudo yumdownloader --resolve --destdir=nms-nap-compiler nms-nap-compiler-v5.527.0 -tar -czvf compiler.tar.gz nms-nap-compiler/ -``` - -#### Step 2: On the target (offline) system - -Before running the steps, make sure the OS libraries are up to date, especially `glibc`. -Move the `compiler.tar.gz` file from Step 1 to this system. - -```shell -sudo yum install tar -y -tar -xzvf compiler.tar.gz -sudo dnf install --disablerepo=* nms-nap-compiler/*.rpm -``` - -{{%/tab%}} - -{{}} - -## Set up attack signatures and threat campaigns - -F5 WAF for NGINX protects your applications using predefined and regularly updated detection patterns: - -- **Attack signatures**: Known threat patterns used to detect common vulnerabilities and exploits. These are included with F5 WAF for NGINX and updated frequently to reflect the latest security threats. See the [attack signatures documentation]({{< ref "/waf/policies/attack-signatures.md" >}}) for more information. - -- **Threat campaigns**: Context-aware threat intelligence based on attack campaigns observed by F5 Threat Labs. These are updated even more frequently than attack signatures and require installation to take effect. Learn more in the [threat campaigns documentation]({{< ref "/waf/policies/threat-campaigns.md" >}}). - -To take advantage of the latest updates, you must upload the attack signature and threat campaign packages to NGINX Instance Manager. - -You can either: - -- Configure NGINX Instance Manager to automatically download new versions, or -- Manually download packages from MyF5 and upload them to NGINX Instance Manager using the REST API. - -### Automatically Download Latest Packages {#automatically-download-latest-packages} - -#### Upload the F5 WAF for NGINX certificate and key - -To enable automatic downloads, NGINX Instance Manager must authenticate with the NGINX repository. You do this by uploading the NGINX repository certificate and private key that come with your F5 WAF for NGINX subscription. Once uploaded, NGINX Instance Manager can securely retrieve the latest attack signature and threat campaign packages on your behalf. - -Follow these steps to get and upload the certificate and key: - -1. Log in to [MyF5](https://account.f5.com/myf5). -2. Go to **My Products and Plans > Subscriptions**. -3. Download the following files from your F5 WAF for NGINX subscription: - - `nginx-repo.crt` (certificate) - - `nginx-repo.key` (private key) -4. Create a JSON file that includes the contents of both files. Replace newlines (`\n`) in each file with literal `\n` characters so the certificate and key can be formatted correctly inside the JSON. - - {{< details summary="Example request" >}} - - ```json - { - "name": "nginx-repo", - "nginxResourceType": "NginxRepo", - "certPEMDetails": { - "caCerts": [], - "password": "", - "privateKey": "-----BEGIN PRIVATE KEY-----\n[content snipped]\n-----END PRIVATE KEY-----\n", - "publicCert": "-----BEGIN CERTIFICATE-----\n[content snipped]\n-----END CERTIFICATE-----", - "type": "PEM" - } - } - ``` - - {{< /details >}} - -5. Upload the file to NGINX Instance Manager using the REST API: - - ```shell - curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/certs' \ - --header "Authorization: Bearer " \ - --header "Content-Type: application/json" \ - -d @nginx-repo-certs.json - ``` - -6. If successful, you should see a response similar to this: - - {{< details summary="Example response" >}} - - ```json - { - "certAssignmentDetails": [], - "certMetadata": [ - { - "authorityKeyIdentifier": "", - "commonName": "", - "expired": false, - "expiry": 59789838, - "issuer": "C=US, ST=Washington, L=Seattle, Inc., O=F5 Networks\\, OU=Certificate Authority, CN=F5 PRD Issuing Certificate Authority TEEM V1", - "publicKeyType": "RSA (2048 bit)", - "serialNumber": "", - "signatureAlgorithm": "SHA256-RSA", - "subject": "CN=", - "subjectAlternativeName": "", - "subjectKeyIdentifier": "", - "thumbprint": "", - "thumbprintAlgorithm": "SHA256-RSA", - "validFrom": "2021-12-21T16:57:55Z", - "validTo": "2024-12-20T00:00:00Z", - "version": 3 - } - ], - "certPEMDetails": { - "caCerts": [], - "password": "**********", - "privateKey": "**********", - "publicCert": "[content snipped]", - "type": "PEM" - }, - "created": "2023-01-27T23:42:41.587760092Z", - "modified": "2023-01-27T23:42:41.587760092Z", - "name": "nginx-repo", - "serialNumber": "", - "uid": "d08d9f54-58dd-447a-a71d-6fa5aa0d880c", - "validFrom": "2021-12-21T16:57:55Z", - "validTo": "2024-12-20T00:00:00Z" - } - ``` - - {{< /details >}} - -#### Enable automatic downloads - -NGINX Instance Manager can automatically download the latest Attack Signatures and Threat Campaign versions. To enable automatic downloads: - -1. Log in to the NGINX Instance Manager host using SSH. - -2. Open the `/etc/nms/nms.conf` file in a text editor. - -3. Adjust the `app_protect_security_update` settings, as shown in the example below: - - ```yaml - integrations: - # enable this for integrations on tcp - # address: 127.0.0.1:8037 - address: unix:/var/run/nms/integrations.sock - dqlite: - addr: 127.0.0.1:7892 - app_protect_security_update: - # enable this to automatically retrieve the latest Attack Signatures and Threat Campaigns - enable: true - # how often, in hours, to check for updates; default is 6 - interval: 6 - # how many updates to download; default is 10, max is 20 - number_of_updates: 10 - ``` - -4. Save the changes and close the file. - -5. {{< include "/nim/nap-waf/restart-nms-integrations.md" >}} - -If the F5 WAF for NGINX certificate and key are missing, invalid, or expired, you’ll see the following error: - -```text -error when creating the nginx repo retriever - NGINX repo certificates not found -``` - -This means NGINX Instance Manager can’t connect to the NGINX repository to retrieve the packages. You may need to re-upload a valid certificate and key to resolve the issue. - -### Manually update packages - -If you prefer not to enable automatic updates, you can manually update the Attack Signature and Threat Campaign packages by downloading them from NGINX repository and uploading them to NGINX Instance Manager. - -#### Download packages from NGINX Repository - -1. Log in to [MyF5](https://account.f5.com/myf5) and then go to **My Products and Plans > Subscriptions**. - -2. Download the following files from your F5 WAF for NGINX subscription: - - `nginx-repo.crt` (certificate) - - `nginx-repo.key` (private key) - -3. Chose the following options while downloading the packages from the [NGINX repository](https://pkgs.nginx.com/app-protect-security-updates): - - Select your **Linux Distribution** path. - - For **Ubuntu**: /ubuntu/pool/nginx-plus/a/ - - For **Debian**: /debian/pool/nginx-plus/a/ - - For **RHEL**: /centos/<8 or 9>/x86_64/RPMS/ - -4. Download the `.deb` or `.rpm` packages from https://pkgs.nginx.com using your F5 WAF for NGINX cert and key: - - For Attack Signatures: package starts with `app-protect-attack-signatures` - - Format for `.deb` package: - - ```text - https://pkgs.nginx.com/app-protect-security-updates//pool/nginx-plus/a/app-protect-attack-signatures/app-protect-attack-signatures_-~_amd64.deb - ``` - - - Example for `.deb` download: - - ```shell - curl --key nginx-repo.key --cert nginx-repo.crt https://pkgs.nginx.com/app-protect-security-updates/ubuntu/pool/nginx-plus/a/app-protect-attack-signatures/app-protect-attack-signatures_2025.07.24-1~noble_amd64.deb --output app-protect-attack-signatures_2025.07.24-1~noble_amd64.deb - ``` - - - Format for `.rpm` package: - - ```text - https://pkgs.nginx.com/app-protect-security-updates/centos/<8 or 9>/x86_64/RPMS/app-protect-attack-signatures--.el<8 or 9>.ngx.x86_64.rpm - ``` - - - Example for `.rpm` download: - - ```shell - curl -v --key nginx-repo.key --cert nginx-repo.crt https://pkgs.nginx.com/app-protect-security-updates/centos/8/x86_64/RPMS/app-protect-attack-signatures-2025.07.24-1.el8.ngx.x86_64.rpm --output app-protect-attack-signatures-2025.07.24-1.el8.ngx.x86_64.rpm - ``` - - - For Threat Campaigns: package starts with `app-protect-threat-campaigns` - - Format for `.deb` package: - - ```text - https://pkgs.nginx.com/app-protect-security-updates//pool/nginx-plus/a/app-protect-threat-campaigns/app-protect-threat-campaigns_-~_amd64.deb - ``` - - - Example for `.deb` download: - - ```shell - curl --key nginx-repo.key --cert nginx-repo.crt https://pkgs.nginx.com/app-protect-security-updates/ubuntu/pool/nginx-plus/a/app-protect-threat-campaigns/app-protect-threat-campaigns_2025.07.29-1~noble_amd64.deb --output app-protect-threat-campaigns_2025.07.29-1~noble_amd64.deb - ``` - - - Format for `.rpm` package: - - ```text - https://pkgs.nginx.com/app-protect-security-updates/centos/<8 or 9>/x86_64/RPMS/app-protect-threat-campaigns--.el<8 or 9>.ngx.x86_64.rpm - ``` - - - Example for `.rpm` download: - - ```shell - curl -v --key nginx-repo.key --cert nginx-repo.crt https://pkgs.nginx.com/app-protect-security-updates/centos/8/x86_64/RPMS/app-protect-threat-campaigns-2025.07.29-1.el8.ngx.x86_64.rpm --output app-protect-threat-campaigns-2025.07.29-1.el8.ngx.x86_64.rpm - ``` - -5. Extract the following three files from the package: - - `signatures.bin.tgz` (or `threat_campaigns.bin.tgz`) - - `signature_update.yaml` (or `threat_campaign_update.yaml`) - - `version` - - Use tools like `rpm2cpio | cpio` or `ar` (for `.deb`) to extract the files. - -6. Create a `.tgz` bundle that includes the three files. For example: - - ```shell - tar -czvf attack-signatures.tgz signatures.bin.tgz signature_update.yaml version - ``` - -#### Upload packages to NGINX Instance Manager - -Use the NGINX Instance Manager REST API to upload the `.tgz` files. - -**Upload Attack Signatures:** - -```shell -curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \ - --header "Authorization: Bearer " \ - --form 'revisionTimestamp="2022.11.16"' \ - --form 'filename=@"/attack-signatures.tgz"' -``` - -**Upload Threat Campaigns:** - -```shell -curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/threat-campaigns' \ - --header "Authorization: Bearer " \ - --form 'revisionTimestamp="2022.11.15"' \ - --form 'filename=@"/threat-campaigns.tgz"' -``` - -{{< call-out "important" >}}The bundle you upload must match the OS of your NGINX Instance Manager host. For example, if the host is running Ubuntu 20.04, create the `.tgz` from the Ubuntu 20.04 package.{{< /call-out >}} - -### Update the Security Monitoring signature database - -The Security Monitoring dashboards in NGINX Instance Manager rely on a Signature Database to show more information about triggered security violations, such as the signature's name, accuracy, and risk level. - -To keep the dashboards accurate and up to date, you need to update the Security Monitoring signature database. - -For instructions, see the [update signatures guide]({{< ref "/nim/nginx-app-protect/security-monitoring/update-signatures.md" >}}). - -## Set up compiler resource pruning - -You can configure NGINX Instance Manager to automatically remove unused compiler resources: - -- Compiled security policies -- Compiled security log profiles -- Attack Signatures -- Threat Campaigns - -Only the compiled bundles are removed. NGINX Instance Manager does not delete the definitions for security policies or log profiles. - -To enable compiler resource pruning: - -1. Log in to the NGINX Instance Manager host using SSH. -1. Open the `/etc/nms/nms.conf` file in a text editor. -1. Update the `policy_manager` section under `integrations` with time-to-live (TTL) values for each resource type: - - ```yaml - integrations: - address: unix:/var/run/nms/integrations.sock - dqlite: - addr: 127.0.0.1:7892 - policy_manager: - # Time to live for attack signatures. If the attack signatures exceed their TTL and are not - # deployed to an instance or instance group, they will be deleted from the database. - # Duration unit can be seconds (s), minutes (m), or hours (h). - attack_signatures_ttl: 336h - - # Time to live for compiled bundles, including compiled security policies and log profiles. - # If a compiled bundle exceeds its TTL and is not deployed to an instance or instance group, - # it will be deleted from the database. The bundle is deleted, not the resource definition. - compiled_bundles_ttl: 336h - - # Time to live for threat campaigns. If the threat campaigns exceed their TTL and are not - # deployed to an instance or instance group, they will be deleted from the database. - threat_campaigns_ttl: 1440h - - app_protect_security_update: - enable: true - interval: 6 - number_of_updates: 10 - ``` - -4. Save the file and close the editor. -5. {{< include "nim/nap-waf/restart-nms-integrations.md" >}} - -NGINX Instance Manager runs the pruning process at startup and every 24 hours after the `nms-integrations` service starts. - -## Onboard F5 WAF for NGINX instances - -To onboard your F5 WAF for NGINX instances to NGINX Instance Manager, install and configure the NGINX Agent on each instance. - -### Install NGINX Agent - -1. Use SSH to connect to the F5 WAF for NGINX instance. Repeat these steps for each instance you want to onboard. - -2. Download the NGINX Agent package from the NGINX Instance Manager host and run the installation script. - - You can group instances that use the same version of F5 WAF for NGINX by using the optional `--instance-group` flag in the install command. - - {{< include "agent/installation/install-agent-api.md" >}} - -### Configure NGINX Agent - -1. Edit the NGINX Agent configuration file to enable support for F5 WAF for NGINX: - - ```shell - sudo vi /etc/nginx-agent/nginx-agent.conf - ``` - -2. Update or confirm the following settings: - - ```yaml - config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" - extensions: - - nginx-app-protect - nginx_app_protect: - report_interval: 15s - precompiled_publication: true - ``` - - These settings: - - - Allow the agent to access F5 WAF for NGINX configuration directories. - - Enable the agent to detect changes in security configurations. - - Enable support for precompiled publication of WAF configurations from NGINX Instance Manager. - - You can also apply these settings automatically during installation by using the `--nginx-app-protect-mode` flag: - - ```shell - curl https:///install/nginx-agent > install.sh - sudo sh ./install.sh --nginx-app-protect-mode precompiled-publication - ``` - -3. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -### Verify installation - -After installing and configuring the NGINX Agent, verify that your F5 WAF for NGINX instances appear in NGINX Instance Manager. - -{{}} - -{{%tab name="UI"%}} - -You should now be able to view your F5 WAF for NGINX instances in the Instance Manager user interface. Take the steps below to verify that NGINX Agent is installed and reporting data to Instance Manager. - -1. {{< include "nim/webui-nim-login.md" >}} -2. In the left menu, select **Instances**. -3. Confirm that each instance shows an F5 WAF for NGINX version in the **NGINX App Protect** column. -4. Select an instance and scroll to the **App Protect Details** section to confirm status and build information. - -{{%/tab%}} - -{{%tab name="API"%}} - -{{< call-out "note" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{< /call-out>}} - -Use the REST API to confirm the version and status of F5 WAF for NGINX: - -| Method | Endpoint | -|--------|------------------------------| -| GET | `/api/platform/v1/instances` | -| GET | `/api/platform/v1/systems` | - -- Send a `GET` request to `/api/platform/v1/systems` to check version info: - - **Example response:** - - ```json - { - "count": 3, - "items": [ - { - "appProtect": { - "attackSignatureVersion": "2022.11.16", - "status": "active", - "threatCampaignVersion": "2022.11.15", - "version": "build-3.954.0" - } - } - ] - } - ``` - -- Send a `GET` request to `/api/platform/v1/instances` to check how many instances have F5 WAF for NGINX installed: - - **Example response:** - - ```json - { - "count": 3, - "items": [ - [...] - ], - "nginxAppProtectWAFCount": 2, - "nginxPlusCount": 3 - } - ``` - -{{%/tab%}} -{{}} - -### Configure Docker Compose for F5 WAF for NGINX v5 - -#### Before you begin - -Before configuring Docker Compose, make sure you’ve completed the following steps: - -- Installed F5 WAF for NGINX using the [official installation guide]({{< ref "/waf/install/docker.md" >}}). -- Created a `docker-compose.yaml` file during the installation process. - -This section explains how to modify that file so F5 WAF for NGINX can work with NGINX Instance Manager. - -#### Edit the Docker Compose file - -1. Edit the `docker-compose.yaml` file created during installation. - - To give F5 WAF for NGINX access to the policy and log profile bundles written by NGINX Instance Manager, make the following changes: - - - Add the line `user: 101:` to each service. The group ID should match the NGINX Agent group on your system. You can find the group ID by running: - - ```shell - cat /etc/group - ``` - - - Add `/etc/nms` to the volume maps for both services. - - **Example:** - - ```yaml - version: "3.9" - - services: - waf-enforcer: - container_name: waf-enforcer - image: private-registry.nginx.com/nap/waf-enforcer:5.2.0 - user: 101:1002 - environment: - - ENFORCER_PORT=50000 - ports: - - "50000:50000" - volumes: - - /opt/app_protect/bd_config:/opt/app_protect/bd_config - - /etc/nms:/etc/nms - networks: - - waf_network - restart: always - - waf-config-mgr: - container_name: waf-config-mgr - image: private-registry.nginx.com/nap/waf-config-mgr:5.2.0 - user: 101:1002 - 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 - - /etc/nms:/etc/nms - restart: always - network_mode: none - depends_on: - waf-enforcer: - condition: service_started - - networks: - waf_network: - driver: bridge - ``` - -2. Restart the containers: - - ```shell - docker compose restart - ``` - -## Onboard security policies {#onboard-security-policies} - -NGINX Instance Manager provides the same [default security policies](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration) as F5 WAF for NGINX: - -- **NGINX Default Policy**: Provides [OWASP Top 10](https://owasp.org/www-project-top-ten/) and Bot protection. -- **NGINX Strict Policy**: Contains more restrictive blocking criteria than the default policy. - -If you plan to use these built-in policies, you can skip to [Add WAF configuration to NGINX instances](#add-waf-config). - -If you’ve created custom security policies on your F5 WAF for NGINX instances, you can upload them to NGINX Instance Manager using the REST API. These policies must be uploaded so NGINX Instance Manager can compile and publish them across your data plane. - -### Upload custom security policies - -To upload a policy, follow these steps: - -1. Encode the JSON policy using `base64`. - - **Example:** - - ```shell - base64 -i ./ignore-xss-policy-example.json - ``` - -2. Create a JSON request that includes the base64-encoded policy from step 1 as the value for the `content` field. - - Replace the example string below with the actual base64-encoded output you generated. - - ```json - { - "metadata": { - "name": "ignore-xss-example", - "displayName": "Ignore cross-site scripting example", - "description": "Security policy that intentionally ignores cross-site scripting" - }, - "content": "" - } - ``` - -3. Send the request to the Instance Manager REST API to create the policy: - - ```shell - curl -X POST https:///api/platform/v1/security/policies \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d @policy.json - ``` - - You should receive a success response with the policy metadata. - -4. To verify that your policy was successfully onboarded, send a GET request: - - ```shell - curl -X GET https:///api/platform/v1/security/policies \ - -H "Authorization: Bearer " - ``` - - The response includes a list of all security policies managed by NGINX Instance Manager. - -## Add WAF configuration to NGINX instances {#add-waf-config} - -The [F5 WAF for NGINX configuration guide](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) shows where and how to add security directives to your NGINX configuration. NGINX Instance Manager includes the same default security policies as F5 WAF for NGINX: - -- **NGINX Default Policy**: Provides [OWASP Top 10](https://owasp.org/www-project-top-ten/) and bot protection out of the box. -- **NGINX Strict Policy**: Contains more restrictive criteria for blocking traffic, with a higher risk of false positives. - -You can use these default policies as-is or customize them for your app. Security Monitoring dashboards can help you fine-tune policy settings. - -Keep the following in mind when configuring F5 WAF for NGINX through NGINX Instance Manager: - -- Instance Manager compiles JSON security policies into `.tgz` bundles. -- Use the `app_protect_policy_file` directive to reference custom policies. - - If you're using precompiled publication with NGINX Agent, make sure to change the file extension from `.json` to `.tgz`. The filename remains the same. NGINX Instance Manager doesn't support referencing both `.json` and `.tgz` in the same NGINX configuration. - -- If you're using custom policies, make sure NGINX Agent has permission to access the directories where those policy files are stored. Update the `config_dirs` setting in the NGINX Agent's configuration file if needed. -- NGINX Instance Manager uses the default log profiles that come with F5 WAF for NGINX. You can reference them with the `app_protect_security_log` directive. Custom log profiles aren't supported. - -If you're using different directories on the data plane, update paths accordingly in your NGINX configuration. - -### Edit the NGINX configuration - -Add the F5 WAF for NGINX directives in the appropriate context (`http`, `server`, or `location`). Here's an example: - -```nginx -server { - ... - - location / { - # Enable F5 WAF for NGINX - app_protect_enable on; - - # Reference a custom security policy bundle - app_protect_policy_file /etc/nms/ignore-xss.tgz; - - # Enable security logging - app_protect_security_log_enable on; - - # Reference the log profile bundle - app_protect_security_log /etc/nms/log-default.tgz /var/log/nginx/security-violations.log; - - ... - } -} -``` - -If you’re using NGINX Instance Manager with Security Monitoring, your configuration may already include the following directive: - -```nginx -app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; -``` - -**Don’t change this value.** See the [Security Monitoring setup guide]({{< ref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md" >}}) for more details. - -If you’re using F5 WAF for NGINX v5: - -- You must add the `app_protect_enforcer_address` directive to the `http` context: - - ```nginx - app_protect_enforcer_address 127.0.0.1:50000; - ``` - -- JSON policies and log profiles aren’t supported. You must precompile and publish them using NGINX Instance Manager. Make sure the precompiled_publication setting in the NGINX Agent configuration is set to true. - - See the [F5 WAF for NGINX configuration guide]({{< ref "/waf/policies/configuration.md" >}}) for details. - -{{}} -{{%tab name="UI"%}} - -1. {{< include "nim/webui-nim-login.md" >}} -2. In the left menu, select **Instances** or **Instance Groups**. -3. From the **Actions** menu (**...**), select **Edit Config** for the instance or group. -4. If you’re using precompiled publication, change any `.json` file extensions to `.tgz`. -5. If you want to apply a default policy, select **Apply Security**, then copy the policy snippet and paste it into your configuration. -6. Add the directives inside an `http`, `server`, or `location` block. -7. Select **Publish** to push the configuration. - -{{%/tab%}} - -{{%tab name="API"%}} - -{{< call-out "note" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{< /call-out>}} - -You can use the NGINX Instance Manager REST API to deploy your F5 WAF for NGINX configuration. - -| Method | Endpoint | -|--------|---------------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{systemUID}/instances` | -| POST | `/api/platform/v1/security/{systemUID}/instances/{nginxUID}/config` | - -{{< call-out "important" >}}Before deploying a configuration to an instance group, make sure all instances in the group are running the same version of F5 WAF for NGINX. Otherwise, the deployment may fail.{{< /call-out >}} - -1. Send a `GET` request to the `/api/platform/v1/systems/{systemUID}/instances` endpoint to list all instances. This response includes the unique identifier (UID) of the instance that you want to update. - - ```shell - curl -X GET https://{{NMS_FQDN}}/api/platform/v1/systems/{systemUID}/instances \ - -H "Authorization: Bearer " - ``` - -2. Add the F5 WAF for NGINX configuration to your NGINX config file (`nginx.conf` or another config file located in a valid `config_dirs` path on the data plane host): - - - At a minimum, add the following directive: - - ```nginx - app_protect_enable on; - ``` - - - If precompiled publication is enabled, change any `.json` policy references to `.tgz`. - - If you want to apply a default policy, you can use: - - ```nginx - app_protect_policy_file /etc/nms/NginxDefaultPolicy.tgz; - ``` - - or - - ```nginx - app_protect_policy_file /etc/nms/NginxStrictPolicy.tgz; - ``` - - - Add the directives to an `http`, `server`, or `location` context. - -3. Encode the updated NGINX configuration file using base64. - - ```shell - base64 -i /etc/nginx/nginx.conf - ``` - -4. Send a `POST` request to the `/api/platform/v1/security/{systemUID}/instances/{nginxUID}/config` endpoint to deploy the configuration. Replace `` with your encoded config: - - ```shell - curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/{systemUID}/instances/{nginxUID}/config \ - -H "Authorization: Bearer " \ - --header "Content-Type: application/json" \ - -d '{ - "configFiles": { - "rootDir": "/etc/nginx", - "files": [ - { - "name": "nginx.conf", - "contents": "" - } - ] - }, - "validateConfig": true - }' - ``` - -{{%/tab%}} -{{}} - -### Verify configuration - -After you add F5 WAF for NGINX directives to your NGINX configuration, you can verify the setup in the NGINX Instance Manager web interface. - -To confirm that the F5 WAF for NGINX configuration was applied: - -1. {{< include "nim/webui-nim-login.md" >}} -2. In the left navigation menu, select **Instances**. -3. In the **NGINX App Protect** column, confirm that the correct version is listed. -4. Select the instance. Then, scroll to the **App Protect Details** section. -5. Confirm that the **F5 WAF for NGINX** status is **Active**, and the **Build** matches the version installed on the instance. - -## Troubleshooting - -If you're having trouble with F5 WAF for NGINX, try the steps below. If these don't solve the issue, reach out to F5 NGINX Customer Support. - -### Check that F5 WAF for NGINX is not installed on the NGINX Instance Manager host - -F5 WAF for NGINX and the WAF compiler shouldn't run on the same host. To check: - -1. Log in to the NGINX Instance Manager host from a terminal. -2. Run the command that matches your operating system: - - - For Debian-based systems: - - ```shell - dpkg -s app-protect - ``` - - - For RPM-based systems: - - ```shell - rpm -qi | grep app-protect - ``` - -If F5 WAF for NGINX is installed, follow the [uninstall instructions]({{< ref "/waf/install/uninstall.md" >}}). - -### Check that the WAF compiler version matches the F5 WAF for NGINX version - -Each F5 WAF for NGINX version has a matching WAF compiler version. To confirm: - -1. Log in to the NGINX Instance Manager host. -2. Run the following command to see installed compiler versions: - - ```shell - ls -l /opt/nms-nap-compiler - ``` - -### Confirm the WAF compiler is working correctly - -You can verify that the WAF compiler is installed and responding: - -```shell -sudo /opt/nms-nap-compiler/app_protect-/bin/apcompile -h -``` - -**Example:** - -```shell -sudo /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -h -``` - -**Expected output:** - -```text -USAGE: - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile - -Examples: - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -p /path/to/policy.json -o mypolicy.tgz - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -p policyA.json -g myglobal.json -o /path/to/policyA_bundle.tgz - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -g myglobalsettings.json --global-state-outfile /path/to/myglobalstate.tgz - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -b /path/to/policy_bundle.tgz --dump - /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -l logprofA.json -o /path/to/logprofA_bundle.tgz -``` - -### Confirm NGINX Agent configuration on the F5 WAF for NGINX instance - -Open the `/etc/nginx-agent/nginx-agent.conf` file and make sure it includes the right settings. - -```yaml -# List of directories the agent monitors for config files -config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" - -# Enable necessary NGINX App Protect extensions -extensions: - - nginx-app-protect - - nap-monitoring - -nginx_app_protect: - # Report interval for NGINX App Protect details — how often the agent checks for changes - report_interval: 15s - # Set to true to publish precompiled policies and log profiles from NGINX Instance Manager - precompiled_publication: true - -nap_monitoring: - # Buffer size for the collector — holds log lines and parsed entries - collector_buffer_size: 50000 - # Buffer size for the processor — processes log lines from the buffer - processor_buffer_size: 50000 - # IP address where the agent listens for syslog messages - syslog_ip: "127.0.0.1" - # Port number for receiving syslog messages - syslog_port: 514 -``` - -### Confirm access to the NGINX packages repository - -If automatic downloads for Attack Signatures or Threat Campaigns are failing, check whether the repo certificate and key are set up correctly. - -Run this command to test access: - -```shell -curl --key /etc/ssl/nginx/nginx-repo.key --cert /etc/ssl/nginx/nginx-repo.crt https://pkgs.nginx.com/app-protect-security-updates/index.xml -``` - -**Expected output:** - -```text -... - - - - - - app-protect-attack-signatures - x86_64 - - - -... -``` - -## Next steps - -Now that configuration management is set up, you can use the NGINX Instance Manager REST API to: - -- Manage F5 WAF for NGINX security policies. -- View system information about your F5 WAF for NGINX instances. -- Update Attack Signatures and Threat Campaigns. - -To learn more, see [Manage WAF Security Policies and Security Log Profiles]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md" >}}). diff --git a/content/nim/nginx-instances/add-tags.md b/content/nim/nginx-instances/add-tags.md index 737f52baa..76fa0e818 100644 --- a/content/nim/nginx-instances/add-tags.md +++ b/content/nim/nginx-instances/add-tags.md @@ -33,7 +33,7 @@ To add tags to the configuration file, take the following steps: 2. Restart the NGINX Agent service: - ```bash + ```shell sudo systemctl restart nginx-agent ``` diff --git a/content/nim/nginx-instances/manage-certificates.md b/content/nim/nginx-instances/manage-certificates.md index 6ade72cdb..ac35a3c6d 100644 --- a/content/nim/nginx-instances/manage-certificates.md +++ b/content/nim/nginx-instances/manage-certificates.md @@ -26,7 +26,7 @@ You need to create a certificate before you can add one to NGINX Instance Manage If you’re uploading a **PKCS12** certificate, make sure to encode it in base64 before adding it to NGINX Instance Manager. Use the following command to encode the certificate: - ```bash + ```shell cat .pkcs12 | base64 > .pkcs12 ``` @@ -77,7 +77,7 @@ To replace a certificate using the web interface: To replace a certificate using the NGINX Instance Manager REST API, send a `PUT` request like the following to the Certificates API endpoint: -```bash +```shell curl -X PUT "https://nginx-manager.example.com/api/platform/v1/certs/pem_cert_with_ca" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ @@ -115,7 +115,7 @@ To delete a certificate using the web interface: To delete a certificate using the NGINX Instance Manager REST API, send a `DELETE` request like the following to the Certificates API endpoint: -```bash +```shell curl -X DELETE "https://nginx-manager.example.com/api/platform/v1/certs/pem_cert_with_ca" \ -H "accept: application/json" ``` @@ -128,7 +128,7 @@ curl -X DELETE "https://nginx-manager.example.com/api/platform/v1/certs/pem_cert To convert a remote certificate to a managed certificate using the NGINX Instance Manager REST API, send a `PUT` request to the Certificates API endpoint. This request should include both the public certificate and private key, like in the following example: -```bash +```shell curl -X PUT "https://nginx-manager.example.com/api/platform/v1/certs/pem_cert_with_ca" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ @@ -160,13 +160,13 @@ To rotate the certificate encryption key: 1. Open an SSH connection to the F5 NGINX Management Suite host. 2. Run the following command to stop the `nms` service: - ```bash + ```shell sudo systemctl stop nms ``` 3. Run the following command to rotate the encryption keys: - ```bash + ```shell sudo runuser -u nms -- nms-core secret rotate ``` @@ -181,6 +181,6 @@ To rotate the certificate encryption key: 4. Now that you've rotated encryption keys, start the `nms` service: - ```bash + ```shell sudo systemctl start nms ``` diff --git a/content/nim/nginx-instances/manage-instance-groups.md b/content/nim/nginx-instances/manage-instance-groups.md index 0c07ce2e2..fb03684dc 100644 --- a/content/nim/nginx-instances/manage-instance-groups.md +++ b/content/nim/nginx-instances/manage-instance-groups.md @@ -97,7 +97,7 @@ You can easily add instances to a default instance group that you specify. To do 4. Save the changes and exit the editor. 5. Restart the NGINX Agent: - ```bash + ```shell sudo systemctl restart nginx-agent ``` @@ -118,19 +118,19 @@ To add an instance to an instance group when installing the NGINX Agent: 1. Open a secure shell (SSH) connection to the NGINX instance and log in. 2. Download the NGINX Agent installation script: - ```bash + ```shell curl https:///install/nginx-agent > install.sh ``` 3. Install the NGINX Agent and specify the instance group by using the `--instance_group` flag: - ```bash + ```shell sudo sh ./install.sh --instance-group ``` For example, the following command adds the instance to an instance group called `nginx-01`. - ```bash + ```shell sudo sh install.sh --instance-group nginx-01 ``` @@ -193,7 +193,7 @@ If the instance group you deleted was specified in the `agent-dynamic.conf` file 4. Save the changes and exit the editor. 5. Restart the NGINX Agent: - ```bash + ```shell sudo systemctl restart nginx-agent ``` diff --git a/content/nim/nginx-instances/scan-instances.md b/content/nim/nginx-instances/scan-instances.md index 64ce534eb..6a55d8f18 100644 --- a/content/nim/nginx-instances/scan-instances.md +++ b/content/nim/nginx-instances/scan-instances.md @@ -266,12 +266,12 @@ The result looks similar to the following: ## Troubleshooting -### Scan reports NGINX versions as "undefined" when NGINX App Protect is enabled +### Scan reports NGINX versions as "undefined" when F5 WAF for NGINX is enabled #### Description -- When [scanning for NGINX instances]({{< ref "/nim/nginx-instances/scan-instances.md" >}}), the NGINX version is reported as `undefined` when NGINX App Protect is installed. +- When [scanning for NGINX instances]({{< ref "/nim/nginx-instances/scan-instances.md" >}}), the NGINX version is reported as `undefined` when F5 WAF for NGINX is installed. #### Resolution -- This behavior is **by design**. As a security precaution when NGINX App Protect is installed, the NGINX server does not report its version in any HTTP headers. The **NGINX Plus** and **Instances** pages in the web interface will continue to report the NGINX and NGINX App Protect versions. +- This behavior is **by design**. As a security precaution when F5 WAF for NGINX is installed, the NGINX server does not report its version in any HTTP headers. The **NGINX Plus** and **Instances** pages in the web interface will continue to report the NGINX and F5 WAF for NGINX versions. diff --git a/content/nim/releases/known-issues.md b/content/nim/releases/known-issues.md index 5cd762ae6..e252930bd 100644 --- a/content/nim/releases/known-issues.md +++ b/content/nim/releases/known-issues.md @@ -12,16 +12,77 @@ This document lists and describes the known issues and possible workarounds in F --- +## 2.21.0 + +November 07, 2025 + +### {{% icon-bug %}} Security Monitoring dashboard doesn't load for custom users {#46763} + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Issue ID | Status | +|----------------|--------| +| 46763 | Open | +{{< /bootstrap-table >}} + +#### Description + +When you sign in using a custom user account that has: + +- read permissions for Security Monitoring +- create, read, update, and delete (CRUD) permissions for Security Policies + +the Security Monitoring dashboard shows the message: **Metrics are disabled** + +This happens even when ClickHouse is enabled. + +#### Workaround + +Add license read permission to the custom role or user. This allows the Security Monitoring dashboard to complete its license check and load as expected. + +--- + +### {{% icon-bug %}} Duplicate security policies appear during RBAC role creation when an F5 WAF for NGINX policy has more than one version {#46754} + +{{}} +| Issue ID | Status | +|----------------|--------| +| 46754 | Open | +{{}} + +#### Description + +If an F5 WAF for NGINX policy has more than one version, the same policy name may appear more than once when you’re assigning access during RBAC role creation. This happens because the system doesn’t show which version is which. + +--- + ## 2.20.0 June 16, 2025 -### {{% icon-bug %}} Failing to fetch CVE data when using forward proxy in K8s environments {#46177} +### {{% icon-bug %}} NGINX configuration editor shows errors for instance group configs created with augment templates {#46726} + +{{}} +| Issue ID | Status | +|----------------|--------| +| 46726 | Open | +{{}} + +#### Description + +The NGINX configuration editor may show errors for files in the `conf.d` directory when a configuration created with augment templates is published to an instance group. The configuration is valid, but the editor doesn’t recognize all template-generated files. + +#### Workaround + +To avoid this issue, use a standalone `nginx.conf` file instead of augment templates when publishing to instance groups. + +--- + +### {{% icon-resolved %}} Failing to fetch CVE data when using forward proxy in K8s environments {#46177} {{}} | Issue ID | Status | |----------------|--------| -| 46177 | Open | +| 46177 | Fixed in 2.21.0 | {{}} #### Description @@ -59,7 +120,7 @@ March 27, 2025 {{}} | Issue ID | Status | |----------------|--------| -| 45991 | Fixed in Instance Manager 2.20.0 | +| 45991 | Fixed in 2.20.0 | {{}} #### Description @@ -82,7 +143,7 @@ February 06, 2025 {{}} | Issue ID | Status | |----------------|--------| -| 45845 | Fixed in Instance Manager 2.19.1 | +| 45845 | Fixed in 2.19.1 | {{}} #### Description @@ -123,7 +184,7 @@ November 08, 2024 {{}} | Issue ID | Status | |----------------|--------| -| 45846 | Fixed in Instance Manager 2.19.1 | +| 45846 | Fixed in 2.19.1 | {{}} #### Description @@ -132,7 +193,7 @@ On Ubuntu 24.04, NGINX Instance Manager v2.18.0 and v2.19.0 fail to automaticall #### Workaround -Manually install the missing compiler by following the instructions in [Install the WAF compiler]({{< ref "nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}). +Manually install the missing compiler by following the instructions in [Install the WAF compiler]({{< ref "nim/waf-integration/configuration/install-waf-compiler/_index.md" >}}). --- @@ -141,7 +202,7 @@ Manually install the missing compiler by following the instructions in [Install {{}} | Issue ID | Status | |----------------|--------| -| 45573 | Fixed in Instance Manager 2.19.0 | +| 45573 | Fixed in 2.19.0 | {{}} #### Description @@ -155,7 +216,7 @@ Saving templates as “staged configs” causes syntax errors due to Augment tem {{}} | Issue ID | Status | |----------------|--------| -| 45570 | Fixed in Instance Manager 2.19.0 | +| 45570 | Fixed in 2.19.0 | {{}} #### Description @@ -170,7 +231,7 @@ If there is an NGINX configuration error when pushing a template configuration, {{}} | Issue ID | Status | |----------------|--------| -| 45301 | Fixed in Instance Manager 2.19.0 | +| 45301 | Fixed in 2.19.0 | {{}} #### Description @@ -184,7 +245,7 @@ If there is an NGINX configuration error when pushing a template configuration, {{}} | Issue ID | Status | |----------------|--------| -| 45024 | Fixed in Instance Manager 2.19.0 | +| 45024 | Fixed in 2.19.0 | {{}} #### Description diff --git a/content/nim/releases/release-notes.md b/content/nim/releases/release-notes.md index f1ea5f93e..8259e27fb 100644 --- a/content/nim/releases/release-notes.md +++ b/content/nim/releases/release-notes.md @@ -15,6 +15,114 @@ The release notes for F5 NGINX Instance Manager highlight the latest features, i {{< /details >}} +## 2.21.0 + +November 07, 2025 + +### Upgrade Paths {#2-21-0-upgrade-paths} + +NGINX Instance Manager 2.21.0 supports upgrades from these previous versions: + +- 2.18.0 - 2.20.0 + +If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version. + +### What's New {#2-21-0-whats-new} + +This release includes the following updates: + +- {{% icon-feature %}} **Added support for bot signatures management in NGINX Instance Manager** + + This release adds bot signature management to NGINX Instance Manager through both the web interface and the API. This update improves web application firewall (WAF) policy protection by detecting and mitigating automated bot traffic and integrates bot signature workflows with existing attack signature and threat campaign management. + + **What’s new** + + - Automatically download bot signatures from the NGINX repository at a configurable interval (set in `nms.conf`). + - Include the latest bot signatures when publishing a WAF policy to an instance or instance group. + - View bot signature deployment associations across instances and instance groups in the web interface. + - Roll out the latest bot signatures to all previously published policies with one click. + - See the bot signatures version on the Instance WAF details page. + - Automatically prune unused bot signatures every 24 hours, with a configurable time-to-live (TTL) value (set in `nms.conf`). + + **API-only operations:** + + - Upload a bot signature package downloaded from the NGINX repository. + - Delete unused bot signatures from NGINX Instance Manager. + - List all bot signatures stored in NGINX Instance Manager. + + **Upgrade and compatibility** + + - No breaking changes. Existing policies continue using their current bot signatures until you re-publish the policy or publish a bot signatures update to the target instance or instance group. + - Bot signatures are compatible with older agents, but **we recommend upgrading to NGINX Agent v2.43.0 or later** for the best results. + + **Notes and limitations** + + - After upgrade, the Instance WAF details page won’t display the bot signatures version for existing policies until you re-publish the policy or publish a bot signatures update. The page will show: + *“Available after publishing Bot Signatures from Instance Manager.”* + - Auto-pruning removes only bot signatures that aren’t associated with any deployed policy. Configure the TTL setting to meet your retention and compliance requirements. + +- {{% icon-feature %}} **On-demand WAF policy bundle download in NGINX Instance Manager web interface** + + This release adds on-demand download of compiled web application firewall (WAF) policy bundles from the NGINX Instance Manager web interface. Previously available only through the API, this feature lets you retrieve the compiled bundle for use cases such as NGINX Ingress Controller deployments in Kubernetes. You can now reference the bundle directly and avoid compilation on the data plane. + + **What’s new** + + - You can now download a compiled policy bundle directly from the web interface. + Go to **WAF > Policies**, select a policy with **Compilation Status = Compiled**, and choose **Download Bundle** to retrieve the latest compiled version. + + **Upgrade and compatibility** + + - No breaking changes. Existing workflows continue to function as before. Web interface–based bundle download complements the existing API and is especially useful for NGINX Ingress Controller deployments in Kubernetes. + + **Limitations** + + - Only the latest version of a WAF policy bundle can be downloaded on demand. + - The **Download Bundle** action is available only for policies that have been successfully compiled. + +- {{% icon-feature %}} **On-demand WAF policy compilation (bundle creation) in NGINX Instance Manager web interface** + + This release adds on-demand compilation of WAF policies in the NGINX Instance Manager web interface. Pre-compiling policies helps reduce publish times and improve reliability. + + Previously, NGINX Instance Manager reused compiled bundles when available and compiled policies during publish if no bundle existed. This could slow down or occasionally fail. You can now compile policies in advance so they’re ready for immediate deployment to instances or instance groups. + + **What’s new** + + - **Web interface support for policy compilation:** Under **WAF > Policies**, select a policy and choose **Compile (bundle creation)** to start compilation on demand. + - **Compilation status visibility:** A new **Compilation Status** column shows which policies are already compiled and which need compilation. + - **Faster publishing:** When a compiled bundle exists for a selected policy, NGINX Instance Manager uses it to speed up publishing to instances and instance groups. + + **Upgrade and compatibility** + + - No breaking changes. Existing workflows continue to function as before. On-demand compilation through the web interface complements the existing API and can improve publish speed and reduce failures during WAF policy deployment. + + **Limitations** + + - By default, the **Compile** action uses the latest revision of the selected policy, the most recent compiler version, and the newest versions of attack signatures, bot signatures, and threat campaigns. + +- {{% icon-feature %}} **Expanded options for configuring security policies with F5 WAF for NGINX** + + You can now configure additional policy settings for F5 WAF for NGINX directly in the NGINX Instance Manager web interface, including: + + - Signature sets + - Signature exceptions + - Parameters + - URLs + - Cookies + + For more information, see the [F5 WAF for NGINX Integration Guide](https://docs.nginx.com/nginx-instance-manager/waf-integration/). + +### Resolved Issues {#2-21-0-resolved-issues} + +This release fixes the following issues. Check the [Known Issues]({{< ref "/nim/releases/known-issues.md" >}}) topic for more information on the latest resolved issues. Use your browser's search function to find the issue ID in the page. + +- {{% icon-resolved %}} Failing to fetch CVE data when using forward proxy in K8s environments (46177) + +### Known Issues {#2-21-0-known-issues} + +You can find information about known issues in the [Known Issues]({{< ref "/nim/releases/known-issues.md" >}}) topic. + +--- + ## 2.20.0 June 16, 2025 @@ -621,7 +729,7 @@ This release includes the following updates: - {{% icon-feature %}} **Work with NGINX App Protect Bundles from Instance Manager** Starting with Instance Manager 2.14, you can now use the "/security/policies/bundles" endpoint to create, read, update, and delete NGINX App Protect bundles, which allow faster deployment through pre-compilation of security policies, attack signatures, and threat-campaign. For additional information on how to use the API endpoint, refer to your product API documentation. - To learn more about this feature, see the [Manage WAF Security Policies]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md" >}}) documentation. + To learn more about this feature, see the [Manage WAF Security Policies]({{< ref "/nim/waf-integration/policies-and-logs/_index.md" >}}) documentation. - {{% icon-feature %}} **Clickhouse LTS 23.8 support** @@ -1148,11 +1256,11 @@ This release includes the following updates: - {{% icon-feature %}} **Automatic retrieval of Attack Signatures and Threat Campaign updates to Instance Manager** - Instance Manager now allows you to [set up automatic downloads of the most recent Attack Signature and Threat Campaign packages]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md##automatically-download-latest-packages" >}}). By publishing these updates to your App Protect instances from Instance Manager, you can ensure your applications are shielded from all recognized attack types. + Instance Manager now allows you to [set up automatic downloads of the most recent Attack Signature and Threat Campaign packages]({{< ref "/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md" >}}). By publishing these updates to your App Protect instances from Instance Manager, you can ensure your applications are shielded from all recognized attack types. - {{% icon-feature %}} **Improved WAF Compiler error messages** - The messaging around [security policy compilation errors]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies.md#check-for-compilation-errors" >}}) has been improved by providing more detailed information and alerting users if the required compiler version is missing. + The messaging around security policy compilation errors has been improved by providing more detailed information and alerting users if the required compiler version is missing. ### Changes in Default Behavior{#2-8-0-changes-in-behavior} @@ -1265,7 +1373,7 @@ This release includes the following updates: - {{% icon-feature %}} **Manage and deploy configurations to F5 WAF for NGINX Instances** - This release introduces the following features to [manage and deploy configurations to NGINX App Protect instances]({{< ref "/nim/nginx-app-protect/overview-nap-waf-config-management.md" >}}): + This release introduces the following features to [manage and deploy configurations to NGINX App Protect instances]({{< ref "/nim/waf-integration/overview.md" >}}): - Create, upsert, and delete F5 WAF for NGINX security policies - Manage F5 WAF for NGINX security configurations by using the NGINX Management Suite user interface or REST API diff --git a/content/nim/security-monitoring/_index.md b/content/nim/security-monitoring/_index.md new file mode 100644 index 000000000..9ad5c6a45 --- /dev/null +++ b/content/nim/security-monitoring/_index.md @@ -0,0 +1,5 @@ +--- +title: Security Monitoring +weight: 800 +url: /nginx-instance-manager/security-monitoring/ +--- diff --git a/content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md b/content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md similarity index 100% rename from content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md rename to content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md diff --git a/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md b/content/nim/security-monitoring/set-up-app-protect-instances.md similarity index 88% rename from content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md rename to content/nim/security-monitoring/set-up-app-protect-instances.md index 94299d3d9..8290c1e27 100644 --- a/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md +++ b/content/nim/security-monitoring/set-up-app-protect-instances.md @@ -65,19 +65,19 @@ Repeat the steps in this section on each F5 WAF for NGINX data plane host to ins # path to aux file dirs can also be added config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" - # Enable reporting NGINX App Protect details to the management plane. + # Enable reporting F5 WAF for NGINX details to the management plane. extensions: - nginx-app-protect - nap-monitoring - # Enable reporting NGINX App Protect details to the control plane. + # Enable reporting F5 WAF for NGINX details to the control plane. nginx_app_protect: - # Report interval for NGINX App Protect details - the frequency the NGINX Agent checks NGINX App Protect for changes. + # Report interval for F5 WAF for NGINX details - the frequency the NGINX Agent checks F5 WAF for NGINX for changes. report_interval: 15s # Enable precompiled publication from the NGINX Instance Manager (true) or perform compilation on the data plane host (false). precompiled_publication: true - # NGINX App Protect Monitoring config + # F5 WAF for NGINX Monitoring config nap_monitoring: # Buffer size for collector. Will contain log lines and parsed log lines collector_buffer_size: 50000 @@ -107,7 +107,7 @@ Repeat the steps in this section on each F5 WAF for NGINX data plane host to ins ``` {{< call-out "important" >}}You can change the values of `syslog_ip` and `syslog_port` to meet your needs. - You must use the same values when configuring logging for the Security Monitoring module. If the `syslog:` configuration does not match these settings, the monitoring dashboards will not display any data. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} + You must use the same values when configuring logging for the Security Monitoring module. If the `syslog:` configuration does not match these settings, the monitoring dashboards will not display any data. Also, the networking changes for F5 WAF for NGINX Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} {{< call-out "note" >}}You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`: @@ -117,7 +117,7 @@ curl https:///install/nginx-agent > install.sh # Use the flag --nap-monitoring to set the child fields for the field 'nap_monitoring', the # child field values will be set to the values in the example configuration from above. Specify -# the -m | --nginx-app-protect-mode flag to set up management of NGINX App Protect on the instance. +# the -m | --nginx-app-protect-mode flag to set up management of F5 WAF for NGINX on the instance. # In the example below we specify 'precompiled-publication' for the flag value which will make the # config field 'precompiled_publication' set to 'true', if you would like to set the config field # 'precompiled_publication' to 'false' you can specify 'none' as the flag value. @@ -175,16 +175,16 @@ Repeat the steps below on each F5 WAF for NGINX data plane instance. app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; ``` - {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} + {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The dashboards won't display any data if these settings don't match. Also, the networking changes for F5 WAF for NGINX Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} 1. Restart NGINX Agent and the NGINX web server. - ```bash + ```shell sudo systemctl restart nginx-agent sudo systemctl restart nginx ``` -You should now be able to view data from your NGINX App Protect instances in the NGINX Security Monitoring dashboards. +You should now be able to view data from your F5 WAF for NGINX instances in the NGINX Security Monitoring dashboards. ## Create instances for Security Monitoring with Instance Manager @@ -208,7 +208,7 @@ Take the steps below to update your F5 WAF for NGINX configurations by using Ins The policy reference must use the `.tgz` file extension when using Instance Manager to perform precompiled publication of F5 WAF for NGINX policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance. - If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up F5 WAF for NGINX Configuration Management]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration. + If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up F5 WAF for NGINX Configuration Management]({{< ref "/nim/waf-integration/configuration/manage-waf-configurations" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration. - Add the `app_protect_security_log_enable on` and the `app_protect_security_log` directive to any NGINX context where F5 WAF for NGINX is enabled and you want to be able to review attack data. @@ -216,7 +216,7 @@ Take the steps below to update your F5 WAF for NGINX configurations by using Ins If the `app_protect_security_log_enable` setting is already present, just add the `app_protect_security_log` beneath it in the same context. - {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} + {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for F5 WAF for NGINX Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{< /call-out >}} 1. Select **Publish** to immediately push the configuration file updates out to your NGINX instance or instance group. @@ -224,5 +224,5 @@ You should now be able to view data from your F5 WAF for NGINX instances in the ## See also -- [Add user access to Security Monitoring dashboards]({{< ref "/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) -- [Manage your F5 WAF for NGINX configs]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md" >}}) +- [Add user access to Security Monitoring dashboards]({{< ref "/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) +- [Manage your F5 WAF for NGINX configs]({{< ref "/nim/waf-integration/configuration/_index.md" >}}) diff --git a/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md b/content/nim/security-monitoring/troubleshooting.md similarity index 81% rename from content/nim/nginx-app-protect/security-monitoring/troubleshooting.md rename to content/nim/security-monitoring/troubleshooting.md index 53ea1dc75..fde43751a 100644 --- a/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md +++ b/content/nim/security-monitoring/troubleshooting.md @@ -15,7 +15,7 @@ If a Security Violation event is not received by the Security Monitoring module, ### Resolution -F5 NGINX App Protect supports logging to multiple destinations. This allows users to send logs to the NGINX agent and store a backup. If Security Monitoring fails to receive Security Events, you can check the backup log to verify attack details. Use the following settings to enable backup logging: +F5 WAF for NGINX supports logging to multiple destinations. This allows users to send logs to the NGINX agent and store a backup. If Security Monitoring fails to receive Security Events, you can check the backup log to verify attack details. Use the following settings to enable backup logging: 1. **For an instance with Security Monitoring only:** diff --git a/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md b/content/nim/security-monitoring/update-geo-db.md similarity index 92% rename from content/nim/nginx-app-protect/security-monitoring/update-geo-db.md rename to content/nim/security-monitoring/update-geo-db.md index 57ac8f971..daa747722 100644 --- a/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md +++ b/content/nim/security-monitoring/update-geo-db.md @@ -19,7 +19,7 @@ Follow these steps to update the Security Monitoring module with the latest geol Ensure the following prerequisites are met: -- NGINX App Protect is configured, and the Security Monitoring dashboard is collecting security violations. +- F5 WAF for NGINX is configured, and the Security Monitoring dashboard is collecting security violations. --- @@ -30,13 +30,13 @@ Ensure the following prerequisites are met: 1. Extract the `.gzip` file to access the GeoLite2 Country database file, named `GeoLite2-Country.mmdb`. 1. Replace the existing `GeoLite2-Country.mmdb` file on the NGINX Instance Manager control plane at `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` with the new database: - ```bash + ```shell sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb ``` 1. Restart the NGINX Instance Manager services to apply the update: - ```bash + ```shell sudo systemctl restart nms-ingestion sudo systemctl restart nms-core ``` diff --git a/content/nim/security-monitoring/update-signatures.md b/content/nim/security-monitoring/update-signatures.md new file mode 100644 index 000000000..41d76de64 --- /dev/null +++ b/content/nim/security-monitoring/update-signatures.md @@ -0,0 +1,28 @@ +--- +title: Update the attack signature database +weight: 300 +toc: true +type: how-to +product: NIM +nd-docs: DOCS-1109 +--- + +The F5 NGINX Security Monitoring module tracks security violations on F5 WAF for NGINX instances. Its analytics dashboards use a Signature Database to provide details about Attack Signatures, including their name, accuracy, and risk. + +If the Signature Database is outdated and doesn’t match the version used in F5 WAF for NGINX, new signatures may appear without attributes like a name, risk, or accuracy. + +Follow these steps to update the Security Monitoring module with the latest Attack Signature data, ensuring the dashboards display complete and accurate information. + +--- + +## Before you begin + +Ensure the following prerequisites are met: + +- [F5 WAF for NGINX is configured]({{< ref "/nim/waf-integration/configuration/_index.md" >}}), and the Security Monitoring dashboard is collecting security violations. + +--- + +## Update the signature database + +{{< include "/nim/security-monitoring/update-security-monitoring-attack-signature-database.md" >}} diff --git a/content/nim/support/contact-support.md b/content/nim/support/contact-support.md index 066f58a78..fa7adb5a9 100644 --- a/content/nim/support/contact-support.md +++ b/content/nim/support/contact-support.md @@ -37,7 +37,7 @@ The Support team might ask you to run one or both of the following scripts to tr 1. Open an SSH connection to the NGINX Instance Manager host and log in. 2. Run the following command: - ```bash + ```shell /usr/share/nginx-manager/support.sh ``` @@ -46,7 +46,7 @@ The Support team might ask you to run one or both of the following scripts to tr 1. Open an SSH connection to the data plane instance and log in. 2. Run the following command: - ```bash + ```shell /usr/share/nginx-agent/support.sh ``` @@ -76,7 +76,7 @@ The script creates a file in the `/tmp` directory, such as `/tmp/nginx-manager-l For example, if your `/etc/nginx-manager` directory contains private keys or certificates, remove them using: -```bash +```shell gzip -d /tmp/nginx-manager-log.tar.gz tar -f /tmp/nginx-manager-log.tar.gz \ diff --git a/content/nim/support/k8s-support-package.md b/content/nim/support/k8s-support-package.md index d5d163e2a..3dd152a52 100644 --- a/content/nim/support/k8s-support-package.md +++ b/content/nim/support/k8s-support-package.md @@ -34,7 +34,7 @@ The F5 NGINX Instance Manager Helm chart includes the `k8s-support-package.sh` s 1. Download the latest NGINX Instance Manager Helm chart: - ```bash + ```shell helm repo add nginx-stable https://helm.nginx.com/stable helm repo update helm pull nginx-stable/nms @@ -51,7 +51,7 @@ The F5 NGINX Instance Manager Helm chart includes the `k8s-support-package.sh` s 3. Extract the package using the `tar` command: - ```bash + ```shell tar -xvf k8s-support-pkg-.tar.gz ``` diff --git a/content/nim/support/support-package.md b/content/nim/support/support-package.md index 72a104490..5141f711e 100644 --- a/content/nim/support/support-package.md +++ b/content/nim/support/support-package.md @@ -42,7 +42,7 @@ To create a support package: 2. To extract the package, use the `tar` command: - ```bash + ```shell tar -xvf support-pkg-.tar.gz ``` @@ -83,7 +83,7 @@ The logs of the Instance Manager processes. You can pipe the logs to `grep` to view entries belonging to only one of the three `nms` processes. For example, to view `nms-core` logs, run the following command: -```bash +```shell cat nms.log | grep 'COR' ``` diff --git a/content/nim/system-configuration/configure-forward-proxy.md b/content/nim/system-configuration/configure-forward-proxy.md index ba7528677..01d24842d 100644 --- a/content/nim/system-configuration/configure-forward-proxy.md +++ b/content/nim/system-configuration/configure-forward-proxy.md @@ -196,13 +196,13 @@ If your proxy uses HTTPS and `proxy_ssl_verify` is set to `true`, NGINX Instance - **Debian/Ubuntu**: - ```bash + ```shell sudo update-ca-certificates ``` - **RHEL/CentOS**: - ```bash + ```shell sudo update-ca-trust ``` @@ -210,7 +210,7 @@ If your proxy uses HTTPS and `proxy_ssl_verify` is set to `true`, NGINX Instance - **VM/bare-metal**: Restart NGINX Instance Manager: - ```bash + ```shell sudo systemctl restart nms ``` diff --git a/content/nim/system-configuration/configure-gateway.md b/content/nim/system-configuration/configure-gateway.md index 186ad6c73..4c8a583fc 100644 --- a/content/nim/system-configuration/configure-gateway.md +++ b/content/nim/system-configuration/configure-gateway.md @@ -27,7 +27,7 @@ To align with the worker connection count, you should also adjust the maximum nu 1. Open the NGINX configuration file on the NGINX Instance Manager host: - ```bash + ```shell sudo nano /etc/nginx/nginx.conf ``` @@ -43,7 +43,7 @@ To align with the worker connection count, you should also adjust the maximum nu 3. Save the changes and restart NGINX: - ```bash + ```shell sudo systemctl restart nginx ``` @@ -61,7 +61,7 @@ By default, the NGINX Instance Manager's NGINX configuration (`/etc/nginx/conf.d 1. Open the gRPC configuration file on the NGINX Instance Manager host: - ```bash + ```shell sudo nano /etc/nginx/conf.d/nms-http.conf ``` @@ -95,6 +95,6 @@ By default, the NGINX Instance Manager's NGINX configuration (`/etc/nginx/conf.d 3. Save the changes and restart NGINX: - ```bash + ```shell sudo systemctl restart nginx ``` diff --git a/content/nim/system-configuration/configure-selinux.md b/content/nim/system-configuration/configure-selinux.md index e29621ec8..279bf93ea 100644 --- a/content/nim/system-configuration/configure-selinux.md +++ b/content/nim/system-configuration/configure-selinux.md @@ -47,14 +47,14 @@ To load the SELinux policy included with NGINX Instance Manager: 1. Load the NGINX Instance Manager policy: - ```bash + ```shell sudo semodule -n -i /usr/share/selinux/packages/nms.pp sudo /usr/sbin/load_policy ``` 2. Restore default SELinux labels for related files and directories: - ```bash + ```shell sudo restorecon -F -R /usr/bin/nms-core sudo restorecon -F -R /usr/bin/nms-dpm sudo restorecon -F -R /usr/bin/nms-ingestion @@ -76,7 +76,7 @@ To load the SELinux policy included with NGINX Instance Manager: 3. Restart NGINX Instance Manager services: - ```bash + ```shell sudo systemctl restart nms ``` @@ -86,21 +86,21 @@ NGINX Instance Manager uses the `nms_t` context in the policy module. To add new 1. Add TCP ports `10000` and `11000` to the `nms_port_t` context: - ```bash + ```shell sudo semanage port -a -t nms_port_t -p tcp 10000 sudo semanage port -a -t nms_port_t -p tcp 11000 ``` 2. If the port context is already defined, use `-m` to modify it: - ```bash + ```shell sudo semanage port -m -t nms_port_t -p tcp 10000 sudo semanage port -m -t nms_port_t -p tcp 11000 ``` 3. Verify the port has the correct label: - ```bash + ```shell seinfo --portcon=10000 seinfo --portcon=11000 ``` @@ -109,7 +109,7 @@ NGINX Instance Manager uses the `nms_t` context in the policy module. To add new If you uninstall NGINX Instance Manager, remove the associated ports: -```bash +```shell sudo semanage port -d -t nms_t 10000 sudo semanage port -d -t nms_t 11000 ``` diff --git a/content/nim/system-configuration/configure-vault.md b/content/nim/system-configuration/configure-vault.md index 2b0bae9e2..1e77e92f3 100644 --- a/content/nim/system-configuration/configure-vault.md +++ b/content/nim/system-configuration/configure-vault.md @@ -40,7 +40,7 @@ To create a periodic service token for NGINX Instance Manager: 2. Create a renewable service token. We recommend a period of 24 hours. NGINX Instance Manager renews tokens automatically, so shorter periods also work. Run the following, replacing `$VAULT_ROOT_TOKEN` with your Vault's Root Token and `$VAULT_ADDR` with your Vault's address: - ```bash + ```shell curl -X POST --header "X-Vault-Token: $VAULT_ROOT_TOKEN" \ --data '{"policies": "nms_secrets", "period": "24h"}' \ $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token" > periodic_token.txt @@ -48,14 +48,14 @@ To create a periodic service token for NGINX Instance Manager: 3. Verify the token works: - ```bash + ```shell curl --header "X-Vault-Token: $(cat periodic_token.txt)" \ $VAULT_ADDR/v1/auth/token/lookup-self | jq .data ``` 4. If everything works, stop the `nms-core` service and configure NGINX Instance Manager to use the token: - ```bash + ```shell sudo systemctl stop nms-core sudo NMS_VAULT_TOKEN=$(cat periodic_token.txt) nms-core secret vault-token sudo systemctl restart nms-core @@ -91,7 +91,7 @@ To create a periodic service token for NGINX Instance Manager: 3. Save the changes and close the file. 4. Restart the NGINX Instance Manager services to start using Vault: - ```bash + ```shell sudo systemctl restart nms ``` @@ -105,13 +105,13 @@ After setting up Vault, you can switch between local encryption and Vault. 1. Stop NGINX Instance Manager: - ```bash + ```shell sudo systemctl stop nms ``` 2. Migrate secrets to local storage: - ```bash + ```shell sudo nms-core secret migrate-secrets-to-local ``` @@ -123,7 +123,7 @@ After setting up Vault, you can switch between local encryption and Vault. 4. Restart NGINX Instance Manager: - ```bash + ```shell sudo systemctl start nms ``` @@ -133,13 +133,13 @@ To switch from using local encryption back to Vault: 1. Stop NGINX Instance Manager: - ```bash + ```shell sudo systemctl stop nms ``` 2. Migrate secrets to Vault: - ```bash + ```shell sudo nms-core secret migrate-secrets-to-vault ``` @@ -151,7 +151,7 @@ To switch from using local encryption back to Vault: 4. Restart NGINX Instance Manager: - ```bash + ```shell sudo systemctl start nms ``` diff --git a/content/nim/troubleshooting.md b/content/nim/troubleshooting.md index 79a5c0882..8c78cd501 100644 --- a/content/nim/troubleshooting.md +++ b/content/nim/troubleshooting.md @@ -22,7 +22,7 @@ The NGINX service must be running **before** you start the NGINX Agent. - To resolve the issue, try restarting the NGINX Agent: - ``` bash + ```shell sudo systemctl restart nginx-agent ``` @@ -51,28 +51,28 @@ Ensure there isn't a process bound to port `80` or `443`. 1. To stop processes bound to ports `80` and `443`, run the following commands: - ```bash + ```shell sudo fuser -k 80/tcp sudo fuser -k 443/tcp ``` 2. Restart the NGINX service: - ```bash + ```shell sudo service nginx restart ``` --- -## Scan reports NGINX versions as `undefined` when NGINX App Protect is enabled +## Scan reports NGINX versions as `undefined` when F5 WAF for NGINX is enabled ### Description -When [scanning for NGINX instances]({{< ref "/nim/nginx-instances/scan-instances" >}}), the NGINX version is reported as `undefined` when NGINX App protect is installed. +When [scanning for NGINX instances]({{< ref "/nim/nginx-instances/scan-instances" >}}), the NGINX version is reported as `undefined` when F5 WAF for NGINX is installed. ### Resolution -This behavior is **by design**. As a security precaution when NGINX App Protect is installed, the NGINX server does not report its version in any HTTP headers. The **NGINX Plus** and **Instances** pages in the web interface will continue to report the NGINX and NGINX App Protect versions. +This behavior is **by design**. As a security precaution when F5 WAF for NGINX is installed, the NGINX server does not report its version in any HTTP headers. The **NGINX Plus** and **Instances** pages in the web interface will continue to report the NGINX and F5 WAF for NGINX versions. --- diff --git a/content/nim/nginx-app-protect/_index.md b/content/nim/waf-integration/_index.md similarity index 52% rename from content/nim/nginx-app-protect/_index.md rename to content/nim/waf-integration/_index.md index 0cc84608c..28c4a9f32 100644 --- a/content/nim/nginx-app-protect/_index.md +++ b/content/nim/waf-integration/_index.md @@ -1,5 +1,5 @@ --- title: Secure with F5 WAF for NGINX weight: 90 -url: /nginx-instance-manager/nginx-app-protect/ +url: /nginx-instance-manager/waf-integration/ --- \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/_index.md b/content/nim/waf-integration/configuration/_index.md new file mode 100644 index 000000000..88e1491f0 --- /dev/null +++ b/content/nim/waf-integration/configuration/_index.md @@ -0,0 +1,39 @@ +--- +title: Set up WAF configuration management +description: Learn how to manage F5 WAF for NGINX configurations in NGINX Instance Manager using the web interface or REST API. +nd-docs: +weight: 200 +nd-content-type: landing-page +nd-landing-page: true +url: /nginx-instance-manager/waf-integration/configuration/ +--- + +F5 NGINX Instance Manager helps you configure and manage F5 WAF for NGINX, so you can keep your applications secure and up to date. +This guide explains how to set up Instance Manager to manage your WAF configurations. + +## Before you begin + +{{< include "/nim/waf/nim-waf-before-you-begin.md" >}} + +## Featured content + +{{}} + {{}} + Set up the WAF compiler so NGINX Instance Manager can precompile and manage F5 WAF for NGINX security configurations. + {{}} + {{}} + Keep F5 WAF for NGINX up to date with the latest attack signatures, bot signatures, and threat campaigns. + {{}} + {{}} + Automatically remove unused compiled security resources in NGINX Instance Manager to keep your system clean and efficient. + {{}} + {{}} + Connect and configure your F5 WAF for NGINX instances so they can be managed in NGINX Instance Manager. + {{}} + {{}} + Configure, customize, and verify F5 WAF for NGINX policies on your managed instances. + {{}} + {{}} + Resolve common issues with F5 WAF for NGINX and NGINX Instance Manager by verifying installation, configuration, and connectivity. + {{}} +{{}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/compiler-resource-pruning.md b/content/nim/waf-integration/configuration/compiler-resource-pruning.md new file mode 100644 index 000000000..1575aa8ee --- /dev/null +++ b/content/nim/waf-integration/configuration/compiler-resource-pruning.md @@ -0,0 +1,63 @@ +--- +title: Set up compiler resource pruning +description: Automatically remove unused compiled security resources in NGINX Instance Manager to keep your system clean and efficient. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can configure NGINX Instance Manager to automatically remove unused compiled security resources, including: + +- Compiled security policies +- Compiled security log profiles +- Attack signatures +- Bot signatures +- Threat campaigns + +Only compiled bundles are removed. NGINX Instance Manager does not delete the base definitions for security policies or log profiles. + +## Enable compiler resource pruning + +1. Log in to the NGINX Instance Manager host using SSH. + +1. Open the `/etc/nms/nms.conf` file in a text editor. + +1. Update the `policy_manager` section under `integrations` to define time-to-live (TTL) values for each resource type: + + ```yaml + integrations: + address: unix:/var/run/nms/integrations.sock + dqlite: + addr: 127.0.0.1:7892 + policy_manager: + # Time to live for attack signatures. If attack signatures exceed their TTL + # and are not deployed to an instance or instance group, they are deleted from the database. + # Duration units: seconds (s), minutes (m), or hours (h). + attack_signatures_ttl: 336h + + # Time to live for compiled bundles, including compiled security policies and log profiles. + # If a compiled bundle exceeds its TTL and is not deployed to an instance or instance group, + # it is deleted from the database. The resource definition remains. + compiled_bundles_ttl: 336h + + # Time to live for bot signatures. If bot signatures exceed their TTL + # and are not deployed to an instance or instance group, they are deleted from the database. + # Duration units: seconds (s), minutes (m), or hours (h). + bot_signatures_ttl: 336h + + # Time to live for threat campaigns. If threat campaigns exceed their TTL + # and are not deployed to an instance or instance group, they are deleted from the database. + threat_campaigns_ttl: 1440h + + app_protect_security_update: + enable: true + interval: 6 + number_of_updates: 10 + ``` + +1. Save the file and close the editor. +1. {{< include "nim/waf/restart-nms-integrations.md" >}} + +NGINX Instance Manager runs the pruning process at startup and every 24 hours after the `nms-integrations` service starts. \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/install-waf-compiler/_index.md b/content/nim/waf-integration/configuration/install-waf-compiler/_index.md new file mode 100644 index 000000000..7f2bf1920 --- /dev/null +++ b/content/nim/waf-integration/configuration/install-waf-compiler/_index.md @@ -0,0 +1,6 @@ +--- +title: Install the WAF compiler +nd-docs: +weight: 100 +url: /nginx-instance-manager/waf-integration/configuration/install-waf-compiler/ +--- \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/install-waf-compiler/automatic-download.md b/content/nim/waf-integration/configuration/install-waf-compiler/automatic-download.md new file mode 100644 index 000000000..8e01c0260 --- /dev/null +++ b/content/nim/waf-integration/configuration/install-waf-compiler/automatic-download.md @@ -0,0 +1,50 @@ +--- +title: Automatically update the WAF compiler +description: Enable NGINX Instance Manager to automatically download and install new WAF compiler versions when needed. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +After you manually [install at least one version of the F5 WAF for NGINX compiler]({{< ref "/nim/waf-integration/configuration/install-waf-compiler/install.md" >}}), NGINX Instance Manager can automatically download and install newer versions as needed. + +Automatic updates occur when: + +- A managed instance is upgraded to a newer version of F5 WAF for NGINX. +- You add a new instance running a different version of F5 WAF for NGINX. + +To enable this feature, upload your F5 WAF for NGINX certificate and key to NGINX Instance Manager. This lets Instance Manager securely connect to the NGINX package repository and download the required compiler files. + +You only need to upload the certificate and key once. + +## Upload the F5 WAF for NGINX certificate and key + +{{< include "/nim/waf/upload-cert-and-key.md" >}} + +--- + +## Troubleshooting automatic updates + +If NGINX Instance Manager can’t connect to the repository, or the certificate is missing or invalid, you’ll see an error like: + +```text +missing the specific compiler, please install it and try again. +``` + +This means the certificate or key might be missing, invalid, or expired, or that Instance Manager can’t reach the NGINX repository. + +Check for related errors in the log file: + +```text +/var/log/nms/nms.log +``` + +If you see a message like this, the certificate or key is likely invalid or expired: + +```text +error when creating the nginx repo retriever - NGINX repo certificates not found +``` + +If needed, you can [install the WAF compiler manually]({{< ref "/nim/waf-integration/configuration/install-waf-compiler/install.md" >}}). diff --git a/content/nim/waf-integration/configuration/install-waf-compiler/download-from-myf5.md b/content/nim/waf-integration/configuration/install-waf-compiler/download-from-myf5.md new file mode 100644 index 000000000..721cbe247 --- /dev/null +++ b/content/nim/waf-integration/configuration/install-waf-compiler/download-from-myf5.md @@ -0,0 +1,48 @@ +--- +title: Manually update the WAF compiler +description: Download and install the WAF compiler manually from MyF5 when your system can’t access the public NGINX repository. +toc: true +weight: 400 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +If your NGINX Instance Manager host doesn’t have access to the public NGINX repository, you can manually download and install the WAF compiler from [MyF5](https://my.f5.com/). + +--- + +## Install the WAF compiler manually + +1. Log in to [MyF5](https://my.f5.com). +1. Go to **Resources > Downloads**. +1. Select the following options: + - **Group/Product Family:** **NGINX** + - **Product Line:** **F5 WAF** + - Choose the **Product version** that matches your environment. + - Select the appropriate **Linux distribution**, **version**, and **architecture**. +1. Download the `.deb` or `.rpm` file for the WAF compiler. +1. Transfer the file to your NGINX Instance Manager host. +1. Install the WAF compiler: + + - **Debian or Ubuntu** + + ```shell + sudo apt-get install -f /path/to/nms-nap-compiler-_focal_amd64.deb + ``` + + To install multiple compiler versions on the same system, use: + + ```shell + sudo apt-get install -f \ + /path/to/nms-nap-compiler-_focal_amd64.deb \ + -o Dpkg::Options::="--force-overwrite" + ``` + + - **RHEL, CentOS, or Oracle Linux** + + ```shell + sudo yum install -f /path/to/nms-nap-compiler-_el8.ngx.x86_64.rpm + ``` + +1. {{< include "nim/waf/restart-nms-integrations.md" >}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md b/content/nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md new file mode 100644 index 000000000..f22880079 --- /dev/null +++ b/content/nim/waf-integration/configuration/install-waf-compiler/install-disconnected.md @@ -0,0 +1,213 @@ +--- +title: Install the WAF compiler in a disconnected environment +description: Install the WAF compiler on a system without internet access by generating and transferring the package from a connected system. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can install the WAF compiler on a system without internet access by creating the package on a connected system, then transferring and installing it offline. + +- **Step 1:** Generate the WAF compiler package on a system with internet access. +- **Step 2:** Move the generated package to the offline target system and install it. + +--- + +## Before you begin + +{{< include "/nim/waf/nim-waf-before-you-begin.md" >}} + +--- + +## WAF compiler version support + +Use the table below to find the correct WAF compiler version for each release of F5 WAF for NGINX: + +{{< include "/waf/f5-waf-for-nginx-compiler-compatibility.md" >}} + +{{< call-out "note" >}} +Beginning with version 5.9.0, both the virtual machine and container installation packages are categorized under the 5.x.x tag. +Earlier releases used 4.x.x for VM packages (for example, NAP 4.15.0, NAP 4.16.0) and 5.x.x for container packages (for example, NAP 5.7.0, NAP 5.8.0). +{{< /call-out >}} + +--- + +## Install the WAF compiler by distribution + +{{< tabs name="install-waf-compiler-offline" >}} + +{{% tab name="Ubuntu 22.04 and 24.04" %}} + +1. **On a system with internet access:** + + Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. + + ```shell + sudo apt-get update -y + sudo mkdir -p /etc/ssl/nginx/ + sudo mv nginx-repo.crt /etc/ssl/nginx/ + sudo mv nginx-repo.key /etc/ssl/nginx/ + + wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ + | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + + printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://pkgs.nginx.com/nms/ubuntu $(lsb_release -cs) nginx-plus\n" | \ + sudo tee /etc/apt/sources.list.d/nms.list + + sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx + mkdir -p compiler && cd compiler + sudo apt-get update + + sudo apt-get download nms-nap-compiler-v5.527.0 + cd ../ + mkdir -p compiler/compiler.deps + sudo apt-get install --download-only --reinstall --yes --print-uris \ + nms-nap-compiler-v5.527.0 \ + | grep ^\' \ + | cut -d\' -f2 \ + | xargs -n 1 wget -P ./compiler/compiler.deps + tar -czvf compiler.tar.gz compiler/ + ``` + +1. **On the offline target system:** + + Make sure the OS libraries are up to date, especially `glibc`. + Move the `compiler.tar.gz` file from Step 1 to this system. + + ```shell + tar -xzvf compiler.tar.gz + sudo dpkg -i ./compiler/compiler.deps/*.deb + sudo dpkg -i ./compiler/*.deb + ``` + +{{% /tab %}} + +{{% tab name="Debian 11 and 12" %}} + +1. **On a system with internet access:** + + Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. + + ```shell + sudo apt-get update -y + sudo mkdir -p /etc/ssl/nginx/ + sudo mv nginx-repo.crt /etc/ssl/nginx/ + sudo mv nginx-repo.key /etc/ssl/nginx/ + + wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ + | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + + printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://pkgs.nginx.com/nms/debian $(lsb_release -cs) nginx-plus\n" | \ + sudo tee /etc/apt/sources.list.d/nms.list + + sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx + mkdir -p compiler && cd compiler + sudo apt-get update + + sudo apt-get download nms-nap-compiler-v5.527.0 + cd ../ + mkdir -p compiler/compiler.deps + sudo apt-get install --download-only --reinstall --yes --print-uris \ + nms-nap-compiler-v5.527.0 \ + | grep ^\' \ + | cut -d\' -f2 \ + | xargs -n 1 wget -P ./compiler/compiler.deps + tar -czvf compiler.tar.gz compiler/ + ``` + +1. **On the offline target system:** + + Make sure the OS libraries are up to date, especially `glibc`. + Move the `compiler.tar.gz` file from Step 1 to this system. + + ```shell + tar -xzvf compiler.tar.gz + sudo dpkg -i ./compiler/compiler.deps/*.deb + sudo dpkg -i ./compiler/*.deb + ``` + +{{% /tab %}} + +{{% tab name="RHEL 8 or Oracle Linux 8" %}} + +1. **On a system with internet access:** + + Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. + + ```shell + sudo yum update -y + sudo yum install yum-utils tar -y + sudo mkdir -p /etc/ssl/nginx/ + sudo mv nginx-repo.crt /etc/ssl/nginx/ + sudo mv nginx-repo.key /etc/ssl/nginx/ + sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo + + sudo tee /etc/yum.repos.d/centos-vault-powertools.repo << 'EOF' + [centos-vault-powertools] + name=CentOS Vault - PowerTools + baseurl=https://vault.centos.org/centos/8/PowerTools/x86_64/os/ + enabled=1 + gpgcheck=0 + EOF + + sudo yum update -y + sudo mkdir -p nms-nap-compiler + + sudo yumdownloader --resolve --destdir=nms-nap-compiler nms-nap-compiler-v5.527.0 + tar -czvf compiler.tar.gz nms-nap-compiler/ + ``` + +1. **On the offline target system:** + + Make sure the OS libraries are up to date, especially `glibc`. + Move the `compiler.tar.gz` file from Step 1 to this system. + + ```shell + sudo yum install tar -y + tar -xzvf compiler.tar.gz + sudo dnf install --disablerepo=* nms-nap-compiler/*.rpm + ``` + +{{% /tab %}} + +{{% tab name="RHEL 9 or Oracle Linux 9" %}} + +1. **On a system with internet access:** + + Place your `nginx-repo.crt` and `nginx-repo.key` files on this system. + + ```shell + sudo yum update -y + sudo yum install yum-utils -y + sudo mkdir -p /etc/ssl/nginx/ + sudo mv nginx-repo.crt /etc/ssl/nginx/ + sudo mv nginx-repo.key /etc/ssl/nginx/ + sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo + sudo yum-config-manager --disable rhel-9-appstream-rhui-rpms + sudo yum update -y + sudo mkdir -p nms-nap-compiler + + sudo yumdownloader --resolve --destdir=nms-nap-compiler nms-nap-compiler-v5.527.0 + tar -czvf compiler.tar.gz nms-nap-compiler/ + ``` + +1. **On the offline target system:** + + Make sure the OS libraries are up to date, especially `glibc`. + Move the `compiler.tar.gz` file from Step 1 to this system. + + ```shell + tar -xzvf compiler.tar.gz + cd nms-nap-compiler + sudo dnf install *.rpm --disablerepo=* + ``` + +{{% /tab %}} + +{{< /tabs >}} diff --git a/content/nim/waf-integration/configuration/install-waf-compiler/install.md b/content/nim/waf-integration/configuration/install-waf-compiler/install.md new file mode 100644 index 000000000..609aaee0a --- /dev/null +++ b/content/nim/waf-integration/configuration/install-waf-compiler/install.md @@ -0,0 +1,142 @@ +--- +title: Install the WAF compiler +description: Install the WAF compiler on the NGINX Instance Manager host to precompile security configurations for F5 WAF for NGINX. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +The WAF compiler lets NGINX Instance Manager precompile security configurations before deploying them to F5 WAF for NGINX instances. +Precompiling configurations improves performance and reduces the risk of runtime errors. + +Install the WAF compiler on the NGINX Instance Manager host only if you plan to compile configurations on the management plane. +If you compile on the data plane, you can skip this step. + +Each version of F5 WAF for NGINX has a corresponding WAF compiler version. +If you manage multiple versions, install the matching compiler for each one on the NGINX Instance Manager host. + +The WAF compiler installs to the `/opt` directory. +Make sure this directory has the correct permissions so the owner can write to it. A typical permission setting of `0755` is sufficient. + +To organize instances running the same version, you can create [instance groups]({{< ref "/nim/nginx-instances/manage-instance-groups" >}}). + +For an overview of how the compiler works, see [Security bundle compilation]({{< ref "/nim/waf-integration/overview#security-bundle" >}}). + +--- + +## Before you begin + +{{< include "/nim/waf/nim-waf-before-you-begin.md" >}} + +--- + +## WAF compiler version support + +Use the table below to find the correct WAF compiler version for each release of F5 WAF for NGINX: + +{{< include "/waf/f5-waf-for-nginx-compiler-compatibility.md" >}} + +{{< call-out "note" >}} +Beginning with version 5.9.0, both the virtual machine and container installation packages are categorized under the 5.x.x tag. +Earlier releases used 4.x.x for VM packages (for example, NAP 4.15.0, NAP 4.16.0) and 5.x.x for container packages (for example, NAP 5.7.0, NAP 5.8.0). +{{< /call-out >}} + +--- + +## Install the WAF compiler + +{{< tabs name="install-waf-compiler" >}} + +{{% tab name="Debian or Ubuntu" %}} + +1. Install the WAF compiler: + + ```shell + sudo apt-get install nms-nap-compiler-v5.527.0 + ``` + +1. To install multiple compiler versions on the same system, append the `--force-overwrite` option after the first installation: + + ```shell + sudo apt-get install nms-nap-compiler-v5.527.0 -o Dpkg::Options::="--force-overwrite" + ``` + +1. {{< include "nim/waf/restart-nms-integrations.md" >}} + +{{% /tab %}} + +{{% tab name="RHEL 8.1" %}} + +1. Download the `dependencies.repo` file to `/etc/yum.repos.d`: + + ```shell + sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo + ``` + +1. Enable the CodeReady Builder repository: + + ```shell + sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms + ``` + +1. Install the WAF compiler: + + ```shell + sudo yum install nms-nap-compiler-v5.527.0 + ``` + +1. {{< include "nim/waf/restart-nms-integrations.md" >}} + +{{% /tab %}} + +{{% tab name="RHEL 9" %}} + +1. Download the `dependencies.repo` file to `/etc/yum.repos.d`: + + ```shell + sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo + ``` + +1. Enable the CodeReady Builder repository: + + ```shell + sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms + ``` + +1. Install the WAF compiler: + + ```shell + sudo yum install nms-nap-compiler-v5.527.0 + ``` + +1. {{< include "nim/waf/restart-nms-integrations.md" >}} + +{{% /tab %}} + +{{% tab name="Oracle Linux 8.1" %}} + +1. Download the `dependencies.repo` file to `/etc/yum.repos.d`: + + ```shell + sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo + ``` + +1. Enable the `ol8_codeready_builder` repository: + + ```shell + sudo yum-config-manager --enable ol8_codeready_builder + ``` + +1. Install the WAF compiler: + + ```shell + sudo yum install nms-nap-compiler-v5.527.0 + ``` + +1. {{< include "nim/waf/restart-nms-integrations.md" >}} + +{{% /tab %}} + +{{< /tabs >}} diff --git a/content/nim/waf-integration/configuration/manage-waf-configurations/_index.md b/content/nim/waf-integration/configuration/manage-waf-configurations/_index.md new file mode 100644 index 000000000..a1dc40927 --- /dev/null +++ b/content/nim/waf-integration/configuration/manage-waf-configurations/_index.md @@ -0,0 +1,8 @@ +--- +title: Configure WAF on instances +nd-docs: +weight: 600 +nd-landing-page: false +url: /nginx-instance-manager/waf-integration/configuration/manage-waf-configurations/ +--- + diff --git a/content/nim/waf-integration/configuration/manage-waf-configurations/add-configuration.md b/content/nim/waf-integration/configuration/manage-waf-configurations/add-configuration.md new file mode 100644 index 000000000..8f9eff61f --- /dev/null +++ b/content/nim/waf-integration/configuration/manage-waf-configurations/add-configuration.md @@ -0,0 +1,36 @@ +--- +title: Add WAF configuration +description: Add default or custom WAF policies to your NGINX instances. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +Start by adding an F5 WAF for NGINX configuration to your instances. You can apply one of the built-in security policies or reference your own custom policy bundle. + +The [F5 WAF for NGINX configuration guide]({{< ref "/waf/policies/configuration.md" >}}) explains how and where to add security directives in your NGINX configuration. **F5 NGINX Instance Manager** provides the same default security policies: + +- **NGINX Default Policy** — Includes [OWASP Top 10](https://owasp.org/www-project-top-ten/) protections and basic bot mitigation. +- **NGINX Strict Policy** — Applies tighter blocking criteria than the default policy and may increase the risk of false positives. + +You can use these defaults as-is or customize them for your application. Security Monitoring dashboards in **NGINX Instance Manager** can help you fine-tune policy behavior over time. + +## Before you begin + +Keep the following points in mind when configuring F5 WAF for NGINX through **NGINX Instance Manager**: + +- **Policy bundles:** Instance Manager compiles JSON security policies into `.tgz` bundles. +- **Custom policies:** Use the `app_protect_policy_file` directive to reference custom policies. If you’re using precompiled publication with NGINX Agent, change the file extension from `.json` to `.tgz`. The filename itself stays the same. **NGINX Instance Manager** doesn’t support mixing `.json` and `.tgz` references in the same configuration. +- **Access permissions:** Ensure the NGINX Agent can access directories where your policy files are stored. Update the `config_dirs` setting in the Agent configuration if needed. +- **Logging:** **NGINX Instance Manager** uses the default log profiles included with F5 WAF for NGINX. You can reference them with the `app_protect_security_log` directive. Custom log profiles aren’t supported. + +If your data plane uses different directory paths, update them accordingly in your configuration files. + +## Next steps + +Once you’ve added your WAF configuration: + +- [Edit the WAF configuration]({{< ref "edit-waf-configuration.md" >}}) to apply directives in your NGINX configuration files. +- [Verify the configuration]({{< ref "verify-configuration.md" >}}) to confirm that WAF is active on your instances. \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/manage-waf-configurations/edit-waf-configuration.md b/content/nim/waf-integration/configuration/manage-waf-configurations/edit-waf-configuration.md new file mode 100644 index 000000000..531bef035 --- /dev/null +++ b/content/nim/waf-integration/configuration/manage-waf-configurations/edit-waf-configuration.md @@ -0,0 +1,153 @@ +--- +title: Edit WAF configuration +description: Apply F5 WAF for NGINX directives in your NGINX configuration files. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +After you’ve added a WAF configuration to your instances, edit your NGINX configuration files to apply the required F5 WAF for NGINX directives. This step ensures that protection is enabled and that your configuration references the correct policy and log profile bundles. You can complete this task using the **F5 NGINX Instance Manager** web interface or REST API. + +## Example configuration + +Add the F5 WAF for NGINX directives in the appropriate context (`http`, `server`, or `location`). The following example shows a typical configuration: + +```nginx +server { + ... + + location / { + # Enable F5 WAF for NGINX + app_protect_enable on; + + # Reference a custom security policy bundle + app_protect_policy_file /etc/nms/ignore-xss.tgz; + + # Enable security logging + app_protect_security_log_enable on; + + # Reference the log profile bundle + app_protect_security_log /etc/nms/log-default.tgz /var/log/nginx/security-violations.log; + + ... + } +} +``` + +If you’re using **NGINX Instance Manager** with Security Monitoring, your configuration may already include the following directive: + +```nginx +app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; +``` + +**Don’t change this value.** For details, see the [Security Monitoring setup guide]({{< ref "/nim/security-monitoring/set-up-app-protect-instances.md" >}}). + +If you’re running **F5 WAF for NGINX Docker Compose**, note the following: + +- Add the `app_protect_enforcer_address` directive to the `http` context: + + ```nginx + app_protect_enforcer_address 127.0.0.1:50000; + ``` + +- JSON policies and log profiles aren’t supported. You must precompile and publish them using **NGINX Instance Manager**. Make sure the `precompiled_publication` setting in the NGINX Agent configuration is set to `true`. + See the [F5 WAF for NGINX configuration guide]({{< ref "/waf/configure/" >}}) for details. + +## Use the web interface or API + +{{}} +{{%tab name="Web interface"%}} + +1. {{< include "nim/webui-nim-login.md" >}} +2. In the left menu, select **Instances** or **Instance Groups**. +3. From the **Actions** menu (**…**), select **Edit Config** for the instance or group. +4. If you’re using precompiled publication, change any `.json` file extensions to `.tgz`. +5. To apply a default policy, select **Apply Security**, then copy the policy snippet and paste it into your configuration. +6. Add the directives inside an `http`, `server`, or `location` block. +7. Select **Publish** to push the configuration. + +{{%/tab%}} + +## Use the API + +{{%tab name="API"%}} + +{{< call-out "note" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{< /call-out>}} + +You can use the **NGINX Instance Manager** REST API to deploy your F5 WAF for NGINX configuration. + +{{}} + +| Method | Endpoint | +|--------|-----------| +| GET | `/api/platform/v1/systems/{systemUID}/instances` | +| POST | `/api/platform/v1/security/{systemUID}/instances/{nginxUID}/config` | + +{{}} + +{{< call-out "important" "Important:" >}}Before deploying a configuration to an instance group, make sure all instances in the group run the same version of F5 WAF for NGINX. Otherwise, deployment may fail.{{< /call-out >}} + +1. Send a `GET` request to list all instances. The response includes the unique identifier (UID) of the instance you want to update. + + ```shell + curl -X GET https://{{NMS_FQDN}}/api/platform/v1/systems/{systemUID}/instances \ + -H "Authorization: Bearer " + ``` + +2. Add the F5 WAF for NGINX configuration to your NGINX config file (`nginx.conf` or another file in a valid `config_dirs` path): + + - At a minimum, add the following directive: + + ```nginx + app_protect_enable on; + ``` + + - If precompiled publication is enabled, change any `.json` policy references to `.tgz`. + - To apply a default policy, use: + + ```nginx + app_protect_policy_file /etc/nms/NginxDefaultPolicy.tgz; + ``` + + or + + ```nginx + app_protect_policy_file /etc/nms/NginxStrictPolicy.tgz; + ``` + + - Add the directives to an `http`, `server`, or `location` context. + +3. Encode the updated NGINX configuration file using base64. + + ```shell + base64 -i /etc/nginx/nginx.conf + ``` + +4. Send a `POST` request to deploy the configuration. Replace `` with your encoded config. + + ```shell + curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/{systemUID}/instances/{nginxUID}/config \ + -H "Authorization: Bearer " \ + --header "Content-Type: application/json" \ + -d '{ + "configFiles": { + "rootDir": "/etc/nginx", + "files": [ + { + "name": "nginx.conf", + "contents": "" + } + ] + }, + "validateConfig": true + }' + ``` + +{{%/tab%}} +{{}} + +## Next steps + +After publishing the configuration, [verify the WAF configuration]({{< ref "verify-configuration.md" >}}) to confirm that protection is active on your instances. diff --git a/content/nim/waf-integration/configuration/manage-waf-configurations/onboard-custom-security-policies.md b/content/nim/waf-integration/configuration/manage-waf-configurations/onboard-custom-security-policies.md new file mode 100644 index 000000000..2a70bf43e --- /dev/null +++ b/content/nim/waf-integration/configuration/manage-waf-configurations/onboard-custom-security-policies.md @@ -0,0 +1,63 @@ +--- +title: Onboard custom security policies +description: Upload and prepare your own security policy bundles for use with NGINX Instance Manager. +toc: true +weight: 400 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +After verifying that F5 WAF for NGINX is active on your instances, you can onboard your own custom security policies. Use this option when you need to apply application-specific rules or integrate policies created in other environments. You’ll upload your JSON policy files, package them into `.tgz` bundles, and publish them through **F5 NGINX Instance Manager**. + +## Before you begin + +- Make sure the policy you plan to onboard is valid JSON and follows the F5 WAF for NGINX schema. +- Confirm that the NGINX Agent has permission to access the directory where you’ll store your bundles. +- Review the [F5 WAF for NGINX configuration guide]({{< ref "/waf/policies/configuration.md" >}}) for examples of policy structure and directive usage. + +## Upload and publish a custom policy + +{{}} +{{%tab name="Web interface"%}} + +1. {{< include "nim/webui-nim-login.md" >}} +2. In the left menu, select **Security Policies**. +3. Choose **Upload Policy**, then select your `.json` or `.tgz` policy file. +4. If you uploaded a `.json` file, **NGINX Instance Manager** automatically compiles it into a `.tgz` bundle. +5. After upload, select **Publish** to make the policy available to your instances. + +{{%/tab%}} + +{{%tab name="API"%}} + +{{< call-out "note" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{< /call-out>}} + +Use the **NGINX Instance Manager** REST API to onboard policies programmatically. + +{{}} + +| Method | Endpoint | +|--------|-----------| +| POST | `/api/platform/v1/security/policies` | +| GET | `/api/platform/v1/security/policies` | + +{{}} + +Example — upload and publish a policy: + +```shell +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " \ + --header "Content-Type: multipart/form-data" \ + -F "file=@my-custom-policy.json" +``` + +The API response includes the policy ID. Use that ID to reference your custom policy in your NGINX configuration: + +```nginx +app_protect_policy_file /etc/nms/my-custom-policy.tgz; +``` + +{{%/tab%}} +{{}} diff --git a/content/nim/waf-integration/configuration/manage-waf-configurations/verify-configuration.md b/content/nim/waf-integration/configuration/manage-waf-configurations/verify-configuration.md new file mode 100644 index 000000000..3a32f7911 --- /dev/null +++ b/content/nim/waf-integration/configuration/manage-waf-configurations/verify-configuration.md @@ -0,0 +1,29 @@ +--- +title: Verify WAF configuration +description: Confirm that F5 WAF for NGINX is active and running correctly on your instances. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +After applying your configuration, verify that F5 WAF for NGINX is active and running as expected on your instances. You can confirm status and version details through the **F5 NGINX Instance Manager** web interface. + +## Verify in NGINX Instance Manager + +1. {{< include "nim/webui-nim-login.md" >}} +2. In the left navigation menu, select **Instances**. +3. In the **F5 WAF** column, confirm that the correct version is listed for each instance. +4. Select an instance to open its details page. +5. Scroll to the **F5 WAF Details** section and confirm the following: + - **Status** is **Active**. + - **Build** matches the version installed on the instance. + - **Policy** reflects the policy bundle you applied. +6. (Optional) If Security Monitoring is enabled, review the dashboard for recent traffic and violation data. + +If WAF is not active or the version does not match, review your configuration and logs for errors. You may need to republish the configuration or verify file paths in the NGINX Agent settings. + +## Next steps + +- [Onboard custom security policies]({{< ref "onboard-custom-security-policies.md" >}}) to upload and prepare your own security bundles for use with NGINX Instance Manager. \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/onboard-instances/_index.md b/content/nim/waf-integration/configuration/onboard-instances/_index.md new file mode 100644 index 000000000..63657e675 --- /dev/null +++ b/content/nim/waf-integration/configuration/onboard-instances/_index.md @@ -0,0 +1,6 @@ +--- +title: Onboard instances +nd-docs: +weight: 400 +url: /nginx-instance-manager/waf-integration/configuration/onboard-instances/ +--- \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/onboard-instances/configure-docker-compose.md b/content/nim/waf-integration/configuration/onboard-instances/configure-docker-compose.md new file mode 100644 index 000000000..c5a6f9ce2 --- /dev/null +++ b/content/nim/waf-integration/configuration/onboard-instances/configure-docker-compose.md @@ -0,0 +1,79 @@ +--- +title: Configure Docker Compose +description: Update your Docker Compose file to run F5 WAF for NGINX. +toc: true +weight: 400 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +## Before you begin + +Before setting up Docker Compose, make sure you’ve done the following: + +- Install F5 WAF for NGINX by following the [installation guide]({{< ref "/waf/install/docker.md#hybrid-configuration" >}}). +- Create a `docker-compose.yaml` file as part of the installation process. + +In this section, you’ll update the file so F5 WAF for NGINX can integrate with NGINX Instance Manager. + +## Edit the Docker Compose file + +1. Edit the `docker-compose.yaml` file created during installation. + + To give F5 WAF for NGINX access to the policy and log profile bundles written by NGINX Instance Manager, make the following changes: + + - Add the line `user: 101:` to each service. The group ID should match the NGINX Agent group on your system. You can find the group ID by running: + + ```shell + cat /etc/group + ``` + + - Add `/etc/nms` to the volume maps for both services. + + **Example:** + + ```yaml + version: "3.9" + + services: + waf-enforcer: + container_name: waf-enforcer + image: private-registry.nginx.com/nap/waf-enforcer:5.2.0 + user: 101:1002 + environment: + - ENFORCER_PORT=50000 + ports: + - "50000:50000" + volumes: + - /opt/app_protect/bd_config:/opt/app_protect/bd_config + - /etc/nms:/etc/nms + networks: + - waf_network + restart: always + + waf-config-mgr: + container_name: waf-config-mgr + image: private-registry.nginx.com/nap/waf-config-mgr:5.2.0 + user: 101:1002 + 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 + - /etc/nms:/etc/nms + restart: always + network_mode: none + depends_on: + waf-enforcer: + condition: service_started + + networks: + waf_network: + driver: bridge + ``` + +2. Restart the containers: + + ```shell + docker compose restart + ``` \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md b/content/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md new file mode 100644 index 000000000..22df7f6e7 --- /dev/null +++ b/content/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md @@ -0,0 +1,57 @@ +--- +title: Configure NGINX Agent +description: Update the NGINX Agent configuration to enable F5 WAF for NGINX. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +{{< call-out "note" "Before you begin" >}} +- [Install NGINX Agent]({{< ref "/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md" >}}) +{{< /call-out >}} + +Follow these steps to enable F5 WAF for NGINX in NGINX Agent. + +1. Edit the NGINX Agent configuration file. + + Use any text editor. For example: + + ```shell + sudo vi /etc/nginx-agent/nginx-agent.conf + ``` + +1. Add or confirm the following settings: + + ```yaml + config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" + extensions: + - nginx-app-protect + nginx_app_protect: + report_interval: 15s + precompiled_publication: true + ``` + + These settings: + + - Let NGINX Agent read F5 WAF for NGINX configuration directories. + - Enable change detection for security configurations. + - Turn on precompiled publication of WAF configurations from NGINX Instance Manager. + + To apply these settings during installation, use the `--nginx-app-protect-mode` flag: + + ```shell + curl https:///install/nginx-agent > install.sh + sudo sh ./install.sh --nginx-app-protect-mode precompiled-publication + ``` + +1. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +{{< call-out "note" "Next steps" >}} +- [Verify the installation]({{< ref "/nim/waf-integration/configuration/onboard-instances/verify-installation.md" >}}) +{{< /call-out >}} diff --git a/content/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md b/content/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md new file mode 100644 index 000000000..758cd7e0e --- /dev/null +++ b/content/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md @@ -0,0 +1,24 @@ +--- +title: Install NGINX Agent +description: Install NGINX Agent on each F5 WAF for NGINX instance to connect it to NGINX Instance Manager. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +To onboard your F5 WAF for NGINX instances to NGINX Instance Manager, install and configure NGINX Agent on each instance. + +1. Use SSH to connect to an F5 WAF for NGINX instance. + Repeat these steps for each instance you want to onboard. + +1. Download the NGINX Agent package from your NGINX Instance Manager host and run the installation script. + + You can group instances that use the same version of F5 WAF for NGINX by including the optional `--instance-group` flag in the install command. + + {{< include "agent/installation/install-agent-api.md" >}} + +{{< call-out "note" "Next steps" >}} +- [Configure NGINX Agent]({{< ref "/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md" >}}) +{{< /call-out >}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/onboard-instances/verify-installation.md b/content/nim/waf-integration/configuration/onboard-instances/verify-installation.md new file mode 100644 index 000000000..14747c422 --- /dev/null +++ b/content/nim/waf-integration/configuration/onboard-instances/verify-installation.md @@ -0,0 +1,82 @@ +--- +title: Verify instance onboarding +description: Verify that F5 WAF for NGINX instances are connected and reporting to NGINX Instance Manager. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +{{< call-out "note" "Before you begin" >}} +- [Install NGINX Agent]({{< ref "/nim/waf-integration/configuration/onboard-instances/install-nginx-agent.md" >}}) +- [Configure NGINX Agent]({{< ref "/nim/waf-integration/configuration/onboard-instances/configure-nginx-agent.md" >}}) +{{< /call-out >}} + +After installing and configuring NGINX Agent, verify that your F5 WAF for NGINX instances appear in NGINX Instance Manager. + +{{}} + +{{%tab name="Web interface"%}} + +You can view your F5 WAF for NGINX instances in the Instance Manager web interface. Follow these steps to confirm that NGINX Agent is installed and reporting data correctly. + +1. {{< include "nim/webui-nim-login.md" >}} +1. In the left menu, select **Instances**. +1. Confirm that each instance lists an F5 WAF for NGINX version in the **F5 WAF** column. +1. Select an instance and scroll to the **F5 WAF Details** section to verify its status and build information. + +{{%/tab%}} + +{{%tab name="API"%}} + +{{< call-out "note" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{< /call-out>}} + +Use the REST API to check version and status details for F5 WAF for NGINX. + +{{}} + +| Method | Endpoint | +|--------|------------------------------| +| GET | `/api/platform/v1/instances` | +| GET | `/api/platform/v1/systems` | + +{{}} + +- Send a `GET` request to `/api/platform/v1/systems` to check version information. + + **Example response:** + + ```json + { + "count": 3, + "items": [ + { + "appProtect": { + "attackSignatureVersion": "2022.11.16", + "status": "active", + "threatCampaignVersion": "2022.11.15", + "version": "build-3.954.0" + } + } + ] + } + ``` + +- Send a `GET` request to `/api/platform/v1/instances` to check how many instances have F5 WAF for NGINX installed. + + **Example response:** + + ```json + { + "count": 3, + "items": [ + [...] + ], + "nginxAppProtectWAFCount": 2, + "nginxPlusCount": 3 + } + ``` + +{{%/tab%}} +{{}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md b/content/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md new file mode 100644 index 000000000..f034f42ce --- /dev/null +++ b/content/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md @@ -0,0 +1,38 @@ +--- +title: Set up attack signatures, bot signatures, and threat campaigns +nd-docs: +weight: 200 +nd-landing-page: true +url: /nginx-instance-manager/waf-integration/configuration/setup-signatures-and-threats/ +--- + +## Overview + +F5 WAF for NGINX protects your applications using predefined and regularly updated detection patterns: + +- **Attack signatures**: Known threat patterns used to detect common vulnerabilities and exploits. These are included with F5 WAF for NGINX and updated frequently to reflect the latest security threats. See the [attack signatures documentation]({{< ref "/waf/policies/attack-signatures.md" >}}) for more information. + +- **Threat campaigns**: Context-aware threat intelligence based on attack campaigns observed by F5 Threat Labs. These are updated even more frequently than attack signatures and require installation to take effect. Learn more in the [threat campaigns documentation]({{< ref "/waf/policies/threat-campaigns.md" >}}). + +- **Bot signatures**: Detection patterns designed to identify and classify automated bot traffic. These signatures help distinguish between legitimate bots, such as search engine crawlers, and malicious ones that perform credential stuffing, scraping, or denial-of-service attacks. See the [bot signatures documentation]({{< ref "/waf/policies/bot-signatures.md" >}}) for more information. + +To take advantage of the latest updates, you must upload the attack signature, bot signature, and threat campaign packages to NGINX Instance Manager. + +You can either: + +- Configure NGINX Instance Manager to automatically download new versions, or +- Manually download packages from MyF5 and upload them to NGINX Instance Manager using the REST API. + +## In this section + +{{}} + {{}} + Enable automatic updates in NGINX Instance Manager to keep F5 WAF for NGINX packages current. + {{}} + {{}} + Manually download and upload F5 WAF for NGINX security packages to NGINX Instance Manager. + {{}} + {{}} + Keep your Security Monitoring dashboards accurate by updating the attack signature database in NGINX Instance Manager. + {{}} +{{}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/setup-signatures-and-threats/automatic-download.md b/content/nim/waf-integration/configuration/setup-signatures-and-threats/automatic-download.md new file mode 100644 index 000000000..c23b2333b --- /dev/null +++ b/content/nim/waf-integration/configuration/setup-signatures-and-threats/automatic-download.md @@ -0,0 +1,50 @@ +--- +title: Automatically update security packages +description: Enable automatic updates in NGINX Instance Manager to keep F5 WAF for NGINX packages current. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +## Upload the F5 WAF for NGINX certificate and key + +To enable automatic downloads, NGINX Instance Manager must authenticate with the NGINX repository. Upload the repository certificate and private key provided with your F5 WAF for NGINX subscription. After you upload these files, NGINX Instance Manager can securely download the latest attack signature, bot signature, and threat campaign packages. + +{{< include "/nim/waf/upload-cert-and-key.md" >}} + +## Enable automatic downloads + +NGINX Instance Manager can automatically download the latest attack signatures, bot signatures, and threat campaign versions. To enable automatic downloads: + +1. Log in to the NGINX Instance Manager host using SSH. +1. Open the `/etc/nms/nms.conf` file in a text editor. +1. Adjust the `app_protect_security_update` settings as shown in the example below: + + ```yaml + integrations: + # enable this for integrations on tcp + # address: 127.0.0.1:8037 + address: unix:/var/run/nms/integrations.sock + dqlite: + addr: 127.0.0.1:7892 + app_protect_security_update: + # enable this to automatically retrieve the latest attack signatures, bot signatures, and threat campaigns + enable: true + # how often, in hours, to check for updates; default is 6 + interval: 6 + # how many updates to download; default is 10, max is 20 + number_of_updates: 10 + ``` + +1. Save the changes and close the file. +1. {{< include "/nim/waf/restart-nms-integrations.md" >}} + +If the F5 WAF for NGINX certificate or key is missing, invalid, or expired, you’ll see an error like this: + +```text +error when creating the nginx repo retriever - NGINX repo certificates not found +``` + +This means NGINX Instance Manager can’t connect to the NGINX repository to retrieve packages. Re-upload a valid certificate and key to resolve the issue. diff --git a/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md b/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md new file mode 100644 index 000000000..519e83b34 --- /dev/null +++ b/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md @@ -0,0 +1,170 @@ +--- +title: Manually update security packages +description: Manually download and upload F5 WAF for NGINX security packages to NGINX Instance Manager. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +If you prefer not to enable automatic updates, you can manually update the attack signature, bot signature, and threat campaign packages by downloading them from the NGINX repository and uploading them to NGINX Instance Manager. + +## Download packages from NGINX repository + +1. Log in to [MyF5](https://account.f5.com/myf5) and go to **My Products and Plans > Subscriptions**. + +1. Download the following files from your F5 WAF for NGINX subscription: + - `nginx-repo.crt` (certificate) + - `nginx-repo.key` (private key) + +1. Choose your Linux distribution path on the [NGINX repository](https://pkgs.nginx.com/app-protect-security-updates): + - **Ubuntu:** `/ubuntu/pool/nginx-plus/a/` + - **Debian:** `/debian/pool/nginx-plus/a/` + - **RHEL:** `/centos/<8 or 9>/x86_64/RPMS/` + +1. Download the `.deb` or `.rpm` packages from [pkgs.nginx.com](https://pkgs.nginx.com) using your F5 WAF for NGINX certificate and key. + + - **Attack signatures:** package names start with `app-protect-attack-signatures`. + + - `.deb` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates//pool/nginx-plus/a/app-protect-attack-signatures/app-protect-attack-signatures_-~_amd64.deb + ``` + + - Example: + + ```shell + curl --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/ubuntu/pool/nginx-plus/a/app-protect-attack-signatures/app-protect-attack-signatures_2025.07.24-1~noble_amd64.deb" \ + --output app-protect-attack-signatures_2025.07.24-1~noble_amd64.deb + ``` + + - `.rpm` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates/centos/<8 or 9>/x86_64/RPMS/app-protect-attack-signatures--.el<8 or 9>.ngx.x86_64.rpm + ``` + + - Example: + + ```shell + curl -v --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/centos/8/x86_64/RPMS/app-protect-attack-signatures-2025.07.24-1.el8.ngx.x86_64.rpm" \ + --output app-protect-attack-signatures-2025.07.24-1.el8.ngx.x86_64.rpm + ``` + + - **Bot signatures:** package names start with `app-protect-bot-signatures`. + + - `.deb` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates//pool/nginx-plus/a/app-protect-bot-signatures/app-protect-bot-signatures_-~_amd64.deb + ``` + + - Example: + + ```shell + curl --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/ubuntu/pool/nginx-plus/a/app-protect-bot-signatures/app-protect-bot-signatures_2025.07.09-1~noble_amd64.deb" \ + --output app-protect-bot-signatures_2025.07.09-1~noble_amd64.deb + ``` + + - `.rpm` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates/centos/<8 or 9>/x86_64/RPMS/app-protect-bot-signatures--.el<8 or 9>.ngx.x86_64.rpm + ``` + + - Example: + + ```shell + curl -v --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/centos/8/x86_64/RPMS/app-protect-bot-signatures-2025.07.09-1.el8.ngx.x86_64.rpm" \ + --output app-protect-bot-signatures-2025.07.09-1.el8.ngx.x86_64.rpm + ``` + + - **Threat campaigns:** package names start with `app-protect-threat-campaigns`. + + - `.deb` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates//pool/nginx-plus/a/app-protect-threat-campaigns/app-protect-threat-campaigns_-~_amd64.deb + ``` + + - Example: + + ```shell + curl --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/ubuntu/pool/nginx-plus/a/app-protect-threat-campaigns/app-protect-threat-campaigns_2025.07.29-1~noble_amd64.deb" \ + --output app-protect-threat-campaigns_2025.07.29-1~noble_amd64.deb + ``` + + - `.rpm` package format: + + ```text + https://pkgs.nginx.com/app-protect-security-updates/centos/<8 or 9>/x86_64/RPMS/app-protect-threat-campaigns--.el<8 or 9>.ngx.x86_64.rpm + ``` + + - Example: + + ```shell + curl -v --key nginx-repo.key \ + --cert nginx-repo.crt \ + "https://pkgs.nginx.com/app-protect-security-updates/centos/8/x86_64/RPMS/app-protect-threat-campaigns-2025.07.29-1.el8.ngx.x86_64.rpm" \ + --output app-protect-threat-campaigns-2025.07.29-1.el8.ngx.x86_64.rpm + ``` + +2. Extract the following files from the package: + - `signatures.bin.tgz`, `bot_signatures.bin.tgz`, or `threat_campaigns.bin.tgz` + - `signature_update.yaml`, `bot_signature_update.yaml`, or `threat_campaign_update.yaml` + - `version` + + Use `rpm2cpio | cpio` for `.rpm` packages or `ar` for `.deb` packages to extract the files. + +3. Create a `.tgz` bundle that includes the three files. For example: + + ```shell + tar -czvf attack-signatures.tgz signatures.bin.tgz signature_update.yaml version + +## Upload packages to NGINX Instance Manager + +Use the NGINX Instance Manager REST API to upload the `.tgz` files. + +**Upload attack signatures** + +```shell +curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \ + --header "Authorization: Bearer " \ + --form 'revisionTimestamp="2022.11.16"' \ + --form 'filename=@"/attack-signatures.tgz"' +``` + +**Upload bot signatures** + +```shell +curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/bot-signatures' \ + --header "Authorization: Bearer " \ + --form 'revisionTimestamp="2025.07.09"' \ + --form 'filename=@"/bot-signatures.tgz"' +``` + +**Upload threat campaigns** + +```shell +curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/threat-campaigns' \ + --header "Authorization: Bearer " \ + --form 'revisionTimestamp="2022.11.15"' \ + --form 'filename=@"/threat-campaigns.tgz"' +``` + +{{< call-out "important" >}} +The bundle you upload must match both the operating system and version of your NGINX Instance Manager host. +Create the `.tgz` file using the package built for the same OS and version to ensure compatibility. +{{< /call-out >}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/setup-signatures-and-threats/update-security-monitoring-signature-db.md b/content/nim/waf-integration/configuration/setup-signatures-and-threats/update-security-monitoring-signature-db.md new file mode 100644 index 000000000..72df36b44 --- /dev/null +++ b/content/nim/waf-integration/configuration/setup-signatures-and-threats/update-security-monitoring-signature-db.md @@ -0,0 +1,15 @@ +--- +title: Update Security Monitoring attack signature database +description: Keep your Security Monitoring dashboards accurate by updating the attack signature database in NGINX Instance Manager. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +The Security Monitoring dashboards in NGINX Instance Manager use an attack signature database to display details about detected security violations, including each signature’s name, accuracy, and risk level. + +To ensure your dashboards remain accurate and up to date, update the Security Monitoring attack signature database regularly. + +{{< include "/nim/security-monitoring/update-security-monitoring-attack-signature-database.md" >}} \ No newline at end of file diff --git a/content/nim/waf-integration/configuration/troubleshooting.md b/content/nim/waf-integration/configuration/troubleshooting.md new file mode 100644 index 000000000..eeb4b7365 --- /dev/null +++ b/content/nim/waf-integration/configuration/troubleshooting.md @@ -0,0 +1,142 @@ +--- +title: Troubleshooting +description: Resolve common issues with F5 WAF for NGINX and NGINX Instance Manager by verifying installation, configuration, and connectivity. +toc: true +weight: 1000 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +If you're having trouble with F5 WAF for NGINX, try the steps below. +If these steps don’t fix the issue, contact F5 Support. + +--- + +### Check that F5 WAF for NGINX is not installed on the NGINX Instance Manager host + +F5 WAF for NGINX and the WAF compiler shouldn’t run on the same host. To check: + +1. Log in to the NGINX Instance Manager host from a terminal. +1. Run the command that matches your operating system: + + - For Debian-based systems: + + ```shell + dpkg -s app-protect + ``` + + - For RPM-based systems: + + ```shell + rpm -qa | grep app-protect + ``` + +If F5 WAF for NGINX is installed, follow the [uninstall instructions]({{< ref "/waf/install/uninstall.md" >}}). + +--- + +### Check that the WAF compiler version matches the F5 WAF for NGINX version + +Each F5 WAF for NGINX release requires a matching WAF compiler version. To confirm: + +1. Log in to the NGINX Instance Manager host. +1. Run the following command to see installed compiler versions: + + ```shell + ls -l /opt/nms-nap-compiler + ``` + +--- + +### Confirm the WAF compiler is working correctly + +You can verify that the WAF compiler is installed and responsive. + +```shell +sudo /opt/nms-nap-compiler/app_protect-/bin/apcompile -h +``` + +**Example:** + +```shell +sudo /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -h +``` + +**Expected output:** + +```text +USAGE: + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile + +Examples: + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -p /path/to/policy.json -o mypolicy.tgz + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -p policyA.json -g myglobal.json -o /path/to/policyA_bundle.tgz + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -g myglobalsettings.json --global-state-outfile /path/to/myglobalstate.tgz + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -b /path/to/policy_bundle.tgz --dump + /opt/nms-nap-compiler/app_protect-5.527.0/bin/apcompile -l logprofA.json -o /path/to/logprofA_bundle.tgz +``` + +--- + +### Confirm NGINX Agent configuration on the F5 WAF for NGINX instance + +Open the `/etc/nginx-agent/nginx-agent.conf` file and make sure it includes the correct settings. + +```yaml +# Directories monitored for config files +config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" + +# Required extensions +extensions: + - nginx-app-protect + - nap-monitoring + +nginx_app_protect: + # Report interval for F5 WAF details + report_interval: 15s + # Enable precompiled policy and log profile publication from NGINX Instance Manager + precompiled_publication: true + +nap_monitoring: + # Buffer size for the collector — holds log lines and parsed entries + collector_buffer_size: 50000 + # Buffer size for the processor — processes log lines from the buffer + processor_buffer_size: 50000 + # IP address where the agent listens for syslog messages + syslog_ip: "127.0.0.1" + # Port number for receiving syslog messages + syslog_port: 514 +``` + +--- + +### Confirm access to the NGINX packages repository + +If automatic downloads for attack signatures, bot signatures, or threat campaigns fail, make sure the repository certificate and key are configured correctly. + +Run this command to test repository access: + +```shell +curl \ + --key /etc/ssl/nginx/nginx-repo.key \ + --cert /etc/ssl/nginx/nginx-repo.crt \ + https://pkgs.nginx.com/app-protect-security-updates/index.xml +``` + +**Expected output:** + +```text +... + + + + + + app-protect-attack-signatures + x86_64 + + + +... +``` diff --git a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md b/content/nim/waf-integration/overview.md similarity index 70% rename from content/nim/nginx-app-protect/overview-nap-waf-config-management.md rename to content/nim/waf-integration/overview.md index 150312e83..50c8deb15 100644 --- a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md +++ b/content/nim/waf-integration/overview.md @@ -8,29 +8,33 @@ type: - reference --- -## Overview - -F5 NGINX Instance Manager helps you manage [F5 WAF for NGINX](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/) security configurations. +F5 NGINX Instance Manager helps you manage [F5 WAF for NGINX]({{< ref "/waf/" >}}) security configurations. Use NGINX Instance Manager with F5 WAF for NGINX to inspect incoming traffic, detect threats, and block malicious requests. You can define policies in one place and push them to some or all of your F5 WAF for NGINX instances. -### Key features +## Key features - Manage WAF policies using the NGINX Instance Manager web interface or REST API -- Update attack signature and threat campaign packages +- Update attack signature, bot signature, and threat campaign packages - Compile WAF configurations into a binary bundle for deployment +{{< call-out "note" >}} +**New in version 2.21.0:** NGINX Instance Manager now supports **bot signatures**. +This feature adds detection and mitigation for automated bot traffic in your WAF policies. +Although it works with older agents, we recommend upgrading the **NGINX Agent to v2.43.0** or later for best results. +{{< /call-out >}} + ## Architecture NGINX Instance Manager lets you define and manage security policies, upload signature packages, and push configurations to your F5 WAF for NGINX instances. It can also compile your security configuration into a bundle before publishing it to the data plane. The **Security Monitoring** module shows real-time data from F5 WAF for NGINX so you can track traffic, spot anomalies, and fine-tune policies. -{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with NGINX App Protect architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to F5 WAF for NGINX instances in the data plane" >}} +{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with F5 WAF for NGINX architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to F5 WAF for NGINX instances in the data plane" >}} -### Security bundle compilation {#security-bundle} +## Security bundle compilation {#security-bundle} -NGINX Instance Manager includes a compiler that packages your complete WAF configuration — security policies, attack signatures, threat campaigns, and log profiles — into a single `.tgz` file. It then pushes this bundle to the selected F5 WAF for NGINX instances. +NGINX Instance Manager includes a compiler that packages your complete WAF configuration, including security policies, attack signatures, bot signatures, threat campaigns, and log profiles, into a single `.tgz` file. It then pushes this bundle to the selected F5 WAF for NGINX instances. **Why precompile with NGINX Instance Manager?** @@ -52,7 +56,7 @@ location / { ## Log profile compilation -You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). +You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`]({{< ref "/waf/logging/security-logs.md#app_protect_security_log" >}}) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). {{< call-out "important" >}} NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`. @@ -60,11 +64,12 @@ NGINX Instance Manager and Security Monitoring both use log profiles, but their ## Security management APIs -Use the NGINX Instance Manager REST API to automate updates across your F5 WAF for NGINX instances. You can use the API to manage: +Use the NGINX Instance Manager REST API to automate updates across your F5 WAF for NGINX instances. You can use the API to manage the following: - Security policies - Log profiles - Attack signatures +- Bot signatures - Threat campaigns Just like with the web interface, the compiler creates a binary bundle with your updates that you can push to your WAF instances. diff --git a/content/nim/waf-integration/policies-and-logs/_index.md b/content/nim/waf-integration/policies-and-logs/_index.md new file mode 100644 index 000000000..ce65f1ee0 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/_index.md @@ -0,0 +1,65 @@ +--- +title: Manage security policies and log profiles +description: Create, update, and deploy F5 WAF for NGINX security policies and log profiles using NGINX Instance Manager. +nd-docs: +weight: 300 +nd-content-type: landing-page +nd-landing-page: true +url: /nginx-instance-manager/waf-integration/policies-and-logs/ +--- + +## Overview + +F5 NGINX Instance Manager provides a centralized way to create, edit, and deploy F5 WAF for NGINX security configurations. You can manage security policies, log profiles, attack signatures, bot signatures, and threat campaigns through either the web interface or the REST API. + +You can also compile security policies and associated components—such as attack signatures, bot signatures, and threat campaigns—into a single policy bundle. Precompiling these bundles improves performance by avoiding separate compilation during deployment. + +{{< call-out "note" "Note" >}} +The following capabilities are available only through the NGINX Instance Manager REST API: + +- Create, read, update, and delete security log profiles +- Publish security policies, log profiles, attack signatures, bot signatures, and threat campaigns to instances and instance groups + +**Access the REST API** + +{{< include "nim/how-to-access-nim-api.md" >}} + +{{< /call-out >}} + + +--- + +## Before you begin + +Before you start, complete these prerequisites: + +- [Set up F5 WAF for NGINX configuration management]({{< ref "/nim/waf-integration/configuration/_index.md" >}}). +- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: + - **Module:** Instance Manager + - **Feature:** Instance Management → `READ` + - **Feature:** Security Policies → `READ`, `CREATE`, `UPDATE`, `DELETE` + +To use policy bundles, you also need: + +- `UPDATE` permissions for each referenced security policy +- The correct [`nms-nap-compiler` package]({{< ref "/nim/waf-integration/configuration/install-waf-compiler/_index.md" >}}) for your F5 WAF for NGINX version +- The required [attack signatures, bot signatures, and threat campaigns]({{< ref "/nim/waf-integration/configuration/setup-signatures-and-threats/_index.md" >}}) + +--- + +## Featured content + +{{}} + {{}} + Create and manage security policies that define how traffic is inspected, including rules for cookies, parameters, URLs, and attack signatures. + {{}} + {{}} + Create and manage precompiled security bundles for consistent, efficient deployment across instances. + {{}} + {{}} + Define how security events are logged and stored for analysis and troubleshooting. + {{}} + {{}} + Deploy and verify updates to security policies and log profiles across managed instances. + {{}} +{{}} \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/bundles/_index.md b/content/nim/waf-integration/policies-and-logs/bundles/_index.md new file mode 100644 index 000000000..462d52806 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/bundles/_index.md @@ -0,0 +1,6 @@ +--- +title: Security bundles +nd-docs: +weight: 200 +url: /nginx-instance-manager/waf-integration/policies-and-logs/bundles/ +--- \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md b/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md new file mode 100644 index 000000000..3a2dc00c2 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md @@ -0,0 +1,168 @@ +--- +title: Create a security policy bundle +description: Create a precompiled security bundle that packages your F5 WAF for NGINX policies, signatures, and threat campaigns into a single file for efficient, reusable deployment across instances. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +NGINX Instance Manager lets you package your complete F5 WAF for NGINX configuration into a precompiled bundle for faster, more reliable deployments. + +A security policy bundle includes your policies, attack signatures, bot signatures, and threat campaigns—compiled into a single `.tgz` file that can be deployed across multiple instances. + +Precompiling with NGINX Instance Manager reduces processing overhead on WAF instances and ensures consistent, reusable configurations. + +{{< call-out "note" "See also" >}}For a full overview of how NGINX Instance Manager handles WAF policy management, compilation, and deployment, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}).{{< /call-out >}} + +{{}} + +{{%tab name="Web interface"%}} + +To create a security policy bundle using the NGINX Instance Manager web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. In the left menu, select **WAF > Policies**. +3. On the **Security Policies** page, find the policy you want to create a bundle for. +4. Select the **Actions** menu (…) and choose **Compile**. +5. Check the **Compilation Status** column to monitor the bundle creation progress. + - The default status is **Not Compiled**. + - Other states include **Compiling**, **Compiled**, and **Error**. + +> **Note:** By default, **Compile** uses the latest revision of the selected policy, the latest available compiler version, and the most recent versions of attack signatures, bot signatures, and threat campaigns. + +{{% /tab %}} + +{{%tab name="REST API"%}} + +To create a security policy bundle, send a `POST` request to the Security Policy Bundles API. The policies you want to include in the bundle must already exist in NGINX Instance Manager. + +Each bundle includes: + +- A security policy +- Attack signatures +- Bot signatures +- Threat campaigns +- A version of F5 WAF for NGINX +- Supporting files required to compile and deploy the bundle + +### Required fields + +- `appProtectWAFVersion`: The version of F5 WAF for NGINX to target. +- `policyName`: The name of the policy to include. Must reference an existing policy. +- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. + +If you don’t include `attackSignatureVersionDateTime`, `botSignatureVersionDateTime`, or `threatCampaignVersionDateTime`, the latest versions are used by default. You can also set them explicitly by using `"latest"` as the value. + +| Method | Endpoint | +|--------|-----------| +| POST | `/api/platform/v1/security/policies/bundles` | + +Example: + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @security-policy-bundles.json +``` + +{{< details summary="JSON request" open=true >}} + +```json +{ + "bundles": [ + { + "appProtectWAFVersion": "4.457.0", + "policyName": "default-enforcement", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.06.20", + "botSignatureVersionDateTime": "2023.07.09", + "threatCampaignVersionDateTime": "2023.07.18" + }, + { + "appProtectWAFVersion": "4.279.0", + "policyName": "default-enforcement", + "attackSignatureVersionDateTime": "latest", + "botSignatureVersionDateTime": "latest", + "threatCampaignVersionDateTime": "latest" + }, + { + "appProtectWAFVersion": "4.457.0", + "policyName": "ignore-xss" + } + ] +} +``` + +{{< /details >}} + +{{< details summary="JSON response" open=true >}} + +```json +{ + "items": [ + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.457.0", + "policyName": "default-enforcement", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.06.20", + "botSignatureVersionDateTime": "2023.07.09", + "threatCampaignVersionDateTime": "2023.07.18", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiling", + "message": "" + } + }, + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.279.0", + "policyName": "default-enforcement", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.08.10", + "botSignatureVersionDateTime": "2023.08.09", + "threatCampaignVersionDateTime": "2023.08.09", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiling", + "message": "" + } + }, + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.457.0", + "policyName": "ignore-xss", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.08.10", + "botSignatureVersionDateTime": "2023.08.09", + "threatCampaignVersionDateTime": "2023.08.09", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiling", + "message": "" + } + } + ] +} +``` + +{{< /details >}} + +{{% /tab %}} + +{{< /tabs >}} diff --git a/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md b/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md new file mode 100644 index 000000000..e29c432f6 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md @@ -0,0 +1,80 @@ +--- +title: Download a security policy bundle +description: Download a compiled F5 WAF for NGINX security bundle from NGINX Instance Manager as a `.tgz` file for reuse or offline deployment. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +{{}} + +{{%tab name="Web interface"%}} + +To download a security policy bundle using the NGINX Instance Manager web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. In the left menu, select **WAF > Policies**. +3. On the **Security Policies** page, find the policy you want to download a bundle for. +4. Select the **Actions** menu (…) and choose **Download Bundle**. + - The **Download Bundle** option is available only when the **Compilation Status** is **Compiled**. +5. When the download starts, a `.tgz` file named `-security-policy-bundle.tgz` is saved to your system. + +> **Note:** By default, **Download Bundle** retrieves the latest bundle revision of the selected policy. + +{{% /tab %}} + +{{%tab name="REST API"%}} + +To download a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. + +You must have `"READ"` permission for the bundle to retrieve it. + +| Method | Endpoint | +|--------|-----------| +| GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | + +Example: + +```shell +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ + -H "Authorization: Bearer " +``` + +The response includes a `content` field that contains the bundle in base64 format. To use it, decode the content and save it as a `.tgz` file. + +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ + -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz +``` + +{{< details summary="JSON response" open=true >}} + +```json +{ + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.457.0", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.08.10", + "botSignatureVersionDateTime": "2023.08.09", + "threatCampaignVersionDateTime": "2023.08.09", + "uid": "" + }, + "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", + "compilationStatus": { + "status": "compiled", + "message": "" + } +} +``` + +{{< /details >}} + +{{% /tab %}} + +{{< /tabs >}} diff --git a/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md b/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md new file mode 100644 index 000000000..f3299c6fb --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md @@ -0,0 +1,118 @@ +--- +title: List security policy bundles +description: View and filter the list of compiled F5 WAF for NGINX security bundles in NGINX Instance Manager, including their status, version, and associated policies. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +{{}} + +{{%tab name="Web interface"%}} + +To view the list of security policy bundles using the NGINX Instance Manager web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. In the left menu, select **WAF > Policies**. + +The list shows all available security policy bundles, including their compilation status and associated F5 WAF for NGINX version. + +{{% /tab %}} + +{{%tab name="REST API"%}} + +To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. + +You’ll only see bundles you have `"READ"` permissions for. + +You can use the following query parameters to filter results: + +- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. +- `policyName`: Return only bundles that match this policy name. +- `policyUID`: Return only bundles that match this policy UID. +- `startTime`: Return only bundles modified at or after this time. +- `endTime`: Return only bundles modified before this time. + +If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. + +| Method | Endpoint | +|--------|-----------| +| GET | `/api/platform/v1/security/policies/bundles` | + +Example: + +```shell +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ + -H "Authorization: Bearer " +``` + +{{< details summary="JSON response" open=true >}} + +```json +{ + "items": [ + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.457.0", + "policyName": "default-enforcement", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.06.20", + "botSignatureVersionDateTime": "2023.07.09", + "threatCampaignVersionDateTime": "2023.07.18", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiled", + "message": "" + } + }, + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.279.0", + "policyName": "default-enforcement", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.08.10", + "botSignatureVersionDateTime": "2023.08.09", + "threatCampaignVersionDateTime": "2023.08.09", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiled", + "message": "" + } + }, + { + "metadata": { + "created": "2023-10-04T23:19:58.502Z", + "modified": "2023-10-04T23:19:58.502Z", + "appProtectWAFVersion": "4.457.0", + "policyName": "ignore-xss", + "policyUID": "", + "attackSignatureVersionDateTime": "2023.08.10", + "botSignatureVersionDateTime": "2023.08.09", + "threatCampaignVersionDateTime": "2023.08.09", + "uid": "" + }, + "content": "", + "compilationStatus": { + "status": "compiling", + "message": "" + } + } + ] +} +``` + +{{< /details >}} + +{{% /tab %}} + +{{< /tabs >}} \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/_index.md b/content/nim/waf-integration/policies-and-logs/log-profiles/_index.md new file mode 100644 index 000000000..dc4331b4a --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/_index.md @@ -0,0 +1,6 @@ +--- +title: Security log profiles +nd-docs: +weight: 300 +url: /nginx-instance-manager/waf-integration/policies-and-logs/log-profiles/ +--- \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md new file mode 100644 index 000000000..78c4c8d24 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md @@ -0,0 +1,69 @@ +--- +title: Create a security log profile +description: Create and upload a new F5 WAF for NGINX security log profile to NGINX Instance Manager using the REST API. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can create and upload new F5 WAF for NGINX security log profiles using the NGINX Instance Manager REST API. + +A log profile defines how security events are recorded and exported from your NGINX instances. + +To upload a log profile, send a `POST` request to the Security Log Profiles API endpoint. The log profile must be encoded in `base64`; sending plain JSON will cause the request to fail. + +{{< call-out "note" "Access the REST API" >}} +{{< include "nim/how-to-access-nim-api.md" >}} +{{< /call-out >}} + +{{< table >}} + +| Method | Endpoint | +|--------|-----------------------------------------| +| POST | `/api/platform/v1/security/logprofiles` | + +{{< /table >}} + + +Example: + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ + -H "Authorization: Bearer " \ + -d @default-log-example.json +``` + +
+JSON Request + +```json +{ + "metadata": { + "name": "default-log-example" + }, + "content": "Cgl7CgkJImZpbHRlciI6IHsKCQkJInJlcXVlc3RfdHlwZSI6ICJpbGxlZ2FsIgoJCX0sCgkJImNvbnRlbnQiOiB7CgkJCSJmb3JtYXQiOiAiZGVmYXVsdCIsCgkJCSJtYXhfcmVxdWVzdF9zaXplIjogImFueSIsCgkJCSJtYXhfbWVzc2FnZV9zaXplIjogIjVrIgoJCX0KCX0=" +} +``` + +
+ +
+JSON Response + +```json +{ + "metadata": { + "created": "2023-07-05T22:09:19.634358096Z", + "externalIdType": "", + "modified": "2023-07-05T22:09:19.634358096Z", + "name": "default-log-example", + "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", + "uid": "" + }, + "selfLink": { + "rel": "/api/platform/v1/security/logprofiles/" + } +} +``` diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md new file mode 100644 index 000000000..8bf195759 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md @@ -0,0 +1,37 @@ +--- +title: Delete a security log profile +description: Remove an existing F5 WAF for NGINX security log profile from NGINX Instance Manager using the REST API. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can delete an existing F5 WAF for NGINX security log profile from NGINX Instance Manager using the REST API. +Deleting a log profile permanently removes it from the system. + +To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. + +{{< call-out "note" "Access the REST API" >}} +{{< include "nim/how-to-access-nim-api.md" >}} +{{< /call-out >}} + +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | + + +1. Retrieve the UID: + + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ + -H "Authorization: Bearer " + ``` + +2. Send the delete request: + + ```shell + curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " + ``` diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md new file mode 100644 index 000000000..f83d0e93b --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md @@ -0,0 +1,58 @@ +--- +title: Update a security log profile +description: Update an existing F5 WAF for NGINX security log profile or create a new revision using the NGINX Instance Manager REST API. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can update an existing F5 WAF for NGINX security log profile using the NGINX Instance Manager REST API. Depending on your workflow, you can either overwrite the current version or create a new revision. + +To update a log profile, use one of the following methods: + +- `POST` with the `isNewRevision=true` parameter to create a new revision. +- `PUT` with the log profile UID to overwrite the existing version. + +{{< call-out "note" "Access the REST API" >}} +{{< include "nim/how-to-access-nim-api.md" >}} +{{< /call-out >}} + +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | +| PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | + +### Create a new revision + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @update-default-log.json +``` + +### Overwrite an existing log profile + +To overwrite an existing security log profile: + +1. Retrieve the profile’s UID: + + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + -H "Content-Type application/json" \ + -d @update-log-profile.json + ``` + +2. Update the log profile using the UID: + + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @update-log-profile.json + ``` + +After updating the security log profile, you can [publish it to specific instances or instance groups]({{< ref "/nim/waf-integration/policies-and-logs/publish/_index.md" >}}). diff --git a/content/nim/waf-integration/policies-and-logs/policies/_index.md b/content/nim/waf-integration/policies-and-logs/policies/_index.md new file mode 100644 index 000000000..49b914088 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/_index.md @@ -0,0 +1,6 @@ +--- +title: Security policies +nd-docs: +weight: 100 +url: /nginx-instance-manager/waf-integration/policies-and-logs/policies/ +--- diff --git a/content/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md b/content/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md new file mode 100644 index 000000000..fd833c14f --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md @@ -0,0 +1,127 @@ +--- +title: "Add signature sets and exceptions" +description: Configure attack signature sets and exceptions in F5 WAF for NGINX policies to fine-tune protection and reduce false positives. +weight: 400 +toc: true +nd-content-type: how-to +nd-product: NIM +--- + +This topic describes how to configure signature sets and signature exceptions in F5 WAF for NGINX policies. When you add or edit a policy, NGINX Instance Manager provides options to customize attack signatures to better protect your applications. + +## Understanding signature sets and exceptions + +Attack signatures are rules or patterns that identify known attack sequences or classes of attacks on a web application. F5 WAF for NGINX includes predefined attack signatures grouped into signature sets. + +### Signature sets + +A **signature set** is a collection of attack signatures with a specific name and purpose. These sets are predefined and can be enabled or disabled in your policy. + +For example, you might have sets for SQL Injection Signatures, Cross-Site Scripting Signatures, or Buffer Overflow Signatures. + +### Signature exceptions + +A **signature exception** allows you to explicitly enable or disable individual attack signatures within a set. This gives you fine-grained control over your policy. For example: + +- If a signature in a set causes false positives (blocking legitimate traffic), you can create an exception to disable that signature while keeping the rest of the set active. +- If you want to enable blocking for a single attack signature rather than an entire set, you can create an exception to enable just that signature. + +## Add signature sets + +From the NGINX Instance Manager web interface, go to **WAF** > **Policies** and select **Add policy**. The policy editor opens, where you can: + +1. In **General Settings**, name and describe the policy. +2. Go to the **Web Protection** section and select **Attack Signature Sets**. Here, you can: + - View all enabled attack signature sets, including the defaults. + - Add new signature sets. + - Modify existing signature sets. + +### Configure signature sets + +For each signature set, you can configure the following options: + +- **Alarm** – When enabled, matching requests are logged. +- **Block** – When enabled, matching requests are blocked. + +For example, to configure the Buffer Overflow Signatures set to log but not block requests: + +```json +{ + "policy": { + "name": "buffer_overflow_signature", + "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, + "signature-sets": [ + { + "name": "Buffer Overflow Signatures", + "alarm": true, + "block": false + } + ] + } +} +``` + +### Remove signature sets + +To remove a signature set from your policy, you can: + +1. Disable the set by setting both `alarm` and `block` to `false`: + + ```json + { + "policy": { + "name": "no_xpath_policy", + "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, + "signature-sets": [ + { + "name": "XPath Injection Signatures", + "block": false, + "alarm": false + } + ] + } + } + ``` + +2. Use the `$action` meta-property to delete the set (preferred for better performance): + + ```json + { + "policy": { + "name": "no_xpath_policy", + "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, + "signature-sets": [ + { + "name": "XPath Injection Signatures", + "$action": "delete" + } + ] + } + } + ``` + +## Add signature exceptions + +From the **Web Protection** section, select **Attack Signature Exceptions**. This allows you to override settings for individual signatures. + +1. Select **Add item** to create a new exception. +2. Choose the signature or signatures you want to modify. +3. Configure the exception. For example, to disable a specific signature: + + ```json + { + "signatures": [ + { + "name": "_mem_bin access", + "enabled": false, + "signatureId": 200100022 + } + ] + } + ``` + +4. Select **Add policy**. The policy JSON updates with your changes, and the new policy appears in the list under the name you provided. + +From the **NGINX Instance Manager** web interface, you can review and modify saved policies at any time. Go to **WAF** > **Policies** to view or edit an existing policy. + +For a complete list of available signature sets and detailed information about attack signatures, see the [Attack Signatures]({{< ref "/waf/policies/attack-signatures.md" >}}) documentation. diff --git a/content/nim/waf-integration/policies-and-logs/policies/cookies-parameters-urls.md b/content/nim/waf-integration/policies-and-logs/policies/cookies-parameters-urls.md new file mode 100644 index 000000000..c7d6e5b18 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/cookies-parameters-urls.md @@ -0,0 +1,182 @@ +--- +title: Add cookies, parameters, and URLs +description: Configure cookie, parameter, and URL protections in your F5 WAF for NGINX policies using NGINX Instance Manager. +toc: true +weight: 500 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +## Add cookies + +Cookie protections can be configured and managed directly in the policy editor by selecting **Cookies** in the web interface. + +### Cookie properties and types + +Each cookie configuration includes: + +- `Cookie Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see [Matching Types: Explicit vs Wildcard]({{< ref "/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md" >}}). +- `Cookie Name`: The name of the cookie to monitor or protect. +- `Enforcement Type`: + - **Allow**: The cookie can be changed by the client and is not protected from modification. + - **Enforce**: The cookie cannot be changed by the client. +- `Attack Signatures`: Indicates whether attack signatures and threat campaigns are enabled, disabled, or not applicable. +- `Mask value in logs`: When enabled, the cookie's value is masked in the request log for improved security and privacy. + +For a complete list of configurable cookie properties and options, see the [Cookie Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `cookies` section. + +### Cookie violations + +Select **Edit configuration** to configure cookie violations. The following violations can be configured for cookies: + +- `VIOL_COOKIE_EXPIRED`: Triggered when a cookie's timestamp is expired. +- `VIOL_COOKIE_LENGTH`: Triggered when a cookie length exceeds the configured limit. +- `VIOL_COOKIE_MALFORMED`: Triggered when cookies are not RFC-compliant. +- `VIOL_COOKIE_MODIFIED`: Triggered when domain cookies have been tampered with. + +For each violation type, you can: + +- Set the enforcement action. +- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings. + +See [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. + +### Add a cookie to your policy + +1. Choose a **Cookie Type**: + - Select either `Explicit` for exact cookie matching or `Wildcard` for pattern-based matching. +2. Configure basic properties: + - Enter the `Cookie Name`. + - Choose whether to mask the cookie value in logs. +3. Set an **Enforcement Type**: + - Choose either `Allow` or `Enforce`. +4. (Optional) Configure attack signatures: + - If enabled, you can override attack signatures for this cookie. + - For details on signature configuration, see [Add Signature Sets]({{< ref "/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md" >}}). +5. Select **Add cookie** to save your configuration. + +## Add parameters + +Parameter protections can be configured and managed directly in the policy editor by selecting **Parameters** in the web interface. + +### Parameter properties and types + +Each parameter configuration includes: + +- `Parameter Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see [Matching Types: Explicit vs Wildcard]({{< ref "/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md" >}}). +- `Parameter Name`: The name of the parameter. +- `Location`: Where the parameter is expected (URL query string, POST data, etc.). +- `Value Type`: The expected type of the parameter value (for example, alphanumeric, integer, or email). +- `Attack Signatures`: Whether attack signature checking is enabled for this parameter. +- `Mask value in logs`: When enabled, the parameter's value is masked in the request log for enhanced security and privacy. This sets the `sensitiveParameter` property of the parameter item. + +For a complete list of configurable parameter properties and options, see the [Parameter Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `parameters` section. + +### Parameter violations + +Select **Edit configuration** to configure parameter violations. The following violations can be configured for parameters: + +- `VIOL_PARAMETER`: Triggered when an illegal parameter is detected. +- `VIOL_PARAMETER_ARRAY_VALUE`: Triggered when an array parameter value is illegal. +- `VIOL_PARAMETER_DATA_TYPE`: Triggered when a parameter’s data type doesn’t match the configured policy. +- `VIOL_PARAMETER_EMPTY_VALUE`: Triggered when a parameter value is empty but shouldn’t be. +- `VIOL_PARAMETER_LOCATION`: Triggered when a parameter is found in the wrong location. +- `VIOL_PARAMETER_MULTIPART_NULL_VALUE`: Triggered when the multi-part request has a parameter value that contains a null character (`0x00`). +- `VIOL_PARAMETER_NAME_METACHAR`: Triggered when illegal meta characters are found in a parameter name. +- `VIOL_PARAMETER_NUMERIC_VALUE`: Triggered when a numeric parameter value is outside the allowed range. +- `VIOL_PARAMETER_REPEATED`: Triggered when a parameter name is repeated illegally. +- `VIOL_PARAMETER_STATIC_VALUE`: Triggered when a static parameter value doesn’t match the configured security policy. +- `VIOL_PARAMETER_VALUE_BASE64`: Triggered when the value isn’t a valid Base64 string. +- `VIOL_PARAMETER_VALUE_LENGTH`: Triggered when a parameter value length exceeds limits. +- `VIOL_PARAMETER_VALUE_METACHAR`: Triggered when illegal meta characters are found in a parameter value. +- `VIOL_PARAMETER_VALUE_REGEXP`: Triggered when a parameter value doesn’t match the required pattern. + +For each violation type, you can: + +- Set the enforcement action. +- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings. + +See [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. + +### Add a parameter to your policy + +1. Choose a **Parameter Type**: + - Select either `Explicit` for exact parameter matching or `Wildcard` for pattern-based matching. +2. Configure basic properties: + - Enter the `Parameter Name`. + - Select the `Location` where the parameter is expected. + - Choose the `Value Type` (alphanumeric, integer, email, etc.). + - Set the `Data Type` if applicable. +3. Set security options: + - Choose whether to enable attack signatures. + + {{< call-out "important" >}} + Attack signatures are only applicable when the Value Type is `User Input` or `Array`, and the Data Type is either `Alphanumeric` or `Binary`. + {{< /call-out >}} + + - Decide if parameter values should be masked in logs. This sets the `sensitiveParameter` property. +4. (Optional) Configure attack signatures: + - If enabled, you can override attack signatures for this parameter. + - For details on signature configuration, see [Add Signature Sets]({{< ref "/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md" >}}). +5. Select **Add parameter** to save your configuration. + +## Add URLs + +URL protections can be configured and managed directly in the policy editor by selecting **URLs** in the web interface. + +### URL properties and types + +Each URL configuration includes: + +- `URL Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see [Matching Types: Explicit vs Wildcard]({{< ref "/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md" >}}). +- `Method`: Specifies the HTTP method(s) for the URL (`GET`, `POST`, `PUT`, etc.). +- `Protocol`: The protocol for the URL (`HTTP` or `HTTPS`). +- `Enforcement Type`: + - **Allow**: Permits access to the URL with optional attack signature checks. + - **Disallow**: Blocks access to the URL entirely. +- `Attack Signatures`: Indicates whether attack signatures and threat campaigns are enabled, disabled, or not applicable. + +{{< call-out "important" >}} +Attack signatures are automatically shown as “Not applicable” when the Enforcement Type is set to `Disallow`, since the URL is explicitly blocked and signature checking is unnecessary. +{{< /call-out >}} + +For a complete list of configurable URL properties and options, see the [URL Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `urls` section. + +### URL violations + +Select **Edit configuration** to configure URL violations. The following violations can be configured for URLs: + +- `VIOL_URL`: Triggered when an illegal URL is accessed. +- `VIOL_URL_CONTENT_TYPE`: Triggered when there’s an illegal request content type. +- `VIOL_URL_LENGTH`: Triggered when the URL length exceeds the configured limit. +- `VIOL_URL_METACHAR`: Triggered when illegal meta characters are found in the URL. + +For each violation type, you can: + +- Set the enforcement action. +- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings. + +See [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. + +### Add a URL to your policy + +1. Choose a **URL Type**: + - Select either `Explicit` for exact URL matching or `Wildcard` for pattern-based matching. +2. Configure basic properties: + - Enter the `URL` path (for example, `/index.html`, `/api/data`). + - The URL path must start with `/`. + - Select the HTTP `Method(s)` (for example, `GET`, `POST`, `*`). + - Choose the `Protocol` (`HTTP` or `HTTPS`). +3. Set enforcement: + - Choose whether to allow or disallow the URL. + - If **Allow** is selected, you can optionally enable attack signatures. + + {{< call-out "important" >}} + Attack signatures cannot be enabled for disallowed URLs. + {{< /call-out >}} + +4. (Optional) Configure attack signatures: + - If enabled, you can override attack signatures for this specific URL. + - For details on signature configuration, see [Add Signature Sets]({{< ref "/nim/waf-integration/policies-and-logs/policies/add-signature-sets.md" >}}). +5. Select **Add URL** to save your configuration. \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/policies/create-policy.md b/content/nim/waf-integration/policies-and-logs/policies/create-policy.md new file mode 100644 index 000000000..09abb4947 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/create-policy.md @@ -0,0 +1,137 @@ +--- +title: Create a security policy +description: Create and customize F5 WAF for NGINX security policies in NGINX Instance Manager using the web interface or REST API. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can create and manage security policies in F5 NGINX Instance Manager to control F5 WAF for NGINX behavior. When you create a policy, the interface provides guided options and presets aligned with F5 WAF for NGINX. If you’re familiar with WAF configuration, you can also customize your policy directly in JSON. + +{{< call-out "note" "See also" >}}For a full overview of how NGINX Instance Manager handles WAF policy management, compilation, and deployment, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}).{{< /call-out >}} + +--- + +{{}} + +{{%tab name="Web interface"%}} + +To create a security policy using the NGINX Instance Manager web interface: + +1. In NGINX Instance Manager, go to **WAF > Policies**. +2. On the **Security Policies** page, select **Create**. +3. In **General Settings**, enter a name and description for the policy. +4. Choose an enforcement mode: + - **Transparent** – Logs violations but doesn’t block requests. + - **Blocking** – Blocks requests that match the configured policy. + + In the configuration file, this is set using the `enforcementMode` property. + +5. To change character encoding, select **Show Advanced Fields**, then choose an application language. The default encoding is Unicode (`utf-8`). + +### Configure a policy + +When you use the web interface, a default policy is created automatically. You can also select **NGINX Strict** for a stricter configuration. + +### Default policy and base template + +The default policy is based on the base template, which serves as a starting point for all policies. + +**Example default policy:** + +```json +{ + "policy": { + "name": "app_protect_default_policy", + "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" } + } +} +``` + +### Violation rating + +The default policy uses the violation rating to assess risk and decide whether to block a request: + +{{< table >}} +| Rating | Description | +|---------|-------------| +| 0 | No violation | +| 1–2 | False positive | +| 3 | Needs examination | +| 4–5 | Threat | +{{}} + +By default, most violations and signature sets have Alarm enabled but not Block. If a request’s violation rating is 4 or 5, it’s blocked by the `VIOL_RATING_THREAT` violation, even if other violations are only set to Alarm. This approach minimizes false positives while maintaining strong protection. + +To block requests with a rating of 3, enable blocking for the `VIOL_RATING_NEED_EXAMINATION` violation. + +### Default blocking behavior + +The following violations and signature sets are considered high accuracy and are configured to block requests regardless of violation rating: + +- High-accuracy attack signatures +- Threat campaigns +- Malformed requests (for example, unparsable headers, cookies, or JSON/XML bodies) + +{{%/tab%}} + +{{%tab name="API"%}} + +To create a security policy using the REST API, send a `POST` request to the Security Policies endpoint. The JSON policy must be encoded in `base64`. If you send plain JSON, the request fails. + +{{< table >}} +| Method | Endpoint | +|--------|-----------| +| POST | `/api/platform/v1/security/policies` | +{{}} + +**Example:** + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @ignore-xss-example.json +``` + +{{< details summary="JSON request" open=true >}} + +```json +{ + "metadata": { + "name": "ignore-cross-site-scripting", + "displayName": "Ignore cross-site scripting", + "description": "A security policy that intentionally ignores cross-site scripting." + }, + "content": "ewoJInBvbGljeSI6IHsKCQkibmFtZSI6ICJzaW1wbGUtYmxvY2tpbmctcG9saWN5IiwKCQkic2lnbmF0dXJlcyI6IFsKCQkJewoJCQkJInNpZ25hdHVyZUlkIjogMjAwMDAxODM0LAoJCQkJImVuYWJsZWQiOiBmYWxzZQoJCQl9CgkJXSwKCQkidGVtcGxhdGUiOiB7CgkJCSJuYW1lIjogIlBPTElDWV9URU1QTEFURV9OR0lOWF9CQVNFIgoJCX0sCgkJImFwcGxpY2F0aW9uTGFuZ3VhZ2UiOiAidXRmLTgiLAoJCSJlbmZvcmNlbWVudE1vZGUiOiAiYmxvY2tpbmciCgl9Cn0=" +} +``` + +{{< /details >}} + +{{< details summary="JSON response" open=true >}} + +```json +{ + "metadata": { + "created": "2022-04-10T23:19:58.502Z", + "description": "string", + "displayName": "Ignore cross-site scripting", + "modified": "2022-04-12T23:19:58.502Z", + "name": "ignore-cross-site-scripting", + "revisionTimestamp": "2022-04-12T23:19:58.502Z", + "uid": "" + }, + "selfLink": { + "rel": "/api/platform/v1/services/environments/prod" + } +} +``` + +{{< /details >}} + +{{%/tab%}} + +{{< /tabs >}} diff --git a/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md b/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md new file mode 100644 index 000000000..d9b8cfbe7 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md @@ -0,0 +1,57 @@ +--- +title: Delete a security policy +description: Remove an existing F5 WAF for NGINX security policy using the NGINX Instance Manager web interface or REST API. +toc: true +weight: 300 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can delete a security policy using either the NGINX Instance Manager web interface or the REST API. + +--- + +{{}} + +{{%tab name="Web interface"%}} + +To delete a policy in the web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +1. From the Launchpad, select **Instance Manager**. +1. In the left menu, select **WAF > Policies**. +1. On the **Security Policies** page, locate the policy you want to delete. +1. Select the **Actions** menu (**...**) and choose **Delete**. + +{{%/tab%}} + +{{%tab name="API"%}} + +To delete a policy using the REST API: + +1. Retrieve the policy’s UID by sending a `GET` request to the Security Policies endpoint: + + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " + ``` + +1. Use the policy UID in a `DELETE` request: + +{{< table >}} +| Method | Endpoint | +|--------|------------------------------------------------------------| +| DELETE | `/api/platform/v1/security/policies/{policy-uid}` | +{{}} + +**Example:** + +```shell +curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ + -H "Authorization: Bearer " +``` + +{{%/tab%}} + +{{}} diff --git a/content/nim/waf-integration/policies-and-logs/policies/review-policy.md b/content/nim/waf-integration/policies-and-logs/policies/review-policy.md new file mode 100644 index 000000000..fddb9611e --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/review-policy.md @@ -0,0 +1,38 @@ +--- +title: Review policy +description: Review and manage stored F5 WAF for NGINX policies and their version history in NGINX Instance Manager. +toc: true +weight: 600 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +Before deploying a policy to an NGINX instance or instance group, you can review it in NGINX Instance Manager. The system stores all F5 WAF for NGINX policies and their version history, so you can review details or roll back to an earlier version if needed. + +## Review policies + +In the NGINX Instance Manager web interface, go to **WAF > Policies**, then select the security policy you want to review. The **Security Policies** page includes the following tabs: + +- **Details**, which includes: + - Policy Details: Descriptions, status, enforcement type, latest version, and last deployed time. + - Deployments: List of instances and instance groups where the F5 WAF for NGINX policy is deployed. +- **Policy JSON** – Shows the full security policy in JSON format. Select **Edit** to make changes directly. +- **Versions** – Displays previous revisions of the security policy. You can redeploy an older version if necessary. + +## Manage existing policies + +From **WAF > Policies**, you can manage your existing policies. On the **Security Policies** page, locate the security policy and select the **Actions** (...) menu. The following options are available: + +- **Edit** – Modify the selected security policy. +- **Compile** – Precompile the complete WAF configuration — including security policies, attack signatures, threat campaigns, and log profiles — into a single `.tgz` bundle and push it to the selected F5 WAF for NGINX instances. +- **Save As** – Create a copy of the security policy under a new name to use as a baseline for customization. +- **Export as JSON** – Download the security policy definition in JSON format. +- **Download Bundle** – Download the compiled `.tgz` security bundle for reuse or offline deployment. +- **Delete** – Permanently remove the security policy from NGINX Instance Manager. + +{{< call-out "note" "Note" >}} +If you use **Save As** to create a new policy, include the `app_protect_cookie_seed` [directive]({{< ref "/waf/policies/directives.md" >}}). +{{< /call-out >}} + +{{< call-out "note" "See also" >}}For a full overview of how NGINX Instance Manager handles WAF policy management, compilation, and deployment, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}).{{< /call-out >}} \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/policies/update-policy.md b/content/nim/waf-integration/policies-and-logs/policies/update-policy.md new file mode 100644 index 000000000..b2a719933 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/update-policy.md @@ -0,0 +1,75 @@ +--- +title: Update a security policy +description: Update an existing F5 WAF for NGINX policy using the NGINX Instance Manager web interface or REST API. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +You can update an existing F5 WAF for NGINX security policy using either the NGINX Instance Manager web interface or the REST API. + +--- + +{{}} + +{{%tab name="Web interface"%}} + +To update a policy in the web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +1. From the Launchpad, select **Instance Manager**. +1. In the left menu, select **WAF > Policies**. +1. On the **Security Policies** page, select **Edit** from the **Actions** column for the policy you want to update. +1. The editor opens, allowing you to modify the policy as described in [Create a security policy]({{< ref "/nim/waf-integration/policies-and-logs/policies/create-policy.md" >}}). +1. After making your changes, select **Save**. + +{{%/tab%}} + +{{%tab name="API"%}} + +To update a policy using the REST API, send either a `POST` or `PUT` request to the Security Policies endpoint. + +- Use `POST` with the `isNewRevision=true` parameter to create a new revision of an existing policy. +- Use `PUT` with the policy UID to overwrite the existing version. + +{{< table >}} +| Method | Endpoint | +|--------|-----------| +| POST | `/api/platform/v1/security/policies?isNewRevision=true` | +| PUT | `/api/platform/v1/security/policies/{policy_uid}` | +{{}} + +**Example using POST (create new revision):** + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @update-xss-policy.json +``` + +**Example using PUT (overwrite existing):** + +1. Retrieve the policy’s unique identifier (UID): + + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " + ``` + +1. Include the UID in your `PUT` request: + + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @update-xss-policy.json + ``` + +After updating the policy, you can [publish it]({{< ref "/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md" >}}) to selected instances or instance groups. + +{{%/tab%}} + +{{}} diff --git a/content/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md b/content/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md new file mode 100644 index 000000000..c4ab83aa4 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/policies/waf-policy-matching-types.md @@ -0,0 +1,41 @@ +--- +title: "Matching types: Explicit vs. Wildcard" +description: Learn how explicit and wildcard matching determine how F5 WAF for NGINX identifies and protects URLs, cookies, and parameters. +toc: true +weight: 700 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +In F5 WAF for NGINX, you can define how the WAF identifies and protects URLs, cookies, and parameters using **explicit** or **wildcard** matching. The matching type determines how closely the WAF compares incoming requests to the entities defined in your security policy. + +## Explicit matching + +Explicit matching applies protection to exact names or paths in your application. Use this option when you want to secure specific, known entities. + +**Examples:** + +- URLs: `/index.html`, `/api/data` +- Cookies: `sessionId`, `userPrefs` +- Parameters: `username`, `email` + +Explicit matching is best for applications with well-defined structures or limited dynamic content. + +## Wildcard matching + +Wildcard matching uses patterns to cover multiple related names or paths. Use this option when names follow a predictable pattern or are generated dynamically. + +**Examples:** + +- URLs: `/test*` matches `/test`, `/test123`, `/testing` +- Cookies: `test*` matches `test`, `test123`, `testing` +- Parameters: `user*` matches `username`, `user_id`, `userEmail` + +Wildcard matching is useful when: + +- You need to apply the same protection to a group of similar entities +- The names or paths may vary dynamically +- You want to simplify maintenance by reducing the number of explicit entries + +Both explicit and wildcard matching let you define additional security properties such as enforcement mode, attack signatures, and other policy options, depending on the entity type. \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/publish/_index.md b/content/nim/waf-integration/policies-and-logs/publish/_index.md new file mode 100644 index 000000000..9dcfa0e85 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/publish/_index.md @@ -0,0 +1,6 @@ +--- +title: Publish updates +nd-docs: +weight: 400 +url: /nginx-instance-manager/waf-integration/policies-and-logs/publish/ +--- \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md b/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md new file mode 100644 index 000000000..007d1f1f4 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md @@ -0,0 +1,92 @@ +--- +title: Check publication status +description: Verify the deployment status of published F5 WAF for NGINX security policies, log profiles, and related updates in NGINX Instance Manager. +toc: true +weight: 200 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +After you publish security updates, you can check their deployment status using the NGINX Instance Manager REST API. + +These endpoints help you verify whether security policies, log profiles, and other configurations were successfully deployed to instances or instance groups. + +{{< call-out "note" "Access the REST API" >}} +{{< include "nim/how-to-access-nim-api.md" >}} +{{< /call-out >}} + +--- + +### Check publication status for a security policy + +To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. + +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | + +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ + -H "Authorization: Bearer " +``` + +In the response, check the `lastDeploymentDetails` field under `instance` or `instanceGroup.instances` for deployment results. + +--- + +### Check publication status for a security log profile + +| Method | Endpoint | +|--------|-------------------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | + +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ + -H "Authorization: Bearer " +``` + +The response includes a `lastDeploymentDetails` field for each instance or instance group. + +--- + +### Check status for a specific instance + +To view deployment status for a specific instance, provide the system UID and instance UID. + +| Method | Endpoint | +|--------|------------------------------------------------------------------| +| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | + +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ + -H "Authorization: Bearer " +``` + +In the response, the `lastDeploymentDetails` field shows deployment status, timestamps, and any related error messages. + +--- + +### Check deployment result by deployment ID + +When you use the Publish API to [publish security content](#publish-policy), NGINX Instance Manager assigns a deployment ID to the request. +You can use this ID to check the final result of the publication. + +| Method | Endpoint | +|--------|------------------------------------------------------------------| +| GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | + +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ + -H "Authorization: Bearer " +``` + +The response includes detailed deployment information, including success or failure status and any compiler error messages. diff --git a/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md b/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md new file mode 100644 index 000000000..7d1493e97 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md @@ -0,0 +1,99 @@ +--- +title: Publish updates to instances +description: Deploy updated F5 WAF for NGINX security policies, log profiles, signatures, and threat campaigns to your NGINX instances or instance groups using the Publish API. +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NIM +nd-docs: +--- + +Use the NGINX Instance Manager Publish API to deploy updated security configurations to your NGINX instances or instance groups. +You can publish security policies, log profiles, attack signatures, bot signatures, and threat campaigns. + +Call this endpoint **after** you’ve created or updated the resources you want to deploy. + +{{< call-out "note" "Access the REST API" >}} +{{< include "nim/how-to-access-nim-api.md" >}} +{{< /call-out >}} + +| Method | Endpoint | +|--------|-----------| +| POST | `/api/platform/v1/security/publish` | + +### Information to include in your request + +Include the following details in your request body, depending on what you’re publishing: + +- Instance and instance group UIDs +- Policy UID and name +- Log profile UID and name +- Attack signature library UID and version +- Bot signature library UID and version +- Threat campaign UID and version + +### Example request + +```shell +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d @publish-request.json +``` + +{{< details summary="JSON request" open=true >}} + +```json +{ + "publications": [ + { + "attackSignatureLibrary": { + "uid": "", + "versionDateTime": "2022.10.02" + }, + "botSignatureLibrary": { + "uid": "", + "versionDateTime": "2022.10.03" + }, + "instanceGroups": [ + "" + ], + "instances": [ + "" + ], + "logProfileContent": { + "name": "default-log-profile", + "uid": "" + }, + "policyContent": { + "name": "default-enforcement", + "uid": "" + }, + "threatCampaign": { + "uid": "", + "versionDateTime": "2022.10.01" + } + } + ] +} +``` + +{{< /details >}} + +{{< details summary="JSON response" open=true >}} + +```json +{ + "deployments": [ + { + "deploymentUID": "ddc781ca-15d6-46c9-86ea-e7bdb91e8dec", + "links": { + "rel": "/api/platform/v1/security/deployments/ddc781ca-15d6-46c9-86ea-e7bdb91e8dec" + }, + "result": "Publish security content request Accepted" + } + ] +} +``` + +{{< /details >}}