NGINX App Protect WAF Configuration Guide

Overview

This guide explains the F5 NGINX App Protect WAF security features and how to use them. This guide also assumes that you have some familiarity with various Layer 7 (L7) Hypertext Transfer Protocol (HTTP) concepts, such as Uniform Resource Identifier (URI)/Uniform Resource Locator (URL), method, header, cookie, status code, request, response, and parameters.

For more information on the NGINX App Protect WAF security features, see NGINX App Protect WAF Terminology.

Supported Security Policy Features

Disallowed File Types

The following file types are disallowed by default:

• bak, bat, bck, bkp, cfg, conf, config, ini, log, old, sav, save, temp, tmp
• bin, cgi, cmd, com, dll, exe, msi, sys, shtm, shtml, stm
• cer, crt, der, key, p12, p7b, p7c, pem, pfx
• dat, eml, hta, htr, htw, ida, idc, idq, nws, pol, printer, reg, wmz

Additional Policy Features

Attack Signatures Overview

Attack signatures are rules or patterns that identify attack sequences or classes of attacks on a web application and its components. You can apply attack signatures to both requests and responses. App Protect includes predefined attack signatures to protect your application against all attack types identified by the system.

Signature Settings

Signature Sets in Default Policy

The following signature sets are included in the default policy. Most of the sets are defined by the Attack Type they protect from. In all sets the Alarm flag is enabled and Block disabled except High Accuracy Signatures, which are set to blocked (block parameter is enabled).

• Command Execution Signatures
• Cross Site Scripting Signatures
• Directory Indexing Signatures
• Information Leakage Signatures
• OS Command Injection Signatures
• Path Traversal Signatures
• Predictable Resource Location Signatures
• Remote File Include Signatures
• SQL Injection Signatures
• Authentication/Authorization Attack Signatures
• XML External Entities (XXE) Signatures
• XPath Injection Signatures
• Buffer Overflow Signatures
• Denial of Service Signatures
• Vulnerability Scan Signatures
• High Accuracy Signatures
• Server Side Code Injection Signatures
• CVE Signatures

Basic Signature Sets Included in App Protect

These signatures sets are included but are not part of the default template.

• All Response Signatures
• All Signatures
• Generic Detection Signatures
• Generic Detection Signatures (High Accuracy)
• Generic Detection Signatures (High/Medium Accuracy)
• High Accuracy Signatures
• Low Accuracy Signatures
• Medium Accuracy Signatures
• OWA Signatures
• WebSphere signatures
• HTTP Response Splitting Signatures
• Other Application Attacks Signatures
• High Accuracy Detection Evasion Signatures

See signature sets for configuring the signature sets included in your policy.

Policy Configuration

The NGINX App Protect WAF ships with two reference policies, both with a default enforcement mode set to Blocking:

• The default policy which is identical to the base template and provides OWASP Top 10 and Bot security protection out of the box.
• The strict policy contains more restrictive criteria for blocking traffic than the default policy. It is meant to be used for protecting sensitive applications that require more security but with higher risk of false positives. You can use those policies as is, but usually you will use them as starting points and further customize them to the needs of the applications they protect.

Policy Configuration Overview

The NGINX App Protect WAF security policy configuration uses the declarative format based on a pre-defined base template. The policy is represented in a JSON file which you can edit to add, modify and remove security capabilities with respect to the base template. The JSON file then should be compiled to a bundle file (.tgz) using the NGINX App Protect WAF Compiler. The way the policy is integrated into the NGINX configuration is via referencing the bundle file (using the full path) in the nginx.conf file.

Refer to the admin guide for instructions on how to mount bundle files to your deployment.

NGINX App Protect WAF provides a JSON Schema which can be used to validate a JSON policy file to ensure file format compliance. The schema file can be generated using a script inside the NGINX App Protect WAF Compiler image:

sudo docker run --rm \
 -v $(pwd):$(pwd) \
 -w $(pwd) \
 --entrypoint=/opt/app_protect/bin/generate_json_schema.pl \
 private-registry.nginx.com/nap/waf-compiler:1.0.0

Replace the 1.0.0 with the version you use.

This script will output the schema to a file named policy.json into the current working directory. Once the schema file is generated, you can use validation tools such as AJV to validate a JSON policy file.

In the following example, the NGINX configuration file with App Protect enabled in the HTTP context and the policy /policies/policy1.tgz is used:

user nginx;
worker_processes  4;

load_module modules/ngx_http_app_protect_module.so;

error_log /var/log/nginx/error.log debug;

events {
    worker_connections  65536;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    app_protect_enable on; # This is how you enable NGINX App Protect WAF in the relevant context/block
    app_protect_policy_file "/etc/app_protect/conf/policy1.tgz"; # This is a reference to the policy bundle file to use. If not defined, the default policy is used
    app_protect_security_log_enable on; # This section enables the logging capability
    app_protect_security_log "/etc/app_protect/conf/log_all.tgz" syslog:server=127.0.0.1:514; # This is where the remote logger is defined in terms of: logging options (defined in the referenced file), log server IP, log server port

    server {
        listen       80;
        server_name  localhost;
        proxy_http_version 1.1;

        location / {
            client_max_body_size 0;
            default_type text/html;
            proxy_pass http://172.29.38.211/;
        }
    }
}

Basic Configuration and the Default Policy

The base template is the common starting point to any policy you write. The default policy just reflects that template without any further modifications, thus we use the terms base template and default policy interchangeably. The default policy appears as follows

{
    "policy" : {
        "name": "app_protect_default_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }
    }
}

The default policy enforces violations by Violation Rating, the App Protect computed assessment of the risk of the request based on the triggered violations.

• 0: No violation
• 1-2: False positive
• 3: Needs examination
• 4-5: Threat

The default policy enables most of the violations and signature sets with Alarm turned ON, but not Block. These violations and signatures, when detected in a request, affect the violation rating. By default, if the violation rating is calculated to be malicious (4-5) the request will be blocked by the VIOL_RATING_THREAT violation. This is true even if the other violations and signatures detected in that request had the Block flag turned OFF. It is the VIOL_RATING_THREAT violation having the Block flag turned ON that caused the blocking, but indirectly the combination of all the other violations and signatures in Alarm caused the request to be blocked. By default, other requests which have a lower violation rating are not blocked, except for some specific violations described below. This is to minimize false positives. However, you can change the default behavior. For example, if you want to add blocking on a violation rating of 3 as well, enable blocking for the VIOL_RATING_NEED_EXAMINATION violation.

The following violations and signature sets have a low chance of being false positives and are, therefore, configured by default to block the request regardless of its Violation Rating:

• High accuracy attack signatures
• Threat campaigns
• Malformed request: unparsable header, malformed cookie and malformed body (JSON or XML).

The Strict Policy

The Strict Policy is recommended as a starting point for applications requiring a higher level of security. Just like all other policies it is based on the base template, so it detects and blocks everything the default policy does. To obtain the Strict Policy, execute the following command:

sudo docker run --rm -v $(pwd):$(pwd) --entrypoint='' private-registry.nginx.com/nap/waf-compiler:1.0.0 cat /etc/app_protect/conf/NginxStrictPolicy.json

Replace the 1.0.0 with the actual release version.

In addition the Strict Policy also blocks the following:

• Requests that have a Violation Rating of 3, “Needs examination”. This occurs because the VIOL_RATING_NEED_EXAMINATION violation’s block flag is enabled in the strict policy.
• Requests with the VIOL_EVASION violation (evasion techniques).
• Requests with violations that restrict options in the request and response: HTTP method, response status code and disallowed file types.

Note:
Other violations, specifically attack signatures and metacharacters, which are more prone to false positives, still have only Alarm turned on, without blocking, contributing to the Violation Rating as in the Default policy.

In addition, the Strict policy also enables the following features in alarm only mode:

• Data Guard: masking Credit Card Number (CCN), US Social Security Number (SSN) and custom patterns found in HTTP responses.

• HTTP response data leakage signatures: preventing exfiltration of sensitive information from the servers.

• More restrictive limitations: mainly sizing and parsing of JSON and XML payloads.

• Cookie attribute insertion: the Strict policy adds the Secure and SameSite=lax attributes to every cookie set by the application server. These attributes are enforced by the browsers and protect against session hijacking and CSRF attacks respectively.

Default Policy Bundles

NGINX App Protect WAF offers prebuilt bundles for security policies:

• app_protect_default_policy
• app_protect_strict_policy

Important:
You cannot mix these prebuilt bundles with custom policy bundles within the same nginx.conf file.

Example:

    ...
    location / {

        # NGINX App Protect WAF
        app_protect_enable on;
        app_protect_policy_file app_protect_strict_policy;
        app_protect_security_log_enable on;
        app_protect_security_log log_all stderr;

        proxy_pass http://127.0.0.1:8080/;
    }

Updating Default Policy Bundles

Note:
This section assumes that you have built a compiler image named waf-compiler-1.0.0:custom.

To generate versions of the default policies that include the latest security updates, use the -factory-policy option instead of a source policy file.

For instance, to create an updated version of the app_protect_default_policy, use the following command:

docker run \
 -v $(pwd):$(pwd) \
 waf-compiler-1.0.0:custom \
 -factory-policy default -o $(pwd)/new_default_policy.tgz

To create an updated version of the app_protect_strict_policy, use:

docker run \
 -v $(pwd):$(pwd) \
 waf-compiler-1.0.0:custom \
 -factory-policy strict -o $(pwd)/new_strict_policy.tgz

After creating the updated version of a policy, reference it in the nginx.conf file:

app_protect_policy_file /policies_mount/new_default_policy.tgz;

Policy Authoring and Tuning

The policy JSON file specifies the settings that are different from the base template, such as enabling more signatures, disabling some violations, adding server technologies, etc. These will be shown in the next sections.

There are two ways to tune those settings:

• Within the policy structure property, the organic structure of the policy.
• Within the modifications structure property that contains a list of changes expressed in a generic manner.

Both options are equivalent in their semantic expression power, but different syntactically and are designated for different use cases. But before that, let’s look at an example - disabling a specific attack signature.

Signature 200001834 disabled in the policy property:

{
    "policy": {
        "name": "signature_exclude_1",
        "signatures": [
            {
                "signatureId": 200001834,
                "enabled": false
            }
        ]
    }
}

As you can see, this is expressed using the signatures property that contains configuration of individual signatures in a policy. If you want to modify other parts of the policy, you would use different JSON properties.

The same configuration in the modifications array looks like this:

{
    "policy": {
        "name": "signature_exclude_2"
    },
    "modifications": [
        {
            "entityChanges": {
                "enabled": false
            },
            "entity": {
                "signatureId": 200001834
            },
            "entityType": "signature",
            "action": "add-or-update"
        }
    ]
}

Note the generic schema that can express manipulation in any policy element: entity, entityType, action etc. The modifications array is a flat list of individual changes applied to the policy after evaluating the policy block.

So when to use policy and when to use modifications? There are some recommended practice guidelines for that:

• Use policy to express the security policy as you intended it to be: the features you want to enable, disable, the signature sets, server technologies and other related configuration attributes. This part of the policy is usually determined when the application is deployed and changes at a relatively slow pace.
• Use modifications to express exceptions to the intended policy. These exceptions are usually the result of fixing false positive incidents and failures in tests applied to those policies. Usually these are granular modifications, typically disabling checks of individual signatures, metacharacters and sub-violations. These changes are more frequent.
• Use modifications also for removing individual collection elements from the base template, for example disallowed file types.

It is a good practice to separate the modifications to a different file and have the main policy file reference the former, as the two parts have different lifecycles.

The sections just below review the common policy feature configurations using examples. For the full reference of the policy JSON properties see the Declarative Policy guide.

Policy Enforcement Modes

A policy’s enforcement mode can be:

• Blocking: Any illegal or suspicious requests are logged and blocked. This is the default enforcement mode for the default policy and any added policy unless changed to Transparent.
• Transparent: Any illegal or suspicious requests are logged but not blocked.

Specific security features can be defined as blocked or transparent in the policy.

Blocking Mode example:

{
    "policy": {
        "name": "policy_name",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking"
    }
}

Transparent Mode example:

{
    "policy": {
        "name": "policy_name",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "transparent"
    }
}

Enabling Violations

Adding and enabling additional security features to the policy can be done by specifying the violation name and the alarm block state to “true”. To set different states to sub-violations within the violation, enable the violation first, then specifying and enable the sub-violations. Also, a violation may have its own section that provides additional configuration granularity for a specific violation/sub-violation.

Note:
The attack signature violation VIOL_ATTACK_SIGNATURE cannot be configured by the user. Rather, the violation is determined by the combination of the signature sets on the policy.

The examples below show how to enable a violation and sub-violation in a declarative format.

Configuration Details Example

In this example, we enable 2 violations: VIOL_JSON_FORMAT and VIOL_PARAMETER_VALUE_METACHAR.

Note that the example defines the blocking and alarm setting for each violation. These settings override the default configuration set above in the enforcementMode directive. Be aware, however, that in a transparent policy no violations are blocked, even if specific violations are set to block: true in the configuration.

{
    "policy": {
        "name": "policy_name",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_JSON_FORMAT",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_METACHAR",
                    "alarm": false,
                    "block": false
                }
            ]
        }
    }
}

HTTP Compliance

HTTP compliance is one of the basic application security violations. It validates the request itself and also prevents the use of the HTTP protocol as an entry point to the application.

In this example, we enable the HTTP compliance violation with the blocking as true. We also configure (enabled or disabled) all of its sub-violations in the relevant HTTP section. Note that you can add/remove sub-violations to match your desired configurations. However, not listing a violation does not mean it will be disabled. Rather, it would actually mean that the default configuration would not be overridden for that specific sub-violation.

{
    "policy": {
        "name": "policy_name",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_HTTP_PROTOCOL",
                    "alarm": true,
                    "block": true
                }
            ],
            "http-protocols": [
                {
                    "description": "Header name with no header value",
                    "enabled": true
                },
                {
                    "description": "Chunked request with Content-Length header",
                    "enabled": true
                },
                {
                    "description": "Check maximum number of parameters",
                    "enabled": true,
                    "maxParams": 5
                },
                {
                    "description": "Check maximum number of headers",
                    "enabled": true,
                    "maxHeaders": 20
                },
                {
                    "description": "Body in GET or HEAD requests",
                    "enabled": true
                },
                {
                    "description": "Bad multipart/form-data request parsing",
                    "enabled": true
                },
                {
                    "description": "Bad multipart parameters parsing",
                    "enabled": true
                },
                {
                    "description": "Unescaped space in URL",
                    "enabled": true
                }
            ]
        }
    }
}

RFC Checks on the Referer Header

This feature introduces RFC checks on the URL referer header.

If a request contains a referer header with a URL that doesn’t comply with RFC standards as per RFC-3986, it will trigger the VIOL_HTTP_PROTOCOL violation along with its associated sub-violations. If this violation is reported, the user should inspect both the request and referer URLs to identify and address the underlying issue.

For example, in the below URL in Referer header in “Example 1” there is NULL used in Referer value and in “Example 2” unescaped space is used. Since these requests are non-RFC compliant, it will trigger the VIOL_HTTP_PROTOCOL violation.

Example 1
...  Referer: http://example.com/hello%2500world\r\n

Example 2
...  Referer: http://example.com/hello world\r\n

Evasion Techniques

Evasion techniques refers to techniques usually used by hackers to attempt to access resources or evade what would otherwise be identified as an attack. Like HTTP compliance, evasion techniques have a list of sub-violations that can be configured for additional granularity and to reduce false positives.

In this example, we enable the evasion technique violation with the blocking as true. We also configure (enabled or disabled) all of its sub-violations in the relevant section. Note that you can add/remove sub-violations to match your desired configurations. However, not listing a violation does not mean it will be disabled. Rather, it would actually mean that the default configuration would not be overridden for that specific sub-violation.

{
    "policy": {
        "name": "evasions_enabled",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_EVASION",
                    "alarm": true,
                    "block": true
                }
            ],
            "evasions": [
                {
                    "description": "Bad unescape",
                    "enabled": true
                },
                {
                    "description": "Directory traversals",
                    "enabled": true
                },
                {
                    "description": "Bare byte decoding",
                    "enabled": true
                },
                {
                    "description": "Apache whitespace",
                    "enabled": true
                },
                {
                    "description": "Multiple decoding",
                    "enabled": true,
                    "maxDecodingPasses": 2
                },
                {
                    "description": "IIS Unicode codepoints",
                    "enabled": true
                },
                {
                    "description": "IIS backslashes",
                    "enabled": true
                },
                {
                    "description": "%u decoding",
                    "enabled": true
                }
            ]
        }
    }
}

User-defined HTTP Headers

HTTP header enforcement refers to the handling of the headers section as a special part of the request. These header elements are parsed and enforced based on header specific criteria. However, it is important to distinguish between 2 distinct types of enforcement for HTTP headers:

• The first type of header enforcement is global enforcement for all header content, regardless of the header field name or value. This type of enforcement enables/disables violations that are effective for all contents of the header section of the request. Examples of this are VIOL_HEADER_LENGTH and VIOL_HEADER_METACHAR. These violations can be configured in the blocking-settings section under the violations list in the declarative policy.
• The second type of header enforcement is the ability to configure certain violations that are relevant only to specific header fields. Examples of this are allowing repeated instances of the same header field and enabling/disabling Attack Signature checks for an HTTP header field. These violations are configured in the headers section where we configure each HTTP header element separately as an object in the list. Additionally, the corresponding violations need to be enabled in the blocking-settings section under the violations list for them to be enforced.

As far as the header field enforcement is concerned, the following violations are enabled by default:

• VIOL_HEADER_REPEATED (in Block mode)
• VIOL_MANDATORY_HEADER (in Alarm mode)

There are 3 additional violations that are part of the header enforcement but are specific to the Cookie header alone:

• VIOL_COOKIE_LENGTH (in Alarm mode)
• VIOL_COOKIE_MALFORMED (in Block mode)
• VIOL_COOKIE_MODIFIED (in Alarm mode)

In the base template, there are 4 header objects configured by default:

• * (wildcard) - This entity represents the default action taken for all the header fields that have not been explicitly defined in the headers section.
• Cookie - This entity handles the Cookie header field; this object is just a placeholder and does not affect configuration (See the cookie note below).
• Referer - This entity handles the Referer header field.
• Authorization - This entity handles the Authorization header field.
• Transfer-Encoding - This entity handles the Transfer-Encoding header field.

It is important to emphasize that the Cookie header field is a special case because its behavior is determined by and configured in the cookie policy entity rather than the header entity. The Cookie HTTP header entity is only a placeholder in that it is read-only and does not affect the way cookies are enforced. To modify the configuration of the cookie header field behavior, modify the respective cookie entity in the declarative policy.

It is possible to customize the policy configuration using different enforcement modes of the above two violations, as well as configuring custom header elements. For example, we can add a new header Myheader and exclude this header from attack signature checks. Alternatively, we can specify a mandatory header that should be present in all requests being sent to our application.

Following is an example configuration where we enable Header violations in blocking mode, create a custom header MyHeader, and configure this custom header to allow multiple occurrences of the same header, disable checking attack signatures for the header, and mark it as optional (not mandatory):

{
    "policy": {
        "name": "user_headers_blocking_policy",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_MANDATORY_HEADER",
                    "block": true
                }
            ]
        },
        "headers": [
            {
                "name": "MyHeader",
                "type": "explicit",
                "decodeValueAsBase64": "disabled",
                "htmlNormalization": false,
                "mandatory": false,
                "allowRepeatedOccurrences": true,
                "checkSignatures": false
            }
        ]
    }
}

Anti Automation (Bot Mitigation)

Anti Automation provides basic bot protection by detecting bot signatures and clients that falsely claim to be browsers or search engines. The bot-defense section in the policy is enabled by default. Anti Automation encompasses both Bot Signatures and Header Anomalies, each of which can be disabled separately.

As new bot signatures are identified, they will be accessible for download and installation so that your system will always have the most up-to-date protection. You can update the bot signatures without updating the App Protect release. Similarly, you can update App Protect without altering the bot signature package, unless you upgrade to a new NGINX Plus release.

Bot Signatures

Bot Signatures provide basic bot protection by detecting bot signatures in the User-Agent header and URI. Each bot signature belongs to a bot class. Search engine signatures such as googlebot are under the trusted_bots class, but App Protect performs additional checks of the trusted bot’s authenticity. If these checks fail, it means that the respective client impersonated the search engine in the signature and it will be classified as class - malicous_bot, anomaly - Search engine verification failed, and the request will be blocked, irrespective of the class’s mitigation actions configuration. An action can be configured for each bot class, or may also be configured per each bot signature individually:

• ignore - bot signature is ignored (disabled)
• detect - only report without raising the violation - VIOL_BOT_CLIENT. The request is considered legal unless another violation is triggered.
• alarm - report, raise the violation, but pass the request. The request is marked as illegal.
• block - report, raise the violation, and block the request

In this example we show how to enable bot signatures using the default bot configuration:

{
    "policy": {
        "name": "bot_defense_policy",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "bot-defense": {
            "settings": {
                "isEnabled": true
            }
        }
    }
}

The default actions for classes are: detect for trusted-bot, alarm for untrusted-bot, and block for malicious-bot. In this example, we enabled bot defense and specified that we want to raise a violation for trusted-bot, and block for untrusted-bot.

{
    "policy": {
        "name": "bot_defense_policy",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "bot-defense": {
            "settings": {
                "isEnabled": true
            },
            "mitigations": {
                "classes": [
                    {
                        "name": "trusted-bot",
                        "action": "alarm"
                    },
                    {
                        "name": "untrusted-bot",
                        "action": "block"
                    },
                    {
                        "name": "malicious-bot",
                        "action": "block"
                    }
                ]
            }
        }
    }
}

In this example, we override the action for a specific signature (python-requests)

{
    "policy": {
        "name": "bot_defense_policy",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "bot-defense": {
            "settings": {
                "isEnabled": true
            },
            "mitigations": {
                "signatures": [
                    {
                        "action": "ignore",
                        "name": "python-requests"
                    }
                ]
            }
        }
    }
}

Bot Signatures Update File

Starting with NGINX App Protect WAF release 4.7, the bot signature file included_bot_signatures, is located at the following path: /opt/app-protect/var/update_files/bot_signatures/included_bot_signatures. This will be part of the app-protect-bot-signatures package.

This file contains an up-to-date list of all bot signatures that have been updated with the new bot signature package. This list is automatically generated as a part of the app-protect-bot-signatures package and follows a format similar to the README-style text file found in the attack signature. This file contains essential information which includes:

• Bot name
• Bot type
• Bot classification/category

List of Trusted Bots

This is a list of the trusted bots that are currently part of the bot signatures. As the title suggests, these bot signatures belong to the trusted-bot class and currently all are search engines.

Header Anomalies

In addition to detecting Bot Signatures, by default NGINX App Protect WAF verifies that a client claiming to be a browser is indeed one by inspecting the HTTP headers. Each request receives a score, is categorized by anomaly, and is enforced according to the default configured anomaly action:

Notice that the default scores for each anomaly can be changed. In this example, we override the score and action of the default bot configuration:

{
    "policy": {
        "name": "bot_anomalies_and_signatures",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "bot-defense": {
            "mitigations": {
                "anomalies": [
                    {
                        "name": "Suspicious HTTP Headers",
                        "action": "alarm",
                        "scoreThreshold": 50
                    },
                    {
                        "name": "Invalid HTTP Headers",
                        "action": "block",
                        "scoreThreshold": 99
                    }
                ]
            }
        }
    }
}

Signature Sets

The default and strict policies include and enable common signature sets, which are categorized groups of signatures applied to the policy. However, you may wish to modify the list of signature sets and their logging and enforcement settings via the signature-sets array property. There are several ways to configure the enforced signature sets.

One way is by use of the All Signatures signature set, which is simply a predefined signature set that includes all signatures known to NGINX App Protect WAF.

In this example, the All Signatures set (and therefore the signatures included within) are configured to be enforced and logged respectively, by setting their block and alarm properties:

{
    "policy": {
        "name": "attack_sigs",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "signature-sets": [
            {
                 "name": "All Signatures",
                 "block": true,
                 "alarm": true
            }
        ]
    }
}

In this example, only high accuracy signatures are configured to be enforced, but SQL Injection signatures are detected and reported:

{
    "policy": {
        "name": "attack_sigs",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "signature-sets": [
            {
                "name": "High Accuracy Signatures",
                "block": true,
                "alarm": true
            },
            {
                "name": "SQL Injection Signatures",
                "block": false,
                "alarm": true
            }
        ]
    }
}

Since the “All Signatures” set is not included in the default policy, turning OFF both alarm and block has no effect because all the other sets with alarm turned ON (and high accuracy signatures with block enabled) are still in place and a signature that is a member of multiple sets behaves in accordance with the strict settings of all sets it belongs to. The only way to remove signature sets is to remove or disable sets that are part of the default policy.

For example, in the below default policy, even though All Signature’s Alarm/Block settings are set to false, we cannot ignore all attack signatures enforcement as some of the signature sets will be enabled in their strict policy. If the end users want to remove a specific signature set then they must explicitly mention it under the strict policy.

{
    "policy": {
        "name": "signatures_block",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "caseInsensitive": false,
        "enforcementMode": "blocking",
        "signature-sets": [
            {
                "name": "Generic Detection Signatures (High/Medium Accuracy)",
                "block": false,
                "alarm": false
            },
            {
                "name": "All Signatures",
                "block": false,
                "alarm": false
            }
        ]
    }
}

A signature may belong to more than one set in the policy. Its behavior is determined by the most severe action across all the sets that contain it. In the above example, a high accuracy SQL injection signature will both alarm and block, because the High Accuracy Signatures set is blocking and both sets trigger alarm.

The default policy already includes many signature sets, most of which are determined by the attack type these signatures protect from, for example Cross-Site Scripting Signatures or SQL Injection Signatures. See the full list above. In some cases you may want to exclude individual signatures.

In this example, signature ID 200001834 is excluded from enforcement:

{
    "policy": {
        "name": "signature_exclude",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "signature-sets": [
            {
                 "name": "All Signatures",
                 "block": true,
                 "alarm": true
            }
        ],
        "signatures": [
            {
                 "signatureId": 200001834,
                 "enabled": false
            }
        ]
    }
}

Another way to exclude signature ID 200001834 is by using the modifications section instead of the signatures section used in the example above:

{
    "policy": {
        "name": "signature_modification_entitytype",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "signature-sets": [
            {
                 "name": "All Signatures",
                 "block": true,
                 "alarm": true
            }
        ]
    },
    "modifications": [
        {
            "entityChanges": {
                "enabled": false
            },
            "entity": {
                "signatureId": 200001834
            },
            "entityType": "signature",
            "action": "add-or-update"
        }
    ]
}

To exclude multiple attack signatures, each signature ID needs to be added as a separate entity under the modifications list:

{
    "modifications": [
        {
            "entityChanges": {
                "enabled": false
            },
            "entity": {
                "signatureId": 200001834
            },
            "entityType": "signature",
            "action": "add-or-update"
        },
        {
            "entityChanges": {
                "enabled": false
            },
            "entity": {
                "signatureId": 200004461
            },
            "entityType": "signature",
            "action": "add-or-update"
        }
    ]
}

In the above examples, the signatures were disabled for all the requests that are inspected by the respective policy. You can also exclude signatures for specific URLs or parameters, while still enable them for the other URLs and parameters. See the sections on User-Defined URLs and User-Defined Parameters for details.

In some cases, you may want to remove a whole signature set that was included in the default policy. For example, suppose your protected application does not use XML and hence is not exposed to XPath injection. You would like to remove the set XPath Injection Signatures. There are two ways to do that. The first is to set the alarm and block flags to false for this signature set overriding the settings in the base template:

{
    "policy": {
        "name": "no_xpath_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "signature-sets": [
            {
                 "name": "XPath Injection Signatures",
                 "block": false,
                 "alarm": false
            }
        ]
    }
}

The second way is to remove this set totally from the policy using the $action meta-property.

{
    "policy": {
        "name": "no_xpath_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "signature-sets": [
            {
                 "name": "XPath Injection Signatures",
                 "$action": "delete"
            }
        ]
    }
}

Although the two methods are functionally equivalent, the second one is preferable for performance reasons.

Server Technologies

Another way to configure attack signature sets is by applying server technologies. Server technologies applies sets of signatures that would be relevant to attacks targeted to a specific OS, application, or server type. The Server technologies are represented in attack signatures as systems using the same name, for example SharePoint. Note, however, that the overlap between Server technologies and signature systems is not complete: there are server technologies that cannot be represented as signature systems, and also a few generic signature systems that are not represented as server technologies. The exact details will follow in the sections just below. Server technologies that are not signature systems will not bring in new signatures when added to the policy. However, associating them with the policy still has declarational value, and in one of the future signature updates they may be associated with new signatures.

In this example, we enable the attack signature violation, and enabled the Apache/NCSA HTTP Server server technology, which in turn enables attack signatures specific to this type of technology. We also enabled signatures with minimum accuracy of low. This would include low, medium, and high accuracy attack signatures.

{
    "policy": {
        "name": "policy_name",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "signature-settings": {
            "minimumAccuracyForAutoAddedSignatures": "low"
        },
        "server-technologies": [
            { "serverTechnologyName": "Apache/NCSA HTTP Server" }
        ]
    }
}

Available Server Technologies

The table below lists all the available Server Technologies. Some of them are built on top others on the stack and including them implies the inclusion of the latter. For example: ASP.NET implies both IIS and Microsoft Windows. This is indicated in the “implied technologies” column when applicable. We also denote the server technologies that currently have a signature system counterpart.

Generic Signature Systems

These signature systems are generic and do not represent a particular technology, therefore do not have a server technology counterpart. Yet, there are signatures associated with them. The Generic Detection Signatures factory signature set includes most of these signatures. You can define your own signature sets using one or more of those systems.

Threat Campaigns

Threat Campaigns is a threat intelligence feature included in an NGINX App Protect WAF subscription. The feature includes frequent update feeds containing contextual information about active attack campaigns currently being observed by F5 Threat Labs that NGINX App Protect WAF can provide protection against. As an example, without threat campaign updates NGINX App Protect WAF (and any WAF in general) may detect an attack pattern in a web application form parameter, but it cannot correlate the singular attack incident as part of a more extensive and sophisticated threat campaign. Threat Campaigns’ contextual information is very specific to current attack campaigns, allowing false positives to be virtually non-existent.

Just like attack signatures, the Threat Campaign patterns, i.e. app-protect-attack-signatures and app-protect-threat-campaigns are installed as a dependency chain of our main package app-protect. Then, these two package dependencies should be updated periodically to get the latest security updates. Due to the highly dynamic nature of threat campaigns the updates are issued far more frequently than the attack signatures. You need to install those updates close to the time they are issued in order to get the most effective protection.

The default policy enables the mechanism with all available Threat Campaigns and blocks when detecting one. Since the risk of false positive is very low, you do not need to enable or disable specific Threat Campaigns. Rather, you can disable the whole mechanism or decide to only alarm rather than block. You can do that by modifying the properties of the Threat Campaign Violation - VIOL_THREAT_CAMPAIGN.

In this example we disable both alarm and blocking.

{
   "policy": {
       "name": "policy_name",
       "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
       "applicationLanguage": "utf-8",
       "enforcementMode": "blocking",
       "blocking-settings": {
           "violations": [
               {
                   "name": "VIOL_THREAT_CAMPAIGN",
                   "alarm": false,
                   "block": false
               }
           ]
       }
   }
}

Data Guard - Blocking

Data Guard is a security feature that can be used to prevent the leakage of sensitive information from an application. This could be credit card numbers (CCN) or Social Security numbers (SSN) or custom patterns. Once this feature is enabled, sensitive data is either blocked or masked, depending on the configuration.

In this example, we enable the data guard violation in blocking mode. In the detailed configuration, we enable enforcement of data guard and specify which items are being protected against information leakage. Note that if blocking is enabled, data masking will have no effect in this case.

{
    "policy": {
        "name": "dataguard_blocking",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_DATA_GUARD",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "data-guard": {
            "enabled": true,
            "maskData": true,
            "creditCardNumbers": true,
            "usSocialSecurityNumbers": true,
            "enforcementMode": "ignore-urls-in-list",
            "enforcementUrls": []
        }
    }
}

Data Guard - Masking

Masking is used when we do not want to block the page entirely but want to mask all sensitive data in the response.

In this example, we enable data guard in alarm mode. In the detailed configuration, we enable enforcement of data guard and specify which items are being protected against information leakage.

{
    "policy": {
        "name": "nginx_default_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_DATA_GUARD",
                    "alarm": true,
                    "block": false
                }
            ]
        },
        "data-guard": {
            "enabled": true,
            "maskData": true,
            "creditCardNumbers": true,
            "usSocialSecurityNumbers": true,
            "enforcementMode": "ignore-urls-in-list",
            "enforcementUrls": []
        }
    }
}

Partial Masking of Data using Data Guard

Here is an example showing partial masking on custom patterns. Custom patterns are specified in customPatternsList, number of unmasked leading and trailing characters are defined in firstCustomCharactersToExpose and lastCustomCharactersToExpose parameters.

{
    "policy": {
        "name": "custom_pattern_mask_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_DATA_GUARD",
                    "alarm": true,
                    "block": false
                }
            ]
        },
        "data-guard": {
            "enabled": true,
            "maskData": true,
            "creditCardNumbers": false,
            "usSocialSecurityNumbers": true,
            "enforcementMode": "ignore-urls-in-list",
            "enforcementUrls": [],
            "customPatterns": true,
            "firstCustomCharactersToExpose": 2,
            "lastCustomCharactersToExpose": 4,
            "customPatternsList": [
               "....-....-....-....",
               "siteTk_[0-9]+"
            ]
        }
    }
}

File Types

A user can enable/disable specific file types in the policy.

In this example, we enable the file type violation in blocking mode. In the detailed configuration, we allow the * wildcard entity which would allow all file types by default. In the last section, we explicitly disable the bat file type. This is an example of allowing all, but specifically blocking (via deny list) certain items. You may add as many file types as you wish, each declared in its own curly brackets, along with the "allowed": false directive.

{
    "policy": {
        "name": "policy1",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_FILETYPE",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "filetypes": [
            {
                "name": "*",
                "type": "wildcard",
                "allowed": true,
                "checkPostDataLength": false,
                "postDataLength": 4096,
                "checkRequestLength": false,
                "requestLength": 8192,
                "checkUrlLength": true,
                "urlLength": 2048,
                "checkQueryStringLength": true,
                "queryStringLength": 2048,
                "responseCheck": false
            },
            {
                "name": "bat",
                "allowed": false
            }
        ]
    }
}

Response Signatures

All Response Signatures are attack signatures detected on the response side, in contrast to the request side.

Restrict Response Signatures

Restrict Response Signatures enhancement assists the users in saving time by limiting the search for response signatures to a specified amount. You can enable the signature verification in the response by setting the responseCheck parameter to true. However, the restriction of certain signatures is set in the policy and then enforced by the App Protect.

In the policy base template under the “filetypes” section, make sure you enable the responseCheck attribute for responseCheckLength to work properly. The default value of responseCheck parameter is set to false.

The responseCheckLength parameter refers to the number of uncompressed bytes in the response body prefix that are examined for signatures. The responseCheckLength field will be added with the default value of 20000 bytes which means that the first 20,000 bytes of the response body will undergo signature verification.

Restrict Response Signature example:

In the below policy example, in the “filetypes” section, the responseCheck parameter is set to true, indicating that response check will be enabled. When enforcing signatures on the response, we have the flexibility to restrict the portion of the response body that requires validation. In this case, the policy is configured with responseCheckLength set to 1000, signifying that only the initial 1000 bytes of the response body will undergo signature verification.

{
    "policy": {
        "name": "response_signatures_block",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "filetypes": [
           {
            "name": "*",
            "type": "wildcard",
            "responseCheck": true,
		    "responseCheckLength": 1000
           }
        ],
            "signature-sets": [
          {
                "name": "All Response Signatures",
                "block": true,
                "alarm": true
           }
        ]
    }
}

How Does Restrict Response Signature Check Work?

The response signature check is always done on the configured responseCheckLength as described above. Usually NGINX App Protect WAF will buffer only that part of the response saving memory and CPU, but in some conditions the whole response may have to be buffered, such as when the response body is compressed.

Allowed Methods

In the policy, you can specify what methods to allow or disallow.

In this example, we enable the illegal method violation in blocking mode. In the methods configuration, we define which of the methods are allowed. If a method is allowed by default, it can be disallowed via "$action": "delete". In the following example we disallow the default allowed method PUT by removing it from the default enforcement. For illustrative purposes this example also has all the other methods that are allowed by default defined in the configuration, but in practicality they do not actually need to be included explicitly to be allowed:

{
    "policy": {
        "name": "blocking_policy",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_METHOD",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "methods": [
            {
                "name": "GET"
            },
            {
                "name": "POST"
            },
            {
                "name": "HEAD"
            },
            {
                "name": "PUT",
                "$action": "delete"
            },
            {
                "name": "PATCH"
            },
            {
                "name": "DELETE"
            },
            {
                "name": "OPTIONS"
            }
        ]
    }
}

Custom Method Enforcement

To enable any custom method other than the above mentioned HTTP standard methods, the user must configure the specific modules that allow those methods. NGINX will reject any custom method other than the standard allowed HTTP methods GET, POST, PUT, DELETE, HEAD, and OPTIONS.

For example, see currently supported WebDAV Methods.

Response Codes

Response codes are a general setting that defines which response codes are acceptable, while all others will be blocked.

In this example, we enable the response status codes violation in blocking mode. In the general configuration, we define which of the response codes are allowed. This would mean that all others will be considered as illegal response codes and will be blocked. In this configuration, you specify a list of comma-separated response codes that are allowed.

{
    "policy": {
        "name": "allowed_response",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_HTTP_RESPONSE_STATUS",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "general": {
            "allowedResponseCodes": [
                400,
                401,
                403,
                404,
                502,
                499
            ]
        }
    }
}

Parameters

When configuring handling of parameters, it is a bit different from other configurations we have dealt with earlier, where we enable a violation and configure its details. With parameters, there are a number of independent violations that need to be enabled on their own, as well as a parameter section to define further customization. The full list of parameter violations can be extracted from the above violation list.

{
    "policy": {
        "name": "parameters_blocking",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_MULTIPART_NULL_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_NAME_METACHAR",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_METACHAR",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "checkMetachars": true,
                "parameterLocation": "any",
                "valueType": "auto-detect",
                "metacharsOnParameterValueCheck": true,
                "name": "*",
                "type": "wildcard",
            }
        ]
    }
}

In this example we configure allowed meta-characters in parameter name and value.

{
    "policy": {
        "name": "parameters_allowed_metachars",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_MULTIPART_NULL_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_NAME_METACHAR",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_METACHAR",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "checkMetachars": true,
                "sensitiveParameter": false,
                "parameterLocation": "any",
                "valueType": "auto-detect",
                "nameMetacharOverrides": [
                    {
                        "isAllowed": true,
                        "metachar": "0x3c"
                    },
                    {
                        "isAllowed": true,
                        "metachar": "0x3e"
                    }
                ],
                "metacharsOnParameterValueCheck": true,
                "allowEmptyValue": true,
                "checkMaxValueLength": false,
                "valueMetacharOverrides": [
                    {
                        "isAllowed": true,
                        "metachar": "0x3c"
                    },
                    {
                        "isAllowed": true,
                        "metachar": "0x3e"
                    }
                ],
                "name": "*",
                "level": "global",
                "allowRepeatedParameterName": true,
                "attackSignaturesCheck": true,
                "signatureOverrides": [],
                "type": "wildcard",
            }
        ]
    }
}

In this example, we define a sensitive parameter mypass configuration.

{
    "policy": {
        "name": "parameters_sensitive",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_MULTIPART_NULL_VALUE",
                    "alarm": true,
                    "block": false
                },
                {
                    "name": "VIOL_PARAMETER_NAME_METACHAR",
                    "alarm": true,
                    "block": false
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_METACHAR",
                    "alarm": true,
                    "block": false
                }
            ]
        },
        "sensitive-parameters": [
            {
                "name": "mypass"
            }
        ]
    }
}

User-Defined URLs

The user-defined URL feature allows the user to configure the URL while supporting the following options:

• Define a protected URL configuration both explicitly and by wildcards.
• Define a per-URL list of allowed/disallowed methods that will override the list defined in the policy level.
• Define a content-type: json/xml/form-data on a user-defined URL.
• Define an Allowed/Disallowed user-defined URL.
• Add a user-defined URL to the Signature/Metacharacters override list.

For urlContentProfiles default values, see NGINX App Protect WAF Declarative Policy guide.

In this example we configure allowed meta-characters in a user-defined URL:

{
    "policy": {
        "name": "/Common/user_defined_URL",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_URL",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_URL_METACHAR",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "urls": [
            {
                "method": "*",
                "name": "/meta*",
                "protocol": "http",
                "type": "wildcard",
                "metacharsOnUrlCheck": true,
                "metacharOverrides": [
                    {
                        "isAllowed": true,
                        "metachar": "0x3c"
                    },
                    {
                        "isAllowed": false,
                        "metachar": "0x28"
                    }
                ],
                "wildcardOrder": 2
            }
        ]
    }
}

In this example, we disable the detection of a specific signature, 200010093 and enable another one, 200010008, both in a user-defined URL /Common/user_defined_URL. These signature settings take effect only in requests to that URL. In other requests, the signature behavior is determined by the signature sets these signatures belong to. See Signature Sets for more details.

{
    "policy": {
        "name": "/Common/user_defined_URL",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_URL",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "urls": [
            {
                "method": "*",
                "name": "/test*",
                "protocol": "http",
                "type": "wildcard",
                "wildcardOrder": 1,
                "attackSignaturesCheck": true,
                "signatureOverrides": [
                    {
                        "enabled": true,
                        "signatureId": 200010008
                    },
                    {
                        "enabled": false,
                        "signatureId": 200010093
                    }
                ]
            }
        ]
    }
}

In this example, we configure Wildcard/Explicit URLs, where the first URL is permitted for all methods, and the second is permitted only for GET:

{
    "policy": {
        "name": "/Common/user_defined_URL",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_URL",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "urls": [
            {
                "method": "*",
                "name": "/test*",
                "protocol": "http",
                "type": "wildcard",
                "wildcardOrder": 1
            },
            {
                "method": "GET",
                "name": "/index.html",
                "protocol": "http",
                "type": "explicit"
            }
        ]
    }
}

In this example, we configure json/xml/form-data content types for a specific user-defined URL:

{
    "policy": {
        "name": "/Common/user_defined_URL",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_URL",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_METHOD",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_JSON_MALFORMED",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_JSON_FORMAT",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_XML_FORMAT",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "json-profiles": [
            {
                "name": "Default",
                "handleJsonValuesAsParameters": false,
                "defenseAttributes": {
                    "maximumTotalLengthOfJSONData": "any",
                    "maximumArrayLength": "any",
                    "maximumStructureDepth": "any",
                    "maximumValueLength": "any"
                }
            }
        ],
        "xml-profiles": [
            {
                "name": "Default",
                "defenseAttributes": {
                    "maximumAttributesPerElement": "any",
                    "maximumDocumentDepth": "any",
                    "maximumAttributeValueLength": "any",
                    "maximumChildrenPerElement": "any",
                    "maximumDocumentSize": "any",
                    "maximumElements": "any",
                    "maximumNameLength": "any",
                    "maximumNSDeclarations": "any",
                    "maximumNamespaceLength": "any",
                    "tolerateLeadingWhiteSpace": true,
                    "tolerateCloseTagShorthand": true,
                    "allowCDATA": true,
                    "allowExternalReferences": true,
                    "allowProcessingInstructions": true
                }
            }
        ],
        "urls": [
            {
                "method": "*",
                "name": "/first*",
                "protocol": "http",
                "type": "wildcard",
                "wildcardOrder": 1,
                "urlContentProfiles": [
                    {
                        "headerValue": "*",
                        "headerName": "*",
                        "headerOrder": "3",
                        "type": "form-data"
                    },
                    {
                        "contentProfile": {
                            "name": "Default"
                        },
                        "headerValue": "*xml*",
                        "headerName": "Content-Type",
                        "headerOrder": "2",
                        "type": "xml"
                    },
                    {
                        "contentProfile": {
                            "name": "Default"
                        },
                        "headerValue": "*json*",
                        "headerName": "Content-Type",
                        "headerOrder": "1",
                        "type": "json"
                    }
                ]
            }
        ]
    }
}

Do-Nothing

The do-nothing in urlContentProfiles allows the user to avoid inspecting or parsing the content in a policy, and instead handle the request’s header according to the specifications outlined in the security policy.

In this example, we configure do-nothing content types for a specific user-defined URL:

{
    "policy" : {
        "name": "ignore_body",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "urls": [
            {
                "method": "*",
                "name": "*",
                "type": "wildcard",
                "urlContentProfiles": [
                    {
                        "headerName": "*",
                        "headerOrder": "default",
                        "headerValue": "*",
                        "type": "do-nothing"
                    }
                ]
            }
        ]
    }
}

User-Defined Parameters

So far, we have been managing the default parameter or * entity. What if we want to give specific attributes to specific parameters? This can be done by creating and configuring the user-defined parameters. This feature gives the user full control over what the parameter should include, where it should be located and allows for granularity in configuring each and every parameter. Here you can:

• Create unique parameters and specify attributes for each.
• Define what data type the parameter should contain.
• Define the allowed location where you expect to see a parameter.
• Define minimum/maximum values and minimum/maximum lengths for a parameter.
• Define whether a parameter is mandatory or not.
• Define whether the parameter can have empty values or not.
• Define whether to inspect a parameter for violations, attack signatures, or meta-characters.
• Decide whether to exclude certain violations, attack signatures, or meta-characters for a parameter.

In the following example, we configure two parameters. The first one, text, takes string values (here configured as alpha-numeric), and limits the length of the allowed string between 4 and 8 characters. Any string below or above these values will trigger the violation VIOL_PARAMETER_VALUE_LENGTH. Note that we enable this violation to block the violating request.

The second parameter, query, is added to the policy just to avoid a false positive condition due to a specific signature, 200002835. Suppose you realized that whenever this signature detected on this parameter, it was false positive. You would like to disable this signature, but only in the context of this parameter. The signature will still be detected on values of other parameters.

{
    "policy": {
        "name": "user_defined_parameters_data_types",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_VALUE_LENGTH",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "name": "text",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": false,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "user-input",
                "dataType": "alpha-numeric",
                "checkMinValueLength": true,
                "checkMaxValueLength": true,
                "minimumLength": 4,
                "maximumLength": 8
            },
            {
                "name": "query",
                "type": "explicit",
                "valueType": "user-input",
                "dataType": "alpha-numeric",
                "signatureOverrides": [
                    {
                        "enabled": false,
                        "signatureId": 200002835
                    }
                ]
            }
        ]
    }
}

In the next example, we configure a numeric parameter. This parameter accepts only integer values and allows values between 9 and 99 (non-inclusive). If the request includes anything other than an integer, it will trigger the VIOL_PARAMETER_DATA_TYPE violation. If the parameter value falls beyond or below the desired values, it will trigger the VIOL_PARAMETER_NUMERIC_VALUE violation. Note that if you change the values of exclusiveMin and exclusiveMax to false, values equal to the boundary values will be accepted (namely 9 and 99).

{
    "policy": {
        "name": "user_defined_parameters_data_types",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_NUMERIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_LENGTH",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_STATIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_DATA_TYPE",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "name": "number",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": false,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "user-input",
                "dataType": "integer",
                "checkMinValue": true,
                "checkMaxValue": true,
                "minimumValue": 9,
                "maximumValue": 99,
                "exclusiveMin": true,
                "exclusiveMax": true
            }
        ]
    }
}

For increased granularity, you can configure whether the parameter value is also a multiple of a specific number. This is useful when you wish to limit the input to specific values. The following example configures a parameter that accepts values in the range of 0 to 10 and are only multiples of 3. This means that the accepted values are 3, 6 and 9. Any other value will trigger the VIOL_PARAMETER_NUMERIC_VALUE violation.

{
    "policy": {
        "name": "user_defined_parameters_data_types",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_NUMERIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_LENGTH",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_STATIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_DATA_TYPE",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "name": "multiples",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": false,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "user-input",
                "dataType": "integer",
                "checkMinValue": true,
                "checkMaxValue": true,
                "minimumValue": 0,
                "maximumValue": 10,
                "checkMultipleOfValue": true,
                "multipleOf": 3
            }
        ]
    }
}

Another very useful example is when the user wants to limit the parameter to a single context, like in a header or a query string. If the same variable appears in a different location, it will trigger the VIOL_PARAMETER_LOCATION violation.

{
    "policy": {
        "name": "user_defined_parameters_misc_test",
        "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_NUMERIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_VALUE_LENGTH",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_STATIC_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_DATA_TYPE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_LOCATION",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "name": "headerparam",
                "type": "explicit",
                "parameterLocation": "header",
                "mandatory": false,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "user-input",
                "dataType": "alpha-numeric",
                "checkMinValueLength": false,
                "checkMaxValueLength": false
            }
        ]
    }
}

Another very useful example is the following configuration. It has:

• A sensitive parameter mypass that should be masked in the logs.
• A parameter empty that is allowed to be empty.
• A parameter repeated that can be repeated multiple times.
• A parameter mandatory that is mandatory for all requests.

Note that new violations were enabled so that the configuration becomes effective.

{
    "policy": {
        "name": "user_defined_parameters_misc_test",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "blocking-settings": {
            "violations": [
                {
                    "name": "VIOL_PARAMETER_EMPTY_VALUE",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER_REPEATED",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_MANDATORY_PARAMETER",
                    "alarm": true,
                    "block": true
                },
                {
                    "name": "VIOL_PARAMETER",
                    "alarm": true,
                    "block": true
                }
            ]
        },
        "parameters": [
            {
                "name": "mypass",
                "type": "explicit",
                "parameterLocation": "any",
                "sensitiveParameter": true,
                "valueType": "auto-detect"
            },
            {
                "name": "empty",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": false,
                "allowEmptyValue": true,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "auto-detect"
            },
            {
                "name": "repeated",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": false,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": true,
                "sensitiveParameter": false,
                "valueType": "auto-detect"
            },
            {
                "name": "mandatory",
                "type": "explicit",
                "parameterLocation": "any",
                "mandatory": true,
                "allowEmptyValue": false,
                "allowRepeatedParameterName": false,
                "sensitiveParameter": false,
                "valueType": "auto-detect"
            }
        ]
    }
}

User-Defined Signatures

Another useful expansion to the customization capabilities is the ability to create user-defined signatures. This capability allows the user to define new signatures, configure how they behave in terms of enforcement, and categorize them in user-defined signature sets (using tags) for ease of management.

The process of creating and implementing a user policy that contains user-defined signatures is a three-fold process:

• Creating the user-defined signature definitions in separate JSON files.
• Adding the relevant references (names, tags, signature sets) to the user-defined signatures in a policy JSON file.
• Referencing user-defined JSON files in a global settings file.
• Compiling a policy bundle using NGINX App Protect WAF Compiler

User-Defined Signature Definitions

The user-defined signature definition file is a JSON file where the signatures themselves are defined and given their properties and tags. The format of the user-defined signature definition is as follows:

{
    "tag": "tag_name",
    "revisionDatetime": "2020-01-21T18:32:02Z",
    "signatures": []
}

Tags help organizing the user-defined signatures in bundles so that all signatures in that bundle are (usually) authored by the same person and share a common purpose or set of applications that will consume it. It also creates name spaces that avoid name conflicts among user-defined signatures. Signatures are uniquely identified by the combination of tag and name. The tag_name should be replaced with the tag name to be assigned to all signatures in this file or group. The revisionDatetime specifies the date or version of the signature file. Note that you can create as many user-defined signature definition files as you wish provided that you assign a unique tag for each file and that the user-defined signatures have unique names, both within the same file, or across different files.

To add user-defined signatures to the signatures list, each signature must have the following format:

{
    "name": "unique_name",
    "description": "Add your description here",
    "rule": "content:\"string\"; nocase;",
    "signatureType": "request",
    "attackType": {
        "name": "Buffer Overflow"
    },
    "systems": [
        {
            "name": "Microsoft Windows"
        },
        {
            "name": "Unix/Linux"
        }
    ],
    "risk": "medium",
    "accuracy": "medium"
}