NGINX Ingress Controller Configuration guide update

docs/content/app-protect/configuration.md

@@ -1,25 +1,31 @@
 ---
 title: Configuration
 
-description: "This document describes how to configure the NGINX App Protect module"
+description: "This document describes how to configure the NGINX App Protect module."
 weight: 1900
 doctypes: [""]
 toc: true
 docs: "DOCS-578"
 ---
 
-This document describes how to configure the NGINX App Protect module
-> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/appprotect).
+> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/appprotect). 
+Refer to [Custom Resource](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/waf) for Custom Resource sample.
 
 ## Global Configuration
 
 The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect 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.
 
 > Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/appprotect).
 
-## Enable App Protect for an Ingress Resource
+## Enabling App Protect
+
+You can enable and configure NGINX App Protect on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis. Refer to [Custom Resource](https://docs.nginx.com/nginx-ingress-controller/configuration/policy-resource/#waf) examples for more details.
+
+Refer to [Custom Resource](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/waf) for Custom Resource sample.
+
+To configure NGINX App Protect 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.
+
 
-You can enable and configure NGINX App Protect on a per-Ingress-resource basis. To do so, you can apply the [App Protect annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) to each desired resource.
 
 ## App Protect Policies
 
@@ -203,3 +209,173 @@ spec:
   softwareVersion: 15.1.0
   tag: Fruits
 ```
+
+## 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. 
+
+NGINX Ingress Controller supports OpenAPI Specification versions 2.0 and 3.0.
+
+The simplest way to create an API protection policy is using an OpenAPI Specification file to import the details of the APIs. If you use an OpenAPI Specification file, NGINX App Protect WAF will automatically create a policy for the following properties (depending on what's included in the spec file):
+* Methods
+* URLs
+* Parameters
+* JSON profiles 
+
+An OpenAPI-ready policy template is provided with the NGINX App Protect WAF packages and is located in: `/etc/app_protect/conf/NginxApiSecurityPolicy.json`
+
+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](#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](#https-reference) for details.
+
+## Configuration in NGINX Ingress Controller
+
+These are the typical steps to deploy an OpenAPI protection Policy in NGINX Ingress Controller:
+
+1. Copy the API security policy `/etc/app_protect/conf/NginxApiSecurityPolicy.json` to a different file so that it can be edited.
+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.
+6. Create a `Policy` object which references the `APPolicy` Customer Resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/custom-resources/waf/waf.yaml).
+7. Finally, attach the `Policy` object to a `VirtualServer` resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/custom-resources/waf/virtual-server.yaml).
+
+**Note**:  You need to make sure that the server where the resource files are located is always available when you are compiling your policy.
+
+##### Example Configuration
+
+In this example, we are adding an OpenAPI Specification file reference to `/etc/app_protect/conf/NginxApiSecurityPolicy.yaml` using the link ` :https://raw.githubusercontent.com/aws-samples/api-gateway-secure-pet-store/master/src/main/resources/swagger.yaml`. This will configure allowed data types for `query_int` and `query_str` parameters values.
+
+**Policy configuration:**
+
+~~~yaml
+---
+apiVersion: appprotect.f5.com/v1beta1
+  kind: APPolicy
+  metadata:
+    name: petstore_api_security_policy
+  spec:
+    policy:
+      name: petstore_api_security_policy
+      description: NGINX App Protect WAF API Security Policy for the Petstore API
+      template:
+        name: POLICY_TEMPLATE_NGINX_BASE
+      open-api-files:
+      - link: https://raw.githubusercontent.com/aws-samples/api-gateway-secure-pet-store/master/src/main/resources/swagger.yaml
+      blocking-settings:
+        violations:
+        - block: true
+          description: Disallowed file upload content detected in body
+          name: VIOL_FILE_UPLOAD_IN_BODY
+        - block: true
+          description: Mandatory request body is missing
+          name: VIOL_MANDATORY_REQUEST_BODY
+        - block: true
+          description: Illegal parameter location
+          name: VIOL_PARAMETER_LOCATION
+        - block: true
+          description: Mandatory parameter is missing
+          name: VIOL_MANDATORY_PARAMETER
+        - block: true
+          description: JSON data does not comply with JSON schema
+          name: VIOL_JSON_SCHEMA
+        - block: true
+          description: Illegal parameter array value
+          name: VIOL_PARAMETER_ARRAY_VALUE
+        - block: true
+          description: Illegal Base64 value
+          name: VIOL_PARAMETER_VALUE_BASE64
+        - block: true
+          description: Disallowed file upload content detected
+          name: VIOL_FILE_UPLOAD
+        - block: true
+          description: Illegal request content type
+          name: VIOL_URL_CONTENT_TYPE
+        - block: true
+          description: Illegal static parameter value
+          name: VIOL_PARAMETER_STATIC_VALUE
+        - block: true
+          description: Illegal parameter value length
+          name: VIOL_PARAMETER_VALUE_LENGTH
+        - block: true
+          description: Illegal parameter data type
+          name: VIOL_PARAMETER_DATA_TYPE
+        - block: true
+          description: Illegal parameter numeric value
+          name: VIOL_PARAMETER_NUMERIC_VALUE
+        - block: true
+          description: Parameter value does not comply with regular expression
+          name: VIOL_PARAMETER_VALUE_REGEXP
+        - block: true
+          description: Illegal URL
+          name: VIOL_URL
+        - block: true
+          description: Illegal parameter
+          name: VIOL_PARAMETER
+        - block: true
+          description: Illegal empty parameter value
+          name: VIOL_PARAMETER_EMPTY_VALUE
+        - block: true
+          description: Illegal repeated parameter name
+          name: VIOL_PARAMETER_REPEATED
+
+~~~
+
+Content of the referenced file `myapi.yaml`:
+
+~~~yaml
+openapi: 3.0.1
+info:
+  title: 'Primitive data types'
+  description: 'Primitive data types.'
+  version: '2.5.0'
+servers:
+  - url: http://localhost
+paths:
+  /query:
+    get:
+      tags:
+        - query_int_str
+      description: query_int_str
+      operationId: query_int_str
+      parameters:
+        - name: query_int
+          in: query
+          required: false
+          allowEmptyValue: false
+          schema:
+            type: integer
+        - name: query_str
+          in: query
+          required: false
+          allowEmptyValue: true
+          schema:
+            type: string           
+      responses:
+        200:
+          description: OK
+        404:
+          description: NotFound
+~~~
+
+In this case, the following request will trigger an `Illegal parameter data type` violation, as we expect to have an integer value in the `query_int` parameter:
+
+```
+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 policy example above.
+
+**Note**: `openApiFileReference` is not an array.