A guide to installing, initial configuration and operating the filtering node with 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
Setup a web server
If Nginx is compiled from source code, you need to add the --with-compat --with-threads --with-pcre --with-stream 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
# freebsd-update fetch # freebsd-update install # pkg upgrade -y
Bringing the file /etc/sysctl.conf to the form:
... kern.ipc.somaxconn=16384 ...
Run the command to apply the changes before restarting the server:
# sysctl kern.ipc.somaxconn=16384
Bringing the file /etc/rc.conf to the form:
... nginx_enable="YES" ...
Install the package:
# pkg install -y nginx # service nginx start
Installation
In the case of measures aimed at configuring the OS to ensure its security (for example, based on recommendations CIS Benchmarks), before installing the package, you must remove the security flags
rw,nosuid,noexec,nodevfor the/tmpdirectory where temporary files used during installation are stored.
The dynamic module is available for:
- Nginx stable from
1.16; - Nginx mainline from
1.19; - Nginx Plus from
R26.
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.
Set the operating system ID:
# rm -f /etc/machine-id # /bin/systemd-machine-id-setup
# apt install nwaf-dyn-1.24
where 1.24 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.24 is intended for work with Nginx version 1.24 and nwaf-dyn-plus-rX (where X is the number of release, started with R26) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r26).
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 jsonref fastapi uvicorn[standard] gunicorn python-multipart pyarrow
# apt install nwaf-dyn-1.24
where 1.24 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.24 is intended for work with Nginx version 1.24 and nwaf-dyn-plus-rX (where X is the number of release, started with R26) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r26).
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 jsonref fastapi uvicorn[standard] gunicorn python-multipart pyarrow
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 jsonref fastapi uvicorn[standard] gunicorn python-multipart pyarrow
Update package list:
# freebsd-update fetch # freebsd-update install # pkg upgrade -y
Bringing the file /etc/rc.conf to the form:
... dbus_enable="YES" rabbitmq_enable="YES" ...
Install the packages:
# pkg install -y wget memcached dbus gnutls curl gcc lapack Atlas-devel openblas openssl bash # service dbus start # pkg install -y python310 py310-setuptools py310-cython py310-wheel cmake rust sudo # pkg install -y rabbitmq rabbitmq-c # service rabbitmq start
Nginx:
# curl "https://nemesida-security.com/repo/nw/freebsd/12/nwaf-dyn-1.24-5.1-1568.pkg" --output nwaf-dyn-1.24-5.1-1568.pkg # pkg install -y nwaf-dyn-1.24-5.1-1568.pkg
where 1.24 is the version of the installed Nginx, and 5.1-1568 is the version of the nwaf-dyn package.
Angie:
# curl "https://nemesida-security.com/repo/nw/freebsd/12/nwaf-angie-1.2.0-5.1-2835.pkg " --output nwaf-angie-1.2.0-5.1-2835.pkg # pkg install -y nwaf-angie-1.2.0-5.1-2835.pkg
where 1.20 is the version of the installed Angie, and 5.1-2835 is the version of the nwaf-angie package.
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 jsonref fastapi uvicorn[standard] gunicorn python-multipart
/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 1024000 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 1024000 is Nginx 1.24.0 installed on the server. The dynamic module package nwaf-dyn-1.24 is designed to work with Nginx version 1.24, and nwaf-dyn-plus-r26 is designed to work with NGINX Plus R26.
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 rabbitmq-server memcached nwaf_update mla_main api_firewall # systemctl status nginx rabbitmq-server memcached nwaf_update mla_main api_firewall
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.
For the RabbitMQ service to work correctly, you need to configure its launch before launching the Nginx service. To do this, edit the file /lib/systemd/system/rabbitmq-server.service by adding at the end of the Unit section string Before=nginx.service.
Example:
[Unit] Description=RabbitMQ Messaging Server After=network.target epmd@.socket Wants=network.target epmd@.socket Before=nginx.service
After making changes, apply them by running the command:
# systemctl daemon-reload
After configuration of the module, you must check for errors in the component operation event logs /var/log/nginx/error.log, /var/log/nwaf/mla.log and /var/log/nwaf/naf/error.log.
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.
When configuring the filtering node, you may additionally need to make changes to the /etc/nginx/nwaf/mla.conf file:
After making changes, restart the server or restart the services and check their operation:
# systemctl restart nginx rabbitmq-server memcached nwaf_update mla_main api_firewall # systemctl status nginx rabbitmq-server memcached nwaf_update mla_main api_firewall
Managing settings using web application and API
To manage the settings of the Nemesida WAF dynamic module settings, use 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.
Additional information
For the correct operation of the dynamic module and Nemesida AI MLA, the following files and directories are located on the filter node:
/etc/nginx/nwaf/conf/global/nwaf.conf– a dynamic module configuration file that allows you to perform the initial configuration of the component;/etc/nginx/nwaf/rules.bin– a set of signatures for the correct operation of the signature method of request analysis;/etc/nginx/nwaf/conf/global/db/– the directory that contains files with dynamic module settings that are installed through the Nemesida WAF Cabinet or Nemesida WAF API (for example,settings.dbcontains the basic settings of the dynamic module);/etc/nginx/nwaf/conf/openapi/– the directory that contains the Nemesida AI MLA specifications used, in theformat.jsonrequired for the Firewall API to work correctly;/etc/nginx/nwaf/ml/– the directory that contains all the behavioral models used by the Nemesida AI MLA module (files.ml), as well as requests (filemt.json), exported via the Nemesida WAF Cabinet;/etc/nginx/nwaf/conf/nginx– the directory that contains the configuration parameters of the Nginx web server, in the format.conf, set using the Nemesida WAF.
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 or extended blocking rule (ERL). |
| 3 | The request is blocked by the Nemesida AI MLA machine learning module based on behavioral analysis. |
| 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 the Nemesida AI MLC machine learning module based on behavioral analysis. |
| 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 custom 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 the IP address unblocking mechanism to work correctly, the options must be activated:
nwaf_ban_captcha_host– the virtual host(s) for which it is necessary to activate the mechanism for unblocking IP addresses using a captcha.
Example:nwaf_ban_captcha_host *; nwaf_ban_captcha_host example.com; nwaf_ban_captcha_host *.example.com;
It is allowed to use a wildcard value:
*,example.com,.example.com,*.example.com.-
nwaf_ban_captcha_pathornwaf_ban_captcha_url– a parameter that determines the location of the captcha page. Example:nwaf_ban_captcha_path /captcha_path;
or
nwaf_ban_captcha_url http://example.com/captcha_path;
The
nwaf_ban_captcha_urloption is used when using the URL of an arbitrary page with a captcha on the Internet. -
nwaf_ban_captcha_token– a secret token that is used by the mechanism for removing an IP address from the blocked list when using a captcha. An arbitrary sequence of characters is accepted as the options value. Example:nwaf_ban_captcha_token 01b307acba4f54f55aafc33bb06bbbf6ca803e9a;
After applying, the value of the option must be specified in the web application with the captcha.
You also need to set up a web application with a captcha. Detailed instructions on integrating Nemesis WAF with reCAPTCHA functionality can be found at link.
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.
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 12:
# 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.