NAD-Alert-Bot

Телеграм-бот для оповещения о появлении сработавших правил обнаружения атак в PT NAD, полученных по механизму webhook, в каналы и общие чаты. По умолчанию бот будет оповещать о срабатываниях наиболее опасных "красных" правил, с которыми необходимо работать в первую очередь. Если правила срабатывают на легитимную активность, рекомендуется добавлять исключения для этих правил.

Рекомендуется установка на отдельном сервере, однако возможна и на сервере с установленным NAD.

Установка и настройка

0. Предварительные условия
   • Установленные Python >= 3.9 и pip
   • Создать Telegram бота с помощью @BotFather
   • Сертификат и приватный ключ для HTTPS (По умолчанию используются cert.pem, key.pem)
   • Сетевой доступ с узла, где установлен бот, к api.telegram.com
   • Сетевой доступ с NAD, по выбранному порту, до узла, где установлен бот
1. Скопировать репозиторий

git clone https://github.com/Security-Experts-Community/NAD-Alert-Bot.git

2. Установить зависимости

pip install -r requirements.txt

3. Выполнить конфигурацию, заполнив обязательные поля в config.yaml либо используя переменные окружения В разделе telegram: - bot_token - токен бота, полученный от @BotFather ( env TELEGRAM_BOT_TOKEN) - chat_id - идентификатор канала/чата, в который будет писать бот (env TELEGRAM_CHAT_ID) В разделе webhook: - secret_token - по умолчанию, ссылка для webhook генерируется в виде /webhook/{secret_token} (env WEBHOOK_SECRET_TOKEN) Остальные поля и разделы являются опциональными
4. Запустить работу бота

python main.py

5. Сконфигурировать NAD для работы, следуя справке. В типах, отправляемых сообщения должно быть выбрано только Атаки. По умолчанию, вебсервер бота слушает запросы на порту 8000.

После завершения конфигурации PT NAD, не забудьте применить изменения, нажав на кнопку Применить все

В случае правильной конфигурации и доступности серверов Telegram'а, в канал придет уведомление об успешном запуске бота. Кроме того, при получении алертов от NADа, в логе, должно увеличиваться число Received requests: N.

Рекомендуется все действия выполнять в виртуальном окружении venv.

---

Для более удобной установки и настройки окружения доступен скрипт setup_env.sh

chmod +x setup_env.sh 
./setup_env.sh --python [nad, system, custom] --create-service --tls --cn "example.com"

• Если системный python имеет версию <3.9, а бота необходимо запустить на сервере, с установленным NAD, то имеется возможность создать виртуальное окружение, используя ptnad-python. Для этого необходимо указать параметр --python nad

• При указании параметра --create-service будет создан systemd сервис для запуска бота, через указанный в параметре python интерпретатор.

  При создании сервиса может быть запрошен пароль для sudo

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

   sudo systemctl start nad_alert_bot
   sudo systemctl enable nad_alert_bot
  

• При указании параметра --tls будут автоматически сгенерирован сертификат и ключ, которые можно использовать с ботом для работы https. Имеется возможность указать вручную CN, используя параметр --cn (По умолчанию в CN используется localhost)

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

chmod +x run_bot.sh
./run_bot.sh

---

Параметры конфигурации:

• Раздел telegram:

Параметр	Описание	Значение по умолчанию
bot_token	Обязательный. Необходимо заполнить токеном бота, полученным от @BotFather. Также может быть заполнено в переменной окружения TELEGRAM_BOT_TOKEN
chat_id	Обязательный. Необходимо указать идентификатор канала/чата, в который будет писать бот.

• Раздел webhook:

Параметр	Описание	Значение по умолчанию
secret_token	Обязательный. Необходимо указать произвольную строку, она будет использоваться для генерации ссылки, на которую необходимо будет со стороны NADа отправлять сообщения по механизму webhook. URL будет представлен в виде /webhook/{secret_token}

• Раздел fastapi:

Параметр	Описание	Значение по умолчанию
port	Порт, который будет "слушать" webook-запросы от NADа	8000
tls_keyfile	Ключ, для работы HTTPS	key.pem
tls_certfile	Сертификат, для работы HTTPS	cert.pem

• Раздел alert:

Параметр	Описание	Значение по умолчанию
priority_filter	Значения приоритетов, оповещения по которым необходимо получать (от 1 до 4, заполняется в виде массива необходимых, например [1, 2, 3, 4]). 1 - Красные, 2 - Желтые, 3 - Синие, 4 - Серые.	[1]
max_buffer_time	Количество секунд, в рамках которых выполняется группировка алертов.	300
timezone	Часовой пояс, используемый оператором NADа в формате "UTC", "Asia/Tokyo", "Europe/Moscow" и т. д.	"UTC"
rules_filter	Фильтр правил по вендорам. Может принимать значения: "PT", "ET", "Custom". Заполняется в виде массива. Пустой массив = фильтрация отключена. Custom - правила, не относящиеся к PT и ET.	["PT"]
ignore_sids	Список sid'ов, о которых не надо оповещать. Заполняется в виде [10000001, 10000002, ...]	[]
ignore_msg	Список ключевых слов, при наличии которых в msg, оповещение не будет генерироваться. ["TEST", "ATTACK", ...]	[]
force_session_link	Если данный параметр включен, то при появлении единственного алерта, в оповещении будет ссылка на сессию, в которой произошла сработка.	false
show_nad_source	Если данный параметр, включен, то в скобках рядом с ссылкой на список алертов в NADе, будет указан hostname NADа в котором они и произошли. Может быть полезно, если данные поступают сразу со множества NADов.	false

• Раздел logging:

Параметр	Описание	Значение по умолчанию
file	Файл, предназначенный для логирования	bot.log
level	Уровень логирования ("DEBUG", "INFO", ...)	"INFO"

---

FAQ

Как получить chat_id?

После создания канала в telgram, добавьте туда бота, как администратора и отправьте в этот канал любое сообщение. После этого сделайте GET запрос на https://api.telegram.org/bot{bot_token}/getUpdates, где bot_token - ваш токен бота, полученный от BotFather. В ответе будет json, из которого можно узнать идентификатор канала, он будет иметь префикс -100. ("chat":{"id”:-1001337,”title":"test”)

Как вручную сгенерировать сертификат, необходимый для работы HTTPS?

openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365