github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/app-protect/configuration.md (about)

     1  # Configuration
     2  This document describes how to configure the NGINX App Protect module
     3  > Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect).
     4  
     5  ## Global Configuration
     6  
     7  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.
     8  
     9  > Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect).
    10  
    11  ## Enable App Protect for an Ingress Resource
    12  
    13  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.
    14  
    15  ## App Protect Policies
    16  
    17  You can define App Protect policies for your Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
    18  
    19   > **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not currently supported.
    20  
    21   > **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 
    22   `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`.
    23  
    24  To add any [App Protect policy](/nginx-app-protect/policy/#policy) to an Ingress resource:
    25  
    26  1. Create an `APPolicy` Custom resource manifest.
    27  2. Add the desired policy to the `spec` field in the `APPolicy` resource.
    28  
    29     > **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.
    30  
    31    For example, say you want to use the [DataGuard policy](/nginx-app-protect/policy/#data-guard) shown below:
    32  
    33    ```json
    34    {
    35        "policy": {
    36            "name": "dataguard_blocking",
    37            "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
    38            "applicationLanguage": "utf-8",
    39            "enforcementMode": "blocking",
    40            "blocking-settings": {
    41                "violations": [
    42                    {
    43                        "name": "VIOL_DATA_GUARD",
    44                        "alarm": true,
    45                        "block": true
    46                    }
    47                ]
    48            },
    49            "data-guard": {
    50                "enabled": true,
    51                "maskData": true,
    52                "creditCardNumbers": true,
    53                "usSocialSecurityNumbers": true,
    54                "enforcementMode": "ignore-urls-in-list",
    55                "enforcementUrls": []
    56            }
    57        }
    58    }
    59    ```
    60  
    61    You would create an `APPolicy` resource with the policy defined in the `spec`, as shown below:
    62  
    63    ```yaml
    64    apiVersion: appprotect.f5.com/v1beta1
    65    kind: APPolicy
    66    metadata:
    67      name: dataguard-blocking
    68    spec:
    69      policy:
    70        name: dataguard_blocking
    71        template:
    72          name: POLICY_TEMPLATE_NGINX_BASE
    73        applicationLanguage: utf-8
    74        enforcementMode: blocking
    75        blocking-settings:
    76          violations:
    77          - name: VIOL_DATA_GUARD
    78            alarm: true
    79            block: true
    80        data-guard:
    81          enabled: true
    82          maskData: true
    83          creditCardNumbers: true
    84          usSocialSecurityNumbers: true
    85          enforcementMode: ignore-urls-in-list
    86          enforcementUrls: []
    87    ```
    88  
    89    > Notice how the fields match exactly in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect policy config.
    90  
    91  ## App Protect Logs
    92  
    93  You can set the [App Protect 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/).
    94  
    95  To add the [App Protect log configurations](/nginx-app-protect/configuration/#security-logs) to an Ingress resource:
    96  
    97  1. Create an `APLogConf` Custom Resource manifest.
    98  2. Add the desired log configuration to the `spec` field in the `APLogConf` resource.
    99  
   100     > **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 log config.
   101  
   102  For example, say you want to [log state changing requests](/nginx-app-protect/troubleshooting/#log-state-changing-requests) for your Ingress resources using App Protect. The App Protect log configuration looks like this:
   103  
   104  ```json
   105  {
   106      "filter": {
   107          "request_type": "all"
   108      },
   109      "content": {
   110          "format": "default",
   111          "max_request_size": "any",
   112          "max_message_size": "5k"
   113      }
   114  }
   115  ```
   116  
   117  You would define that config in the `spec` of your `APLogConf` resource as follows:
   118  
   119  ```yaml
   120  apiVersion: appprotect.f5.com/v1beta1
   121  kind: APLogConf
   122  metadata:
   123    name: logconf
   124  spec:
   125    filter:
   126      request_type: all
   127    content:
   128      format: default
   129      max_request_size: any
   130      max_message_size: 5k
   131  ```
   132  ## App Protect User Defined Signatures
   133  
   134  You can define App Protect [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) for your Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
   135  
   136   > **Note**: The field `revisionDatetime` is not currently supported.
   137  
   138  > **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.
   139  
   140  To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) to an Ingress resource:
   141  
   142  1. Create an `APUserSig` Custom resource manifest.
   143  2. Add the desired User defined signature to the `spec` field in the `APUserSig` resource.
   144  
   145     > **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 User Defined signature. There is no need to reference the user defined signature resource in the ingress resource.
   146  
   147  For example, say you want to create the following user defined signature:
   148  
   149  ```json
   150  {  "softwareVersion": "15.1.0",
   151      "tag": "Fruits",
   152      "signatures": [
   153        {
   154        "name": "Apple_medium_acc",
   155        "rule": "content:\"apple\"; nocase;",
   156        "signatureType": "request",
   157        "attackType": {
   158           "name": "Brute Force Attack"
   159        },
   160        "systems": [
   161           {"name": "Microsoft Windows"},
   162           {"name": "Unix/Linux"}
   163                       ],
   164        "risk": "medium",
   165        "accuracy": "medium",
   166        "description": "Medium accuracy user defined signature with tag (Fruits)"
   167        }
   168     ]
   169  }
   170  ```
   171  
   172  You would add that config in the `spec` of your `APUserSig` resource as follows:
   173  
   174  ```yaml
   175  apiVersion: appprotect.f5.com/v1beta1
   176  kind: APUserSig
   177  metadata:
   178    name: apple
   179  spec:
   180    signatures:
   181    - accuracy: medium
   182      attackType:
   183        name: Brute Force Attack
   184      description: Medium accuracy user defined signature with tag (Fruits)
   185      name: Apple_medium_acc
   186      risk: medium
   187      rule: content:"apple"; nocase;
   188      signatureType: request
   189      systems:
   190      - name: Microsoft Windows
   191      - name: Unix/Linux
   192    softwareVersion: 15.1.0
   193    tag: Fruits
   194  ```