Скрипт пакетной отправки в Hybrid Analysis

Этот скрипт на Python рекурсивно сканирует папку и отправляет исполняемые файлы, скрипты, документы и другие релевантные файлы в Hybrid Analysis (Falcon Sandbox) для автоматического анализа вредоносного ПО.

Возможности

• Рекурсивный обход каталогов
• Отправка только поддерживаемых типов файлов (см. список ниже)
• Пропуск пустых, слишком больших или ранее отправленных файлов
• Предотвращение атак с обходом пути – гарантирует, что файлы находятся в корне сканирования
• Пропуск символических ссылок для избежания дублирования или непреднамеренной отправки
• Использование постоянной сессии requests для эффективного взаимодействия с API
• Хранение кэша в специальной папке пользователя (~/.hybrid_analysis_submitter/) для предотвращения загрязнения сканируемых папок
• Использование локального SHA‑256 кэша для предотвращения повторных отправок
• Корректная обработка ограничения скорости API (ошибки 429)
• Автоматическая остановка при исчерпании квоты API
• Поддержка конфигурации через командную строку: папка, ограничение размера файла, ID среды и имя файла кэша
• Чтение API-ключа из файла .env для безопасности

Требования

• Python 3.6+
• Действительный API-ключ Hybrid Analysis (доступен бесплатный тариф)

Установка

1. Клонируйте или скачайте этот скрипт на вашу локальную машину.

2. Установите необходимые пакеты:

pip install requests python-dotenv

3. Создайте файл .env в той же папке, где находится скрипт, и укажите ваш API-ключ:

HYBRID_API_KEY=ваш_ключ_api_здесь

Вы можете получить API-ключ, зарегистрировавшись на Hybrid Analysis.

Использование

Запустите скрипт из командной строки, указав папку для сканирования:

python submit_to_hybrid.py /путь/к/папке

Аргументы командной строки

Примеры

Сканирование папки с настройками по умолчанию:

python submit_to_hybrid.py C:\подозрительные_файлы

Сканирование папки с увеличением лимита размера до 200 МБ и использованием другой среды (например, Android):

python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

Использование собственного имени файла кэша:

python submit_to_hybrid.py ./malware --cache-file my_cache.json

Пример вывода

Сканирование папки: C:\подозрительные_файлы

Отправка: C:\подозрительные_файлы\malware.exe (2.34 МБ)
 -> Успешно! ID задания: 5f8a9c2d3e4f5a6b7c8d9e0f
Отправка: C:\подозрительные_файлы\document.pdf (0.12 МБ)
 -> Успешно! ID задания: 6g9b0c1d2e3f4a5b6c7d8e9f
Пропуск уже отправленного: C:\подозрительные_файлы\malware.exe
Пропуск симлинка: C:\подозрительные_файлы\link_to_malware.exe

Готово.
Файлов найдено:      42
Файлов отправлено:   35
Файлов пропущено:    6
Файлов с ошибкой:    1

Поддерживаемые типы файлов

• Исполняемые файлы Windows (PE): .exe, .scr, .pif, .dll, .com, .cpl
• Установщики и пакеты: .msi
• Скрипты Windows: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

Официальный список всех поддерживаемых типов файлов можно найти в FAQ Hybrid Analysis.

Как это работает

1. Рекурсивный обход – скрипт использует os.walk() для обхода всех подпапок.
2. Проверки безопасности – проверяет, что каждый файл разрешается в путь внутри корня сканирования (предотвращает обход пути) и пропускает символические ссылки.
3. Фильтрация файлов – проверяет расширение файла, размер (пропускаются 0 байт или > --max-file-size), а также был ли файл отправлен ранее (SHA‑256 кэш).
4. Отправка – каждый файл загружается на конечную точку https://hybrid-analysis.com/api/v2/submit/file через постоянную сессию requests с вашим API-ключом.
5. Ограничение скорости – после каждой отправки скрипт делает паузу на 2 секунды. При получении HTTP 429 (Too Many Requests) он подсчитывает ошибку. После 3 последовательных ошибок 429 сканирование останавливается автоматически.
6. Постоянное хранение кэша – успешно отправленные файлы сохраняются в файле JSON-кэша внутри ~/.hybrid_analysis_submitter/, чтобы не отправлять их повторно в будущих запусках. Кэш сохраняется отсортированным для удобства чтения.

Ограничение скорости и квоты

• У бесплатных аккаунтов Hybrid Analysis есть часовые/дневные лимиты отправки.
• Скрипт обнаруживает ответы HTTP 429 и останавливается после 3 таких ошибок, чтобы избежать бесконечных повторных попыток.
• Для уважительного отношения к API добавлена задержка в 2 секунды между отправками.

Важные замечания

• API-ключ читается только из файла .env – не встраивайте его напрямую в код.
• Пустые файлы (0 байт) всегда пропускаются.
• Файлы размером больше --max-file-size пропускаются.
• Отправляются только файлы с расширениями из ALLOWED_EXTENSIONS.
• Символические ссылки пропускаются для предотвращения дублирования и путаницы с путями.
• Предотвращается обход пути – скрипт пропустит любой файл, который разрешается за пределы указанной директории сканирования.
• Кэш предотвращает повторную отправку одинаковых файлов при нескольких запусках и хранится в вашей домашней папке (~/.hybrid_analysis_submitter/).
• Для каждого HTTP-запроса используется таймаут в 120 секунд.
• Файлы кэша хранятся в специальной папке – не смешиваются с сканируемым содержимым.

Устранение неполадок

Лицензия

Данный скрипт предоставляется «как есть» для образовательных целей и целей анализа безопасности. Используйте ответственно и в соответствии с Условиями использования Hybrid Analysis.

Отказ от ответственности

Отправка файлов в стороннюю песочницу может привести к раскрытию потенциально конфиденциального содержимого. Убедитесь, что у вас есть право делиться файлами перед загрузкой.