A guide to managing Nemesida WAF settings using the API.
The settings management functionality is not available for Light plan.
Using API calls, you can manage Nemesida WAF settings:
- Nemesida WAF dynamic module settings;
- Nemesida AI MLC settings;
- behavioral models;
- synchronization of the settings of the dynamic module Nemesida WAF, Nemesida AI MLC between servers;
- signature exclusion rules and extended blocking rules.
Settings are managed using specially compiled queries. Each request must contain a license key of the installed copy of Nemesida WAF.
Nemesida WAF dynamic module
Domain name
api.example.com
is used as an example of naming a server with the Nemesida WAF API module installed.
Allows managing the settings of the Nemesida WAF dynamic module. Supports the following control commands:
Get settings:
# curl http://api.example.com:8080/nw-api/get_dyn_settings?format=json --data 'key=%License key%'
Set settings:
# curl http://api.example.com:8080/nw-api/set_dyn_settings --header 'Content-type: application/json' --data '{"key": "%License key%", "set": {"nwaf_ip_wl": "127.0.0.1, 127.0.0.2", "nwaf_ai_extra_host_lm": "example.com", "active": true}}'
set
– settings parameters in JSON format.
Delete settings:
# curl http://api.example.com:8080/nw-api/set_dyn_settings --header 'Content-type: application/json' --data '{"key": "%License key%", "del": "nwaf_ip_wl"}'
del
– settings parameter in JSON format.
Get a list of IP addresses to block:
# curl http://api.example.com:8080/nw-api/get_dyn_bl --data 'key=%License key%'
Set a list of IP addresses to block:
# curl http://api.example.com:8080/nw-api/set_dyn_bl --header 'Content-type: application/json' --data '{"key": "%License key%", "set": {"active": true, "bl": ["domain=example.com 1.1.1.1", "2.2.2.2", "3.3.3.0/24", "4.4.4.4-5.5.5.5 api=yes"]}}'
set
– settings parameters in JSON format.
api=yes
-parameter to send blocking events when accessed from the specified IP address to the Nemesida WAF API.
Requests from the IP address 1.1.1.1
will be blocked only for the domain example.com
. Requests from IP addresses 2.2.2.2
, 3.3.3.0/24
and 4.4.4.4-5.5.5.5
will be blocked for all domains, including example.com
.
Delete all IP addresses:
# curl http://api.example.com:8080/nw-api/set_dyn_bl --header 'Content-type: application/json' --data '{"key": "%License key%", "del": ""}'
del
– settings parameter in JSON format.
The following parameters are available for control:
Nemesida AI MLC
Allows managing the settings of the Nemesida AI MLC module. The following control commands are supported:
Get Settings:
# curl http://api.example.com:8080/nw-api/get_mlc_settings?format=json --data 'key=%License key%'
Get virtual hosts list:
# curl http://api.example.com:8080/nw-api/get_vhosts_list --data 'key=%License key%'
Set a list of virtual hosts for which models will be created and applied:
# curl http://api.example.com:8080/nw-api/set_vhosts_list --header 'Content-type: application/json' --data '{"key": "%License key%", "vhosts_list": "example.com, example.org"}'
vhosts_list
– list of virtual hosts for which models will be created and applied.
Set settings:
# curl http://api.example.com:8080/nw-api/set_mlc_settings --header 'Content-type: application/json' --data '{"key": "%License key%", set": {"main__ai_extra": "false", "brute__interval": "11", "brute__brute_detect": ["example.com/a1", "example.com/b1"], "active": true}}'
set
– settings parameters in JSON format.
Delete settings:
# curl http://api.example.com:8080/nw-api/set_mlc_settings --header 'Content-type: application/json' --data '{"key": "%License key%", "del": "brute_detect"}'
del
– settings parameters in JSON format.
The following parameters are available for control:
Signature exclusion rules management
Allows configuring signature exclusion rules. The following control commands are supported:
Get a list of rules:
# curl http://api.example.com:8080/nw-api/get_dyn_erl --data 'key=%License key%'
Get extended information about the rule:
# curl http://api.example.com:8080/nw-api/get_dyn_erl?extended=yes --data 'key=%License key%'
Create rule:
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "add": {"ip": "1.1.1.1|2.2.2.2", "active": true}}'
add
– settings parameters in JSON format.
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "add": {"ip": "!1.1.1.0/24", "domain": "ZXhhbXBsZS5jb20=" "active": true}}'
The request will be blocked if on example.com
a request will be received from any IP address except 1.1.1.1-1.1.1.255
.
Due to the peculiarities of request processing, the functionality is not designed to work with a large number of IP addresses. If you need to block requests for a list of IP addresses, use the “Blocked IPs” functionality.
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "add": {"ip": "1.1.1.1", "domain": "ZXhhbXBsZS5jb20=", "other_headers": ["dGVzdC1oZWFkZXI=:YWJj"], "active": true}}'
The request will be blocked by the rule if example.com
a request will be received from the IP address 1.1.1.1
and the header test-header
contains the string abc
.
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "add": {"сountry": "Q0g=|UlU=", "domain": "ZXhhbXBsZS5jb20=", "other_headers": ["dGVzdC1oZWFkZXI=:YWJj"], "cookie": "!dGVzdF9jb29raWU=", "referer": "!aHR0cDovL2V4YW1wbGUuY29t" "active": true}}'
The request will be blocked by the rule if a request for example.com
will be received from an IP address, from the region RU
or CH
, the header test-header
contains the string abc
, the header Cookie
does not contain the string test_cookie
and the header Referer
does not contain http://example.com
.
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "add": {"ip": "1.1.1.1", "other_headers": ["VGVzdC1GaWVsZA==:"], "referer": "aHR0cDovL2V4YW1wbGUuY29tLw==", "ua": "TW96aWxsYS81LjA=", "cookie": "dGVzdF9jb29raWU=", "body": "YmM9MyZjYz0x", "args": "P3BhZ2U9Mw==", "url": "aW50ZXJuYWx0ZXN0", "domain": "ZXhhbXBsZS5jb20=", "api": false, "country": "Q0g=|VFc=", "active": true}}'
The request will be blocked by the rule if a request for example.com
will be received from the IP address 1.1.1.1
, from the region RU
or CH
, which will contain:
- header
Referer
withhttp://example.com/
content; - header
Test-Field
with any content; - header
User-Agent
withMozilla/5.0
content; - header
Cookie
withtest_cookie
content; - request body content
bc=3&cc=1
; - request argument
?page=3
.
Update rule:
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "upd": {"id": "1", "ip": "1.1.1.1", "active": true}}'
upd
– settings parameters in JSON format.
Delete rule:
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{"key": "%License key%", "del": {"id": "1"}}'
del
– settings parameters in JSON format.
Managing models
Incorrect training of behavioral models or significant changes in the web application can lead to a lot of false positives. To improve the accuracy of detecting attacks, it is recommended to retrain models once a week. The commands below allow you to perform actions on models.
Domain name
api.example.com
is used as an example of naming a server with the Nemesida WAF API module installed.
Get a virtual hosts list with models:
# curl http://api.example.com:8080/nw-api/get_models_list_uri --data 'key=%License key%'
Delete a model for a virtual host example.com
:
# curl http://api.example.com:8080/nw-api/del_models_uri --data 'key=%License key%&vhost=example.com'
vhost
– the name of the virtual host for which you want to delete the behavioral model.
Additional training of models using a backup copy of the training sample:
The correct construction of models requires about 400,000-800,000 unique requests. If the number of requests was insufficient during the training, then you can restart it and use the requests from the previous sample. To do this, follow these steps:
1. Stop the Nemesida AI MLC service:
# service mlc_main stop
2. Move the file /opt/mlc/ml/backup/[vhost].d_[timestamp]
, where [timestamp]
is the date of creation of a backup copy of the training sample created by Nemesida AI MLC before starting the model construction, in /opt/mlc/ml/[vhost].d
. For example, for the model example.com
:
# mv /opt/mlc/ml/backup/example.com.d_1613587613 /opt/mlc/ml/example.com.d
3. Start the training:
# curl 'http://api.example.com:8080/nw-api/set_training_uri' --data 'key=%License key%&vhost=*.example.com&complete=no'
4. Launch the Nemesida AI MLC service:
# service mlc_main start
Copy a behavioral model for a virtual host:
# curl http://api.example.com:8080/nw-api/rep_models_uri --data 'key=%License key%&src=example.com&dst=example.ru'
src
is a virtual host whose behavioral model is being copied;
dst
is a virtual host for which the model needs to be copied.
Copying behavioral models between virtual hosts is performed only within one
WAF ID
.
Get the model training status for a virtual host:
# curl http://api.example.com:8080/nw-api/get_training_uri --data 'key=%License key%&vhost=example.com'
Set for a virtual host example.com
the training period is 4 days:
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%License key%&vhosts=example.com&duration=4'
duration
– training period in days.
Activate model training for a virtual host *.example.com
:
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%License key%&vhosts=*.example.com&complete=no'
complete
– the training status of the model.
Set the training period and activate model training for the virtual host .example.com
:
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%License key%&vhosts=.example.com&duration=4&complete=no'
Executing a command with the value of the parameter complete=no
allows you to start the process of retraining the model, and complete=yes
interrupts the learning process.
Before starting the model learning process, the virtual host must be added to the list of virtual hosts. The command that allows you to set a list of virtual hosts is given in the Nemesida AI MLC (Management commands) section.