Directives

This topic describes the global NGINX directives and directives specific to F5 WAF for NGINX.

Global directives

Global configuration consists of a series of nginx.conf directives at the http context controlling aspects that are not specific to a specific application. When applied to a cluster, all cluster members will get the same globals.

The URL in a request determines whether or not it will be inspected by F5 WAF for NGINX. This is defined by app_protect_enable and app_protect_policy_file directives in the location scope.

In the case that the URL itself has violations such as bad unescape or illegal metacharacter, the request may be assigned to a location in which F5 WAF for NGINX is disabled or has a relaxed policy that does not detect these violations.

Such malicious requests will be allowed without inspection.

In order to avoid this, it is recommended to have a basic policy enabled at the http scope or at least at the server scope to process malicious requests in a more complete manner.

Name Syntax Description Default app_protect_physical_memory_util_thresholds app_protect_physical_memory_util_thresholds high=<number_0-100> low=<number_0-100> Sets the physical memory utilization thresholds for entering (high) and exiting (low) failure mode. When the high threshold is exceeded the system enters failure mode until memory drops below the low threshold. Setting the value of 100 disables this feature. high=low=100 (disabled) app_protect_cpu_thresholds app_protect_cpu_thresholds high=<number_0-100> low=<number_0-100> Sets the CPU utilization thresholds for entering and exiting failure mode respectively: when the high threshold is exceeded the system enters failure mode until CPU drops below the low threshold. Setting the value of 100 disables this feature.
Note: The system does not enter failure mode during policy compilation after reload even if the threshold is exceeded. high=low=100 (disabled) app_protect_failure_mode_action app_protect_failure_mode_action pass | drop How to handle requests when the F5 WAF for NGINX Enforcer cannot process them, either because it is down, disconnected or because of excessive CPU or memory utilization. There are two values:

pass: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".
drop: Drop the request by returning the response "503 Service Unavailable", a.k.a. "fail-close".

pass app_protect_cookie_seed app_protect_cookie_seed A long randomized string that serves to generate the encryption key for the cookies generated by F5 WAF for NGINX. The string should contain only alphanumeric characters and be no longer than 1000 characters. Auto-generated random string app_protect_compressed_requests_action app_protect_compressed_requests_action pass | drop Determines how to handle compressed requests. There are two values:

pass: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".
drop: Drop the request by returning the response "501 Not Implemented", a.k.a. "fail-close".

Note: Starting with F5 WAF for NGINX release version 4.6, this directive has been deprecated from the nginx.conf file. drop app_protect_request_buffer_overflow_action app_protect_request_buffer_overflow_action pass | drop Determines how to handle requests in case the NGINX request buffer is full and requests cannot be buffered anymore. There are two values:

pass: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".
drop: Drop the request by resetting connection. No response page is returned, a.k.a. "fail-close".

pass app_protect_user_defined_signatures app_protect_user_defined_signatures Imports the user-defined tagged signature file with the respective tag name from the provided path. Multiple instances of this directive are supported. In order to import multiple signatures files, each file must have a different tag. N/A app_protect_reconnect_period_seconds app_protect_reconnect_period_seconds
Value type: number with decimal fraction
Value Range: 0-60. 0 is illegal Determines the period of time between reconnect retries of the module to the web application firewall (WAF) engine. The time unit is seconds. 5

F5 WAF for NGINX directives

Name Syntax Functionality Contexts Example load_module load_module <library_file_path> NGINX directive to load the F5 WAF for NGINX module. It must be invoked with the F5 WAF for NGINX library path Global load_module modules/ngx_http_app_protect_module.so app_protect_enable app_protect_enable on | off Whether to enable F5 WAF for NGINX at the respective context. If not present, inherits from the parent context HTTP, Server, Location app_protect_enable on app_protect_policy_file app_protect_policy_file <file_path> Set a F5 WAF for NGINX policy configuring behavior for the respective context. HTTP, Server, Location app_protect_policy_file /config/waf/strict_policy.json app_protect_security_log_enable app_protect_security_log_enable on | off Whether to enable the F5 WAF for NGINX per-request log at the respective context. HTTP, Server, Location app_protect_security_log_enable on app_protect_security_log app_protect_security_log <file_path> Specifies the per-request logging: what to log and where HTTP, Server, Location app_protect_security_log /config/waf/log_illegal.json syslog:localhost:522 app_protect_custom_log_attribute app_protect_custom_log_attribute <key_value> Specifies the assigned location/server/http dimension of each request. HTTP, Server, Location app_protect_custom_log_attribute ‘environment' ’env1'

Horizontal scaling

F5 WAF for NGINX can be deployed in multiple instances that share the traffic to the same applications.

In this case, all instances must share the same configuration files.

It is your responsibility to synchronize the files on all instances. You must also load balancing each of those instances, such as using additional NGINX instances.

When deploying multiple scalability instances add the app_protect_cookie_seed directive to nginx.conf in the http block:

nginx...
http {
    ...
    app_protect_cookie_seed jkldsf90upiokasdj120;
    ...
    server {
        listen       80;
...
}
...

The argument for the directive should be a random alphanumeric string of at least 20 characters (Maximum 1000 characters).

This is a seed used by F5 WAF for NGINX to generate the encryption key for the cookies it creates. These cookies are used for various purposes such as validating the integrity of the cookies generated by the application.

In the absence of this directive, F5 WAF for NGINX generates a random string by itself. In that case, each instance will have a different seed.

A cookie created and encrypted on one instance of F5 WAF for NGINX will fail to be decrypted when sent by the same client to another F5 WAF for NGINX instance having a different encryption key.

Failure modes

If the F5 WAF for NGINX daemons are down or disconnected from the NGINX workers, there are two modes of operation until they are up and connected again:

Pass the traffic without inspection. Use this when preferring availability over security. This mode is also known as "fail open".
Drop the traffic. Use this when preferring security over availability. This mode is also known as "fail closed".

The default is to pass, fail open, but you can control this using the app_protect_failure_mode_action directive with one argument with two possible values: "pass" or "fail" for the two above options.

This directive is also placed in the http block of the nginx.conf file.

nginx...
http {
    ...
    app_protect_failure_mode_action drop;
    ...
    server {
        listen       80;
...
    }
...

Handling compressed requests

Warning

From F5 WAF for NGINX release version 4.6, the app_protect_compressed_requests_action directive was removed deprecated from the NGINX configuration.

When configuring this directive in the nginx.conf file, F5 WAF for NGINX disregards any previously used values ("pass" or "drop") and issues a warning.

By default, the enforcer will now decompress the whole HTTP compressed payload request and will apply the enforcement.

The supported compression algorithms for this feature are "gzip" and "deflate".

Decompression may fail under certain conditions:

If the compression method is not supported
If the 'Content-Encoding' header does not match the compression algorithm used while sending a compressed payload in a HTTP request
If the decompressed request is larger than 10 MB

If it does exceed this limit, F5 WAF for NGINX will only decompress the first 10 KB, ignoring the remainder, and trigger the VIOL_REQUEST_MAX_LENGTH violation, just as it would for an uncompressed request that exceeds 10 MB.

In the cases where decompression fails, F5 WAF for NGINX will continue with the scan in the same manner as it does for uncompressed requests.

View source

Edit this page

Create a new issue