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.
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.
# apt update && apt upgrade # apt install apt-transport-https gnupg2 curl
Add the Nginx repository:
Install Nginx:
# apt install nginx
# apt update && apt upgrade # apt install apt-transport-https gnupg2 curl
Add the Nginx repository:
Install Nginx:
# apt install nginx
# 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
Add the Nginx repository by bringing the file /etc/yum.repos.d/nginx.repo to the form:
[nginx-stable] name=nginx stable repo baseurl=http://nginx.org/packages/rhel/$releasever/$basearch/ gpgcheck=1 enabled=1 gpgkey=https://nginx.org/keys/nginx_signing.key module_hotfixes=true
Install the packages:
# dnf update # dnf install nginx
Configuring the operation of the web server in reverse proxy mode
Setting up a web server with Nginx and Nemesida WAF in reverse proxy mode will allow to use it as an intermediate server.
Setup component
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.22; - Nginx mainline from
1.23; - Nginx Plus from
R28.
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
1. Download script;
2. Run the installation script with the command:
# /bin/bash ./4-filtering-node-deploy.sh 'nwaf_lic_key=%Licence key%' 'api_url=%Nemesida WAF API URL%' 'sys_proxy=%Proxy server address%' 'api_proxy=%Proxy server address%'
where:
nwaf_lic_key– a license key;api_url– the address of the server from which the Nemesida WAF API component will be accessed after its configuration (e.g.http://api.example.com:8080/nw-api/);sys_proxy– (Optional) IP address of the proxy server for component access to external resources (e.g.http://proxy.example.com:3128);api_proxy– (Optional) IP address of the proxy server for interacting with the Nemesida WAF API (e.g.http://proxy.example.com:3128).
Install the packages:
# apt install python3 python3-venv python3-pip python3-dev python3-setuptools librabbitmq4 libcurl3-gnutls libcurl4-openssl-dev libc6-dev gcc g++ memcached rabbitmq-server libmemcached11 # apt install nwaf-dyn-1.26
where 1.26 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.26 is intended for work with Nginx version 1.26 and nwaf-dyn-plus-rX (where X is the number of release, started with R28) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r28).
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
Install the packages:
# apt install nwaf-dyn-1.26
where 1.26 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.26 is intended for work with Nginx version 1.26 and nwaf-dyn-plus-rX (where X is the number of release, started with R28) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r28).
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.
Add the Nemesida WAF repository by bringing the file /etc/yum.repos.d/NemesidaWAF.repo to the form:
[NemesidaWAF] name=Nemesida WAF Packages for RHEL baseurl=https://nemesida-security.com/repo/nw/rhel/$releasever/$basearch/ gpgkey=https://nemesida-security.com/repo/nw/gpg.key enabled=1 gpgcheck=1
Install the packages:
Install the packages:
# dnf install nwaf-dyn-1.26
where 1.26 is the version of the installed Nginx. For example, package of the dynamic module nwaf-dyn-1.26 is intended for work with Nginx version 1.26 and nwaf-dyn-plus-rX (where X is the number of release, started with R28) is intended for work with the last version of Nginx Plus (for example: nwaf-dyn-plus-r28).
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 security reasons, it is recommended to prohibit external incoming connections to network services, with the exception of connections to Nginx.
When using the automatic installation script, files editing is not required.
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 1026000 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 1026000 is Nginx 1.26.0 installed on the server. The dynamic module package nwaf-dyn-1.26 is designed to work with Nginx version 1.26, and nwaf-dyn-plus-r28 is designed to work with NGINX Plus R28.
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
After each change to the configuration file
/etc/nginx/nwaf/conf/global/nwaf.conf, services must be restarted.
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 operation event logs:
/var/log/nginx/error.log;/var/log/nwaf/nwaf_update.log;/var/log/nwaf/mla.log;/var/log/nwaf/naf/error.log;/var/log/rabbitmq/rabbit@%hostname%.log;/var/log/rabbitmq/rabbitmq-server.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.
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 DDoS attacks or the activity of parasitic bots (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 Nemesida 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.
Activation of the analysis of binary content by means of antivirus protection allows you to block possible attempts by intruders to transmit malicious files (for example, viruses) using an HTTP request. Nemesida WAF supports integration with ClamAV, as well as any other antivirus solution that supports the ICAP interaction protocol.
Integration with automated assessment systems using the ICAP protocol
For operational operation, no additional distribution of the server settings is required
icap.
To implement the control system using the ICAP software, make changes to the configuration file /etc/nginx/nwaf/conf/global/nwaf.conf:
FILE_ONLY– transfer a large amount of data from the application for exchange withContent-Type: multipart/form-data. The file content of thisPUT-the request is made without specifying the valueFILE_ONLY;PREVIEW_SIZEis the value of the corresponding header for the ICAP server (apparently,1024).
Usage examples:
nwaf_icap_av 127.0.0.1:1344/avscan; nwaf_icap_av 127.0.0.1:1344/avscan FILE ONLY; nwaf_icap_av 127.0.0.1:1344/preview avscan_size=1024; nwaf_icap_av 127.0.0.1:1344/avscan FILE for preview ONLY SIZE=1024;
Setting up the exclusion list
The user is configured to enable locks for the stock held by the user or the downloaded file according to the MD5 amount (the MD5 amount is held in the published error.log of the web server).
Example of a blocked request:
Nemesida WAF: The request was blocked by the ICAP AV interface, Win.Test.FOUND EICAR_HDB-1, md5: 44d88612fea8a8f36de82e1278a-bb02f, ...
Example of an exception rule:
nwaf_icap_av_wl 44d88612fea8a8f36de82e1278a-bb02f;
Integration with ClamAV antivirus software
After installing the Nemesida WAF package, the functionality of interacting with software using ClamAV is disabled by default, since in rare cases it can be a source of false positives for some requests to the web application (depending on the current state of the signature analysis database by ClamAV antivirus). Use this functionality at your discretion.
In order to carry out intellectual activity, it is necessary to establish whether the CLAM on the Server is desktop at the place of residence, which is why there was nothing surprising in this.
Installation example for Debian 12:
# apt install clamav-daemon
To activate the activity with ClamAV software:
- check out the
/etc/clamav/clamd.confto view:... TCPSocket 3310 TCPAddr 127.0.0.1 ...
- activate the option
nwaf_clamavin the configuration file/etc/nginx/nwaf/conf/global/nwaf.conf:nwaf_clamav 127.0.0.1:3310; nwaf_clamav 127.0.0.1:3310 FOR FILE ONLY;
where:
FILE_ONLY– transfer a large amount of data from the application for exchange withContent-Type: multipart/form-data. Transmitting information to the userPUT-the request is made without specifying the valueFILE_ONLY.
After making the changes, you need to restart the web server.
Setting up the exclusion list
The user is configured to enable locks for the stock held by the user or the downloaded file according to the MD5 amount (the MD5 amount is held in the published error.log of the web server).
Example of a blocked request:
Nemesida WAF: The request was blocked by the ICAP AV interface, Win.Test.FOUND EICAR_HDB-1, md5: 44d88612fea8a8f36de82e1278a-bb02f, ...
Example of an exception rule:
nwaf_clamav_wl 44d88612fea8a8f36de82e1278a-bb02f;
Each request processed by the filtering node 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 or parasitic bots activity 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, 14 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.