PTSB-NOTIFIER

Telegram-бот для отправки уведомлений о новых сработках в системе Positive Technologies Sandbox

Текущая версия приложения проверена и работает с указанной версией PT Sandbox

📋 Содержание

• Описание проекта
• Требования
• Установка приложения
• Удаление приложения
• Изменение конфигурации приложения
• Обновление приложения
• Участие в разработке
• Лицензия
• Авторы

📖 Описание проекта

Данная утилита предназначена для отправки уведомлений о новых подозрительных вердиктах в системе Positive Technologies Sandbox через Telegram-бота.

Принцип работы

Основная интеграция этого приложения и PT Sandbox выполняется по протоколу syslog (на транспортном уровне используется TCP).

Приложение:

1. Прослушивает весь входящий трафик на специализированном порту
2. Отсеивает неподходящие syslog-события
3. Выбирает только те события, которые содержат подстроку - scan_machine.final_result - (событие вынесения вердикта по заданию)
4. Выполняет фильтрацию по тело сообщения → result → verdict → threat_level
5. Отправляет информацию через Telegram-бота, если уровень угрозы соответствует настройкам пользователя

⚙️ Требования

• Docker с модулем Docker Compose для запуска приложения в контейнере

• Сетевая доступность для трансляции syslog-сообщений от PT Sandbox до хоста с приложением

  ℹ️ Встроенный сервер работает по протоколу TCP. Приём UDP сообщений не тестировался. Syslog-сообщения могут транслироваться через балансировщики нагрузки.

• Доступ к https://api.telegram.org для взаимодействия с Telegram Bot API

• Аккаунт в Telegram

🚀 Установка приложения

1️⃣ Создание бота в Telegram

Для работы Telegram-бота необходимо получить токен доступа.

1. Перейдите в диалог с BotFather — официальным Telegram-ботом для создания новых ботов

2. Отправьте команду /start

3. Выберите /newbot из предложенного списка

4. Введите имя для создаваемого бота (любое название в рамках цензуры, не обязательно уникальное)

5. Введите username (ссылку) для бота:

   • Должен быть уникальным
   • Должен заканчиваться на bot
   • При некорректном вводе BotFather запросит ввод повторно

6. При успешном создании BotFather предоставит:

   • Ссылку на бота (t.me/<username>) — рекомендуется перейти и нажать "Запустить", чтобы бот отобразился в ваших диалогах
   • Токен доступа — можно скопировать нажатием на текст токена. Понадобится при настройке приложения

⚠️ Важно: Никому не сообщайте токен от вашего бота! При компрометации токена удалите бота через BotFather и создайте нового.

---

2️⃣ Настройка чата в Telegram

Необходимо получить Telegram ID беседы для отправки сообщений.

📱 Для личных сообщений

Если бот должен уведомлять только вас:

1. Перейдите к боту Get My ID для получения вашего ID
2. Отправьте команду /start
3. Скопируйте или запомните числовое значение Your user ID из ответного сообщения

👥 Для групповых сообщений

Если бот должен уведомлять группу пользователей:

1. Создайте группу в Telegram. Название и аватарка могут быть любыми. Приглашать участников пока не требуется

2. Перейдите к боту Get My ID для получения Telegram ID группы

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

4. Скопируйте или запомните числовое значение Current chat ID (включая знак "-", если присутствует)

   ℹ️ Если сообщение не появилось, отправьте /start@getmyid_bot

5. Удалите бота Get My ID из группы через меню управления группой

6. Добавьте вашего основного бота в созданную группу аналогичным образом

🔒 Рекомендации по безопасности группы

• Тип группы: Установить как Частная группа. Новых людей приглашать следует только лично
• Сохранение контента: Запретить копирование (пересылку)
• Разрешения: Выключить все разрешения у пользователей
• Администраторы: Добавить бота как администратора. Это позволит отправлять сообщения, даже если всем пользователям отправка запрещена. Все возможности администратора у бота могут быть выключены

---

3️⃣ Скачивание проекта

Скачайте исходный код одним из способов:

Через Git:

git clone https://github.com/Security-Experts-Community/ptsb-notifier.git

Или скачайте ZIP-архив по ссылке:

https://github.com/Security-Experts-Community/ptsb-notifier/archive/refs/heads/main.zip

---

4️⃣ Установка и настройка

⚠️ Важно: Установка должна выполняться от имени супер пользователя root или sudo.

ℹ️ Порт по умолчанию: Приложение будет слушать входящий syslog-трафик от PT Sandbox на локальном порту 1468 хоста. Если порт занят, измените 1468:514 на <нужный порт>:514 в файле builder/docker-compose.yaml. Порт 514 является внутренним в docker-контейнере и его менять не нужно.

1. Перейдите в директорию проекта:

   cd ptsb-notifier

2. Сделайте установочный скрипт исполняемым:

   chmod +x install.sh

3. Запустите процесс установки:

   sudo ./install.sh

4. Настройте параметры конфигурации:

   ℹ️ Для значений по умолчанию просто нажимайте Enter

   • Адрес веб-интерфейса PT Sandbox:

     Enter value for parameter PTSB_MAIN_WEB (current: ''): 

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

   ---

   • Режим фильтрации угроз (THREAT_FILTER_MODE):

     Режим	Описание	Цветовая индикация
     ALL	Все вердикты	🔘 Серый, 🟡 Жёлтый, 🔴 Красный
     UNWANTED	Потенциально опасное и опасное ПО	🟡 Жёлтый, 🔴 Красный
     DANGEROUS	Только опасное ПО	🔴 Красный

     Enter value for parameter THREAT_FILTER_MODE (current: ALL):

     ⚠️ Важно: Ввод регистрозависим, необходимо вводить значение заглавными буквами.

   ---

   • Токен Telegram-бота:

     Enter value for parameter TG_BOT_TOKEN (current: ''):

     Вставьте токен, который был получен от BotFather при создании бота.

   ---

   • ID чата Telegram:

     Enter value for parameter TG_CHAT_ID (current: ''):

     Введите Telegram ID чата (ваш личный или группы), который был получен ранее. Если содержит знак минус, вставьте с минусом.

   ---

   • Смещение часового пояса от UTC:

     Enter value for parameter UTC_CUSTOM_OFFSET (current: 3):

     Syslog-демон на PT Sandbox отправляет время в UTC+0. Для МСК укажите +3, для МСК-1 укажите +2. Поддерживается ввод отрицательного числа (например, -1).

5. Дождитесь завершения установки:

   ✔ Service ptsb-notifier    Built
   ✔ Container ptsb-notifier  Started

---

5️⃣ Настройка PT Sandbox

В веб-интерфейсе PT Sandbox перейдите: Система → Основные параметры → Отправка сообщений в системный журнал по протоколу syslog

1. Включите отправку сообщений по протоколу syslog
2. В качестве адреса Сервера системного журнала укажите адрес хоста, на котором было развернуто приложение
3. В качестве порта укажите 1468 (или ваш настроенный порт)
4. Протоколом выберите TCP
5. Сохраните изменения и подождите несколько минут для их применения

ℹ️ Примечание: Если syslog-трафик от PT Sandbox будет поступать в приложение через балансировщик — произведите его настройку аналогичным образом.

Для проверки работоспособности приложения, отправьте на проверку любой файл, хэш которого добавлен в черный список.

🗑️ Удаление приложения

⚠️ Важно: Удаление должно выполняться от имени суперпользователя root или через sudo.

1. Перейдите в корневую директорию скачанного проекта:

   cd ptsb-notifier

2. Сделайте файл исполняемым:

   chmod +x uninstall.sh

3. Запустите процесс удаления приложения:

   sudo ./uninstall.sh

По окончании удаления скрипт выведет информацию о том, что удаление docker-контейнера и образа завершено.

🔧 Изменение конфигурации приложения

Изменение конфигурации может потребоваться, если вы хотите поменять параметры (например, токен Telegram-бота или Telegram ID чата). При этом переустановки не происходит.

⚠️ Важно: Изменение конфигурации должно выполняться от имени суперпользователя root или через sudo.

1. Перейдите в корневую директорию скачанного проекта и запустите процесс установки:

   cd ptsb-notifier
   sudo ./install.sh

2. Введите новые значения для тех параметров, которые требуется изменить. Если параметр менять не нужно, просто нажмите Enter

3. При запросе выберите update для переконфигурации основных параметров:

   Image of 'ptsb-notifier' already exists. Do you want to update parameters of application or fully rebuild? (update/rebuild): update

🔄 Обновление приложения

Обновление может потребоваться, если вышла новая версия. В этом случае происходит пересборка приложения.

1️⃣ Ручное обновление

⚠️ Важно: Перед обновлением сохраните текущие параметры: cat config/default.env. При скачивании новой версии через git clone может перезаписаться файл со старыми параметрами.

⚠️ Важно: Обновление должно выполняться от имени суперпользователя root или через sudo.

1. Перейдите в корневую директорию скачанного проекта и запустите процесс установки:

   cd ptsb-notifier
   sudo ./install.sh

2. Если параметр менять не нужно, просто нажмите Enter и значение останется равным тому, что сохранено в скобках

3. При запросе введите rebuild для пересборки приложения:

   Image of 'ptsb-notifier' already exists. Do you want to update parameters of application or fully rebuild? (update/rebuild): rebuild

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

---

2️⃣ Автоматическое обновление

⚠️ Важно: Обновление должно выполняться от имени пользователя владельца директории, где находится сейчас проект. По факту, от того пользователя, который изначально скачивал проект через git clone, а не от имени суперпользователя root или через sudo. Но пользователь должен иметь доступ к sudo правам.

⚠️ Важно: Данный метод работает только при установленном git на хосте.

1. Перейдите в корневую директорию скачанного проекта:

   cd ptsb-notifier

2. Сделайте файл исполянеым:

   chmox +x update.sh

3. Запустите процесс обновления:

   ./update.sh

4. Скрипт проверит, есть ли новые версии в оригинальном репозитории.

   • Если таких версий нет, будет выведено сообщение о том, что используется самая последняя доступная версия.
   • Если новые версии вышли, выведется сообщение обо всех новых коммитах, а также будет предложено установить самую свежую версию из origin/main.

5. Запустится проверка локальных файлов на соответствие файлам в origin/main.

   • Если конфликтов в изменениях нет, то скрипт продолжит работу по обновлению.
   • Если есть конфликты, будет предложено 3 варианта дальнейших действий:
     1. Удаление всех локальных изменений и приведение папки-проекта к виду оригинального репозитория origin/main

        ⚠️ Важно: Будут выполнены команды git reset --hard origin/main и git clean -fd. При этом, файл config/default.env не затрагивается.

     2. Отмена обновления и выход из завершения скрипта обновления без внесения каких-либо изменений.
     3. Ручное разрешение конфликтов для последующего возможного обновления.

        ⚠️ Важно: Если по итогам разрешения конфликтов всё равно будут обнаружены diff файлы - процесс обновления прервется и скрипт завершит выполнение.

6. Выведется сообщение с запросом на перезапуск контейнера приложения. Ввод y или Y осуществит перезапуск:

   Are you ready to proceed with restaring newer version of container? (y/N): y

7. Если для пользователя, запускавшего обновление настроен запрос пароля для выполнения sudo - потребуется ввести пароля для перезапуска контейнера с приложением.

   ⚠️ Важно: В случае трех неудачных попыток ввода пароля - скрипт заверштися с ошибкой. При этом, локальная папка-проект будет соответствовать состоянию самой последней версии origin/main. Однако, новая версия контейнера запущена не будет. В таком случае необходимо запустить скрипт install.sh и выбрать rebuild в конце.

8. Запустится пересборка проекта. По результатам установки будет проверена работоспособность созданного проекта через 5 секунд после запуска. А также будет выведена информация о вновь установленной версии.

🤝 Участие в разработке

Мы приветствуем вклад от сообщества! Если вы хотите внести свой вклад в развитие проекта, ознакомьтесь с руководством по участию в разработке.

Мы приветствуем:

• Сообщения об ошибках и предложения улучшений
• Улучшение документации
• Добавление новых функций
• Улучшение обработки ошибок и логирования

📄 Лицензия

Этот проект распространяется под лицензией Creative Commons Attribution-NonCommercial 4.0 International License.

p.s. If we meet some day, and you think this stuff is worth it, you can buy me a beer in return.

Отказ от обязательств

Автор не имеет отношения к компании Positive Technologies и не является её сотрудником. Также автор не несет ответственности за любые последствия от использования приложения на реальных инсталляциях. Ответственность лежит исключительно на конечном пользователе.

👥 Авторы и контрибьюторы

👨‍💻 Основной разработчик

Кирилл Красновский
Full-fledged work on the project

---

🙏 Благодарности

Роман
Наставничество и поддержка при разработке проекта

Александр
Помощь с оформлением документации, вклад в развитие сообщества