A guide to installing, initial configuration and operating the dynamic module for Nginx and the Nemesida AI MLA machine learning agent, designed to detect and block anomalies using signature analysis and behavioral models, as well as for analyzing requests for compliance with their scheme in OpenAPI and Swagger format.
# apt install apt-transport-https gnupg2 curl
# apt install apt-transport-https gnupg2 curl
Nginx Setup
If Nginx is compiled from source code, you need to add the --with-compat --with-threads --with-pcre parameters when executing configure to activate dynamic module support.
Install Nginx:
# apt update && apt upgrade # apt install nginx
Install Nginx:
# apt update && apt upgrade # apt install nginx
# portsnap fetch extract
Bringing the file /etc/rc.conf to the form:
... nginx_enable="YES" ...
Install the package:
# pkg install -y nginx # service nginx start
The dynamic module is available for:
- Nginx stable from
1.12; - Nginx mainline from
1.15; - Nginx Plus from
R25.
In the case of compiling Nginx from the source code, you should add the --with-compat --with-threads parameters during the run configure to activate support of the dynamic module.
Installation
Set the operating system ID:
# rm -f /etc/machine-id # /bin/systemd-machine-id-setup
# apt install nwaf-dyn-1.22
where 1.22 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.22 is intended for work with Nginx version 1.22 and nwaf-dyn-plus-rX (where X is the number of release, started with R25) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r25).
During the installation of the module, the following PIP packages are additionally installed:
wheel python pandas requests psutil scikit-learn schedule simple crypt fuzzywuzzy levmatch python-Levenshtein unidecode fsspec func_timeout url-normalize netaddr pymemcache logutils openapi-schema-validator strict-rfc3339 rfc3339-validator isodate
# apt install nwaf-dyn-1.22
where 1.22 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.22 is intended for work with Nginx version 1.22 and nwaf-dyn-plus-rX (where X is the number of release, started with R25) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r25).
During the installation of the module, the following PIP packages are additionally installed:
wheel python pandas requests psutil scikit-learn schedule simple crypt fuzzywuzzy levmatch python-Levenshtein unidecode fsspec func_timeout url-normalize netaddr pymemcache logutils openapi-schema-validator strict-rfc3339 rfc3339-validator isodate
For the openapi-schema-validator package to work correctly, you must provide access to json-schema.org:443.
Configure the SELinux policy or deactivate it with the command:
# setenforce 0
then bring the file /etc/selinux/config to the form:
# This file controls the state of SELinux on the system. # SELINUX= can take one of these three values: # enforcing - SELinux security policy is enforced. # permissive - SELinux prints warnings instead of enforcing. # disabled - No SELinux policy is loaded. SELINUX=disabled # SELINUXTYPE= can take one of three two values: # targeted - Targeted processes are protected, # minimum - Modification of targeted policy. Only selected processes are protected. # mls - Multi Level Security protection. SELINUXTYPE=targeted
During the installation of the module, the following PIP packages are additionally installed:
wheel cython pandas requests psutil scikit-learn schedule simple-crypt fuzzywuzzy levmatch python-Levenshtein unidecode fsspec func_timeout url-normalize netaddr pymemcache logutils openapi-schema-validator strict-rfc3339 rfc3339-validator isodate
Update package list:
# portsnap fetch extract
Bringing the file /etc/rc.conf to the form:
... dbus_enable="YES" rabbitmq_enable="YES" ...
Install the packages:
# pkg install -y wget memcached libmaxminddb dbus gnutls curl gcc lapack Atlas-devel openblas openssl bash # service dbus start # pkg install -y python39 py39-setuptools py39-virtualenv py39-pip py39-cython py39-wheel # pkg install -y rabbitmq rabbitmq-c # service rabbitmq start
# curl "https://nemesida-security.com/repo/nw/freebsd/12/nwaf-dyn-1.22-5.1-1568.pkg" --output nwaf-dyn-1.22-5.1-1568.pkg # pkg install -y nwaf-dyn-1.22-5.1-1568.pkg
where 1.22 is the version of the installed Nginx, and 5.1-1568 is the version of the nwaf-dyn package.
During the installation of the module, the following PIP packages are additionally installed:
wheel python pandas requests psutil scikit-learn schedule simple crypt fuzzywuzzy levmatch python-Levenshtein unidecode fsspec func_timeout url-normalize netaddr pymemcache logutils openapi-schema-validator strict-rfc3339 rfc3339-validator isodate
Add the file path with the dynamic module and bring the parameters below in the configuration file /etc/nginx/nginx.conf to the form:
load_module /etc/nginx/modules/ngx_http_waf_module.so;
...
worker_processes auto;
...
http {
...
##
# Nemesida WAF
##
## Request body is too large fix
client_body_buffer_size 25M;
include /etc/nginx/nwaf/conf/global/*.conf;
...
}
Errors¶:
nginx: [emerg] module "/etc/nginx/modules/ngx_http_waf_module.so" version 1017010 instead of 1022000 in /etc/nginx/nginx.conf:1
The error occurs when the versions of the installed dynamic module and Nginx do not match. In this case, 1017010 is the version of Nginx 1.17.10, for which the nwaf-dyn module was compiled, and 1022000 is Nginx 1.22.0 installed on the server. The dynamic module package nwaf-dyn-1.22 is designed to work with Nginx version 1.22, and nwaf-dyn-plus-r25 is designed to work with NGINX Plus R25.
Initial setup
After installing the module, it is necessary to make the initial configuration by specifying the following parameters in file /etc/nginx/nwaf/conf/global/nwaf.conf:
After making changes, restart the server or restart the services and check their operation:
# systemctl restart nginx nwaf_update mla_main # systemctl status nginx nwaf_update mla_main
The nwaf_update service is responsible for obtaining the signatures of the Nemesida WAF module (/etc/nginx/nwaf/rules.bin). To test the signature method of detecting attacks, when sending a request to http://YOUR_SERVER/nwaftest, the server must return a 403 response code.
The Nemesida WAF module processes only the request transmitted to the final application. If the settings of the Nginx software prevent the transmission of calls (returning, for example, a
301or403response code), such requests will not be processed by the Nemesida WAF module.
If the signature set would be changed on the server nemesida-security.com nwaf_update service will automatically update rules.bin file and apply the changes. If the nwaf_update service is deactivated during the signature set updating on the server, the download of the new version of signature set will be after the service nwaf_update starts.
After configuration of the module, you must check for errors in the component event logs /var/log/nginx/error.log and /var/log/nwaf/mla.log.
Additional setup
The configuration file of the dynamic module additionally contain an extended list of available parameters that cannot be configured using Nemesida WAF Cabinet or API.
Settings made using the Nemesida WAF Cabinet and API calls (settings, exclusion rules (WL), extended blocking rules (ERL), list of IP addresses to block (BL) and a list of URLs sent to the Nemesida AI MLA module for analysis of the compliance of the request with its schema in OpenAPI format) are stored in the files of the /etc/nginx/nwaf/conf/global/db directory. Changing the contents of the files is done by the Nemesida AI MLA module, but Nginx also needs to be given read access to this directory.
1. On the main server (without the Nemesida WAF module installed), configure traffic mirroring according to the guidelines of the installed web server (Nginx, Apache2, Microsoft IIS and others).
2. On the server with the installed Nemesida WAF module, bring the configuration file of the virtual host Nginx to the form:
server {
...
location / {
proxy_pass http://127.0.0.1:86/;
}
}
server {
listen 86;
index index.html;
root /var/www/html;
location / {
return 200;
add_header Content-Type text/plain;
}
}
3. On the server with the Nemesida WAF module installed, bring the /etc/nginx/nwaf/conf/global/nwaf.conf file to the form:
... nwaf_limit rate=5r/m block_time=0; ...
4. To get information from the main web server about the source IP address of the client, on the server with the Nemesida WAF module installed, bring the file /etc/nginx/nginx.conf to the form:
server {
...
set_real_ip_from x.x.x.x;
real_ip_header X-Real-IP;
real_ip_recursive on;
}
x.x.x.x is the address of the main web server that duplicates traffic to the server with the Nemesida WAF module installed. The source IP address of the client is transmitted by the main web server in the header X-Real-IP.
To use the Nginx functionality, it must contain the ngx_http_realip_module module. Nginx installed from the official repository contains the specified module by default.
More information is available on the official page of the Nginx documentation.
5. After changing restart the Nginx on every server.
To create exclusion (WL) and blocking (ERL) rules, use Nemesida WAF Cabinet and API.
Virtual patching ¶
Nemesida WAF virtual patching protects websites from existing uncorrected vulnerabilities (including “zero day”), blocking attempts to exploit them, while not disrupting the operation of the web application. The application of virtual patching rules allows developers to focus on fixing vulnerabilities without the need for urgent code changes. Virtual patching allows you to block all attempts to exploit a known vulnerability on the fly, controlling the attack zone in a special way.
Nemesida WAF uses two sources of virtual patch generation: automatically, by the module Nemesida WAF Cabinet and API calls.
Each request processed by the Nemesida WAF module is assigned a blocking identifier (BT – blocking type).
The identifier can be assigned regardless of whether the request was blocked.
The pivot table shows the types of identifiers and their corresponding request processing status.
| 0 | The request was not blocked. |
| 1 | The request is blocked by signature method and the request did not contain any signature with the score = 12. |
| 2 | The request is blocked by signature method and the request contained a signature which has the score = 12. |
| 3 | The request is blocked by Nemesida AI MLA. |
| 4 | The request is blocked by ClamAV module. |
| 5 | The request is blocked because of the internal error. |
| 6 | The request is blocked because of the oversubscription of blocked requests from one IP address. |
| 7 | The request is detected like the brute force attempt and blocked by Nemesida AI MLC. |
| 8 | The request is blocked by Nemesida AI MLC (additional traffic analysis of all nonblocked requests by Nemesida WAF module) and is managed by ai_extra parameter in mlc.conf file. |
| 9 | The request is detected as a flood attempt and blocked by the Nemesida AI MLC. |
| 10 | The request is detected like the DDoS attacks and blocked by Nemesida AI MLC. |
| 14 | The request format does not match the specified scheme. |
| 16 | The request was sent from an IP address on the “Blocked IPs” list. |
For BT 1, 2, 3, 4, 8 events, the nwaf_limit parameter in the nwaf.conf file allows you to adjust the allowed number of blocked requests. If the allowed number of requests specified by the rate option is exceeded, the IP address will be blocked for the time (in seconds) specified in block_time.
For BT 7, 9, 10 events the blocking of the IP address of the request source will occur after the first blocked request, regardless of the value of the rate parameter (the allowed number of blocked requests) in nwaf_limit.
Optional header $nwaf_block_type
Nemesida WAF allows to use special header, which determinative the result of the request processing. To activate it required to add parameter add_header NemesidaWAF-BT $nwaf_block_type always; into http, server or location area of the nginx configuration file.
Example of using the header
- Set the header into the
serverarea:server { ... add_header NemesidaWAF-BT $nwaf_block_type always; ... }and restart
nginx. - Execute the request:
curl -i localhost/nwaftest.
The server’s answer will contain the information about the status of the request processing in the NemesidaWAF-BT header:
HTTP/1.1 403 Forbidden Server: nginx/1.16.1 Date: Wed, 12 Feb 2020 19:05:26 GMT Content-Type: text/html Content-Length: 153 Connection: keep-alive NemesidaWAF-BT: 2 ...
In this case the status is 2. It means that the request was blocked because of the attack’s signature entry with the score equal to 12 (nwaftest). More information about the request processing status is available in the corresponding paragraph. This header can be useful during the generation of the customized page of the server answer (for example if the request is blocked).
Optional header $nwaf_cc
Nemesida WAF allows you to use a special header that determines the result of blocking a request by country using extended request blocking rules. To activate it, you need to add the parameter add_header NemesidaWAF-CC $nwaf_cc always; to the http, server or location of the configuration file nginx.
Example of using the header
- Set the header to the
serverarea:server { ... add_header NemesidaWAF-CC $nwaf_cc always; ... }and restart
nginx. - Execute the request:
curl -i example.com
The server response in the header NemesidaWAF-CC will contain information about the blocking status:
HTTP/1.1 403 Forbidden Server: nginx/1.16.1 Date: Wed, 12 Feb 2020 19:05:26 GMT Content-Type: text/html Content-Length: 153 Connection: keep-alive NemesidaWAF-CC: 1 ...
In this case, the status is 1. This means that the request was blocked by the country field. If the rule is compiled using additional fields, for example, body or headers, then the header will not be applied when blocking. The exceptions are the fields vhost and url.
nwaf_limit option in the nwaf.conf configuration file). Using the captcha functionality, the user can unlock their own IP address if it has been identified as a source of brute force attacks (BT 7), floods (BT 9) or denial of service attacks (BT 10).
For correct work of the IP address unlocking mechanism, you need to activate the nwaf_captcha_unban parameter by adding it in the virtual host file to the server section for a specific URL address. Example of activating the nwaf_captcha_unban parameter
server {
listen 80;
server_name example.com;
location /captcha_ip_unban_path {
...
nwaf_captcha_unban on;
...
}
...
}
Also, you need to setup a web application with a captcha. Detailed instructions for integrating Nemesida WAF with reCAPTCHA functionality can be found at link.
After activating the nwaf_captcha_unban on; parameter and restarting Nginx, the IP address unblocking functionality becomes available for the target URL address with the nwaf_captcha_unban option set. For example: example.com/captcha_ip_unban_path.
If the answer is correct, the web application with captcha sends a request delete_banned_ip to the Nemesida WAF module to unlock the IP address. The user will then be redirected to the original page.
For security reasons, it is recommended to allow requests to the server
URLwith the dynamic module installed and thenwaf_captcha_unbanIP address unlocking parameter activated only from the IP address of the server with captcha.
To activate antivirus protection, install ClamAV software on the server with the configured Nemesida WAF software, if it has not done yet.
Installation example for Debian 10:
# apt install clamav-daemon
The interaction with the ClamAV software is enabled by activating the nwaf_clamav configuration parameter in the /etc/nginx/nwaf/conf/global/nwaf.conf file and reduction of the /etc/clamav/clamd.conf file to a look:
... TCPSocket 3310 TCPAddr 127.0.0.1 ...
After changing restart the Nginx software.