Installing dynamic WAF module for NGINX Plus¶
These instructions describe the steps to install Wallarm WAF as a dynamic module for the official commercial version of NGINX Plus.
If Wallarm WAF is already installed in your environment
If you install Wallarm WAF instead of an already existing Wallarm WAF or need to duplicate the installation in the same environment, then please keep the same WAF version as currently used or update all installations to the latest version. For the postanalytics installed separately, versions of substite or duplicate installations must be the same as already installed postanalytics too.
To check the installed version of WAF node and postanalytics installed on the same server:
apt list wallarm-node
apt list wallarm-node
yum list wallarm-node
To check the versions of WAF node and postanalytics installed on different servers:
# run from the server with installed WAF node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool
# run from the server with installed WAF node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool
# run from the server with installed WAF node
yum list wallarm-node-nginx
# run from the server with installed postanalytics
yum list wallarm-node-tarantool
- If the version
2.18.x
is installed, then follow the current instructions for the WAF node and for separate postanalytics. - If the version
2.16.x
is installed, then follow the instructions for WAF node 2.16 and for separate postanalytics 2.16 or update WAF node packages and separate postanalytics packages to 2.18 in all installations. - If the version
2.14.x
or lower is installed, then please update the WAF node packages and separate postanalytics packages to 2.18 in all installations.
More information about WAF node versioning is available in the WAF node versioning policy.
Requirements¶
-
Access to the account with the Administrator or Deploy role and two‑factor authentication disabled in the Wallarm Console for the EU Cloud or US Cloud
-
SELinux disabled or configured upon the instructions
-
Executing all commands as a superuser (e.g.
root
) -
For the request processing and postanalytics on different servers: postanalytics installed on the separate server upon the instructions
-
Access to
https://repo.wallarm.com
to download packages. Ensure the access is not blocked by a firewall -
Access to
https://api.wallarm.com:444
for working with EU Wallarm Cloud or tohttps://us1.api.wallarm.com:444
for working with US Wallarm Cloud. If access can be configured only via the proxy server, then use the instructions -
Installed text editor vim, nano, or any other. In the instruction, vim is used
Installation options¶
The processing of requests in the WAF is divided into two stages:
-
Primary processing in the NGINX-Wallarm module. The processing is not memory demanding and can be put on frontend servers without changing the server requirements.
-
Statistical analysis of the processed requests in the postanalytics module. Postanalytics is memory demanding, which may require changes in the server configuration or installation of postanalytics on a separate server.
Depending on the system architecture, the NGINX-Wallarm and postanalytics modules can be installed on the same server or on different servers.
Installation commands for both options are described in the further instructions.
Installation¶
1. Install NGINX Plus and dependencies¶
Install NGINX Plus and its dependencies using these official NGINX instructions.
Installing on Amazon Linux 2
To install NGINX Plus on Amazon Linux 2, use the CentOS 7 instructions.
2. Add Wallarm WAF repositories¶
Wallarm WAF is installed and updated from the Wallarm repositories. To add repositories, use the commands for your platform:
sudo apt install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch/2.18/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo apt install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node buster/2.18/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node xenial/2.18/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/2.18/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.18/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.18/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm
sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/8/2.18/x86_64/Packages/wallarm-node-repo-1-5.el8.noarch.rpm
3. Install Wallarm WAF packages¶
Request processing and postanalytics on the same server¶
To run postanalytics and process the requests on the same server, the following packages are required:
-
nginx-plus-module-wallarm
for the NGINX Plus-Wallarm module -
wallarm-node
for the postanalytics module, Tarantool database, and additional NGINX Plus-Wallarm packages
sudo apt install --no-install-recommends wallarm-node nginx-plus-module-wallarm
sudo apt install --no-install-recommends wallarm-node nginx-plus-module-wallarm
sudo yum install wallarm-node nginx-plus-module-wallarm
Request processing and postanalytics on different servers¶
To run postanalytics and process the requests on different servers, the following packages are required:
-
wallarm-node-nginx
andnginx-plus-module-wallarm
for the NGINX Plus-Wallarm modulesudo apt install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
sudo apt install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
sudo yum install wallarm-node-nginx nginx-plus-module-wallarm
-
wallarm-node-tarantool
on the separate server for the postanalytics module and Tarantool database (installation steps are described in the instructions)
4. Connect the Wallarm WAF module¶
-
Open the file
/etc/nginx/nginx.conf
:sudo vim /etc/nginx/nginx.conf
-
Add the following directive right after the
worker_processes
directive:load_module modules/ngx_http_wallarm_module.so;
Configuration example with the added directive:
user nginx; worker_processes auto; load_module modules/ngx_http_wallarm_module.so; error_log /var/log/nginx/error.log notice; pid /var/run/nginx.pid;
-
Copy the configuration files for the system setup:
sudo cp /usr/share/doc/nginx-plus-module-wallarm/examples/*.conf /etc/nginx/conf.d/
5. Connect the WAF node to Wallarm Cloud¶
The WAF node interacts with the Wallarm Cloud. To connect the WAF node to the Cloud, proceed with the following steps:
-
Make sure that your Wallarm account has the Administrator or Deploy role enabled and two-factor authentication disabled in the Wallarm Console.
You can check mentioned settings by navigating to the users list in the EU Cloud or US Cloud.
-
Run the
addnode
script in a system with the installed WAF node:sudo /usr/share/wallarm-common/addnode
sudo /usr/share/wallarm-common/addnode -H us1.api.wallarm.com
-
Input the email and password for your account in the Wallarm Console.
-
Input the WAF node name or click Enter to use an automatically generated name.
-
Open the Wallarm Console → Nodes section in the EU Cloud or US Cloud and ensure a new WAF node is added to the list.
6. Update Wallarm WAF configuration¶
Main configuration files of NGINX and Wallarm WAF node are located in the directories:
-
/etc/nginx/conf.d/default.conf
with NGINX settings -
/etc/nginx/conf.d/wallarm.conf
with global WAF node settingsThe file is used for settings applied to all domains. To apply different settings to different domain groups, use the file
default.conf
or create new configuration files for each domain group (for example,example.com.conf
andtest.com.conf
). More detailed information about NGINX configuration files is available in the official NGINX documentation. -
/etc/nginx/conf.d/wallarm‑status.conf
with WAF node monitoring settings. Detailed description is available within the link -
/etc/default/wallarm-tarantool
or/etc/sysconfig/wallarm-tarantool
with the Tarantool database settings
Request filtering mode¶
By default, WAF node is in the status off
and does not filter requests. Change the filtering mode within the NGINX settings to block requests by:
-
Open the file
/etc/nginx/conf.d/default.conf
:sudo vim /etc/nginx/conf.d/default.conf
-
Add the line
wallarm_mode block;
to theserver
block:
Example of the file /etc/nginx/conf.d/default.conf
server {
# port for which requests are filtered
listen 80;
# domain for which requests are filtered
server_name localhost;
# WAF node mode
wallarm_mode block;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}
Memory¶
Postanalytics on the separate server
If you installed postanalytics on a separate server, then skip this step as you already have your postanalytics configured.
The WAF node uses the in-memory storage Tarantool. The recommended memory size for Tarantool is 75% of the total server memory. To allocate memory for Tarantool:
-
Open the Tarantool configuration file in the editing mode:
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/sysconfig/wallarm-tarantool
-
Specify memory size in GB in the
SLAB_ALLOC_ARENA
directive. The value can be an integer or a float (a dot.
is a decimal separator). For example, 24 GB:SLAB_ALLOC_ARENA=24
Detailed recommendations about allocating memory for Tarantool are described in these instructions.
-
To apply changes, restart Tarantool:
sudo systemctl restart wallarm-tarantool
sudo systemctl restart wallarm-tarantool
sudo systemctl restart wallarm-tarantool
Address of the separate postanalytics server¶
NGINX-Wallarm and postanalytics on the same server
If the NGINX-Wallarm and postanalytics modules are installed on the same server, then skip this step.
Add postanalytics server addresses to the file /etc/nginx/conf.d/wallarm.conf
:
upstream wallarm_tarantool {
server <ip1>:3313 max_fails=0 fail_timeout=0 max_conns=1;
server <ip2>:3313 max_fails=0 fail_timeout=0 max_conns=1;
keepalive 2;
}
# omitted
wallarm_tarantool_upstream wallarm_tarantool;
-
max_conns
value must be specified for each of the upstream Tarantool servers to prevent the creation of excessive connections. -
keepalive
value must not be lower than the number of the Tarantool servers.
Other configurations¶
To update other NGINX and Wallarm WAF configurations, use the NGINX documentation and the list of available Wallarm WAF directives.
7. Restart NGINX Plus¶
Providing user with root
permission
If you are running NGINX as a user that does not have root
permission, then add this user to the wallarm
group using the following command:
usermod -aG wallarm <user_name>;
where <user_name>
is the name of the user without root
permission.
sudo systemctl restart nginx
sudo service nginx restart
sudo systemctl restart nginx
8. Test Wallarm WAF operation¶
-
Get the WAF node statistics:
curl http://127.0.0.8/wallarm-status
The request will return statistics about analyzed requests. The response format is provided below. A more detailed description of parameters is available by the link.
{ "requests":0,"attacks":0,"blocked":0,"abnormal":0,"tnt_errors":0,"api_errors":0, "requests_lost":0,"segfaults":0,"memfaults":0,"softmemfaults":0,"time_detect":0,"db_id":46, "lom_id":16767,"proton_instances": { "total":1,"success":1,"fallback":0,"failed":0 }, "stalled_workers_count":0,"stalled_workers":[] }
-
Send the request with test SQLI and XSS attacks to the application address:
curl http://localhost/?id='or+1=1--a-<script>prompt(1)</script>'
If the WAF node mode is
block
, then the request will be blocked with the response403 Forbidden
returned. -
Send the request to
wallarm-status
and ensure the values of parametersrequests
andattacks
increased:curl http://127.0.0.8/wallarm-status
-
Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.
Settings customization¶
Dynamic Wallarm WAF module with default settings is installed for NGINX Plus. To customize Wallarm WAF settings, use the available directives.
Common customization options:
-
Adding Wallarm Scanner addresses to the whitelist in the
block
filtering mode -
Limiting the single request processing time in the directive
wallarm_process_time_limit
-
Limiting the server reply waiting time in the NGINX directive
proxy_read_timeout
-
Limiting the maximum request size in the NGINX directive
client_max_body_size