NGINX App Protect DoS Live Activity Monitoring

Learn about the NGINX App Protect DoS Live Activity Monitoring.

Overview

NGINX App Protect DoS provides various monitoring tools for your application:

The interactive App Protect DoS Dashboard page - a real-time live activity monitoring interface that shows the status and information of the Protected Objects.
NGINX App Protect DoS REST API - an interface that provides extended metrics information of the Protected Objects.

Prerequisites

NGINX Plus R26 and later for NGINX App Protect DoS REST API and the DoS Dashboard

Configuring the API

To enable the API:

In the http context, specify a server block that will be responsible for the API:

http {
    server {
        # your api configuration will be here
    }
}

Create a location for API requests and specify the app_protect_dos_api directive in this location:

http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            app_protect_dos_api;
            # ...
        }
    }
}

It is recommended restricting access to the API location, for example, allow access only from local networks with allow and deny directives:

http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            app_protect_dos_api;
            allow 192.168.1.0/24;
            deny all;
        }
    }
}

It is also recommended restricting access to PATCH, POST, and DELETE methods to particular users. This can be done by implementing HTTP basic authentication:

http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            app_protect_dos_api;
            allow 192.168.1.0/24;
            deny  all;
        }
    }
}

Enable the DoS Dashboard by specifying the /dashboard-dos.html location. By default the DoS Dashboard is located in the root directory (for example, /usr/share/nginx/html) specified by the root directive:

http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            app_protect_dos_api;
            allow 192.168.1.0/24;
            deny  all;
        }
        location = /dashboard-dos.html {
            root   /usr/share/nginx/html;
        }
    }
}

Using the Dashboard

Accessing the Dashboard

In the address bar of your browser, type in the address that corresponds to your Dashboard page (in our example http://192.168.1.23/dashboard-dos.html). This will display the Dashboard page located at /usr/share/nginx/html as specified in the root directive.

DoS Tab Overview

The DoS tab provides live statistics, configuration, and traffic graph per Protected Object.
In case of deployment with arbitrator and multiple NGINX App Protect DoS instances, the statistics will be aggregated.

Metric name	Values	Description
Name	-	The name of the Protected Object, as defined by the `app_protect_dos_name` directive (or auto-generated if not present)
Health	[good\|bad]	The health of the backend server, as defined by the `uri` argument of the `app_protect_dos_monitor` directive
Under Attack	[yes\|no]	Whether the Protected Object is under attack or not
Req/s	-	Number of incoming requests per second
Mitigations/s	-	Number of mitigated requests per second
Requests	-	Total number of incoming requests
Mitigations	-	Total number of mitigated requests
Learning	[ready\|ba only\|not ready]	Whether NGINX App Protect DoS collected enough data to protect the Protected Object
Protocol	[http1\|http2\|grpc]	As defined by the `protocol` argument of the `app_protect_dos_monitor` directive
Mitigation Mode	[standard\|conservative\|none]	As defined by the `mitigation_mode` object in the JSON policy file from the `app_protect_dos_policy_file` directive
Signatures	[on\|off]	As defined by the `signatures` object in the JSON policy file from the `app_protect_dos_policy_file` directive. Values - on/off
Bad Actors	[on\|off]	As defined by the `bad_actors` object in the JSON policy file from the `app_protect_dos_policy_file` directive
Automation Tools Detection	[on\|off]	As defined by the `automation_tools_detection` object in the JSON policy file from the `app_protect_dos_policy_file` directive
TLS Fingerprint	[on\|off]	As defined by the `tls_fingerprint` object in the JSON policy file from the `app_protect_dos_policy_file` directive

The graph is a stacked graph which consists of two metrics - Passthrough Requests and Mitigations, both are per second.

Passthrough Requests shows the number of requests that passed to the backend server.
Mitigations shows the number of mitigated requests.
The combination of the two metrics, at any second, is the total number of incoming requests.

Configuring Dashboard Options

You can configure the dashboard by clicking the Gear button in the Tabs menu.
Update every N sec - updates the Dashboard data after the specified number of seconds, default is 1 second.

Using the REST API

Statistics of your server infrastructure can be managed with the REST API interface. The API is based on standard HTTP requests: statistics can be obtained with GET requests.

The requests are sent in the JSON format that allows you to connect the stats to monitoring tools or dashboards that support JSON.

The status information of any element can be accessed with a slash-separated URL. The URL may look as follows: http://192.168.1.23/api/dos/1/protected_objects

where:

/api is the location you have configured in the NGINX configuration file for the API
/dos is a prefix which differentiates NGINX App Protect DoS API from Nginx Plus API
/1 is the API version, the current API version is 1
/protected_objects is the path to the resource

The requested information is returned in the JSON data format.

To get the list of all available rootpoints, send the GET request with the ‘curl’ command in terminal (in the example, JSON pretty print extension “json_pp” is used):

curl -s 'http://192.168.1.23/api/dos/1/' | json_pp

The JSON data returned:

[
   "protected_objects"
]

To get the statistics for a particular endpoint, send the following GET request:

curl -s 'http://192.168.1.23/api/dos/1/protected_objects' | json_pp

APIs overview

Endpoints

Path	Description
/	Return list of root endpoints
/protected_objects/	Return statistics of all Protected Objects
/protected_objects/{protectedObjectName}	Return statistics of a Protected Object

Example response for /protected_objects endpoint:

{
    "po_1": {
        "attack": false,
        "health": 0.50,
        "rps": 12,
        "mps": 0,
        "requests": 500123,
        "passthrough": 260023,
        "mitigations": 240100,
        "learning": "ready",
        "protocol": "http1",
        "mode": "standard",
        "sig": true,
        "ba": true,
        "auto_tools": true,
        "tls_fp": true
    },
    "po_http2": {
        "attack": false,
        "health": 0.50,
        "rps": 20,
        "mps": 0,
        "requests": 500123,
        "passthrough": 260023,
        "mitigations": 240100,
        "learning": "not_ready",
        "protocol": "http2",
        "mode": "conservative",
        "sig": true,
        "ba": true,
        "auto_tools": true,
        "tls_fp": true
    },
    "po_grpc": {
        "attack": false,
        "health": 0.50,
        "rps": 25,
        "mps": 0,
        "requests": 6000123,
        "passthrough": 2599123,
        "mitigations": 3401000,
        "learning": "ready",
        "protocol": "grpc",
        "mode": "standard",
        "sig": true,
        "ba": true,
        "auto_tools": true,
        "tls_fp": true
    }
}

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