Telegram-бот для проверки файлов и URL-адресов через PT Sandbox API
Текущая версия приложения проверена и работает с указанной версией PT Sandbox
- Описание проекта
- Требования
- Установка приложения
- Удаление приложения
- Изменение конфигурации приложения
- Обновление приложения
- Руководство администратора
- Руководство пользователя
- Участие в разработке
- Лицензия
- Авторы
Приложение представляет собой Docker-контейнер с Telegram-ботом, который служит пользовательским интерфейсом для проверки объектов в песочнице через публичный API.
- Проверка файлов - загрузка и анализ файлов до 20 МБ
- Проверка ссылок - анализ URL-адресов и загружаемого контента
- Поддержка паролей - работа с зашифрованными архивами
- Пересылка файлов - без необходимости скачивания на устройство пользователя
- Ролевая модель - разделение прав администраторов и пользователей
| Функция | Описание |
|---|---|
| Управление пользователями | Создание, блокировка, разблокировка, удаление |
| Бэкап данных | Получение резервных копий базы данных |
| Мониторинг | Проверка состояния API песочницы |
| Аналитика | Информация о доступных проверках |
- Отправка файлов на проверку
- Отправка ссылок на проверку
- Просмотр доступных проверок
- Указание количества доступных проверок в день
- Указание приоритета проверки заданий
- Указание возможности получения пользователем ссылок на задания в системе ptsb
- Docker & Docker Compose - для контейнеризации приложения
- Сетевое подключение - доступ к системе PTSB по порту
443/HTTPS - Интернет-доступ - подключение к
https://api.telegram.orgдля взаимодействовия с Public API Telegram - Аккаунт Telegram - для создания и настройки бота
Для работы Telegram-бота необходимо получить токен доступа. Через этот токен бот будет осуществлять взаимодействие с публичным API Telegram.
-
Перейдите в диалог с BotFather — официальным Telegram-ботом для создания новых ботов
-
Отправьте команду
/start -
Выберите
/newbotиз предложенного списка -
Введите имя для создаваемого бота (любое название в рамках цензуры, не обязательно уникальное)
-
Введите
username(ссылку) для бота:- Должен быть уникальным
- Должен заканчиваться на
bot - При некорректном вводе BotFather запросит ввод повторно
-
При успешном создании BotFather предоставит:
- Ссылку на бота (
t.me/<username>) — рекомендуется перейти и нажать "Запустить", чтобы бот отобразился в ваших диалогах - Токен доступа — можно скопировать нажатием на текст токена. Понадобится при настройке приложения
- Ссылку на бота (
⚠️ Важно: Никому не сообщайте токен от вашего бота! При компрометации токена удалите бота через BotFather и создайте нового.
Необходимо получить Ваш Telegram ID, чтобы занести его в БД пользователей. Таким образом, сразу после запуска бота - Вы будете довернным пользователем в приложении с правами администратора.
- Перейдите к боту Get My ID для получения вашего ID
- Отправьте команду
/start - Скопируйте или запомните числовое значение
Your user IDиз ответного сообщения
Создайте токен доступа и источник для проверки объектов:
Создание токена:
- Перейдите в веб-интерфейс PTSB →
Система→Токены доступа - Нажмите кнопку
Создать токен доступа - В разрешенных действиях укажите: Проверка с параметрами источника
- Нажмите кнопку
Создатьи после сохраните полученное значение токена.
Создание источника:
- Перейдите в веб-интерфейс PTSB →
Источники - Нажмите кнопку
Добавить источник - В типе источника выберите: API с выбранными параметрами проверки
- В разделе
Токен доступаукажите созданный ранее токен - Настройте параметры источника по своему усмотрению
Скачайте исходный код одним из способов:
Через Git:
git clone https://github.com/kaifuss/ptsb-checkbot.gitИли скачайте ZIP-архив по ссылке:
https://github.com/kaifuss/ptsb-checkbot/archive/refs/heads/main.zip
⚠️ Важно: Установка приложения выполняется с правами sudo
-
Перейдите в корневую директорию скачанного проекта:
cd ptsb-checkbot -
Сделайте файл исполняемым:
chmod +x install.sh
-
Запустите процесс установки:
sudo ./install.sh
-
Настройте параметры конфигурации:
ℹ️ Для значений по умолчанию просто нажимайте Enter
- Настройка Telegram-бота:
Input value for parameter TG_BOT_TOKEN (текущее: ''):
Введите токен, который был получен на предыдущих шагах. Достаточно просто скопировать и вставить токен.
- Создание профиля администратора:
Input value for parameter FIRST_BOT_ADMIN_ID (текущее: ''):
Введите
Telegram IDпользователя, который был получен ранее (ваш личный TG ID).
- Настройка адреса PTSB:
Input value for parameter PTSB_ROOT_ADDR (текущее: ''):
Введите адрес веб-интерфейса, по которому доступен PTSB. Если используется FQDN — вводите FQDN вместо IP. Если используется отказоустойчивый кластер — вводите адрес кластера.
- Настройка токена доступа к PTSB:
Input value for parameter PTSB_TOKEN (текущее: ''):
Укажите токен доступа к PTSB, по которому приложение будет авторизовываться в системе, а песочница будет ассоциировать запрос с настроенным ранее источником API.
-
Настройка проверки SSL:
Input value for parameter VERIFY_SSL_CONNECTIONS (текущее: ''):
Укажите, нужно ли проверять валидность SSL соединения с песочницей:
0— не проверять корректность SSL соединения1— проверять SSL сертификат
ℹ️ При выборе
0соединение остается защищенным по HTTPS, но сертификат не проверяется.
-
Завершение установки:
После ввода последнего параметра начнется сборка Docker-образа и установка приложения. По завершении установки выведутся сообщения:
✔ Service ptsb-checkbot Built ✔ Container ptsb-checkbot Started
- Настройка Telegram-бота:
⚠️ Важно: Удаление приложения производится с правами sudo
-
Перейдите в корневую директорию скачанного проекта:
cd ptsb-checkbot -
Сделайте файл исполняемым:
chmod +x uninstall.sh
-
Запустите процесс удаления приложения:
sudo ./uninstall.sh
По окончании удаления скрипт выведет информацию о том, что удаление Docker-контейнера и образа Docker-контейнера завершено.
Изменение конфигурации может потребоваться, если вы хотите поменять какие-то параметры. Например, токен Telegram-бота в связи с созданием нового бота или токен доступа к PTSB. При этом переустановки не происходит, меняются только системные параметры.
⚠️ Важно: ИзменениеFIRST_BOT_ADMIN_IDне рекомендуется, так как это создаст нового пользователя с правами главного администратора. Выполняйте только в том случае, если потеряли доступ к старому аккаунту.
Изменение параметров производится с правами sudo:
-
Перейдите в корневую директорию скачанного проекта:
cd ptsb-checkbot -
Запустите процесс установки:
sudo ./install.sh
-
Введите новые значения для тех параметров, которые требуется изменить. Если какой-то параметр менять не нужно, то просто нажмите
Enterи значение останется равным тому, что сохранено в скобках. -
Скрипт укажет, что образ контейнера уже найден. Введите
updateдля переконфигурации основных параметров приложения:Image of 'ptsb-checkbot' already exists. Do you want to update parameters of application or fully rebuild? (update/rebuild): update
-
По завершении переконфигурации выведутся сообщения:
✔ Service ptsb-checkbot Built ✔ Container ptsb-checkbot Started
Обновление может потребоваться, если вышла новая версия. В этом случае происходит пересборка приложения.
⚠️ Важно: Перед обновлением сохраните текущие параметры:cat config/default.env. При скачивании новой версии черезgit cloneможет перезаписаться файл со старыми параметрами.
Обновление приложения производится с правами sudo:
-
Перейдите в корневую директорию скачанного проекта:
cd ptsb-checkbot -
Запустите процесс установки:
sudo ./install.sh
-
Скрипт укажет, что образ контейнера уже найден. Введите
rebuildдля обновления приложения:Image of 'ptsb-checkbot' already exists. Do you want to update parameters of application or fully rebuild? (update/rebuild): rebuild
-
По завершении пересборки приложения выведутся сообщения:
✔ Network ptsb-checkbot Created ✔ Container ptsb-checkbot Started
Административные действия внутри приложения делятся на действия по управлению пользователями и действия по взаимодействию с песочницей.
Для перехода к управлению пользователями необходимо нажать кнопку 👤 Управление пользователями.
Для создания пользователя необходимо нажать кнопку ➕ Добавить пользователя по ID, после чего начнется заполнение параметров пользователя приложения (бота):
-
Ввод
TG ID:На этом шаге необходимо ввести ID пользователя, который просит, чтобы его добавили в бота. Этот ID может сообщить ему сам бот, если пользователь отправит ему команду
/start.ℹ️ Примечание: Во избежание путаницы просите, чтобы пользователи пересылали вам приветственное сообщение от бота.
-
Ввод роли пользователя:
На этом шаге необходимо указать, какая роль будет доступна пользователю. Бот в ответном сообщении укажет список поддерживаемых ролей и их описание.
-
Ввод комментария:
На этом шаге можно указать любую полезную информацию о пользователе, которая поможет в последствии его как-либо идентифицировать.
-
Ввод количества проверок в день:
На этом шаге нужно указать целое число, которое будет обозначать количество возможных проверок в день, которые может создать пользователь. Считаются как проверки ссылок, так и проверки файлов.
-
Ввод приоритета проверки:
На этом шаге необходимо указать приоритет проверки объектов от этого пользователя. Используется градация согласно официальной документации песочницы.
-
Указание возможности получать ссылки:
На этом шаге нужно указать, будет ли этот пользователь получать ссылки на страницы заданий в системе PTSB. Если вы не хотите, чтобы пользователь знал адрес песочницы вашей организации, запретите пользователю получать ссылки. Для людей, кому адрес песочницы доступен и известен, можете разрешить получать ссылки.
Для получения информации о профиле пользователя внутри бота необходимо нажать кнопку ℹ️ Подробная информация о пользователе по ID, после чего отправить боту TG ID пользователя.
В ответ на это сообщение бот вернет всю доступную информацию по пользователю, включающую в себя как сведения о доступе к боту, так и профиль взаимодействия с песочницей.
Для блокировки пользователя внутри бота необходимо нажать кнопку 🔒 Заблокировать по ID, после чего отправить боту TG ID пользователя.
Заблокированный пользователь теряет возможность отправлять файлы и ссылки на проверку, при этом его профиль продолжает существовать в боте.
Для разблокировки пользователя внутри бота необходимо нажать кнопку 🔓 Разблокировать по ID, после чего отправить боту TG ID пользователя.
Разблокированный пользователь снова получает возможность отправлять файлы и ссылки на проверку.
Для удаления пользователя из бота необходимо нажать кнопку 🗑 Удалить пользователя по ID, после чего отправить боту TG ID пользователя.
Удаленный пользователь теряет возможность отправлять файлы и ссылки на проверку, при этом его профиль больше не существует в боте.
Для перехода к взаимодействию с песочницей необходимо нажать кнопку 🏖 Взаимодействие с песочницей.
Для проверки состояния API необходимо нажать кнопку ✅ Проверить состояние API. Проверка занимает до 10 секунд, поэтому проявите терпение. Это время необходимо для исключения ошибок, связанных с таймаутом подключения.
В ответ бот пришлет сообщение с информацией о том, доступен ли API песочницы или нет. В случае известной ошибки бот даст ее описание, благодаря чему вы сможете ее решить. В случае, если ошибка неизвестна, бот также это подсветит.
Для перехода к меню управления приложением необходимо нажать кнопку 🗄 Получить бэкап БД.
Для получения файла БД приложения, в котором содержится информация обо всех пользователях, необходимо нажать кнопку 🗄 Получить бэкап БД. В ответ на это действие будет отправлен файл БД приложения, который содержит профили пользователей и профили взаимодействия с песочницей на текущий момент времени. В последствии этот файл можно будет использовать для восстановления приложения.
ℹ️ Примечание: Файл можно также использовать для переноса приложения на другой хост. Однако при этом потребуется сначала установить приложение на новом хосте обычным путем из раздела "Установка и настройка", а затем выполнить восстановление с файлом бэкапа БД. Рекомендуется также скопировать файл из директории
config/default.envс настройками приложения.
-
Перейдите в корневую директорию скачанного проекта:
cd ptsb-checkbot -
Создайте директорию для базы данных (если она еще не существует):
mkdir ptsb-checkbot/database
-
Перенесите полученный ранее файл без изменения его названия:
cp /path/to/kernel_base.db ptsb-checkbot/database
-
Сделайте файл исполняемым:
chmod +x install.sh
-
Запустите процесс установки приложения с восстановлением:
sudo ./install.sh --backup_db=true
-
Введите новые параметры приложения или оставьте их равными текущим.
-
Скрипт укажет, что образ контейнера уже найден. Введите
rebuildдля пересборки приложения с новой БД:Image of 'ptsb-checkbot' already exists. Do you want to update parameters of application or fully rebuild? (update/rebuild): rebuild
-
По завершении пересборки приложения выведутся сообщения:
✔ Network ptsb-checkbot Created ✔ Container ptsb-checkbot Started
Для перехода к взаимодействию с песочницей необходимо нажать кнопку 🏖 Взаимодействие с песочницей.
Для отправки файла на проверку нажмите кнопку 📁 Отправить файл на проверку. После чего начнется указание параметров проверки и загрузка файла в бота.
-
Загрузка файла:
Сперва загрузите файл, который необходимо проверить. Вы также можете переслать сообщение от другого пользователя, при этом скачивать его к себе на устройство не придется.
ℹ️ Примечание: Поддерживается загрузка 1 файла размером до 20 МБ. В случае, если отправить файл большего размера, загрузить его бот не сможет — это ограничения Telegram. Если отправить больше 1 файла — бот возьмет только первый из них.
-
Указание паролей:
Введите пароли для проверки файла, если вы знаете, что файл зашифрован. Поддерживается ввод до 5 паролей, каждый из которых отделяется от другого вводом с новой строки (
Shift+Enterпо умолчанию для Telegram). Если паролей нет, нажмите кнопку⏫ Отправить на проверкуи задание будет проверено без указания паролей. -
Отслеживание результатов:
Для получения результатов проверки периодически (но не чаще
10 секунд) обновляйте статус задания нажатием кнопки🔄 Обновить статус задания. Если результаты проверки были получены — бот сообщит об этом и вернет вас в главное меню.
Для перехода к отправке ссылки необходимо нажать кнопку 🔗 Отправить ссылку на проверку.
-
Ввод ссылки:
Отправьте боту ссылку, которую необходимо проверить, указав ее текстом в сообщении.
-
Указание паролей:
Введите пароли для проверки файла, который скачается по этой ссылке, если вы знаете, что файл зашифрован. Поддерживается ввод до 5 паролей, каждый из которых отделяется от другого вводом с новой строки (
Shift+Enterпо умолчанию для Telegram). Если паролей нет, нажмите кнопку⏫ Отправить на проверкуи задание будет проверено без указания паролей. -
Отслеживание результатов:
Для получения результатов проверки периодически (но не чаще
10 секунд) обновляйте статус задания нажатием кнопки🔄 Обновить статус задания. Если результаты проверки были получены — бот сообщит об этом и вернет вас в главное меню.
Для получения информации об оставшемся количестве проверок на сегодня необходимо нажать кнопку 📊 Получить сведения о проверках.
В ответ на это бот вернет сообщение, в котором будет указана информация о количестве проверок, доступных для вас.
Мы приветствуем вклад от сообщества! Если вы хотите внести свой вклад в развитие проекта, ознакомьтесь с руководством по участию в разработке.
Мы приветствуем:
- Сообщения об ошибках и предложения улучшений
- Улучшение документации
- Добавление новых функций
- Улучшение обработки ошибок и логирования
Этот проект распространяется под лицензией 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 и не является её сотрудником. Также автор не несет ответственности за любые последствия от использования приложения на реальных инсталляциях. Ответственность лежит исключительно на конечном пользователе.
