«Cкрытые» возможности PT Sandbox, или Как пользоваться OAS/Swagger и WEB UI API

Еще будучи обычным инженером, я часто проводил пилотные демонстрации PT Sandbox. Основной проблемой было доставить на стенд семплы ВПО не привлекая внимания санитаров СЗИ и ИБ-службы заказчика. И конечно, при работе с вредоносами нельзя забывать о статье 273 УК РФ, которая добавляет сложности и без того непростой задаче. В процессе ее решения я, сам того не заметив, глубоко погрузился во внутренности нашей песочницы, а теперь хочу рассказать о некоторых ее «скрытых» возможностях.

«Почему скрытых и почему в кавычках?» — спросите вы. Смотрите: у PT Sandbox есть хорошо задокументированный публичный API, на основе которого мы создали бесчисленное количество интеграций (например, с CommuniGate и с Telegram-ботом для проверки файлов и ссылок). Как показывает практика, с помощью одного этого API песочницу можно встроить практически в любой пайплайн обработки данных. Хотите прикрутить S3-хранилище? Можно подключить его как сетевой диск с помощью стандартного коннектора. Либо написать небольшой скрипт, чтобы получать ссылки на каждый добавленный в S3 объект из Kafka-топика и забирать объекты по ссылкам, а вердикты отправлять в другой топик (или топики — в зависимости от требуемой логики). То есть формально в документации не заявлена возможность интеграции с Kafka, но она есть.

А почему все-таки в кавычках? Все просто: если у вас есть стенд PT Sandbox, откройте в браузере ссылку https://<sandbox.address>/api/docs/ — и увидите следующую картинку (см. рис. 1).

Да, у PT Sandbox есть встроенная документация по всем API-методам в формате OpenAPI Specification (ранее известная как Swagger Specification). В ней описаны методы не только Public API, но и UI API, о которых не говорится в официальной справке, причем данные обновляются с каждым новым релизом. Но читайте это так: если что-то можно сделать через веб-интерфейс, это можно сделать с помощью скрипта! Если вы (как и я) «выучили» Python на удаленке в период ковидных локдаунов и программирование — не ваша основная работа, то налейте себе чашечку чая/кофе: сейчас расскажу, как можно использовать эти «скрытые» возможности. 

OAS

С OAS можно работать прямо со страницы документации — для этого достаточно выпустить токен с нужными разрешениями и вставить его в поле авторизации (см. рис. 2–3).

После авторизации можно выполнить тестовый запрос. Давайте, к примеру, запросим информацию о текущей версии продукта:

• скроллим до раздела maintenance;
• открываем метод GET maintenance / getVersion (собственно получение версии);
• нажимаем Try it out;
• жмем на Execute (для получения версии не нужно передавать дополнительные параметры).

Если все прошло хорошо, вы получите json с версией продукта (см. рис. 4).

Ошиблись с токеном? Получите в ответ «Authorization required». Бывает! Отмечу, что, если у вас несколько пеcочниц, в этом интерфейсе можно обращаться к разным серверам. Поэтому не забывайте указывать в примечаниях к токенам, к какому именно серверу обращаетесь.

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

Если вы тоже постоянно ходите с приподнятой бровью, то на рис. 4 наверняка заметили: помимо json и заголовков OAS, я любезно предоставил вам полный запрос в формате curl. Берите и гоняйте через командную строку!

UI API

Пора погружаться глубже. Переходим на вкладку UI API: увы, токен для Public API уже не сработает.

Когда я задумал написать эту статью, как раз вышла новость: для работы с API продуктов, зарегистрированных в PT MC, теперь можно выпускать PAT-токены. Причем с довольного гибким сроком действия: хочешь, выпускай сразу на ГОД и используй в интеграциях! Увы, есть и ложка дегтя, даже две:

• с этим токеном доступны не все возможности UI API;
• даже доступные привилегии работают не совсем стабильно, если используется внешний PT MC.

В общем, для работы с UI API лучше по старинке выпускать сессионные токены в PT MC. Я честно пробовал получить их в интерфейсе OAS, но это, прямо скажем, не слишком удобно. Поэтому воспользуемся еще одной приятной фичей: выгрузим спецификацию в формате json (ui-bundle.json, ссылка есть в левом верхнем углу на рис. 6) и загрузим в API-клиент — у меня Bruno, но подойдет почти любое современное решение.

После импорта вам будут доступны все API-методы — с ними можно комфортно работать.

Но и это еще не все... Помните, как мы выгружали запрос в формате curl в интерфейсе OAS? В API-клиенте его можно выгрузить в виде кода практически для любого языка программирования! 

Python — то, что нужно, чтобы перейти к практической части. Давайте напишем самый простой, но полезный интеграционный модуль для управления ЧБ-списками. Use case: ФСТЭК присылает IoC в виде хэшей SHA256 и MD5, ваша песочница работает в блокирующем режиме и вы хотите блокировать соответствующие файлы не дожидаясь анализа. Конечно, это можно сделать руками аналитика или администратора песочницы через UI, но, если поток IoC’ов большой, есть шанс, что человек будет постоянно заниматься копипастой. Согласитесь, не у всех есть бюджет, чтобы содержать такого «ценного» спеца в SOC. Значит, автоматизируем!

Что для этого нужно:

• получить токен авторизации у PT MC;
• дернуть ручку API GET /api/ui/v2/bw_list/export и сохранить текущий список (на случай, если что-то пойдет не так и нужно будет восстановить список);
• дернуть ручку API POST /api/ui/v2/bw_list для добавления полученного IoC в черный список;
• можно также добавить возможность фильтрации списка по заданным параметрам — ручка API GET /api/ui/v2/bw_list.

Я уже упоминал, что получить токен у PT MC по описанию API, не сломав себе мозг, могут «не только лишь все». Поэтому сразу обозначу основные подводные камни (детали доступны по нажатию F12 в браузере):

• fingerprint — уникальный идентификатор устройства пользователя, строка из 32 символов. Ее можно генерировать рандомно на каждый запрос, а можно захардкодить для скрипта специфичное значение, чтобы потом отслеживать активность в логах PT MC. Это может быть полезно для дебага, если вы используете существующую УЗ, а не создаете для скрипта новую.
• authType — не описан в спецификации, но, если PT MC интегрирован с LDAP, это дополнительный параметр в запросе авторизации.

Хорошая практика — создание для скриптов отдельной УЗ (если есть такая возможность). При этом нужно помнить, что в PT Sandbox пользователь с ролью «Администратор» имеет доступ только к настройкам продукта и к результатам своих заданий. Чтобы получить доступ ко всем заданиям УЗ, добавьте роль «Специалист по безопасности».

Теперь можно написать функцию, чтобы получить токен для авторизации запросов в UI API. Надеюсь, Python у вас установлен :) Версия не особенно важна, лишь бы поддерживалась (на момент написания статьи — 3.10 и выше). Проводить эксперименты можно в любой ОС. 

Для удобства создадим отдельную директорию, а в ней — виртуальное окружение, куда установим библиотеку requests:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

Создаем файл config.py, который будет содержать данные для авторизации:

Заполняем config.py своими данными, создаем файл get_token.py и прописываем туда функцию авторизации:

Настало время убедиться, что все работает. После вызова функция должна вернуть вам сессионный токен (см. рис. 11).

Получилось? Отлично, идем дальше! Создаем файл get_bw.py, идем в Bruno (или любой другой агент) и генерируем код для запроса содержимого ЧБ-списков. Видим, что у запроса могут быть дополнительные параметры, по которым формируется ответ сервера. Чтобы уточнить дефолтные параметры, открываем страничку OAS. В итоге получаем следующий код (см. рис. 12).

Осталось записать код в файл get_bw.py и трансформировать его в функцию. Итоговый результат будет выглядеть так:

Если все сделано верно, вы получите ответ в формате json, сформированный по указанным параметрам (см. рис. 14).

Осталось самое интересное: добавим запись в черный список через API. Например, SHA256 файла EICAR.com. Смотрим необходимые параметры для запроса в OAS, генерируем код в API-клиенте, переносим код в файл insert_bw.py:

Запускаем скрипт и проверяем результат в интерфейсе PT Sandbox (см. рис. 16).

Поздравляю! Вы получили базовые навыки работы с OAS и UI API — теперь можете разработать свой интеграционный сервис, используя фреймворки flask и FastAPI. Либо скомпилировать код в бинарный файл и использовать его как утилиту в CLI.

***

Не буду скрывать основной минус описанного подхода: UI API официально не задокументирован, и по нему невозможно получить поддержку. Наша команда разработки не может гарантировать, что UI API кардинально не изменится в следующем релизе и ваш сервис не превратится в тыкву :( Но полноценная поддержка есть у Public API, так что, если вам нужна стабильность, используйте его.

Если вы разрабатываете сервисы интеграции с помощью UI API и хотите гарантировать их работоспособность при обновлении продукта (или получить немного времени на доработку перед публичным релизом), то разверните тестовый стенд и получите лицензию для использования на нем RC-сборок (если вам доступны такие опции). 

Если же вам нужна готовая библиотека с функциями авторизации и работы с UI API, добро пожаловать в наш каталог расширений! Там есть полностью типизированная асинхронная библиотека Py-ptsandbox, написанная моими коллегами. Форкайте, ставьте лайки, контрибьютьте и вливайтесь в ряды Security Experts Community. Тогда отсутствие официальной поддержки вам никак не помешает, ведь у вас будет поддержка целого сообщества экспертов ;) 

Happy hacking!