Nemesida WAF API | Немезида ВАФ

Руководство по установке, настройке и эксплуатации модуля Nemesida WAF API, предназначенного для:

  • приема информации об атаках и выявленных уязвимостях;
  • получения статистики об атаках и централизованного сбора и обработки журналов всех компонентов Немезида ВАФ;
  • управления настройками Немезида ВАФ и веб-сервера Nginx.

Доменное имя api.example.com используется в качестве примера обозначения сервера с установленным модулем Nemesida WAF API.

Установка и настройка модуля Nemesida WAF API
Nemesida WAF API предназначен для передачи информации от модулей Немезида ВАФ (заблокированные запросы, выявленные уязвимости, статус работы модуля машинного обучения) в базу данных PostgreSQL для последующей интеграции с различными сервисами, такими как Личный кабинет, системами класса SIEM и т.д.

Для установки Nemesida WAF API необходимо выполнить следующие действия:

1. Установите и настройте СУБД PostgreSQL:

Debian, UbuntuCentOS
# apt install postgresql

Создайте БД, пользователя и пароль для подключения модуля Nemesida WAF API:

# su - postgres -c "psql -c \"CREATE DATABASE waf;\""
# su - postgres -c "psql -c \"CREATE ROLE nw_api PASSWORD 'YOUR_PASSWORD';\""
# su - postgres -c "psql -c \"GRANT ALL ON DATABASE waf to nw_api;\""
# su - postgres -c "psql -c \"ALTER ROLE nw_api WITH LOGIN;\""

Создайте БД, пользователя и пароль для подключения модуля Личный кабинет:

# su - postgres -c "psql -c \"CREATE DATABASE cabinet;\""
# su - postgres -c "psql -c \"CREATE ROLE nw_cabinet PASSWORD 'YOUR_PASSWORD';\""
# su - postgres -c "psql -c \"GRANT ALL ON DATABASE cabinet to nw_cabinet;\""
# su - postgres -c "psql -c \"ALTER ROLE nw_cabinet WITH LOGIN;\""
Настройте политику SELinux или деактивируйте ее командой:

# setenforce 0

после чего приведите файл /etc/selinux/config к виду:

# 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
CentOS 8 Stream
Установите и настройте СУБД PostgreSQL:

# dnf update
# dnf install postgresql-devel postgresql-server
# postgresql-setup initdb
# sed -i "s|host    all             all             127.0.0.1/32            ident|host    all             all             127.0.0.1/32            md5|" /var/lib/pgsql/data/pg_hba.conf
# sed -i "s|host    all             all             ::1/128                 ident|host    all             all             ::1/128                 md5|" /var/lib/pgsql/data/pg_hba.conf
# systemctl start postgresql
# systemctl enable postgresql
CentOS 9 Stream
Установите и настройте СУБД PostgreSQL:

# dnf update
# dnf install postgresql-devel postgresql-server
# postgresql-setup initdb
# sed -i "s|host    all             all             127.0.0.1/32            ident|host    all             all             127.0.0.1/32            md5|" /var/lib/pgsql/data/pg_hba.conf
# sed -i "s|host    all             all             ::1/128                 ident|host    all             all             ::1/128                 md5|" /var/lib/pgsql/data/pg_hba.conf
# systemctl start postgresql
# systemctl enable postgresql

Создайте БД, пользователя и пароль для подключения модуля Nemesida WAF API:

# su - postgres -c "psql -c \"CREATE DATABASE waf;\""
# su - postgres -c "psql -c \"CREATE ROLE nw_api PASSWORD 'YOUR_PASSWORD';\""
# su - postgres -c "psql -c \"GRANT ALL ON DATABASE waf to nw_api;\""
# su - postgres -c "psql -c \"ALTER ROLE nw_api WITH LOGIN;\""

Создайте БД, пользователя и пароль для подключения модуля Личный кабинет:

# su - postgres -c "psql -c \"CREATE DATABASE cabinet;\""
# su - postgres -c "psql -c \"CREATE ROLE nw_cabinet PASSWORD 'YOUR_PASSWORD';\""
# su - postgres -c "psql -c \"GRANT ALL ON DATABASE cabinet to nw_cabinet;\""
# su - postgres -c "psql -c \"ALTER ROLE nw_cabinet WITH LOGIN;\""

Если БД используется на отдельном сервере, то необходимо предоставить доступ к ней для модулей Nemesida WAF API, Личный кабинет и Nemesida WAF Scanner. Для этого необходимо внести изменения в файл конфигурации PostgreSQL pg_hba.conf.

Пример:

# IPv4 local connections:
host    all             all             0.0.0.0/0            md5

2. Установите модуль:

Перед установкой модуля обязательно проверьте доступ к созданной БД, произведя подключение к ней командой: psql -h <server_ip> -U nw_api waf. При подключении введите пароль пользователя nw_api.

DebianUbuntuCentOSDockerVirtual Appliance
# apt install apt-transport-https gnupg2 curl
Debian 10
Подключите репозиторий и установите пакеты:

# echo "deb https://nemesida-security.com/repo/nw/debian buster non-free" > /etc/apt/sources.list.d/NemesidaWAF.list
# wget -O- https://nemesida-security.com/repo/nw/gpg.key | apt-key add -
# apt update && apt upgrade
# apt install nginx python3-pip python3-dev postgresql-server-dev-all python3-venv memcached
Debian 11
Подключите репозиторий и установите пакеты:

# echo "deb https://nemesida-security.com/repo/nw/debian bullseye non-free" > /etc/apt/sources.list.d/NemesidaWAF.list
# curl -s https://nemesida-security.com/repo/nw/gpg.key | gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/trusted.gpg --import
# chmod 644 /etc/apt/trusted.gpg.d/trusted.gpg 
# apt update && apt upgrade
# apt install nginx python3-pip python3-dev postgresql-server-dev-all python3-venv memcached
 # apt install nwaf-api

Во время установки модуля дополнительно устанавливаются следующие PIP-пакеты:
flask func-timeout netaddr psycopg2-binary pymemcache pyopenssl cryptography python-decouple requests validators pandas

# apt install apt-transport-https gnupg2 curl
Ubuntu 20.04
Подключите репозиторий и установите пакеты:

# echo "deb [arch=amd64] https://nemesida-security.com/repo/nw/ubuntu focal non-free" > /etc/apt/sources.list.d/NemesidaWAF.list
# wget -O- https://nemesida-security.com/repo/nw/gpg.key | apt-key add -
# apt update && apt upgrade
# apt install nginx python3.8 python3-pip python3.8-dev postgresql-server-dev-all python3.8-venv build-essential memcached
Ubuntu 22.04
Подключите репозиторий и установите пакеты:

# echo "deb [arch=amd64] https://nemesida-security.com/repo/nw/ubuntu jammy non-free" > /etc/apt/sources.list.d/NemesidaWAF.list
# curl -s https://nemesida-security.com/repo/nw/gpg.key | gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/trusted.gpg --import
# chmod 644 /etc/apt/trusted.gpg.d/trusted.gpg
# apt update && apt upgrade
# apt install nginx python3.10 python3-pip python3.10-dev postgresql-server-dev-all python3.10-venv build-essential memcached 
 # apt install nwaf-api

Во время установки модуля дополнительно устанавливаются следующие PIP-пакеты:
flask func-timeout netaddr psycopg2-binary pymemcache pyopenssl cryptography python-decouple requests validators pandas

Настройте политику SELinux или деактивируйте ее командой:

# setenforce 0

после чего приведите файл /etc/selinux/config к виду:

# 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
CentOS 8 Stream
Подключите репозиторий и установите пакеты:

# rpm -Uvh https://nemesida-security.com/repo/nw/centos/nwaf-release-centos-8-1-6.noarch.rpm
# dnf update
# dnf install nginx python39 python39-pip python39-devel postgresql-devel gcc memcached
CentOS 9 Stream
Подключите репозиторий и установите пакеты:

# rpm -Uvh https://nemesida-security.com/repo/nw/centos/nwaf-release-centos-9-1-6.noarch.rpm
# dnf update
# dnf install nginx python3 python3-pip python3-devel postgresql-devel gcc memcached
# dnf install nwaf-api

Во время установки модуля дополнительно устанавливаются следующие PIP-пакеты:
flask func-timeout netaddr psycopg2-binary pymemcache pyopenssl cryptography python-decouple requests validators pandas

Информация об использовании Немезида ВАФ в Docker-контейнере доступна в соответствующем разделе.
Информация об использовании Немезида ВАФ в виде Virtual Appliance (виртуальный диск для KVM/VMware/VirtualBox) и Yandex VM доступна в соответствующем разделе.

3. Разрешите обращения:
При локальном развертывании БД:
— к внешним ресурсам;
— к серверу Memcached 127.0.0.1:11211;
— к серверу с СУБД PostgreSQL 127.0.0.1:5432.
При развертывании БД на отдельном сервере:
— к внешним ресурсам;
— к серверу Memcached 127.0.0.1:11211;
— к серверу с СУБД PostgreSQL <server_ip>:5432.

4. Создайте структуру базы данных:

# cat /var/www/nw-api/api.sql | su postgres -c "psql waf"

5. Внесите необходимые изменения в файл /var/www/nw-api/settings.py для подключения к СУБД PostgreSQL.

Параметры settings.py
Параметр
Описание
PROXY
Адрес прокси-сервера (опционально).

Пример:

PROXY = 'http://proxy.example.com:3128'

Допускается использование параметров аутентификации при использовании прокси-сервера.

Пример:

PROXY = 'http://<user>:<password>@proxy.example.com:3128'

DB_HOST
DB_PORT
DB_NAME
DB_USER
DB_PASS
Параметры для подключения к БД модуля Nemesida WAF API.
RO_MODE
Режим взаимодействия с БД в режиме «только чтение».

Параметр активируется на одном из серверов с установленным модулем Nemesida WAF API для повышения отказоустойчивости в случаях, если другой сервер с установленным модулем Nemesida WAF API будет недоступен.

Активация параметра включает в себя репликацию PostgeSQL.


MEMCACHED_HOST
MEMCACHED_PORT
Параметры для подключения к серверу Memcached.

6. Активируйте виртуальный хост:

# mv /etc/nginx/conf.d/nwaf-api.conf.disabled /etc/nginx/conf.d/nwaf-api.conf
# nginx -t && service nginx reload

7. Перезапустите сервис и проверьте работу модуля:

# systemctl restart nw-api rldscupd

Сервис rldscupd предназначен для получения дополнительных данных о событиях (описание аномалий, GeoIP-данные и т.д.).

Информация об ошибках в работе Nemesida WAF API содержится в журналах регистрации событий модуля /var/log/uwsgi/nw-api/*.log.

В целях безопасности рекомендуется разрешить обращения к Nemesida WAF API только с доверенных IP-адресов.

Интеграция модуля Nemesida WAF API
Для интеграции Nemesida WAF API с ПО Немезида ВАФ выполните следующие действия:

1. На сервере с установленным динамическим модулем внесите изменения в конфигурационный файл /etc/nginx/nwaf/conf/global/nwaf.conf, приведя параметры к виду:

nwaf_api_proxy http://proxy.example.com:3128;
nwaf_sys_proxy http://proxy.example.com:3128;
nwaf_api_conf host=http://api.example.com:8080/nw-api/;

где api.example.com:8080/nw-api/ — адрес и порт сервера, на котором установлен модуль Nemesida WAF API, а http://proxy.example.com:3128 — адрес прокси-сервера для обращения к Nemesida WAF API.

2. На сервере с установленным модулем Nemesida AI MLC внесите изменения в конфигурационный файл /opt/mlc/mlc.conf, приведя параметры к виду:

api_uri = http://api.example.com:8080/nw-api/
api_proxy = http://proxy.example.com:3128

3. На сервере с установленным модулем Nemesida WAF Scanner внесите изменения в конфигурационный файл /opt/nws/main.conf, приведя параметры к виду:

api_host = http://api.example.com:8080/nw-api/
api_proxy = http://proxy.example.com:3128

4. После внесения изменений необходимо перезапустить сервисы или перезагрузить сервер.

Управление настройками Немезида ВАФ

🔗 Общие сведения

Используя вызовы API, можно управлять настройками Немезида ВАФ:

  • настройками динамического модуля;
  • настройками Nemesida AI MLC;
  • поведенческими моделями;
  • синхронизацией между серверами настроек динамического модуля и Nemesida AI MLC;
  • правилами исключения сигнатур и расширенными правилами блокировки.

Управление настройками осуществляется с помощью специально составленных запросов. Каждый запрос должен содержать лицензионный ключ установленной копии Немезида ВАФ.

🔗 Настройка динамического модуля

Позволяет управлять настройками динамического модуля. Поддерживает следующие команды управления:

Получить настройки
# curl http://api.example.com:8080/nw-api/get_dyn_settings?format=json --data 'key=%Лицензионный ключ%'
Задать настройки
# curl http://api.example.com:8080/nw-api/set_dyn_settings --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "nwaf_ip_wl": "127.0.0.1, 127.0.0.2",
    "nwaf_ai_extra_host_lm": "example.com",
    "active": true
  }
}'

set — параметры настроек в формате JSON.

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра
nwaf_limit

Устанавливает лимит заблокированных запросов. При превышении допустимого количества запросов, определенного опцией rate, IP-адрес будет заблокирован на время (в секундах), указанное в block_time.

Пример:

{... "nwaf_limit": "rate=5r/m block_time=600" ...}

Параметр domain является опциональным и требуется только для установки лимита заблокированных запросов для конкретного домена. Для этого необходимо привести параметр к виду: nwaf_limit rate=... block_time=... domain=.... Допускается использовать строгое соответствие и wildcard-значения: *, example.com, .example.com, *.example.com.

Пример:

{... "nwaf_limit": "domain=example.com rate=5r/m block_time=600" ...}

Для установки разных лимитов для разных доменов необходимо указать параметры для каждого из них.

Пример:

{... "nwaf_limit": "domain=a.example.com rate=5r/m block_time=300, domain=example.com rate=5r/m block_time=300" ...}

или

{... "nwaf_limit": "rate=10r/m block_time=600, domain=example.com rate=5r/m block_time=300" ...}

В последнем примере будут установлены лимиты на 5 запросов в минуту для домена example.com (с последующей блокировкой IP-адреса атакующего на 300 секунд), а также лимиты на 10 запросов в минуту для всех остальным доменов (с последующей блокировкой IP-адреса атакующего на 600 секунд).

nwaf_ip_wl

Деактивация механизма анализа запроса средствами Немезида ВАФ для конкретного IP-адреса или подсети.

Пример:

{... "nwaf_ip_wl": "127.0.0.1, 192.168.0.1" ...}

При использовании "nwaf_ip_wl": "domain=example.com 127.0.0.1" механизм анализа будет деактивирован только при обращении с конкретного IP-адреса на конкретный домен. Опция domain является опциональной. Допускается использовать строгое соответствие и wildcard-значения: *, example.com, .example.com, *.example.com. Допускается использование IPv4/IPv6 адресов, в том числе использование CIDR (например, x.x.x.x/24) и диапазона IP-адресов.

Пример:

{... "nwaf_ip_wl": "127.0.0.1, 192.168.61.0/24, 192.168.61.1-192.168.61.255" ...}

Для снижения количества ложных срабатываний рекомендуется указывать статический IP-адрес пользователей (администраторов, контент-менеджеров, редакторов) в параметре nwaf_ip_wl. Запросы, попадающие под действие параметра не будут блокироваться, передаваться в RabbitMQ, и, как результат, анализироваться модулем Nemesida AI. При использовании параметра будьте предельно осторожны.

nwaf_ip_lm

Настройка обработки запросов для конкретного IP-адреса или подсети с фиксацией в СУБД, но без фактической блокировки (пассивный режим).

Пример:

{... "nwaf_ip_lm": "127.0.0.1, 192.168.0.1" ...}

При использовании "nwaf_ip_lm": "domain=example.com 127.0.0.1" пропуск будет производиться только при обращении с конкретного IP-адреса на конкретный домен. Опция domain является опциональной. Допускается использовать строгое соответствие и wildcard-значения: *, example.com, .example.com, *.example.com. Допускается использование IPv4/IPv6 адресов, в том числе использование CIDR (например, x.x.x.x/24) и диапазона IP-адресов.

Пример:

{... "nwaf_ip_lm": "127.0.0.1, 192.168.61.0/24, 192.168.61.1-192.168.61.255" ...}

Допускается использование IPv6 и IPv4-адресов.

nwaf_host_wl

Деактивация механизма анализа запроса средствами Немезида ВАФ для виртуального хоста. При параметре nwaf_host_wl * пропуск будет производиться для всех виртуальных хостов.

Пример использования одного значения:

{... "nwaf_host_wl": "*" ...}

или

{... "nwaf_host_wl": "example.com" ...}

или

{... "nwaf_host_wl": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_host_wl": "example.com, a.example.com" ...}

или

{... "nwaf_host_wl": "example.com, *.example.com" ...}
nwaf_host_lm

Настройка обработки запросов для конкретного виртуального хоста с фиксацией в СУБД, но без фактической блокировки (пассивный режим). При параметре nwaf_host_lm * пропуск будет производиться для всех виртуальных хостов.

Пример использования одного значения:

{... "nwaf_host_lm": "*" ...}

или

{... "nwaf_host_lm": "example.com" ...}

или

{... "nwaf_host_lm": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_host_lm": "example.com, a.example.com" ...}

или

{... "nwaf_host_lm": "example.com, *.example.com" ...}
nwaf_mla_host_lm

Параметр, активирующий режим LM (пассивный режим) для запросов, определенных модулем Nemesida AI MLA как нелегитимные.

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос фиксируется в системе управления базами данных, но не блокируется.

Пример использования одного значения:

{... "nwaf_mla_host_lm": "*" ...}

или

{... "nwaf_mla_host_lm": "example.com" ...}

или

{... "nwaf_mla_host_lm": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_mla_host_lm": "example.com, a.example.com" ...}

или

{... "nwaf_mla_host_lm": "example.com, *.example.com" ...}
nwaf_ai_extra_host_wl

Параметр, активирующий режим WL для запросов, определенных модулем Nemesida AI MLC как нелегитимные.

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос не фиксируется в СУБД и не блокируется.

Пример использования одного значения:

{... "nwaf_ai_extra_host_wl": "*" ...}

или

{... "nwaf_ai_extra_host_wl": "example.com" ...}

или

{... "nwaf_ai_extra_host_wl": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_ai_extra_host_wl": "example.com, a.example.com" ...}

или

{... "nwaf_ai_extra_host_wl": "example.com, *.example.com" ...}
nwaf_ai_extra_host_lm

Параметр, активирующий режим LM (пассивный режим) для запросов, определенных модулем Nemesida AI MLC как нелегитимные.

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос фиксируется в СУБД, но не блокируется.

Пример использования одного значения:

{... "nwaf_ai_extra_host_lm": "*" ...}

или

{... "nwaf_ai_extra_host_lm": "example.com" ...}

или

{... "nwaf_ai_extra_host_lm": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_ai_extra_host_lm": "example.com, a.example.com" ...}

или

{... "nwaf_ai_extra_host_lm": "example.com, *.example.com" ...}
nwaf_bf_detect_host_lm

Параметр, активирующий режим LM для запросов, определенных модулем Nemesida AI MLC как атаки методом перебора (BT 7) и флуд (BT 9).

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос фиксируется в СУБД, но не блокируется.

Пример использования одного значения:

{... "nwaf_bf_detect_host_lm": "*" ...}

или

{... "nwaf_bf_detect_host_lm": ".example.com" ...}

или

{... "nwaf_bf_detect_host_lm": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_bf_detect_host_lm": "example.com, *.example.org" ...}
nwaf_ddos_detect_host_lm

Параметр, активирующий режим LM для запросов, определенных модулем Nemesida AI MLC как DDoS-атаки (BT 10).

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос фиксируется в СУБД, но не блокируется.

Пример использования одного значения:

{... "nwaf_ddos_detect_host_lm": "*" ...}

или

{... "nwaf_ddos_detect_host_lm": ".example.com" ...}

или

{... "nwaf_ddos_detect_host_lm": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_ddos_detect_host_lm": "example.com, example.org" ...}
nwaf_rmq_host_exclude

Параметр, исключающий отправку некоторых запросов на сервер RabbitMQ (очередь nwaf).

В случае, если имя виртуального хоста из запроса попадает под действие параметра, то такой запрос не передается в очередь nwaf, и, соотвественно, не обрабатывается модулем Nemesida AI MLC (не анализируется на предмет аномалий и атак методом перебора, не участвует при построении поведенческих моделей).

Пример использования одного значения:

{... "nwaf_rmq_host_exclude": "*" ...}

или

{... "nwaf_rmq_host_exclude": "example.com" ...}

или

{... "nwaf_rmq_host_exclude": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_rmq_host_exclude": "example.com, a.example.com" ...}

или

{... "nwaf_rmq_host_exclude": "example.com, *.example.com" ...}
nwaf_body_exclude

Параметр, исключающий анализ сигнатурным методом зоны BODY, а также отправку её содержимого в модули Nemesida AI MLA и Nemesida AI MLC. Опция полезна, если нет возможности изменить значение параметра client_body_buffer_size в файле /etc/nginx/nginx.conf.

Пример:

{... "nwaf_body_exclude": "*" ...}

или

{... "nwaf_body_exclude": "example.com/uploads.php" ...}

или

{... "nwaf_body_exclude": "example.com/uploads" ...}

При применении параметра учитывается точное совпадение пути (vhost/path).

Например, при значении: example.com/uploads исключение анализа зоны BODY будет применяться для запросов к example.com/uploads, но для example.com/uploads.php и example.com/uploads/index.php параметр применен не будет. При значении * исключение анализа зоны BODY будет применяться для любого адреса.

nwaf_put_body_exclude

Параметр, исключающий анализ сигнатурным методом содержимого зоны BODY для PUT-запросов, а также отправку содержимого зоны в модули Nemesida AI MLA и Nemesida AI MLC. Опция полезна при взаимодействии с веб-приложениями ownCloud или аналогичными, позволяющими клиенту производить загрузку файла на сервер по протоколу HTTP.

Пример использования одного значения:

{... "nwaf_put_body_exclude": "*" ...}

или

{... "nwaf_put_body_exclude": "example.com" ...}

или

{... "nwaf_put_body_exclude": "*.example.com" ...}

Пример использования нескольких значений:

{... "nwaf_put_body_exclude": "example.com, a.example.com" ...}

или

{... "nwaf_put_body_exclude": "example.com, *.example.com" ...}
Удалить настройки
# curl http://api.example.com:8080/nw-api/set_dyn_settings --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": "nwaf_ip_wl"
}'

del — параметр настроек в формате JSON.

🔗 Управление списком заблокированных IP-адресов

Функционал позволяет создавать списки для блокировки запросов на основе IP-адреса источника запроса.

Получить список IP-адресов для блокировки
# curl http://api.example.com:8080/nw-api/get_dyn_bl --data 'key=%Лицензионный ключ%'

Задать список IP-адресов для блокировки
# curl http://api.example.com:8080/nw-api/set_dyn_bl --header 'Content-type: application/json' --data '{
  "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 — параметры настроек в формате JSON.
api=yes — параметр отправки событий о блокировках при обращении с указанного IP-адреса(ов) в Nemesida WAF API.

Запросы с IP-адреса 1.1.1.1 будут заблокированы только для домена example.com. Обращения с IP-адресов 2.2.2.2, 3.3.3.0/24 и 4.4.4.4-5.5.5.5 будут блокироваться для всех доменов, включая example.com.

Удалить все IP-адреса
# curl http://api.example.com:8080/nw-api/set_dyn_bl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": ""
}'

del — параметр настроек в формате JSON.

🔗 Управление списком автоматически заблокированных IP-адресов

Функционал позволяет управлять списком автоматически заблокированных IP-адресов для всех фильтрующих нод.

Получить список заблокированных IP-адресов
Пример запроса:

# curl http://api.example.com:8080/nw-api/get_dyn_sync_ban --data 'key=%Лицензионный ключ%'

Пример ответа:

{
  "status": "success",
  "ban_data": [
    {
      "ip-address": "127.0.0.1",
      "ttl": 30,
      "is_banned": true,
      "domain": "1.example.com",
      "timestamp": 1234567890
    },
    {
      "ip-address": "127.0.0.2",
      "ttl": 30,
      "is_banned": true,
      "domain": "2.example.com",
      "timestamp": 1234567891
    },
    {
      "ip-address": "127.0.0.3",
      "ttl": 30,
      "is_banned": true,
      "domain": "DEFAULT",
      "timestamp": 1234567892
    }
  ]
}

или

{"status": "fail", "description": "%описание ошибки%"}

ip-address — IP-адрес;
ttl — оставшееся время блокировки в секундах;
is_banned — параметр указывает, заблокирован ли IP-адрес;
domain — виртуальный хост (доменное имя), обращения к которому блокируются для IP-адреса. DEFAULT означает, что для IP-адреса блокируются обращения на любой виртуальный хост;
timestamp — дата добавления IP-адреса в список в формате Unix Timestamp.

Удалить IP-адрес из списка
Пример запроса:

# curl http://api.example.com:8080/nw-api/del_dyn_sync_ban --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "ip-address": "127.0.0.1"
}'

ip-address — параметр настроек в формате JSON.

Пример ответа:

{
  "status": "success",
  "description": "%описание ошибки%"
}

🔗 Настройка Nemesida AI MLC

Позволяет управлять настройками модуля Nemesida AI MLC. Поддерживает следующие команды управления:

Получить настройки
# curl http://api.example.com:8080/nw-api/get_mlc_settings?format=json --data 'key=%Лицензионный ключ%'
Получить список виртуальных хостов
# curl http://api.example.com:8080/nw-api/get_vhosts_list --data 'key=%Лицензионный ключ%'
Задать список виртуальных хостов, для которых будут созданы и применены модели
# curl http://api.example.com:8080/nw-api/set_vhosts_list --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "vhosts_list": ["example.com, example.org"]
}'

vhosts_list — список виртуальных хостов, для которых будут созданы и применены модели.

Задать настройки
# curl http://api.example.com:8080/nw-api/set_mlc_settings --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "main__ai_extra": "false",
    "brute__interval": "11",
    "brute__brute_detect": [
      "example.com/a1",
      "example.com/b1"
    ],
    "active": true
  }
}'

set — параметры настроек в формате JSON.

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра

main__ai_extra

Активация/деактивация функционала дополнительного анализа запросов, позволяющего выявлять пропущенные атаки и производить временное блокирование их источника по IP-адресу. При неактивном функционале дополнительного анализа все незаблокированные запросы будут включены в обучающую выборку (за исключением запросов, попадающих под действие режима WL, или нелегитимных запросов, попавших под действия режима LM).

Пример:

{... "main__ai_extra": true ...}

ddos__enable
Активация/деактивация функционала выявления DDoS-атак.

Пример:

{... "ddos__enable": true ...}
ddos__wl_ip
Параметр, определяющий список IP-адресов, для которых функционал будет отключен. Допускается использование IPv4/IPv6 адресов, в том числе использование CIDR (например, x.x.x.x/24). Каждое последующее значение указывается через пробел.

Пример:

{... "ddos__wl_ip": "127.0.0.1 192.168.1.0/24" ...}
ddos__wl_url
Параметр, в котором задаются адреса как в формате vhost, так и в формате vhost/path, где:

vhost — имя виртуального хоста, для которого функционал выявления DDoS-атак будет отключен.
path — вхождение адреса ресурса.

Допускается использовать строгое соответствие и wildcard-значения: example.com, .example.com, *.example.com.

Пример:

{... "ddos__wl_url": ["example.com/feed", ".example.com/feed", "*.example.com/feed", "*/feed"] ...}
ddos__interval
Временной интервал (в секундах), в течение которого производится анализ запросов.

Пример:

{... "ddos__interval": "10" ...}
ddos__latest_only
Активация передачи в Nemesida WAF API только последнего заблокированного запроса по каждому IP-адресу. При значении false в Nemesida WAF API передаются все заблокированные запросы по каждому IP-адресу.

Пример:

{... "ddos__latest_only": true ...}
ddos__send_possible
Активация механизма передачи в Nemesida WAF API запросов с типом Possible DDoS. При значении false запросы в Nemesida WAF API передаваться не будут.

Пример:

{... "ddos__send_possible": true ...}

Приставка Possible добавляется к названию атаки в том случае, если её тип не был достоверно установлен.


brute__enable
Активация/деактивация функционала выявления атак методом перебора.

Пример:

{... "brute__enable": true ...}
brute__wl_host
Деактивация функционала выявления атак методом перебора для конкретных виртуальных хостов. Допускается использовать строгое соответствие и wildcard-значения: example.com, .example.com, *.example.com.

Пример:

{... "brute__wl_host": ["example.com", ".example.org", "*.example.us"] ...}
brute__interval
Временной интервал (в секундах), в течение которого производится анализ запросов.

Пример:

{... "brute__interval": "10" ...}
brute__max_val
Количество запросов, при достижении значения которого производится блокирование IP-адреса источника(-ов) атаки.

Пример:

{... "brute__mav_val": "15" ...}
brute__brute_detect
Параметр, определяющий список адресов для выявления атак методом перебора в формате vhost/path, где path — вхождение адреса ресурса на веб-сервере. Для виртуального хоста допускается использование строгого соответствия и wildcard-значения: example.com, .example.com, *.example.com.

Пример:

{... "brute__brute_detect": ["example.com/auth", ".example.com/auth"] ...}

или

{... "brute__brute_detect": ["*.example.com/auth"] ...}

Таким образом, при установленном значении example.com/auth, мониторинг атак методом перебора будет производиться как для example.com/auth, так и для example.com/auth/reset_password.

Параметр применяется для выявления атак методом перебора, но не блокирует повторяющиеся запросы с одинаковым содержимым в зонах ARGS или BODY.

brute__flood_detect
Параметр, имеет схожий с параметром brute_detect функционал, но предназначен для выявления попыток флуда или аналогичных атак с повторением запроса. Единственное различие заключается в том, что в процессе анализа запросов, попадающих под действие параметра flood_detect, не происходит удаление дублей.

Таким образом, в случае повторной отправки идентичных запросов (например, множественные попытки восстановления пароля по СМС), запросы, имеющие схожее содержание и попадающие под действие параметра flood_detect, не будут удалены, в отличие от запросов, имеющие схожее содержание, но попадающих под действие параметра brute_detect.

Пример:

{... "brute__flood_detect": ["example.com/auth", ".example.com/auth"] ...}

или

{... "brute__flood_detect": ["*.example.com/auth"] ...}
brute__latest_only
Активация передачи в Nemesida WAF API только последнего заблокированного запроса по каждому IP-адресу. При значении false в Nemesida WAF API передаются все заблокированные запросы по каждому IP-адресу.

Пример:

{... "brute__latest_only": true ...}
brute__send_possible
Активация механизма передачи в Nemesida WAF API запросов с типом Possible Brute force/Possible Flood. При значении false запросы в Nemesida WAF API передаваться не будут.

Пример:

{... "brute__send_possible": true ...}

Приставка Possible добавляется к названию атаки в том случае, если её тип не был достоверно установлен.

Удалить настройки
# curl http://api.example.com:8080/nw-api/set_mlc_settings --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": "brute_detect"
}'

del — параметры настроек в формате JSON.

🔗 Правила исключения сигнатур

Позволяет настроить правила исключения сигнатур. Поддерживает следующие команды управления:

Получить список правил
# curl http://api.example.com:8080/nw-api/get_dyn_wl --data 'key=%Лицензионный ключ%'
Получить расширенную информацию о правиле
# curl http://api.example.com:8080/nw-api/get_dyn_wl?extended=yes --data 'key=%Лицензионный ключ%'
Создать правило
# curl http://api.example.com:8080/nw-api/set_dyn_wl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "add": {
    "rl_id": "50001",
    "domain": "example.com",
    "mz": "url",
    "extension": "$URL_X:/test"
  }
}'

add — параметры настроек в формате JSON;
rl_id — ID сигнатуры (правила блокировки), к которой применяется правило исключения. При использовании значения * правило исключения будет применяться ко всем сигнатурам.

Более подробная информация по созданию правил доступна соответствующем разделе документации.

Обновить правило
# curl http://api.example.com:8080/nw-api/set_dyn_wl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "upd": {
    "rid": "50001",
    "pattern": "ABC"
  }
}'

upd — параметры настроек в формате JSON.

Удалить правило
# curl http://api.example.com:8080/nw-api/set_dyn_wl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "rid": "50001"
  }
}'

del — параметры настроек в формате JSON.

🔗 Расширенные правила блокировки запросов

Механизм расширенных правил блокирования запросов позволяет при составлении персональных правил использовать дополнительные условия для более точного результата. Например, можно составить правило, по которому запрос будет заблокирован если:

  • соответствует географическому местоположению на основе IP-адреса (определение страны по IP-адресу атакующего);
  • происходит обращение на определенный домен или URL;
  • содержит определенный заголовок (например, User-Agent, Cookie, Referer и т.д.) и/или содержимое этих заголовков.

Для более точного результата параметры можно комбинировать между собой. В таком случае правило сработает только в случае соответствия всех условий.

Принцип работы функционала
Поддерживаются следующие параметры:

  • ip — IP-адрес атакующего;
  • api — отправлять результат срабатывания правила в модуль Nemesida WAF API;
  • lm — обработка правила в режиме LM (фиксируется срабатывание правила, но запрос не блокируется);
  • noban — со значением false при срабатывании правила запрос будет заблокирован, но счетчик rate параметра nwaf_limit, необходимый для блокировки IP-адреса источника запросов, не будет увеличиваться;
  • no_cookie — со значением true правило применяется только к запросу с пустой зоной Cookie;
  • country — страна (для работы функционала определения географического местоположения на основе IP-адреса необходимо подключить файл с базой GeoIP2 в /etc/nginx/nwaf/conf/global/nwaf.conf);
  • domain — домен;
  • url — вхождение строки в содержимое зоны URL;
  • args — вхождение строки в содержимое зоны ARGS;
  • body — вхождение строки в содержимое зоны BODY;
  • cookies — вхождение строки в содержимое зоны Cookie;
  • ua — вхождение строки в содержимое зоны User-Agent;
  • referer — вхождение строки в содержимое зоны Referer;
  • other_headers — вхождение строки в содержимое зоны HEADERS, за исключением зон Cookie, User-Agent и Referer.

Для поля domain допускается использовать строгое соответствие и wildcard-значения: *, example.com, .example.com, *.example.com.

Пример:

{... "domain": "base64(*.example.com)" ...}

При таком значении правило будет применяться ко всем поддоменам (a.example.com, b.example.com и т.д.), исключая основной домен example.com. Если значение поля domain пустое, то правило будет применяться ко всем запросам.

Префикс base64 перед параметром означает, что значение параметра при составлении правила необходимо передавать в формате base64. Например: "domain": "base64(*.example.com)" будет выглядеть как "domain": "Ki5leGFtcGxlLmNvbQ=="

Для всех параметров (кроме api,lm, noban и no_cookie) допускается использовать несколько значений в одном параметре, используя логические операторы условий «не» (!), «и» (&), «или» (|). Операторы не имеют приоритета и выполняются по очереди, слева направо.

Пример:

{... "ip": "192.168.61.0/24|192.168.62.0/24" ...}

При таком значении правило будет применяться ко всем IP-адресам из диапазонов 192.168.61.1-192.168.61.255 или 192.168.62.1-192.168.62.255.


Пример:

{... "country": "!base64(RU)&!base64(US)" ...}

При таком значении правило будет применяться ко всем запросам, в которых IP-адрес источника запроса не из России и не из США.


Пример:

{... "cookie": "!base64(abc)&!base64(def)" ...}

При таком значении правило будет применяться ко всем запросам, которые не содержат abc и def в Cookie.

При проверке срабатывания расширенного правила блокирования запроса все поля, кроме ip, country, api, lm и noban, проверяются на вхождение содержимого поля из правила блокирования в проверяемое поле запроса. Например, при "url": "base64(/abc)" будет заблокирован запрос с вхождением /abcd в URL.

other_headers

Формат поля:

{... "other_headers": ["base64(header_name):base64(header_value)", "base64(header_name):base64(header_value)" ...] ...}

base64(header_name) — название заголовка в base64;
base64(header_value) — значение заголовка в base64.

Для поля other_headers содержимое секций base64(header_name) и base64(header_value) являются опциональными, но необходимо указать хотя бы одну из секций . Например, при наличии заголовка header_name будет проверяться содержимое header_value только этого заголовка, а при отсутствии — содержимое всех заголовков.

Пример:

{... "other_headers": ["base64(example_header):base64(abcd)"] ...}

При таком значении запрос будет заблокирован при наличии abcd в заголовке example_header.


Пример:

{... "other_headers": [":base64(abcd)"] ...}

При таком значении запрос будет заблокирован при наличии abcd в любом заголовке.


Если base64(header_name) указан без последующего значения, то блокирование запроса произойдет при любом значении заголовка header_name (блокировка по наличию заголовка).

Пример:

{... "other_headers": ["base64(example_header):"] ...}

Пример:

{... "other_headers": ["base64(example1_header):base64(abc)","base64(example2_header):base64(def)"] ...}

При таком значении запрос будет заблокирован при наличии заголовков example1_header, который содержит abc и example2_header, который содержит def.


Пример:

{... "other_headers": ["base64(example1_header):","base64(example2_header):"] ...}

При таком значении запрос будет заблокирован при наличии заголовков example1_header и example1_header с любыми значениями.


Для имени заголовка допустимо применение логического оператора !!, означающего отсутствие заголовка с таким именем в запросе. Блокирование запроса сработает в том случае, если среди всех заголовков запроса отсутствует заголовок с указанным именем. При этом, значение заголовка игнорируется, даже если присутствует в правиле.

Пример:

{... "other_headers": ["!!base64(example_header):"] ...}

Пример:

{... "other_headers": ["base64(example_header):base64(abc)&base64(def)"] ...}

При таком значении запрос будет заблокирован при наличии заголовка example_header, который содержит abc и def.


Пример:

{... "other_headers": ["base64(example_header):!base64(abc)"] ...}

При таком значении запрос будет заблокирован при наличии заголовка example_header, который не содержит abc.


Пример:

{... "other_headers": ["base64(example_header):!base64(a)&!base64(b)&!base64(c)"] ...}

При таком значении запрос будет заблокирован при наличии заголовка example_header, который не содержит a, b и c.


Пример:

{... "other_headers": ["base64(example_header):!base64(a)|base64(b)"] ...}

При таком значении запрос будет заблокирован при наличии заголовка example_header, который не содержит a или содержит b.

Если в запросе недоступно получение какого-либо поля, указанного в расширенном правиле блокирования, то запрос будет пропущен.

Поддерживает следующие команды управления:

Получить список правил
# curl http://api.example.com:8080/nw-api/get_dyn_erl --data 'key=%Лицензионный ключ%'
Получить расширенную информацию о правиле
# curl http://api.example.com:8080/nw-api/get_dyn_erl?extended=yes --data 'key=%Лицензионный ключ%'
Создать правило
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "add": {
    "ip": "1.1.1.1|2.2.2.2",
    "active": true
  }
}'

add — параметры настроек в формате JSON.

# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "add": {
    "ip": "!1.1.1.0/24",
    "domain": "ZXhhbXBsZS5jb20=",
    "active": true
  }
}'

Запрос будет заблокирован, если на example.com поступит запрос c любого IP-адреса, кроме 1.1.1.1-1.1.1.255.

Из-за особенностей обработки запросов функционал не предназначен для работы с большим количеством IP-адресов. Если необходимо блокировать обращения для списка IP-адресов — воспользуйтесь функционалом добавления IP-адреса в список «Заблокированные IP».

# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "add": {
    "ip": "1.1.1.1",
    "domain": "ZXhhbXBsZS5jb20=",
    "other_headers": [
      "dGVzdC1oZWFkZXI=:YWJj"
    ],
    "active": true
  }
}'

Запрос будет заблокирован правилом в случае, если на example.com поступит запрос с IP-адреса 1.1.1.1 и заголовок test-header содержит строку abc.

# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "add": {
    "сountry": "Q0g=|UlU=",
    "domain": "ZXhhbXBsZS5jb20=",
    "other_headers": [
      "dGVzdC1oZWFkZXI=:YWJj"
    ],
    "cookie": "!dGVzdF9jb29raWU=",
    "referer": "!aHR0cDovL2V4YW1wbGUuY29t",
    "active": true
  }
}'

Запрос будет заблокирован правилом в случае, если на example.com поступит запрос с IP-адреса из региона RU или CH, заголовок test-header содержит строку abc, заголовок Cookie не содержит строку test_cookie и заголовок Referer не содержит http://example.com.

# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "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
  }
}'

Запрос будет заблокирован правилом в случае, если на example.com поступит запрос c IP-адреса 1.1.1.1 из региона RU или CH, который будет содержать:

  • заголовок Referer с содержимым http://example.com/;
  • заголовок Test-Field с любым содержимым;
  • заголовок User-Agent с содержимым Mozilla/5.0;
  • заголовок Cookie с содержимым test_cookie;
  • содержимое тела запроса bc=3&cc=1;
  • аргумент запроса ?page=3.

Обновить правило
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "upd": {
    "rid": "1",
    "ip": "1.1.1.1",
    "active": true
  }
}'

upd — параметры настроек в формате JSON.

Удалить правило
# curl http://api.example.com:8080/nw-api/set_dyn_erl --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "rid": "1"
  }
}'

del — параметры настроек в формате JSON.

🔗 Управление поведенческими моделями

Некорректное обучение поведенческих моделей или значительные изменения в веб-приложении могут привести ко множеству ложных срабатываний. Для повышения точности определения атак рекомендуется выполнять переобучение моделей раз в неделю. Команды ниже позволяют производить действия над моделями.

Получить список виртуальных хостов с моделями
# curl http://api.example.com:8080/nw-api/get_models_list_uri --data 'key=%Лицензионный ключ%'
Удалить модель для виртуального хоста example.com
# curl http://api.example.com:8080/nw-api/del_models_uri --data 'key=%Лицензионный ключ%&vhost=example.com'

vhost — имя виртуального хоста, для которого необходимо удалить поведенческую модель.

Дообучение моделей с использованием резервной копии обучающей выборки
Для корректного построения моделей требуется порядка 400.000-800.000 уникальных запросов. Если во время обучения количество запросов было недостаточным, то можно его перезапустить и воспользоваться запросами из прошлой выборки. Для этого выполните 4 шага:

1. Остановите сервис Nemesida AI MLC:

# service mlc_main stop

2. Переместите файл /opt/mlc/ml/backup/[vhost].d_[timestamp], где [timestamp] — дата создания резервной копии обучающей выборки, созданной Nemesida AI MLC перед началом построения модели, в /opt/mlc/ml/[vhost].d. Например, для модели example.com:

# mv /opt/mlc/ml/backup/example.com.d_1613587613 /opt/mlc/ml/example.com.d

3. Запустите обучение:

# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%Лицензионный ключ%&vhost=*.example.com&complete=no'

4. Запустите сервис Nemesida AI MLC:

# service mlc_main start
Скопировать поведенческую модель для виртуального хоста
# curl http://api.example.com:8080/nw-api/rep_models_uri --data 'key=%Лицензионный ключ%&src=example.com&dst=example.ru'

src — виртуальный хост, поведенческая модель которого копируется;
dst — виртуальный хост, для которого необходимо скопировать модель.

Получить статус обучения модели для виртуального хоста
# curl http://api.example.com:8080/nw-api/get_training_uri --data 'key=%Лицензионный ключ%&vhost=example.com'
Установить для виртуального хоста example.com период обучения 4 дня
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%Лицензионный ключ%&vhost=example.com&duration=4'

duration — период обучения в днях.

Активировать обучение модели для виртуального хоста *.example.com
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%Лицензионный ключ%&vhost=*.example.com&complete=no'

complete — статус обучения модели.

Задать период обучения и активировать обучение модели для виртуального хоста .example.com
# curl http://api.example.com:8080/nw-api/set_training_uri --data 'key=%Лицензионный ключ%&vhost=.example.com&duration=4&complete=no'

Выполнение команды со значением параметра complete=no позволяет запустить процесс переобучения модели, а complete=yes — прерывает процесс обучения.

Перед запуском процесса обучения модели виртуальный хост должен быть добавлен в список виртуальных хостов.

Управление настройками веб-сервера Nginx
Используя вызовы API, можно управлять настройками Nginx. Каждый запрос должен содержать лицензионный ключ установленной копии Немезида ВАФ.

🔗 Глобальные настройки Nginx

Секция позволяет задать глобальные настройки Nginx, которые будут располагаться в /etc/nginx/nwaf/conf/global/nginx/nginx.conf. Поддерживает следующие команды управления:

Получить настройки
# curl http://api.example.com:8080/nw-api/nginx/get_nginx --data 'key=%Лицензионный ключ%'
Задать настройки
# curl http://api.example.com:8080/nw-api/nginx/set_nginx --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "active": true,
    "resolver": "127.0.0.1 [::1]:5353 valid=30s",
    "resolver_timeout": 30,
    "set_real_ip_from": [
      "192.168.1.0/24",
      "192.168.2.1"
    ],
    "real_ip_header": "X-Forwarded-For",
    "client_max_body_size": 100,
    "limit_req_zone": [
      "$binary_remote_addr zone=mylimit_1:10m rate=10r/s",
      "$binary_remote_addr zone=mylimit_2:10m rate=10r/s"
    ]
  }
}'

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра

Адрес DNS-сервера. Значение valid (в секундах) означает как долго ответ DNS-сервера будет считаться действительным.

Параметр устанавливает значение (в секундах), в течение которого Nginx будет ожидать ответа от DNS-сервера.

Параметр задаёт доверенные адреса, которые передают верный адрес для замены. Доверенные адреса могут быть также заданы при помощи имени хоста.

Допускается использование IPv6 и IPv4-адресов.

Задаёт поле заголовка запроса, значение которого будет использоваться для замены адреса клиента.

Параметр задаёт максимально допустимый размер тела запроса клиента в мегабайтах. Если размер больше заданного, то клиенту возвращается ошибка 413 (Request Entity Too Large). Установка параметра со значением 0 отключает проверку размера тела запроса клиента.

Задаёт параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. В качестве ключа можно использовать текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.

Сбросить настройки
# curl http://api.example.com:8080/nw-api/nginx/set_nginx --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "resolver": null,
    "resolver_timeout": null,
    "set_real_ip_from": null,
    "real_ip_header": null,
    "client_max_body_size": null,
    "limit_req_zone": null
  }
}'

🔗 Настройка виртуального хоста

Параметр name — имя конфигурации, которое будет располагаться в /etc/nginx/nwaf/conf/global/nginx/%name%.conf.

Секция предназначена для настройки файла виртуального хоста. Поддерживает следующие команды управления:

Получить настройки
# curl http://api.example.com:8080/nw-api/nginx/get_vhost --data 'key=%Лицензионный ключ%'
Задать настройки
# curl http://api.example.com:8080/nw-api/nginx/set_vhost --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "active": true,
    "listen": "localhost:443 default_server ssl http2",
    "server_name": "www.example.com example.com",
    "certificate_name": "%name%",
    "dhparam_name": "%name%",
    "ssl_session_timeout": 10,
    "ssl_ciphers": "AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5",
    "ssl_protocols": "TLSv1 TLSv1.1 TLSv1.2",
    "root": "/var/www/site",
    "index": "index.php index.html",
    "locations": [
      {
        "location": "/static_1",
        "pass_type": "root",
        "path": "/var/www/html",
        "index": "index.php",
        "limit_req": "zone=mylimit_1 burst=20 nodelay",
        "limit_req_status": 444
      },
      {
        "location": "/static_2",
        "pass_type": "alias",
        "path": "/var/www/static_2",
        "autoindex": "on",
        "limit_req": "zone=mylimit_1 burst=20 nodelay",
        "limit_req_status": 444
      },
      {
        "location": "/abc_1",
        "pass_type": "proxy_pass",
        "proxy_pass": "http://main_proxy",
        "limit_req": "zone=mylimit_1 burst=20 nodelay",
        "limit_req_status": 444
      },
      {
        "location": "/abc_2",
        "pass_type": "memcached_pass",
        "memcached_pass": "main_memc",
        "limit_req": "zone=mylimit_1 burst=20 nodelay",
        "limit_req_status": 444
      }
    ]
  }
}'

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра
name

Имя конфигурации.

Параметр задаёт адрес и порт для IP-адреса или путь для UNIX-сокета, на которых сервер будет принимать запросы. Можно указать адрес и порт, либо только адрес или только порт. Кроме того, адрес может быть именем хоста, например:

127.0.0.1:8000
127.0.0.1
8000
*:8000
localhost:8000
[::]:8000
[::1]
unix:/var/run/nginx.sock

Значение default_server, означает, что сервер будет сервером по умолчанию для указанной пары адрес:порт. Если же параметра default_server нет, то сервером по умолчанию будет первый сервер, в котором описана пара адрес:порт.

Параметр ssl указывает на то, что все соединения, принимаемые на данном порту, должны работать в режиме SSL. Это позволяет задать компактную конфигурацию для сервера, работающего сразу в двух режимах — HTTP и HTTPS.

Параметр http2 позволяет принимать на этом порту HTTP/2-соединения. Обычно, следует также указать параметр ssl, однако Nginx можно также настроить и на приём HTTP/2-соединений без SSL.

Имя сервера.

Допускается использование wildcard-значений для замены первой или последней части имени.

certificate_name

Каноническое имя SSL-сертификата и приватного ключа для сервера. Имя задается при создании, в разделе настройки SSL-сертификатов.

Каноническое имя pem-файла, необходимого для работы Forward Secrecy (если злоумышленник узнает какой-либо сеансовый ключ, то он сможет получить доступ лишь к данным, защищенным этим ключом). Имя задается при создании в разделе настройки DHParam.

Параметр задаёт время (в секундах), в течение которого клиент может повторно использовать параметры сессии.

Параметр задает разрешённые шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.

Параметр разрешает использование указанных протоколов.

Параметр задаёт корневой каталог для запросов.

Параметр определяет файлы, которые будут использоваться в качестве индекса. В имени файла можно использовать переменные. Наличие файлов проверяется в порядке их перечисления. В конце списка может стоять файл с абсолютным путём.

Параметр определяет список используемых location для виртуального хоста и их параметры:

  • location — URI запроса;
  • pass_type — используемый тип конфигурации (root, alias, proxy_pass или memcached_pass);
  • index — файлы, которые будут использоваться в качестве индекса;
  • limit_req — зона разделяемой памяти (zone) и максимальный размер всплеска запросов (burst). Если скорость поступления запросов превышает описанную в зоне, то их обработка cдерживается так, чтобы запросы обрабатывались с заданной скоростью;
  • limit_req_status — код ответа, используемый при отклонении запросов;
  • autoindex — разрешение на листинг каталога;
  • proxy_pass/memcached_pass — протокол и адрес проксируемого сервера, а также URI (опционально), на который должен перенаправлять location при использовании параметра pass_type со значениями proxy_pass или memcached_pass соответственно.
Сбросить отдельные настройки
# curl http://api.example.com:8080/nw-api/nginx/set_vhost --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "listen": null,
    "server_name": null,
    "certificate_name": null,
    "dhparam_name": null,
    "ssl_session_timeout": null,
    "ssl_ciphers": null,
    "ssl_protocols": null,
    "root": null,
    "index": null,
    "locations": null
  }
}'
Удалить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_vhost --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "name": "%Имя конфигурации%"
  }
}'

🔗 Настройка балансировки нагрузки

Параметр name — имя конфигурации с параметрами балансировки нагрузки, который будет располагаться в /etc/nginx/nwaf/conf/global/nginx/%name%.conf.

Секция предназначена для настройки параметров балансировки нагрузки. Поддерживает следующие команды управления:

Получить настройки
# curl http://api.example.com:8080/nw-api/nginx/get_upstream --data 'key=%Лицензионный ключ%'
Задать настройки
# curl http://api.example.com:8080/nw-api/nginx/set_upstream --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "balancing_method": "ip_hash",
    "servers": [
      {
        "server": "backend1.example.com",
        "weight": 3
      },
      {
        "server": "127.0.0.1:8080",
        "fail_timeout": 60
      },
      {
        "server": "192.0.2.1",
        "max_fails": 5
      },
      {
        "server": "backend3.example.com",
        "weight": 3,
        "fail_timeout": 60,
        "max_fails": 5
      },
      {
        "server": "backend4.example.com"
      },
      {
        "server": "backend5.example.com",
        "backup": true
      },
      {
        "server": "backend4.example.com",
        "down": true
      }
    ]
  }
}'

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра

Название группы серверов для балансировки нагрузки.

balancing_method

Метод распределения нагрузки между серверами. Допускается использовать одно из значений (hash, ip_hash, least_conn, least_time или random).

Список серверов, которые используются для обработки запросов, а также их параметры:

  • server — адрес сервера. Адрес может быть указан в виде доменного имени, IP-адреса и порта (опционально), или в виде пути UNIX-сокета. Допускается использование IPv6 и IPv4-адресов;
  • weight — числовой показатель приоритета выбора сервера при обработке запроса;
  • fail_timeout — время (в секундах), в течение которого должно произойти заданное число неудачных попыток работы с сервером для того, чтобы сервер считался недоступным;
  • max_fails — максимальное число неудачных попыток связи с сервером за время, заданное параметром fail_timeout;
  • slow_start — время (в секундах), в течение которого восстановится номинальное значение weight в ситуации, когда неработоспособный сервер вновь становится работоспособным;
  • down — помечает сервер как постоянно недоступный;
  • backup — помечает сервер как запасной. На него будут передаваться запросы в случае, если не работают основные серверы.
Сбросить отдельные настройки
# curl http://api.example.com:8080/nw-api/nginx/set_upstream --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "balancing_method": null,
    "servers": null
  }
}'
Удалить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_upstream --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "name": "%Имя конфигурации%"
  }
}'

🔗 Настройка SSL-сертификатов

Параметр name — имя конфигурации для SSL-сертификатов и их приватных ключей, которые будут располагаться в /etc/nginx/nwaf/conf/global/nginx/ssl/certs/%name%.crt и /etc/nginx/nwaf/conf/global/nginx/ssl/private/%name%.key.

Секция предназначена для настройки параметров SSL-сертификатов и их приватных ключей. Поддерживает следующие команды управления:

Получить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/get_certificate --data 'key=%Лицензионный ключ%'
Задать конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_certificate --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "certificate": "asd3aedcwe==",
    "certificate_key": "sdaedfasdva=="
  }
}'

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра
name

Каноническое имя SSL-сертификата и его приватного ключа, которое будет использоваться в качестве имен соответствующих файлов.

SSL-cертификат и цепочку SSL-сертификатов (опционально) в формате Base64. Параметр задается вместе с параметром certificate_key.

Приватный ключ SSL-сертификата в формате Base64. Параметр задается вместе с параметром certificate.

Удалить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_certificate --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "name": "%Имя конфигурации%"
  }
}'

🔗 Настройка DHParam

Параметр name — имя конфигурации с параметрами DHParam, который будет располагаться в /etc/nginx/nwaf/conf/global/nginx/ssl/dhparam/%name%.pem.

Секция предназначена для настройки параметра DHParam. Поддерживает следующие команды управления:

Получить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/get_dhparam --data 'key=%Лицензионный ключ%'
Задать конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_dhparam --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "set": {
    "name": "%Имя конфигурации%",
    "dhparam": "asd3aedcwe=="
  }
}'

Для управления доступны следующие параметры:

Поддерживаемые параметры
Параметр
Описание параметра
name

Каноническое имя pem-файла, необходимого для работы Forward Secrecy. Forward Secrecy означает, что если злоумышленник узнает какой-либо сеансовый ключ, то он сможет получить доступ лишь к данным, защищенным этим ключом.

Значение ключа в формате Base64.

Удалить конфигурацию
# curl http://api.example.com:8080/nw-api/nginx/set_dhparam --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "del": {
    "name": "%Имя конфигурации%"
  }
}'

Сборщик событий компонентов Немезида ВАФ

Доступно только для тарифа Enterprise.

Функционал предназначен для централизованного приема, хранения и обработки журналов всех компонентов Немезида ВАФ.

Получить список событий компонентов Немезида ВАФ
# curl http://api.example.com:8080/nw-api/get_event --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "startTime": 1234567891,
  "endTime": 1987654321,
  "level": [
    "info",
    "error"
  ],
  "ip": [
    "1.1.1.1",
    "2.2.2.2"
  ],
  "uuid": [
    "198be506d69ba8a9bdbcf87b22ef5bc",
    "198be506d69ba8a9bdbcf87b22ef5bb"
  ],
  "agent": [
    "dyn",
    "mlc"
  ],
  "category": [
    "auth",
    "settings"
  ]
}'

Опциональные параметры:

  • startTime — начальная дата в формате Unix Timestamp, за который будет запрошена информация;
  • endTime — конечная дата в формате Unix Timestamp, за который будет запрошена информация;
  • level — уровень серьезности сообщения;
  • ip — IP-адрес сервера, где установлен компонент;
  • uuid — идентификатор сервера, где установлен компонент;
  • agent — название компонента;
  • category — категория события.
Поддерживаемые параметры
Временной интервал:

  • startTime — начальная дата в формате Unix Timestamp, за который будет запрошена информация;
  • endTime — конечная дата в формате Unix Timestamp, за который будет запрошена информация.

Ранжирование событий:

  • level — уровень серьезности события;
    • debug — события с отладочной информацией;
    • info — информационные сообщения о состоянии компонента;
    • warning — предупреждения о потенциальной проблеме в работе компонента;
    • error — сообщения об ошибках в работе компонента;
    • fatal — сообщения о критических ошибках в работе компонента, приводящие к сбою в работе.
  • category — категория события:
    • Динамический модуль:
      • auth — события, связанные с проверкой программного ключа, тарифного плана и т.д.;
      • os — события взаимодействия с операционной системой (память, диск);
      • network — события, связанные с сетью (невозможно установить соединение, отправки, таймауты, обрывы, запуск/остановка сокета/порта);
      • api — события, связанные со взаимодействием с Nemesida WAF API;
      • settings — события, связанные с настройками модуля;
      • nginx — события, связанные со взаимодействием с Nginx (несоответствие настроек, необходимых для работы динамического модуля, нарушения RFC);
      • signature — события, связанные с сигнатурным анализом;
      • clamav — события, связанные со взаимодействием с ClamAV;
      • mla — события, связанные со взаимодействием с Nemesida AI MLA;
      • mlc — события, связанные со взаимодействием с Nemesida AI MLC;
      • rabbitmq — события, связанные со взаимодействием с RabbitMQ;
      • autoban — события, связанные механизмом автоматической блокировки;
      • geo — события, связанные с функционалом GeoIP;
      • openapi — события, связанные с работой OpenAPI;
      • parsing — события, связанные с декодом и нормазизацией данных;
      • analysis — события, связанные с обработкой запроса, но не вошедшие ни в одну группу (signature, ml, openapi и т.д.);
      • misc — события, не вошедшие ни в одну категорию (например, вывод информаци об UUID, WAF ID, количестве сигнатур и т.д.).
    • Nemesida AI MLA:
      • auth — события, связанные с проверкой программного ключа, тарифного плана и т.д.;
      • os — события взаимодействия с операционной системой (память, диск);
      • network — события, связанные с сетью (невозможно установить соединение, отправки, таймауты, обрывы, запуск/остановка сокета/порта);
      • api — события, связанные со взаимодействием с Nemesida WAF API;
      • settings — события, связанные с настройками модуля;
      • dyn — события, связанные со взаимодействием с динамическим модулем;
      • ml — события, связанные с работой машинного обучения;
      • geo — события, связанные с функционалом GeoIP;
      • openapi — события, связанные с работой OpenAPI;
      • analysis — события, связанные с обработкой запроса, но не вошедшие ни в одну группу (signature, ml, openapi и т.д.);
      • misc — события, не вошедшие ни в одну категорию (например, вывод информаци об UUID, WAF ID, количестве сигнатур и т.д.).
    • Nemesida AI MLC:
      • auth — события, связанные с проверкой программного ключа, тарифного плана и т.д.;
      • os — события взаимодействия с операционной системой (память, диск);
      • network — события, связанные с сетью (невозможно установить соединение, отправки, таймауты, обрывы, запуск/остановка сокета/порта);
      • api — события, связанные со взаимодействием с Nemesida WAF API;
      • settings — события, связанные с настройками модуля;
      • dyn — события, связанные со взаимодействием с динамическим модулем;
      • rabbitmq — события, связанные со взаимодействием с RabbitMQ;
      • ml — события, связанные с работой машинного обучения;
      • geo — события, связанные с функционалом GeoIP;
      • bf — события, связанные с работой Brute-force/Flood анализа;
      • ddos — события, связанные с работой DDoS анализа;
      • openapi — события, связанные с работой OpenAPI;
      • analysis — события, связанные с обработкой запроса, но не вошедшие ни в одну группу (signature, ml, openapi и т.д.);
      • misc — события, не вошедшие ни в одну категорию (например, вывод информаци об UUID, WAF ID, количестве сигнатур и т.д.).

Идентификация компонентов:

  • ip — IP-адрес сервера, где установлен компонент;
  • uuid — идентификатор сервера, где установлен компонент;
  • agent — название компонента:
    • dyn — динамический модуль;
    • mla — Nemesida AI MLA;
    • mlc — Nemesida AI MLC;
    • cabinet — Личный кабинет;
    • nws — Nemesida WAF Scanner.
Удалить события
# curl http://api.example.com:8080/nw-api/del_event --data 'key=%Лицензионный ключ%&timestamp=1677211703'

Опциональные параметры:
timestamp — дата в формате Unix Timestamp, до которой (включительно) все события будут удалены.

Все события старше 90 дней удаляются автоматически.

Получение информации об атаках

Функционал позволяет получить информацию о заблокированных запросах, включая статистику за период.

Получить список атак
Пример запроса:

# curl http://api.example.com:8080/nw-api/get_attack --header 'Content-type: application/json' --data '{
    "key": "%Лицензионный ключ%",
    "startTime": 1677211703,
    "endTime": 1677211703,
    "bt": [1, 2, 3, 7, 9],
    "ip": ["1.1.1.1", "2.2.2.2", "3.3.3.3"],
    "cc": ["RU", "US", "UK"],
    "vhost": ["example.com", "api.example.com", "shop.example.com"]
}'

Опциональные параметры:

  • startTime и endTime — начальная и конечная дата в формате Unix Timestamp, за который будет запрошена информация;
  • btидентификатор блокировки;
  • ip — IP-адрес;
  • cc — код страны;
  • vhost — виртуальный хост, доменное имя.

Пример ответа:

{
  "status": "success",
  "attacks": [
    {
      "id": 1,
      "timestamp": 1677211703,
      ...
      "description": "%data in plain-text%"
    },
    {
      "id": 2,
      "timestamp": 1234567891,
      ...
      "description": "%data in plain-text%"
    },
    ...
  ]
}

или

{"status": "fail", "description": "%описание ошибки%"}
Запросить статистику атак
Пример запроса:

# curl http://api.example.com:8080/nw-api/get_attack_stats --header 'Content-type: application/json' --data '{
  "key": "%Лицензионный ключ%",
  "startTime": 1677211703,
  "endTime": 1677211753
}'

Опциональные параметры:
startTime и endTime — начальная и конечная дата в формате Unix Timestamp, за который будет запрошена информация.

Пример ответа:

{
  "status": "success",
  "bt": [
    {
      "bt": 1,
      ...
      "period": 14
    },
    {
      "bt": 2,
      ...
      "period": 14
    }
  ],
  "ip": [
    {
      "ip": "1.1.1.1",
      ...
      "period": 14
    },
    {
      "ip": "2.2.2.2",
      ...
      "period": 14
    }
  ],
  "cc": [
    {
      "cc": "RU",
      ...
      "period": 14
    },
    {
      "cc": "US",
      ...
      "period": 14
    }
  ],
  "vhost": [
    {
      "vhost": "example.com",
      ...
      "period": 14
    }
  ]
}

или

{"status": "fail", "description": "%описание ошибки%"}

period — количество событий по каждому bt/сс/vhost/ip за выбранный период;
btидентификатор блокировки;
ip — IP-адрес;
cc — код страны;
vhost — виртуальный хост, доменное имя.

Если период, за который необходимо получить данные, не задан параметрами startTime и endTime, то информация будет выводиться за последние 24 часа, 7 и 30 дней.

{
  "status": "success",
  "bt": [
    {
      "bt": 1,
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    },
    {
      "bt": 2,
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    }
  ],
  "ip": [
    {
      "ip": "1.1.1.1",
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    },
    {
      "ip": "2.2.2.2",
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    }
  ],
  "cc": [
    {
      "cc": "RU",
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    },
    {
      "cc": "US",
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    }
  ],
  "vhost": [
    {
      "vhost": "example.com",
      ...
      "lastDay": 1,
      "last7Days": 13,
      "last30Days": 84
    }
  ]
}

или

{"status": "fail", "description": "%описание ошибки%"}

btидентификатор блокировки;
ip — IP-адрес;
cc — код страны;
vhost — виртуальный хост, доменное имя.