Manage App Security

How to add NGINX Controller App Security to your applications.

Overview

You can use the App Security add-on for NGINX Controller ADC to enable Web Application Firewall (WAF) capabilities to protect your applications. WAF lets you flag or block suspicious requests or attacks. WAF can be added to individual app components.

Important:
App Security is an add-on for the NGINX Controller Application Delivery Module. It is not included with the NGINX Controller API Management Module and cannot be added to API Components.

Before You Begin

Before proceeding with this guide, complete the following tasks.

Note:
These steps may need to be completed by a user with admin permissions.

  1. Add an NGINX App Protect instance to NGINX Controller.

In addition, the following resources must exist in order to complete the steps in this topic:

Enable WAF for a Component using the Default Policy

To enable WAF functionality for Application Security using the default policy, send a POST or PUT request to the Components endpoint, with a JSON object similar to the following:

        "security": {
            "waf": {
                "isEnabled": true
            }
        }

This JSON object should be added to the Component endpoint similar to the following example:

{
    "metadata": {
        "name": "secure",
        "displayName": "protected web server",
        "description": "ProtectedWeb Server",
        "tags": [
            "dev",
            "protected"
        ]
    },
    "desiredState": {
        "ingress": {
            "gatewayRefs": [
                {
                    "ref": "/services/environments/dev/gateways/dev-gw"
                }
            ],
            "uris": {
                "/secure": {
                    "matchMethod": "PREFIX"
                }
            }
        },
        "security": {
            "waf": {
                "isEnabled": true
            }
        },
        "backend": {
            "ntlmAuthentication": "DISABLED",
            "preserveHostHeader": "DISABLED",
            "workloadGroups": {
                "farm": {
                    "locationRefs": [
                        {
                            "ref": "/infrastructure/locations/unspecified"
                        }
                    ],
                    "loadBalancingMethod": {
                        "type": "ROUND_ROBIN"
                    },
                    "uris": {
                        "http://{{workload-1}}:8080": {
                            "isBackup": false,
                            "isDown": false,
                            "isDrain": false,
                            "resolve": "DISABLED"
                        },
                        "http://{{workload-2}}:8080": {
                            "isBackup": false,
                            "isDown": false,
                            "isDrain": false,
                            "resolve": "DISABLED"
                        },
                        "http://{{workload-3}}:8080": {
                            "isBackup": false,
                            "isDown": false,
                            "isDrain": false,
                            "resolve": "DISABLED"
                        },
                        "http://{{workload-4}}:8080": {
                            "isBackup": false,
                            "isDown": false,
                            "isDrain": false,
                            "resolve": "DISABLED"
                        }
                    }
                }
            }
        },
        "logging": {
            "errorLog": "ENABLED",
            "accessLog": {
                "state": "DISABLED",
                "format": ""
            }
        }
    }
}

Enable WAF for a Component Using Your Own NAP Policy (Beta)

Important:
This is a beta feature introduced in NGINX Controller App Security v3.17. We don’t recommend using beta features in Production environments.

Instead of using NGINX Controller’s default policy for WAF, you can bring your own NGINX App Protect declarative JSON policy (also called a “BYO NAP policy”) to NGINX Controller and use that policy to protect your app components. To do this, you first need to upload your NGINX App Protect declarative JSON policy to the Security Policy endpoint. Then, you can use the Component endpoint to reference the Security Strategy for the NGINX App Protect declarative JSON policy.

To learn more about using your own NAP policy and implementing a Security Strategy, see the topic Bring Your Own NGINX App Protect Policy for details.

Upload your NAP Policy to NGINX Controller

To upload your NGINX App Protect declarative JSON Policy to NGINX Controller, use an HTTP client like cURL and send a POST or PUT to the Security Policy endpoint – https://{{CONTROLLER_FQDN}}/api/v1/security/policies/{resource ID} – with a JSON object similar to the following example :

{
  "metadata": {
    "name": "yourPolicyName",
    "displayName": "App Protect Policy",
    "description": "my special NAP policy",
    "tags": ["test1", "test2"]
  },
  "desiredState": {
    "content": {"policy": {"name": "/Common/yourPolicyName", "template": {"name": "POLICY_TEMPLATE_NGINX_BASE"}, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signatures": [{"signatureId": 123458888, "enabled": false}, {"signatureId": 200000098, "enabled": false}, {"signatureId": 200001475, "enabled": false}, {"signatureId": 200002595, "enabled": false}], "bot-defense": {"settings": {"isEnabled": false}}, "headers": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}, {"name": "*-bin", "type": "wildcard", "decodeValueAsBase64": "required"}, {"name": "Referer", "type": "explicit", "decodeValueAsBase64": "disabled"}, {"name": "Authorization", "type": "explicit", "decodeValueAsBase64": "disabled"}, {"name": "Transfer-Encoding", "type": "explicit", "decodeValueAsBase64": "disabled"}], "cookies": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}], "parameters": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}]}}
  }
}

Reference Your BYO NAP policy from an App Component

When you upload an NGINX App Protect policy to NGINX Controller, a corresponding Security Strategy that embeds the security policy is created with the same name. You can then reference the Security Strategy from an app component by sending a POST or PUT request to the Components endpoint – https://{{CONTROLLER_FQDN}}/api/v1/services/environments/{environmentName}/apps/{appName}/components/{componentName} – with a JSON object similar to the following:


     "security": {
      "strategyRef": {
        "ref": "/security/strategies/yourPolicyName"
      },
      "waf": {
        "isEnabled": true,
      }
    }

Note:

The following WAF security parameters are not supported by app components referencing BYO NAP policies:

  • isMonitorOnly
  • signatureOverrides

These preceding parameters are supported by NGINX Controller’s default policy for WAF.

 

Verify that WAF is Enabled

Complete the tasks in this section to verify that the Web Application Firewall is active and processing traffic.

To verify that WAF has been enabled by NGINX Controller App Security to protect your app component, send a GET request to the app component.

Example using NGINX Controller’s default policy: GET: https://[gateway FQDN]<app component path>/?a=<script>.

Note:
The WAF does not begin to emit security events immediately upon activation. We recommend that you wait a minute or two after enabling WAF for your Component to query the REST API for security events.

The request should be blocked. You should be able to view the Security Violation event for the request using the Analytics Events API or Security Events in the web interface. Detailed steps are mentioned below.

Note:
The [gateway FQDN] is the URI specified in the ingress block of the Gateway referenced by the app component. The <app component path> is the URI specified in the ingress block of the app component.

Take the steps below to review the WAF Security Events that correspond to the simulated malicious request.

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Services.
  3. On the Services menu, select Apps.
  4. On the Analytics sub-menu, select Security Events.
  5. If you see a list of security violations and the outcome, this confirms that App Protect and WAF are running.

To view all events:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Analytics.
  3. On the Analytics menu, select Events.
  4. Select All Events to view security violations and the status. Flagged and rejected status means that App Protect and WAF are running.
Note:
The WAF does not begin to emit security events immediately upon activation. We recommend that you wait a minute or two after enabling WAF for your Component to query the REST API for security events.
Note:
If NGINX Controller isn’t logging any Security Violation Events for your app component, check Security Events Not Available for troubleshooting instructions.

Disable WAF for Component

To disable WAF for App Security, send a POST or PUT request to the Components endpoint, with a JSON object similar to the following:

        "security": {
            "waf": {
                "isEnabled": false
            }
        }

You can also delete the WAF block from the Components endpoint to disable WAF.


This documentation applies to the following versions of NGINX Controller Documentation: 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.