NGINX App Protect DoS Directives and Policy

Learn about the NGINX App Protect DoS Directives and Policy

Introduction

NGINX directives are written in the nginx.conf file and are used to configure specific modules of NGINX.
NGINX App Protect DoS has its own directives (which follows the same rules of all other directives) and are used to enable and configure it.

The table below summarizes all the NGINX App Protect DoS directives.

Although only the first directive is mandatory (used for enabling NGINX App Protect DoS), it is advised to use as many directives as possible in order to make use of the product’s monitoring and application health detection capabilities.
When reloading NGINX after inserting the directives, pay attention to any errors or warnings that might be written to the NGINX error log.

Directives table

This is a summary of all NGINX App Protect DoS directives. You can find the description of each below.

Directive syntax Options Context Description Mandatory Default
app_protect_dos_enable [on|off] http,
server,
location
Enable/Disable DoS protection Yes off
app_protect_dos_policy_file [FILE-PATH] http,
server,
location
Load DoS configuration from a policy file No /etc/app_protect_dos/BADOSDefaultPolicy.json
app_protect_dos_name [SERVICE-NAME] http,
server,
location
Name of protected object No line_num-server_name:seq-location_name

(i.e. 30-backend:1-/abc)
app_protect_dos_monitor [MONITOR-URL] http,
server,
location
URL to monitor server’s stress No None

URL will be extracted from the first request which arrives and taken from “Host” header or from destination ip+port
app_protect_dos_security_log_enable [on|off] http,
server,
location
Enable/Disable security logger No off
app_protect_dos_security_log [LOG-CONFIG-FILE] [DESTINATION] http,
server,
location
Second argument:
“syslog:server={ip}:{port}” or
“stderr” or
“{absolute_file_path}”
No /etc/app_protect_dos/log-default.json stderr
app_protect_dos_liveness [on|off] [uri:URI] [port:PORT] http Liveness prob. Second and third arguments are optional No off uri:/app_protect_dos_liveness port:8090
app_protect_dos_readiness [on|off] [uri:URI] [port:PORT] http Readiness prob. Second and third arguments are optional No off uri:/app_protect_dos_readiness port:8090

Directives Info

Enable directive (app_protect_dos_enable)

Enables/disables App Protect DOS module in the relevant block/s. It can be written in the following contexts: location/server/http.

The derived blocks/contexts also inherit the directive. For example: A directive written in http context will be considered as if written also in all of the http’s server blocks and their location blocks.

In case of multiple directives in different contexts, the derived overwrites the base’s directive.

Config Expected
Http block: directive is on
Server block: none is written
Location-1 block: none is written
Location-2 block: none is written
VS1: the server block
VS2: location-1 block
VS3: location-2 block
Server block: directive is on
Location-1 block: directive is off
Location-2 block: none is written
VS1: the server block
VS2: location-2 block
Http block: directive is on
Server block: directive is off
Location-1 block: directive is on
Location-2 block: none is written
VS1: location-1 block

Example:

app_protect_dos_enable on;

Policy directive (app_protect_dos_policy_file)

This is the path to the JSON policy file which includes the product’s configuration parameters. It can be written in the following contexts: location/server/http.

The directive is optional. If not inserted then default path will be used, which is /etc/app_protect_dos/BADOSDefaultPolicy.json.

If the configuration file doesn’t exist or its attributes are invalid, default values will be used.

BADOSDefaultPolicy.json:

{
    "mitigation_mode": "standard",
    "signatures": "on",
    "bad_actors": "on"
    "use_automation_tools_detection": "on",
    "tls_fingerprint" : "on"
}
Parameter name Values Default Description
mitigation_mode standard / conservative / none standard Standard - module allowed to use global rate mitigation
Conservative - module is not allowed to use global rate but only Signatures/Bad Actors mitigation
None - module is not allowed to mitigate. Only to learn and report.
signatures [on|off] on Enable mitigation by Signatures algorithm
bad_actors [on|off] on Enable mitigation by Bad Actors algorithm
automation_tools_detection [on|off] on Enable the usage of automation tools detection (via cookies and redirect)
tls_fingerprint [on|off] on Enable source identification using TLS fingerprinting
Scenario Result
Directive is not written Default path is used: “/etc/app_protect_dos/BADOSDefaultPolicy.json”
Directive is written Path from the directive is used
File not found / file syntax is invalid Default values are used

Example:

app_protect_dos_policy_file /etc/app_protect_dos/BADOSPolicy.json;

Service Name directive (app_protect_dos_name)

This is the VS (protected object) name, it should be unique and is used to identify the VS in the logs. It can be used in location/server/http blocks.

Directive is optional. If not written, then each protected object (VS) will have an auto-generated name according to the following syntax:

line_number-server_name:seq-location_name

For example: 30-backend:1-/abc

  • line number: the line number of the server block (server {) in the nginx.conf file (i.e. 30)
  • server name: taken from directive server_name (i.e. backend)
    seq: 0 for server block, increments for each location block. i.e. VS created from server block will have 0 and VS’s from location blocks will be 1,2,3,… (i.e. 1)
  • location name: the name of the location (i.e. /abc)

Example:

app_protect_dos_name po-example;

Monitor directive (app_protect_dos_monitor)

This is the URL which is going to be monitored in order to know the VS stress. It can be used in location/server/http blocks.

The directive is optional. If the directive is not present in neither of the blocks then server’s health will not be monitored using URL but only using the embedded algorithm.

Example:

app_protect_dos_monitor

Security log enable directive (app_protect_dos_security_log_enable)

Enable/Disable App Protect DoS security logger. It can be used in location/server/http blocks.

Directive is optional. If not written, then logger is disabled.

Example:

app_protect_dos_security_log_enable on;

Security log directive (app_protect_dos_security_log)

This directive has two string arguments.

First argument is the configuration file path, i.e. /etc/app_protect_dos/log-default.json.

Second argument is the destination (the location which the events will be sent to). The destination can be one of three options:

  • syslog:server={ip}:{port}, i.e. syslog:server=1.2.3.4:3000
  • stderr (default)
  • {absolute_file_path}, i.e. /shared/dos_sec_logger.log

Implemented according to: NGINX App Protect DoS Security Log

Note:
  • When using stderr, make sure that the process admd is not redirecting the stderr output to file.
  • When using the Docker entrypoint.sh startup script from the admin guide, make sure that it doesn’t redirect stderr.

Examples:

  • Syslog:
app_protect_dos_security_log "/etc/app_protect_dos/log-default.json" syslog:server=1.2.3.4:5000;
  • File:
app_protect_dos_security_log "/etc/app_protect_dos/log-default.json" /shared/logger.log;
  • Stderr:
app_protect_dos_security_log "/etc/app_protect_dos/log-default.json" stderr;

While /etc/app_protect_dos/log-default.json is:

{
    "filter": {
        "traffic-mitigation-stats": "all",
        "bad-actors": "top 10",
        "attack-signatures": "top 10"
    },
    "content": {
        "format": "splunk"
    }
}

Liveness probe directive (app_protect_dos_liveness)

This directive has 3 arguments.

First argument Second argument Third argument
[on|off]
depending if this feature should be enabled or disabled.
URI
Syntax is: uri:___
Port
Syntax is: port:____
Note:
Second and Third arguments are optional; if one or more is not written, the default will take place.

If liveness is enabled, a request with URI and PORT that matches the probe configuration (i.e. /app_protect_dos_liveness:8090) will be answered with RC 200 “Alive” by our NGINX module, without being counted or pass to other handlers nor the backend server.

Any other response will indicate that our NGINX module (NGINX App Protect DoS) has not received the request (possibly means that NGINX is down).

Example:

app_protect_dos_liveness on uri:/liveness port:8090;

Readiness probe directive (app_protect_dos_readiness)

This directive has 3 arguments.

First argument Second argument Third argument
[on|off]
depending if this feature should be enabled or disabled.
URI
Syntax is: uri:___
Port
Syntax is: port:____
Note:
Second and Third arguments are optional; if one or more is not written, the default will take place.

If readiness is enabled, a request with URI and PORT that matches the probe configuration (i.e. /app_protect_dos_readiness:8090) will be answered with RC 200 “Ready” or RC 503 “Not Ready” by our NGINX module, without being counted or pass to other handlers nor the backend server.

Any other response will indicate that our NGINX module (NGINX App Protect DoS) has not received the request (possibly means that NGINX is down).

RC 200 “Ready” will occur if two conditions are met:

  1. NGINX worker successfully connected to the global shared memory block
  2. ADMD process is running (and not stuck)

Example:

app_protect_dos_readiness on uri:/readiness port:8090;

This documentation applies to the following versions of NGINX App Protect DoS: 1.0.