Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix links and product name usage in NAP WAF config guide #3972

Merged
merged 4 commits into from
Jun 20, 2023
Merged

fix links and product name usage in NAP WAF config guide #3972

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bdf40fd
fix links and product name usage in NAP WAF config guide
jputrino Jun 7, 2023
23e90f8
Merge branch 'main' into jp-docops-1683
ADubhlaoich Jun 14, 2023
5feb8e1
Merge branch 'main' into jp-docops-1683
ADubhlaoich Jun 20, 2023
573a523
Merge branch 'main' into jp-docops-1683
shaun-nx Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 36 additions & 37 deletions docs/content/app-protect-waf/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,48 +1,47 @@
---
title: Configuration

description: "This document describes how to configure the NGINX App Protect WAF module."
description: "Learn how to use NGINX Ingress Controller to configure NGINX App Protect WAF."
weight: 1900
doctypes: [""]
toc: true
docs: "DOCS-578"
aliases: ["/app-protect/configuration/"]
---

> Check out the complete NGINX Ingress Controller with App Protect WAF example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.1.1/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.1.1/examples/ingress-resources/app-protect-waf).
> Check out the complete NGINX Ingress Controller with NGINX App Protect WAF example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.1.1/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.1.1/examples/ingress-resources/app-protect-waf).

## Global Configuration

The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect WAF module. See [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#modules) for the complete list. The App Protect parameters use the `app-protect*` prefix.
NGINX Ingress Controller has a set of global configuration parameters that align with those available in NGINX App Protect WAF. See [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#modules) for the complete list. The NGINX App Protect WAF parameters use the `app-protect*` prefix.

## Enabling App Protect
## Enable NGINX App Protect WAF

You can enable and configure NGINX App Protect WAF on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis.

To configure NGINX App Protect WAF on a VirtualServer resource, you would create a Policy Custom Resource referencing the APPolicy Custom Resource, and add this to the VirtualServer definition. See the documentation on the [App Protect WAF Policy](/nginx-ingress-controller/configuration/policy-resource/#waf).
To configure NGINX App Protect WAF on a VirtualServer resource, you would create a Policy Custom Resource referencing the APPolicy Custom Resource, and add this to the VirtualServer definition. See the documentation on the [NGINX App Protect WAF Policy](/nginx-ingress-controller/configuration/policy-resource/#waf).

To configure NGINX App Protect WAF on an Ingress resource, you would apply the [App Protect annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) to each desired resource.
To configure NGINX App Protect WAF on an Ingress resource, you would apply the [`app-protect` annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) to each desired resource.


## App Protect WAF Policies
## NGINX App Protect WAF Policies

You can define App Protect WAF policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
You can define NGINX App Protect WAF policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

> **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not currently supported.
> **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not supported.

> **Note**: [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect/configuration/#advanced-grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and
> **Note**: [The Advanced gRPC Protection for Unary Traffic](/nginx-app-protect-waf/configuration-guide/configuration/#grpc-protection-for-unary-traffic) only supports providing an `idl-file` inline. The fields `policy.idl-files[].link`, `policy.idl-files[].$ref`, and
`policy.idl-files[].file` are not supported. The IDL file should be provided in field `policy.idl-files[].contents`. The value of this field can be base64 encoded. In this case the field `policy.idl-files[].isBase64` should be set to `true`.

> **Note**: [External References](/nginx-app-protect/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases.
> **Note**: [External References](/nginx-app-protect-waf/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases.

To add any [App Protect WAF policy](/nginx-app-protect/declarative-policy/policy/) to an Ingress resource:
To add any [NGINX App Protect WAF policy](/nginx-app-protect-waf/declarative-policy/policy/) to an Ingress resource:

1. Create an `APPolicy` Custom resource manifest.
2. Add the desired policy to the `spec` field in the `APPolicy` resource.

> **Note**: The relationship between the Policy JSON and the resource spec is 1:1. If you're defining your resources in YAML, as we do in our examples, you'll need to represent the policy as YAML. The fields must match those in the source JSON exactly in name and level.

For example, say you want to use the [DataGuard policy](/nginx-app-protect/declarative-policy/policy/#policy/data-guard) shown below:
For example, say you want to use the [DataGuard policy](/nginx-app-protect-waf/declarative-policy/policy/#policy/data-guard) shown below:

```json
{
Expand Down Expand Up @@ -100,22 +99,22 @@ To add any [App Protect WAF policy](/nginx-app-protect/declarative-policy/policy
enforcementUrls: []
```

> Notice how the fields match exactly in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF policy config.
> Notice how the fields match exactly in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF policy config.
<br>

## App Protect WAF Logs
## NGINX App Protect WAF Logs

You can set the [App Protect WAF log configurations](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
You can set the [NGINX App Protect WAF log configurations](/nginx-app-protect-waf/logging-overview/logs-overview/) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

To add the [App Protect WAF log configurations](/nginx-app-protect/configuration/#security-logs) to a VirtualServer or an Ingress resource:
To add the [log configurations](/nginx-app-protect-waf/logging-overview/security-log/) to a VirtualServer or an Ingress resource:

1. Create an `APLogConf` Custom Resource manifest.
2. Add the desired log configuration to the `spec` field in the `APLogConf` resource.
3. Add the `APLogConf` reference to the [VirtualServer Policy resource](/nginx-ingress-controller/configuration/policy-resource/#waf) or the [Ingress resource](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) as per the documentation.

> **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF log config.
> **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. NGINX Ingress Controller will transform the YAML into a valid JSON WAF log config.

For example, say you want to [log state changing requests](/nginx-app-protect/configuration/#security-log-configuration-file) for your VirtualServer or Ingress resources using App Protect WAF. The App Protect WAF log configuration looks like this:
For example, say you want to [log state changing requests](/nginx-app-protect-waf/logging-overview/security-log/#security-log-configuration-file) for your VirtualServer or Ingress resources using NGINX App Protect WAF. The log configuration looks like this:

```json
{
Expand Down Expand Up @@ -145,20 +144,20 @@ spec:
max_request_size: any
max_message_size: 5k
```
## App Protect WAF User Defined Signatures
## NGINX App Protect WAF User Defined Signatures

You can define App Protect WAF [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) for your VirtualServer or Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
You can define NGINX App Protect WAF [User-Defined Signatures](/nginx-app-protect-waf/configuration-guide/configuration/#user-defined-signatures) for your VirtualServer or Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

> **Note**: The field `revisionDatetime` is not currently supported.

> **Note**: `APUserSig` resources increase the reload time of NGINX Plus compared with `APPolicy` and `APLogConf` resources. Refer to [NGINX Fails to Start or Reload](/nginx-ingress-controller/app-protect/troubleshooting/#nginx-fails-to-start-or-reload) for more information.

To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) to a VirtualServer or Ingress resource:
To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect-waf/configuration-guide/configuration/#user-defined-signatures) to a VirtualServer or Ingress resource:

1. Create an `APUserSig` Custom resource manifest.
2. Add the desired User defined signature to the `spec` field in the `APUserSig` resource.

> **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF User Defined signature. There is no need to reference the user defined signature resource in the Policy or Ingress resources.
> **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON User-Defined signature. There is no need to reference the user defined signature resource in the Policy or Ingress resources.

For example, say you want to create the following user defined signature:

Expand Down Expand Up @@ -211,7 +210,7 @@ spec:

## OpenAPI Specification in NGINX Ingress Controller

The OpenAPI Specification defines the spec file format needed to describe RESTful APIs. The spec file can be written either in JSON or YAML. Using a spec file simplifies the work of implementing API protection. Refer to the [OpenAPI Specification](#https://github.com/OAI/OpenAPI-Specification) (formerly called Swagger) for details.
The OpenAPI Specification defines the spec file format needed to describe RESTful APIs. The spec file can be written either in JSON or YAML. Using a spec file simplifies the work of implementing API protection. Refer to the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) (formerly called Swagger) for details.

NGINX Ingress Controller supports OpenAPI Specification versions 2.0 and 3.0.

Expand All @@ -227,15 +226,15 @@ It contains violations related to OpenAPI set to blocking (enforced).

### Types of OpenAPI References

There are different ways of referencing OpenAPI Specification files. The configuration is similar to [External References](/nginx-app-protect/configuration-guide/configuration/#external-references).
There are different ways of referencing OpenAPI Specification files. The configuration is similar to [External References](/nginx-app-protect-waf/configuration-guide/configuration/#external-references).

**Note**: Any update of an OpenAPI Specification file referenced in the policy will not trigger a policy compilation. This action needs to be done actively by reloading the NGINX configuration.

#### URL Reference

URL reference is the method of referencing an external source by providing its full URL.

Make sure to configure certificates prior to using the HTTPS protocol - see the [External References](/nginx-app-protect/configuration-guide/configuration/#types-of-references) for details.
Make sure to configure certificates prior to using the HTTPS protocol - see the [External References](/nginx-app-protect-waf/configuration-guide/configuration/#types-of-references) for details.

## Configuration in NGINX Ingress Controller

Expand All @@ -245,7 +244,7 @@ These are the typical steps to deploy an OpenAPI protection Policy in NGINX Ingr
2. Add the reference to the desired OpenAPI file.
3. Make other custom changes if needed (e.g. enable Data Guard protection).
4. Use a tool to convert the result to YAML. There are many, for example: [`yq` utility](https://github.com/mikefarah/yq).
5. Add the YAML properties to create an `APPolicy` Custom Resource putting the policy itself (as in step 4) within the `spec` property of the Custom Resource. Refer to [App Protect Policies](#app-protect-policies) section above.
5. Add the YAML properties to create an `APPolicy` Custom Resource putting the policy itself (as in step 4) within the `spec` property of the Custom Resource. Refer to the [NGINX App Protect Policies](#nginx-app-protect-waf-policies) section above.
6. Create a `Policy` object which references the `APPolicy` Custom Resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v3.1.1/examples/custom-resources/app-protect-waf/waf.yaml).
7. Finally, attach the `Policy` object to a `VirtualServer` resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v3.1.1/examples/custom-resources/app-protect-waf/virtual-server.yaml).

Expand Down Expand Up @@ -375,25 +374,25 @@ http://localhost/query?query_int=abc

The request will be blocked.

The `link` option is also available in the `openApiFileReference` property and is synonymous with the `open-api-files` property as seen in the App Protect WAF policy example above.
The `link` option is also available in the `openApiFileReference` property and is synonymous with the `open-api-files` property as seen in the policy example above.

**Note**: `openApiFileReference` is not an array.


## Configuration in NGINX Plus Ingress Controller using Virtual Server Resource
In this example we deploy the NGINX Plus Ingress Controller with NGINX App Protect WAF, a simple web application and then configure load balancing and WAF protection for that application using the VirtualServer resource.
In this example we deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF, deploy a simple web application, and then configure load balancing and WAF protection for that application using the VirtualServer resource.

**Note:** You can find the example, and the files referenced, on [GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v3.1.1/examples/custom-resources/app-protect-waf).

## Prerequisites

1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress Controller with NGINX App Protect WAF.
2. Save the public IP address of the Ingress Controller into a shell variable:
1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy NGINX Ingress Controller with NGINX Plus and NGINX App Protect WAF.
2. Save the public IP address of NGINX Ingress Controller into a shell variable:
```
$ IC_IP=XXX.YYY.ZZZ.III
```

3. Save the HTTP port of the Ingress Controller into a shell variable:
3. Save the HTTP port of NGINX Ingress Controller into a shell variable:
```
$ IC_HTTP_PORT=<port number>
```
Expand All @@ -407,12 +406,12 @@ Create the application deployment and service:

### Step 2. Deploy the AP Policy

1. Create the syslog service and pod for the App Protect security logs:
1. Create the syslog service and pod for the NGINX App Protect WAF security logs:
```
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/custom-resources/app-protect-waf/syslog.yaml
```

2. Create the User Defined Signature, App Protect WAF policy, and log configuration:
2. Create the User-Defined Signature, WAF policy, and log configuration:

```
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/custom-resources/app-protect-waf/ap-apple-uds.yaml
Expand All @@ -426,7 +425,7 @@ Create the WAF policy
```
$ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/custom-resources/app-protect-waf/waf.yaml
```
Note the App Protect configuration settings in the Policy resource. They enable WAF protection by configuring App Protect with the policy and log configuration created in the previous step.
Note the NGINX App Protect WAF configuration settings in the Policy resource. They enable WAF protection by configuring NGINX App Protect WAF with the policy and log configuration created in the previous step.

### Step 4 - Configure Load Balancing

Expand Down Expand Up @@ -458,7 +457,7 @@ To access the application, curl the coffee and the tea services. We'll use the -
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP -X POST -d "apple" http://webapp.example.com:$IC_HTTP_PORT/
<html><head><title>Request Rejected</title></head><body>
```
As you can see, the suspicious requests were blocked by App Protect
As you can see, the suspicious requests were blocked by NGINX App Protect WAF.

4. To check the security logs in the syslog pod:
```
Expand Down