From 41c149761033a322d89d9323e7cdd23ee834178d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 28 Jun 2024 12:23:09 +0100 Subject: [PATCH 01/19] Initial draft of WAF policy compilation document --- .../app-protect-waf/compile-waf-policies.md | 356 ++++++++++++++++++ 1 file changed, 356 insertions(+) create mode 100644 docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md new file mode 100644 index 0000000000..9512a54188 --- /dev/null +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -0,0 +1,356 @@ +--- +docs: DOCS-000 +title: Compile NAP WAF policies using NGINX Instance Manager +weight: 300 +--- + +# Overview + +A very important piece to understanding is why the need to compline NAP waf policies and why do we want to accomplish this using NIM, instead of on our NGINX Ingress controller deployment. + +A new WAF policy needs to be compiled so the enforcing engage can act upon the newly created policy. Therefore, it is critical to ensure that any new or modifications to exisiting security policies are compiled so the enforcement engine will enforce the new rules in WAF. + +Why do we do this through NIM and not directly within NGINX Ingress controller or kubernetes? +The reason is simple. Compling a new policy can take quite a bit of time, depending on the size of the policy. It also consumes a lot of resources during compliation. This is not ideal for a Kubernetes environment and NGINX Ingress controller setup. Another benefit of compiling the WAF policies within NIM and then deploying them to your NGINX Ingress controlled deployment is that this new bundle can be consumed without having NGINX Ingress controller peform a reload. With that in mind, the better solution is to use NIM as your main point to build new policiess and bundles for NAP. Once the bundle is compiled, then update/add new policies to your NGINX Ingress controller deployment. + +In the following steps, we are going to walk through step by step the process of what it takes to create a security policy, create a bundle and then add that to our NGINX Ingress controller deployment. + +# Outline of the steps to follow + +1. Setup NIM console (install all necessary pieces including authentication) +2. Create a new security policy through the API + a. To create security policy bundles, send an HTTP POST request to the Security Policies Bundles API endpoint. The specified security policies you’d like to compile into security policy bundles must already exist in Instance Manager. This will be a .json file that will be uploaded (POST) to NIM. + b. The content of the policy **must** be base64 encoded before uploading. +3. Create a new security bundle through the API. + a. This has to have specific requirements for the security policy it will be attached to. +4. Once the bundle has been compiled, download the bundle through the API +5. Use new bundle with NAP in NIC + +# Step 1. +## Setup and ensure NIM is running and a user account as Access to the API + +The first step required when creating a NAP bundle for NIC is to create a new security policy, or use an exisiting security policy within NIM. This is required as we will associate the bundle we are creating with the security policy, allowing us to use a variety of policies and their perspective bundles as needed. In this example, we are going to be using the NIM API to create both the security policy and the bundle. Once those are created, we are then going to download the bundle in a .tgz format, which can then be used with NIC+NAP. + +Before we can create our policy and generate the bundle, we need to make sure have proper access. Once you have created the account to be used and has proper RBAC access, we need to Authorize the request user to the NIM API. You can use Basic Auth or OIDC. + +# Step 2. +## Create the security policy + +Now we are going to create our security policy using the API. +https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy + +We can use a tool like `Postman`, or `curl` to interact with API. + +We will be uploading .json files to create the security policy as well as the bundle in this document. + +NOTE: For the policy "content" itself, this **MUST** be base64 encoded or it will fail. + +For are example, we are going to use this`simple-policy.json` file with contents below: +```json +{ + "metadata": { + "name": "Nginxbundletest", + "displayName": "Nginxbundletest", + "description": "Ignore cross-site scripting is a security policy that intentionally ignores cross site scripting." + }, + "content": "ewoJInBvbGljeSI6IHsKCQkibmFtZSI6ICJzaW1wbGUtYmxvY2tpbmctcG9saWN5IiwKCQkic2lnbmF0dXJlcyI6IFsKCQkJewoJCQkJInNpZ25hdHVyZUlkIjogMjAwMDAxODM0LAoJCQkJImVuYWJsZWQiOiBmYWxzZQoJCQl9CgkJXSwKCQkidGVtcGxhdGUiOiB7CgkJCSJuYW1lIjogIlBPTElDWV9URU1QTEFURV9OR0lOWF9CQVNFIgoJCX0sCgkJImFwcGxpY2F0aW9uTGFuZ3VhZ2UiOiAidXRmLTgiLAoJCSJlbmZvcmNlbWVudE1vZGUiOiAiYmxvY2tpbmciCgl9Cn0=" +} +``` + +Next step, we need to POST the new security policy into NIM through the API. + +```shell +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " \ + -d @simple-policy.json +``` + +THe response back from the API, after the policy is successfully created. + +```json +{ + "metadata": { + "created": "2024-06-12T20:28:08.152171922Z", + "description": "Ignore cross-site scripting is a security policy that intentionally ignores cross site scripting.", + "displayName": "Nginxbundletest", + "externalId": "", + "externalIdType": "", + "modified": "2024-06-12T20:28:08.152171922Z", + "name": "Nginxbundletest", + "revisionTimestamp": "2024-06-12T20:28:08.152171922Z", + "uid": "6af9f261-658b-4be1-b07a-cebd83e917a1" + }, + "selfLink": { + "rel": "/api/platform/v1/security/policies/6af9f261-658b-4be1-b07a-cebd83e917a1" + } +} +``` + +NOTE: Take note of the `uid` field as we will need that when we download our bundle. + +# Step 3. +## Create the security bundle + +Next, we are going to create the security policy bundle using the API. +https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles + +A very important item that must be followed is that the bundle you will be creating, must line up with the proper WAF compiler version you are using. If you use the wrong version in your json payload (see above), you will receive an error similar to the below: + +``` +{"code":13018,"message":"Error compiling the security policy set: One or more of the specified compiler versions does not exist. Check the compiler versions, then try again."} +``` + +You can verify which compilers are installed on NIM, by checking which packages have been installed through the operating system (apt, dnf for example): + +Here is the contents of our `security-policy-bundles.json` file: + +```json +{ + "bundles": [ + { + "appProtectWAFVersion": "4.815.0", + "policyName": "Nginxbundletest", + "policyUID": "", + "attackSignatureVersionDateTime": "latest", + "threatCampaignVersionDateTime": "latest" + } + ] +} +``` + +Now, we send our request to create the bundle in NIM: + +``` +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ + -H "Authorization: Bearer " \ + -d @security-policy-bundles.json +``` +Response from NIM after successful POST of our bundle: + +```json +{ + "items": [ + { + "compilationStatus": { + "message": "", + "status": "compiling" + }, + "content": "", + "metadata": { + "appProtectWAFVersion": "4.815.0", + "attackSignatureVersionDateTime": "2024.02.21", + "created": "2024-06-12T13:28:20.023775785-07:00", + "modified": "2024-06-12T13:28:20.023775785-07:00", + "policyName": "Nginxbundletest", + "policyUID": "6af9f261-658b-4be1-b07a-cebd83e917a1", + "threatCampaignVersionDateTime": "2024.02.25", + "uid": "cbdf9577-6d81-43d6-8ce1-2e3d4714e8b5" + } + } + ] +} +``` + +Now we can query for the bundlle that we just created in the above command: + +# Step 4. +## List security bundles +Here we are going to list or newly created bundle +Here we can list our security bundles: + +``` +curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ +-H 'Authorization: Bearer +``` +Response showing our bundle we created earlier +```json +{ + "items": [ + { + "compilationStatus": { + "message": "", + "status": "compiled" + }, + "content": "", + "metadata": { + "appProtectWAFVersion": "4.815.0", + "attackSignatureVersionDateTime": "2024.02.21", + "created": "2024-06-13T09:09:10.809-07:00", + "modified": "2024-06-13T09:09:20-07:00", + "policyName": "Nginxbundletest", + "policyUID": "ec8681eb-1e25-4b71-93bd-b91f67c5ac99", + "threatCampaignVersionDateTime": "2024.02.25", + "uid": "de08b324-99d8-4155-b2eb-fe687b21034e" + } + } + ] +} +``` +Take note of the `uid` field. this is the UID for the security bundle which is required when download our bundle once it is compiled. + + +# Step 5. +## Download our security bundle + +```shell +curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz +``` + +In our example, we are using the `seucrity-policy-id` and the `security-policy-bundle-id` +```shell +curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658b-4be1-b07a-cebd83e917a1/bundles/de08b324-99d8-4155-b2eb-fe687b21034e' \ + -H "Authorization: Basic YWRtaW46UncxQXBQS3lRRTRuQXRXOFRYa1J4ZFdVSWVTSGtU" \ + | jq -r '.content' | base64 -d > security-policy-bundle.tgz +``` + + +# Step 6. +## Configure NIC Deployment + +Since we are going to use bundles for WAF running on NGINX Ingress controller, we will need to modify the deployment for NIC to add volumes and volumeMounts, where NIC can pick up the bundle when new ones are uploaded to the cluster. This path is specific and must be correct in order for the bundle to be pickedup and used within NIC: +Quick overview of what needs to be added: + +```yaml +volumes: +- name: +persistentVolumeClaim: + claimName: + +volumeMounts: +- name: + mountPath: /etc/nginx/waf/bundles +``` + +Full example of a deployment file with `volumes` and `volumeMounts` added: + +```yaml + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + app.kubernetes.io/name: nginx-ingress + #annotations: + #prometheus.io/scrape: "true" + #prometheus.io/port: "9113" + #prometheus.io/scheme: http + spec: + serviceAccountName: nginx-ingress + automountServiceAccountToken: true + securityContext: + seccompProfile: + type: RuntimeDefault + volumes: + - name: nginx-bundle-mount + emptydir: {} + containers: + - image: + imagePullPolicy: IfNotPresent + name: nginx-ingress + ports: + - name: http + containerPort: 80 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + resources: + requests: + cpu: "100m" + memory: "128Mi" + #limits: + # cpu: "1" + # memory: "1Gi" + securityContext: + allowPrivilegeEscalation: false + runAsUser: 101 #nginx + runAsNonRoot: true + capabilities: + drop: + - ALL + add: + - NET_BIND_SERVICE + volumeMounts: + - name: bundle-mount + mountPath: /etc/nginx/waf/bundles + env: + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + args: + - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + - -report-ingress-status + - -external-service=nginx-ingress +``` + +# Step 7. +## Create WAF policy: + +Before applying a policy, a WAF policy needs to be created. This WAF policy will use the newly created bundle we did in the previous steps. It must be copied over to `/etc/nginx/waf/bundles` so NIC can load the new bundle into WAF. + +In the below, `spec.waf.apBundle` is the name of the bundle that we downloaded from NIM. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: waf-policy +spec: + waf: + enable: true + apBundle: ".tgz" ### <-- this is the name of the bundle downloaded from NIM + securityLogs: + - enable: true + apLogConf: ".tgz" + logDest: "syslog:server=syslog-svc.default:514" +``` + +# Step 8. +## Create virtualServer resource and apply WAF policy +Now that we have our WAF policy created, we can now link the policy to our `virtualServer` resource: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: webapp +spec: + host: webapp.example.com + policies: + - name: waf-policy + upstreams: + - name: webapp + service: webapp-svc + port: 80 + routes: + - path: / + action: + pass: webapp +``` + +# Step 9. +## Upload the bundle to Kubernetes storage +Upload tarball to kubernetes cluster. `kubectl cp` or another mechanism. +Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. \ No newline at end of file From bb2b97d730ce5ab31ff286efee15db5321f38660 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 28 Jun 2024 13:35:44 +0100 Subject: [PATCH 02/19] Add initial IA corresponding to existing steps --- .../app-protect-waf/compile-waf-policies.md | 54 ++++++++++++++++--- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 9512a54188..9a85f3c806 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -4,16 +4,56 @@ title: Compile NAP WAF policies using NGINX Instance Manager weight: 300 --- -# Overview +## Overview -A very important piece to understanding is why the need to compline NAP waf policies and why do we want to accomplish this using NIM, instead of on our NGINX Ingress controller deployment. +This guide describes how to use F5 NGINX Instance Manager to compile NGINX App WAF Policies for use with NGINX Ingress Controller. -A new WAF policy needs to be compiled so the enforcing engage can act upon the newly created policy. Therefore, it is critical to ensure that any new or modifications to exisiting security policies are compiled so the enforcement engine will enforce the new rules in WAF. +NGINX App Protect WAF uses policies to configure which security features are enabled or disabled. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources (Depending on the size), so the preferred way to do this is with NGINX Instance Manager, reducing the impact on a NGINX Ingress Controller deployment. -Why do we do this through NIM and not directly within NGINX Ingress controller or kubernetes? -The reason is simple. Compling a new policy can take quite a bit of time, depending on the size of the policy. It also consumes a lot of resources during compliation. This is not ideal for a Kubernetes environment and NGINX Ingress controller setup. Another benefit of compiling the WAF policies within NIM and then deploying them to your NGINX Ingress controlled deployment is that this new bundle can be consumed without having NGINX Ingress controller peform a reload. With that in mind, the better solution is to use NIM as your main point to build new policiess and bundles for NAP. Once the bundle is compiled, then update/add new policies to your NGINX Ingress controller deployment. +By using NGINX Instance Manager to compile WAF policies, the policy bundle can also be used immediately by NGINX Ingress Controller without reloading. -In the following steps, we are going to walk through step by step the process of what it takes to create a security policy, create a bundle and then add that to our NGINX Ingress controller deployment. +The following steps describe how to use the NGINX Instance Manager API to create a new security policy, compile a bundle, then add it to NGINX Ingress Controller. + +## Before you start +### Requirements +- A working [NGINX Management Suite](https://docs.nginx.com/nginx-management-suite/installation/) instance. +- A NGINX Ingress Controller [deployment with NGINX App Protect WAF]({{< relref "/installation/integrations/app-protect-waf/installation" >}}). + +## Configure NGINX Instance Manager + + +## Create a new security policy + + + +## Create a new security bundle + + + +## Download the security bundle + + + +## Add volumes and volumeMounts to NGINX Ingress Controller + + + +## Upload the security bundle + + + +## Create WAF policy + + + +## Create VirtualServer resource and apply policy + + + + # Outline of the steps to follow @@ -96,7 +136,7 @@ https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf- A very important item that must be followed is that the bundle you will be creating, must line up with the proper WAF compiler version you are using. If you use the wrong version in your json payload (see above), you will receive an error similar to the below: -``` +```text {"code":13018,"message":"Error compiling the security policy set: One or more of the specified compiler versions does not exist. Check the compiler versions, then try again."} ``` From 9afe167ff4cc3fc3909d9bf779ce56880beaef4e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:36:25 +0000 Subject: [PATCH 03/19] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 9a85f3c806..641eac3df7 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -393,4 +393,4 @@ spec: # Step 9. ## Upload the bundle to Kubernetes storage Upload tarball to kubernetes cluster. `kubectl cp` or another mechanism. -Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. \ No newline at end of file +Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. From 3c3aaeb51cc95e4ec78d529c9c8b673b142e7fe5 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 5 Jul 2024 16:39:40 +0100 Subject: [PATCH 04/19] Add old content under new section headings --- .../app-protect-waf/compile-waf-policies.md | 77 +++++-------------- 1 file changed, 19 insertions(+), 58 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 641eac3df7..1c2f96934a 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -17,45 +17,10 @@ The following steps describe how to use the NGINX Instance Manager API to create ## Before you start ### Requirements - A working [NGINX Management Suite](https://docs.nginx.com/nginx-management-suite/installation/) instance. +- An [NGINX Management Suite user](https://docs.nginx.com/nginx-management-suite/admin-guides/authentication/basic-authentication/) for API requests. - A NGINX Ingress Controller [deployment with NGINX App Protect WAF]({{< relref "/installation/integrations/app-protect-waf/installation" >}}). -## Configure NGINX Instance Manager - - -## Create a new security policy - - - -## Create a new security bundle - - - -## Download the security bundle - - - -## Add volumes and volumeMounts to NGINX Ingress Controller - - - -## Upload the security bundle - - - -## Create WAF policy - - - -## Create VirtualServer resource and apply policy - - - - - -# Outline of the steps to follow +### What to expect 1. Setup NIM console (install all necessary pieces including authentication) 2. Create a new security policy through the API @@ -66,15 +31,18 @@ The following steps describe how to use the NGINX Instance Manager API to create 4. Once the bundle has been compiled, download the bundle through the API 5. Use new bundle with NAP in NIC -# Step 1. -## Setup and ensure NIM is running and a user account as Access to the API +## Configure NGINX Instance Manager + The first step required when creating a NAP bundle for NIC is to create a new security policy, or use an exisiting security policy within NIM. This is required as we will associate the bundle we are creating with the security policy, allowing us to use a variety of policies and their perspective bundles as needed. In this example, we are going to be using the NIM API to create both the security policy and the bundle. Once those are created, we are then going to download the bundle in a .tgz format, which can then be used with NIC+NAP. Before we can create our policy and generate the bundle, we need to make sure have proper access. Once you have created the account to be used and has proper RBAC access, we need to Authorize the request user to the NIM API. You can use Basic Auth or OIDC. -# Step 2. -## Create the security policy + +## Create a new security policy Now we are going to create our security policy using the API. https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy @@ -128,8 +96,7 @@ THe response back from the API, after the policy is successfully created. NOTE: Take note of the `uid` field as we will need that when we download our bundle. -# Step 3. -## Create the security bundle +## Create a new security bundle Next, we are going to create the security policy bundle using the API. https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles @@ -193,8 +160,7 @@ Response from NIM after successful POST of our bundle: Now we can query for the bundlle that we just created in the above command: -# Step 4. -## List security bundles + Here we are going to list or newly created bundle Here we can list our security bundles: @@ -228,9 +194,7 @@ Response showing our bundle we created earlier ``` Take note of the `uid` field. this is the UID for the security bundle which is required when download our bundle once it is compiled. - -# Step 5. -## Download our security bundle +## Download the security bundle ```shell curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz @@ -243,9 +207,7 @@ curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658 | jq -r '.content' | base64 -d > security-policy-bundle.tgz ``` - -# Step 6. -## Configure NIC Deployment +## Add volumes and volumeMounts to NGINX Ingress Controller Since we are going to use bundles for WAF running on NGINX Ingress controller, we will need to modify the deployment for NIC to add volumes and volumeMounts, where NIC can pick up the bundle when new ones are uploaded to the cluster. This path is specific and must be correct in order for the bundle to be pickedup and used within NIC: Quick overview of what needs to be added: @@ -345,8 +307,7 @@ spec: - -external-service=nginx-ingress ``` -# Step 7. -## Create WAF policy: +## Create WAF policy Before applying a policy, a WAF policy needs to be created. This WAF policy will use the newly created bundle we did in the previous steps. It must be copied over to `/etc/nginx/waf/bundles` so NIC can load the new bundle into WAF. @@ -367,8 +328,8 @@ spec: logDest: "syslog:server=syslog-svc.default:514" ``` -# Step 8. -## Create virtualServer resource and apply WAF policy +## Create VirtualServer resource and apply policy + Now that we have our WAF policy created, we can now link the policy to our `virtualServer` resource: ```yaml @@ -390,7 +351,7 @@ spec: pass: webapp ``` -# Step 9. -## Upload the bundle to Kubernetes storage +## Upload the security bundle + Upload tarball to kubernetes cluster. `kubectl cp` or another mechanism. -Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. +Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. \ No newline at end of file From a80ef9e04f9c17155bb259f5e162e84a3086bf76 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:41:04 +0000 Subject: [PATCH 05/19] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 1c2f96934a..7e46c9e16e 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -354,4 +354,4 @@ spec: ## Upload the security bundle Upload tarball to kubernetes cluster. `kubectl cp` or another mechanism. -Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. \ No newline at end of file +Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. From 25f6e7fe2ade7cae13513a2f3be17dfe065ed613 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 11 Jul 2024 11:43:10 +0100 Subject: [PATCH 06/19] Push working changes to clarify instructions --- .../app-protect-waf/compile-waf-policies.md | 75 +++++++------------ 1 file changed, 26 insertions(+), 49 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 7e46c9e16e..01a5c0ff6f 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -1,6 +1,7 @@ --- docs: DOCS-000 title: Compile NAP WAF policies using NGINX Instance Manager +toc: true weight: 300 --- @@ -17,43 +18,19 @@ The following steps describe how to use the NGINX Instance Manager API to create ## Before you start ### Requirements - A working [NGINX Management Suite](https://docs.nginx.com/nginx-management-suite/installation/) instance. -- An [NGINX Management Suite user](https://docs.nginx.com/nginx-management-suite/admin-guides/authentication/basic-authentication/) for API requests. -- A NGINX Ingress Controller [deployment with NGINX App Protect WAF]({{< relref "/installation/integrations/app-protect-waf/installation" >}}). - -### What to expect - -1. Setup NIM console (install all necessary pieces including authentication) -2. Create a new security policy through the API - a. To create security policy bundles, send an HTTP POST request to the Security Policies Bundles API endpoint. The specified security policies you’d like to compile into security policy bundles must already exist in Instance Manager. This will be a .json file that will be uploaded (POST) to NIM. - b. The content of the policy **must** be base64 encoded before uploading. -3. Create a new security bundle through the API. - a. This has to have specific requirements for the security policy it will be attached to. -4. Once the bundle has been compiled, download the bundle through the API -5. Use new bundle with NAP in NIC - -## Configure NGINX Instance Manager - - -The first step required when creating a NAP bundle for NIC is to create a new security policy, or use an exisiting security policy within NIM. This is required as we will associate the bundle we are creating with the security policy, allowing us to use a variety of policies and their perspective bundles as needed. In this example, we are going to be using the NIM API to create both the security policy and the bundle. Once those are created, we are then going to download the bundle in a .tgz format, which can then be used with NIC+NAP. - -Before we can create our policy and generate the bundle, we need to make sure have proper access. Once you have created the account to be used and has proper RBAC access, we need to Authorize the request user to the NIM API. You can use Basic Auth or OIDC. - +- An [NGINX Management Suite user](https://docs.nginx.com/nginx-management-suite/admin-guides/rbac/rbac-getting-started/) for API requests. +- A NGINX Ingress Controller [deployment with NGINX App Protect WAF]({{< relref "/installation/integrations/app-protect-waf/installation.md" >}}). ## Create a new security policy -Now we are going to create our security policy using the API. -https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy +{{< tip >}} You can skip this step if you intend to use an existing security policy. {{< /tip >}} -We can use a tool like `Postman`, or `curl` to interact with API. +First, create a [new security policy](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#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/) -We will be uploading .json files to create the security policy as well as the bundle in this document. +You will use the API to upload JSON files for the policy, which will be the same method for creating the bundle later. -NOTE: For the policy "content" itself, this **MUST** be base64 encoded or it will fail. +Create the file `simple-policy.json` with the contents below: -For are example, we are going to use this`simple-policy.json` file with contents below: ```json { "metadata": { @@ -65,7 +42,13 @@ For are example, we are going to use this`simple-policy.json` file with contents } ``` -Next step, we need to POST the new security policy into NIM through the API. +{{< warning >}} + +The `content` value must be base64 encoded or you will encounter an error. + +{{< /warning >}} + +In the same directory you created `simple-policy.json`, create a POST request for NGINX Instance Manager using the API. ```shell curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ @@ -73,7 +56,8 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ -d @simple-policy.json ``` -THe response back from the API, after the policy is successfully created. +You should receive an API response similar to the following output, indicating the policy has been successfully created. + ```json { @@ -94,22 +78,19 @@ THe response back from the API, after the policy is successfully created. } ``` -NOTE: Take note of the `uid` field as we will need that when we download our bundle. +**Take note of the *uid* field**, which will be used to download the bundle later. ## Create a new security bundle -Next, we are going to create the security policy bundle using the API. -https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles +Once you have created (Or selected) a security policy, you can now [create a security bundle](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles) 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. -A very important item that must be followed is that the bundle you will be creating, must line up with the proper WAF compiler version you are using. If you use the wrong version in your json payload (see above), you will receive an error similar to the below: +If the wrong version is noted in the JSON payload, you will receive an error similar to below: ```text {"code":13018,"message":"Error compiling the security policy set: One or more of the specified compiler versions does not exist. Check the compiler versions, then try again."} ``` -You can verify which compilers are installed on NIM, by checking which packages have been installed through the operating system (apt, dnf for example): - -Here is the contents of our `security-policy-bundles.json` file: +Create the file `security-policy-bundles.json`: ```json { @@ -125,14 +106,15 @@ Here is the contents of our `security-policy-bundles.json` file: } ``` -Now, we send our request to create the bundle in NIM: +Send a POST request to create the bundle through the API: -``` +```shell curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -d @security-policy-bundles.json ``` -Response from NIM after successful POST of our bundle: + +You should receive a response similar to the following: ```json { @@ -158,17 +140,12 @@ Response from NIM after successful POST of our bundle: } ``` -Now we can query for the bundlle that we just created in the above command: +You can use the API to list the security bundles, verifying the new addition: - -Here we are going to list or newly created bundle -Here we can list our security bundles: - -``` +```shell curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ -H 'Authorization: Bearer ``` -Response showing our bundle we created earlier ```json { "items": [ From 0d7e15a5213c2b299964dbfc32622653d97b72f2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 11 Jul 2024 15:16:10 +0100 Subject: [PATCH 07/19] Adjust whitespace --- .../integrations/app-protect-waf/compile-waf-policies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 01a5c0ff6f..9912a0d4ac 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -58,7 +58,6 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ You should receive an API response similar to the following output, indicating the policy has been successfully created. - ```json { "metadata": { From f439926e84d6b8ec4dd48b4812806fe3ddbd0f3b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 12 Jul 2024 14:37:02 +0100 Subject: [PATCH 08/19] Fix quotation marks breaking GH diff view --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 9912a0d4ac..d32e3fa159 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -143,7 +143,7 @@ You can use the API to list the security bundles, verifying the new addition: ```shell curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ --H 'Authorization: Bearer +-H "Authorization: Bearer " ``` ```json { From c066c6284fdcbc820b24f7302648e96b985bcaf3 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 12 Jul 2024 14:56:11 +0100 Subject: [PATCH 09/19] Add clarifying details for UIDs, update examples --- .../app-protect-waf/compile-waf-policies.md | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index d32e3fa159..507066e106 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -77,7 +77,13 @@ You should receive an API response similar to the following output, indicating t } ``` -**Take note of the *uid* field**, which will be used to download the bundle later. +{{< important >}} + +Take note of the *uid* field. + +It is one of two unique IDs we will use to download the bundle: it will be referenced as *policy-UID*. + +{{< /important >}} ## Create a new security bundle @@ -105,6 +111,8 @@ Create the file `security-policy-bundles.json`: } ``` +The *policyUID* value is left blank, as it is generated as part of the creating the bundle. + Send a POST request to create the bundle through the API: ```shell @@ -168,15 +176,25 @@ curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ ] } ``` -Take note of the `uid` field. this is the UID for the security bundle which is required when download our bundle once it is compiled. + +{{< important >}} + +Take note of the *uid* field. + +It is one of two unique IDs we will use to download the bundle: it will be referenced as *bundle-UID*. + +{{< /important >}} ## Download the security bundle +Use a GET request to download the security bundle using the policy and bundle IDs: + ```shell -curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz +curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies//bundles/" -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz ``` -In our example, we are using the `seucrity-policy-id` and the `security-policy-bundle-id` +This GET request uses the policy and bundle IDs from the previous examples: + ```shell curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658b-4be1-b07a-cebd83e917a1/bundles/de08b324-99d8-4155-b2eb-fe687b21034e' \ -H "Authorization: Basic YWRtaW46UncxQXBQS3lRRTRuQXRXOFRYa1J4ZFdVSWVTSGtU" \ From 96eda9fc82e387523cc5145dfcb0c2e641d17a45 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 16 Jul 2024 12:24:15 +0100 Subject: [PATCH 10/19] Make final draft edits --- .../app-protect-waf/compile-waf-policies.md | 30 ++++++++++++------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 507066e106..86feca319e 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -203,8 +203,9 @@ curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658 ## Add volumes and volumeMounts to NGINX Ingress Controller -Since we are going to use bundles for WAF running on NGINX Ingress controller, we will need to modify the deployment for NIC to add volumes and volumeMounts, where NIC can pick up the bundle when new ones are uploaded to the cluster. This path is specific and must be correct in order for the bundle to be pickedup and used within NIC: -Quick overview of what needs to be added: +In order to use the WAF security bundles, your NGINX Ingress Controller instance must have *volumes* and *volumeMounts*. Precise paths are used to detect when bundles are uploaded to the cluster. + +Here is an example of what must be added: ```yaml volumes: @@ -217,7 +218,7 @@ volumeMounts: mountPath: /etc/nginx/waf/bundles ``` -Full example of a deployment file with `volumes` and `volumeMounts` added: +A full example of a deployment file with `volumes` and `volumeMounts` may look like the following: ```yaml @@ -303,19 +304,21 @@ spec: ## Create WAF policy -Before applying a policy, a WAF policy needs to be created. This WAF policy will use the newly created bundle we did in the previous steps. It must be copied over to `/etc/nginx/waf/bundles` so NIC can load the new bundle into WAF. +Before a bundle can be processed, a WAF policy must be created. + +This policy is added to `/etc/nginx/waf/bundles`, allowing NGINX Ingress Controller to load it into WAF. -In the below, `spec.waf.apBundle` is the name of the bundle that we downloaded from NIM. +The example below shows the required WAF policy, and the *apBundle* and *apLogConf* fields you must use for the security bundle binary file (A tar ball). ```yaml apiVersion: k8s.nginx.org/v1 kind: Policy metadata: - name: waf-policy + name: spec: waf: enable: true - apBundle: ".tgz" ### <-- this is the name of the bundle downloaded from NIM + apBundle: ".tgz" securityLogs: - enable: true apLogConf: ".tgz" @@ -324,7 +327,7 @@ spec: ## Create VirtualServer resource and apply policy -Now that we have our WAF policy created, we can now link the policy to our `virtualServer` resource: +Once the WAF policy has been created, link it to your *virtualServer resource*. ```yaml apiVersion: k8s.nginx.org/v1 @@ -334,7 +337,7 @@ metadata: spec: host: webapp.example.com policies: - - name: waf-policy + - name: upstreams: - name: webapp service: webapp-svc @@ -347,5 +350,10 @@ spec: ## Upload the security bundle -Upload tarball to kubernetes cluster. `kubectl cp` or another mechanism. -Once the new bundle is uploaded to the kubernetes cluster, NIC will pick up the new bundle and load in the new WAF policy automatically. +The final step is to upload the security bundle binary to the Kubernetes cluster. + +```shell +kubectl cp +``` + +Once the bundle has been uploaded to the cluster, NGINX Ingress Controller will pick up and automatically load the new WAF policy. From d5c5f2e9c355d60567f43004b3f6382bcba4380c Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 16 Jul 2024 12:38:15 +0100 Subject: [PATCH 11/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Co-authored-by: Venktesh Shivam Patel Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 86feca319e..f7c16837e6 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -353,7 +353,7 @@ spec: The final step is to upload the security bundle binary to the Kubernetes cluster. ```shell -kubectl cp +kubectl cp /your/local/path/.tgz /:etc/nginx/waf/bundles.tgz ``` Once the bundle has been uploaded to the cluster, NGINX Ingress Controller will pick up and automatically load the new WAF policy. From 7fb674f57079af31af9c657be5b2d2c72439569a Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 16 Jul 2024 12:39:52 +0100 Subject: [PATCH 12/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Co-authored-by: Venktesh Shivam Patel Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index f7c16837e6..43a9d55b51 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -350,7 +350,7 @@ spec: ## Upload the security bundle -The final step is to upload the security bundle binary to the Kubernetes cluster. +The final step is to upload the security bundle binary to the NIC pods. ```shell kubectl cp /your/local/path/.tgz /:etc/nginx/waf/bundles.tgz From 8656e07cd58ea64504eaeaa0b2a7ea227d96bf86 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 16 Jul 2024 14:55:28 +0100 Subject: [PATCH 13/19] Apply suggestions from code review Co-authored-by: Shaun Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 43a9d55b51..9187e12ffc 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -7,9 +7,9 @@ weight: 300 ## Overview -This guide describes how to use F5 NGINX Instance Manager to compile NGINX App WAF Policies for use with NGINX Ingress Controller. +This guide describes how to use F5 NGINX Instance Manager to compile NGINX App Protect WAF Policies for use with NGINX Ingress Controller. -NGINX App Protect WAF uses policies to configure which security features are enabled or disabled. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources (Depending on the size), so the preferred way to do this is with NGINX Instance Manager, reducing the impact on a NGINX Ingress Controller deployment. +NGINX App Protect WAF uses policies to configure which security features are set. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources, depending on the size. The preferred way to do this is with NGINX Instance Manager. This will reduce the impact on a NGINX Ingress Controller deployment. By using NGINX Instance Manager to compile WAF policies, the policy bundle can also be used immediately by NGINX Ingress Controller without reloading. @@ -79,8 +79,7 @@ You should receive an API response similar to the following output, indicating t {{< important >}} -Take note of the *uid* field. - +Take note of the *uid* field: `"uid": "6af9f261-658b-4be1-b07a-cebd83e917a1"` It is one of two unique IDs we will use to download the bundle: it will be referenced as *policy-UID*. {{< /important >}} From 2cddcdb1c4518a07a993175f9aa7595c8032531f Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 16 Jul 2024 15:19:32 +0100 Subject: [PATCH 14/19] Apply suggestions from code review Co-authored-by: Shaun Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 9187e12ffc..20c6bd9406 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -178,7 +178,7 @@ curl --location 'https://127.0.0.1/api/platform/v1/security/policies/bundles' \ {{< important >}} -Take note of the *uid* field. +Take note of the *uid* field: `"uid": "de08b324-99d8-4155-b2eb-fe687b21034e"` It is one of two unique IDs we will use to download the bundle: it will be referenced as *bundle-UID*. @@ -320,7 +320,7 @@ spec: apBundle: ".tgz" securityLogs: - enable: true - apLogConf: ".tgz" + apLogBundle: ".tgz" logDest: "syslog:server=syslog-svc.default:514" ``` From 9c0bb202bec61ab887111b67d983c6bfb740a983 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 17 Jul 2024 11:51:44 +0100 Subject: [PATCH 15/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 20c6bd9406..389bbbda0f 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -321,7 +321,7 @@ spec: securityLogs: - enable: true apLogBundle: ".tgz" - logDest: "syslog:server=syslog-svc.default:514" + logDest: "" ``` ## Create VirtualServer resource and apply policy From 6a824ef19e5ddcc6111bc3c24ebd43898f36caad Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 17 Jul 2024 11:52:16 +0100 Subject: [PATCH 16/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 389bbbda0f..5eaf0fccc0 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -349,7 +349,7 @@ spec: ## Upload the security bundle -The final step is to upload the security bundle binary to the NIC pods. +The final step is to upload the security bundle binary to the NGINX Ingress Controller pods. ```shell kubectl cp /your/local/path/.tgz /:etc/nginx/waf/bundles.tgz From 3349ca7e079cec5715ff17cc80c3bd6689a24ca0 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 25 Jul 2024 12:10:51 +0100 Subject: [PATCH 17/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 5eaf0fccc0..1b4c6736b1 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -1,6 +1,6 @@ --- docs: DOCS-000 -title: Compile NAP WAF policies using NGINX Instance Manager +title: Compile NGINX App Protect WAF policies using NGINX Instance Manager toc: true weight: 300 --- From d65855d37d7c27bc15636fa1d56998c2f9ec32a7 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 1 Aug 2024 11:14:00 +0100 Subject: [PATCH 18/19] Update docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md Co-authored-by: Mike Jang Signed-off-by: Alan Dooley --- .../integrations/app-protect-waf/compile-waf-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index 1b4c6736b1..d225d9f537 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -9,7 +9,7 @@ weight: 300 This guide describes how to use F5 NGINX Instance Manager to compile NGINX App Protect WAF Policies for use with NGINX Ingress Controller. -NGINX App Protect WAF uses policies to configure which security features are set. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources, depending on the size. The preferred way to do this is with NGINX Instance Manager. This will reduce the impact on a NGINX Ingress Controller deployment. +NGINX App Protect WAF uses policies to configure which security features are set. When these policies are changed, they need to be compiled so that the engine can begin to use them. Compiling policies can take a large amount of time and resources. You can do this with the NGINX Instance Manager. This reduces the impact on a NGINX Ingress Controller deployment. By using NGINX Instance Manager to compile WAF policies, the policy bundle can also be used immediately by NGINX Ingress Controller without reloading. From d2171aaeb2e4b736f41110a59f9317376244aa6d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 1 Aug 2024 11:52:01 +0100 Subject: [PATCH 19/19] Fix tenses, other grammar improvements for imperative style --- .../app-protect-waf/compile-waf-policies.md | 28 ++++++++----------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md index d225d9f537..46ad91d8b3 100644 --- a/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md +++ b/docs/content/installation/integrations/app-protect-waf/compile-waf-policies.md @@ -25,9 +25,7 @@ The following steps describe how to use the NGINX Instance Manager API to create {{< tip >}} You can skip this step if you intend to use an existing security policy. {{< /tip >}} -First, create a [new security policy](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#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/) - -You will use the API to upload JSON files for the policy, which will be the same method for creating the bundle later. +Create a [new security policy](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#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 the file `simple-policy.json` with the contents below: @@ -42,11 +40,9 @@ Create the file `simple-policy.json` with the contents below: } ``` -{{< warning >}} - -The `content` value must be base64 encoded or you will encounter an error. +{{< warning >}} The `content` value must be base64 encoded or you will encounter an error. {{< /warning >}} -{{< /warning >}} +Upload the policy JSON files with the API, which is the same method to create the bundle later. In the same directory you created `simple-policy.json`, create a POST request for NGINX Instance Manager using the API. @@ -86,9 +82,9 @@ 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, you can now [create a security bundle](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles) 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. +Once you have created (Or selected) a security policy, [create a security bundle](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/manage-waf-security-policies/#create-security-policy-bundles) using the API. The version in the bundle you create **must** match the WAF compiler version you intend to use. -If the wrong version is noted in the JSON payload, you will receive an error similar to below: +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: ```text {"code":13018,"message":"Error compiling the security policy set: One or more of the specified compiler versions does not exist. Check the compiler versions, then try again."} @@ -202,9 +198,9 @@ curl -X GET -k 'https://127.0.0.1/api/platform/v1/security/policies/6af9f261-658 ## Add volumes and volumeMounts to NGINX Ingress Controller -In order to use the WAF security bundles, your NGINX Ingress Controller instance must have *volumes* and *volumeMounts*. Precise paths are used to detect when bundles are uploaded to the cluster. +To use WAF security bundles, your NGINX Ingress Controller instance must have *volumes* and *volumeMounts*. Precise paths are used to detect when bundles are uploaded to the cluster. -Here is an example of what must be added: +Here is an example of what to add: ```yaml volumes: @@ -217,7 +213,7 @@ volumeMounts: mountPath: /etc/nginx/waf/bundles ``` -A full example of a deployment file with `volumes` and `volumeMounts` may look like the following: +A full example of a deployment file with `volumes` and `volumeMounts` could look like the following: ```yaml @@ -303,9 +299,7 @@ spec: ## Create WAF policy -Before a bundle can be processed, a WAF policy must be created. - -This policy is added to `/etc/nginx/waf/bundles`, allowing NGINX Ingress Controller to load it into WAF. +To process a bundle, you must create a new WAF policy. This policy is added to `/etc/nginx/waf/bundles`, allowing NGINX Ingress Controller to load it into WAF. The example below shows the required WAF policy, and the *apBundle* and *apLogConf* fields you must use for the security bundle binary file (A tar ball). @@ -349,10 +343,10 @@ spec: ## Upload the security bundle -The final step is to upload the security bundle binary to the NGINX Ingress Controller pods. +To finish adding a security bundle, the binary file to the NGINX Ingress Controller pods. ```shell kubectl cp /your/local/path/.tgz /:etc/nginx/waf/bundles.tgz ``` -Once the bundle has been uploaded to the cluster, NGINX Ingress Controller will pick up and automatically load the new WAF policy. +Once the bundle has been uploaded to the cluster, NGINX Ingress Controller will detect and automatically load the new WAF policy.