Hybrid Analysis 批量提交脚本

该 Python 脚本可递归扫描文件夹，并将可执行文件、脚本、文档及其他相关文件提交至 Hybrid Analysis（Falcon Sandbox）进行自动化恶意软件分析。

功能特点

• 递归遍历目录
• 仅提交支持的文件类型（参见下方列表）
• 跳过空文件、过大文件及已提交过的文件
• 防止路径遍历攻击 – 确保文件位于扫描根目录内
• 跳过符号链接 – 避免重复或非预期的提交
• 使用持久的 requests Session 实现高效的 API 通信
• 在专用用户目录（~/.hybrid_analysis_submitter/）中存储缓存，避免污染扫描文件夹
• 使用本地 SHA‑256 缓存避免重复提交
• 优雅处理 API 速率限制（429 错误）
• 当 API 配额耗尽时自动停止
• 支持通过命令行配置文件夹、文件大小限制、环境 ID 和缓存文件名
• 从 .env 文件中读取 API 密钥，确保安全

依赖

• Python 3.6+
• 有效的 Hybrid Analysis API 密钥（提供免费套餐）

安装

1. 克隆或下载 本脚本到本地机器。

2. 安装所需包：

pip install requests python-dotenv

3. 在与脚本相同的目录中创建 .env 文件，写入你的 API 密钥：

HYBRID_API_KEY=your_api_key_here

你可以通过注册 Hybrid Analysis 获取 API 密钥。

使用方式

从命令行运行脚本，指定要扫描的文件夹：

python submit_to_hybrid.py /path/to/folder

命令行参数

示例

使用默认设置扫描文件夹：

python submit_to_hybrid.py C:\suspicious_files

扫描文件夹，但将大小上限提高到 200 MB，并使用不同的环境（例如 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

示例输出

Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

支持的文件类型

• Windows 可执行文件（PE）：.exe, .scr, .pif, .dll, .com, .cpl
• 安装程序与包：.msi
• Windows 脚本：.bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

官方支持的所有文件类型列表，请参阅 Hybrid Analysis FAQ。

工作原理

1. 递归遍历 – 脚本使用 os.walk() 遍历所有子文件夹。
2. 安全检查 – 它验证每个文件解析后的路径是否位于扫描根目录内（防止路径遍历），并跳过符号链接。
3. 文件过滤 – 检查文件扩展名、大小（0 字节或大于 --max-file-size 的跳过）、以及文件是否已提交过（SHA‑256 缓存）。
4. 提交 – 使用持久化的 requests Session（带 API 密钥）将每个文件上传到 https://hybrid-analysis.com/api/v2/submit/file 端点。
5. 速率限制 – 每次提交后脚本暂停 2 秒。如果收到 HTTP 429（请求过多）响应，则计数错误。连续出现 3 次 429 错误后，扫描自动停止。
6. 缓存持久化 – 成功提交的文件存储在 ~/.hybrid_analysis_submitter/ 内的 JSON 缓存文件中，避免在后续运行中重复提交。缓存保存时已排序，便于人工阅读。

速率限制与配额

• Hybrid Analysis 免费账户有每小时/每日提交限制。
• 脚本检测 HTTP 429 响应，并在出现 3 次此类错误后停止，避免无限重试。
• 提交之间增加 2 秒延迟，以示对 API 的尊重。

重要说明

• API 密钥仅从 .env 文件读取 – 请勿硬编码。
• 空文件（0 字节）始终跳过。
• 大于 --max-file-size 的文件跳过。
• 仅提交扩展名在 ALLOWED_EXTENSIONS 中的文件。
• 符号链接被跳过，以防止重复提交和路径混乱。
• 路径遍历被阻止 – 脚本将跳过任何解析到指定扫描目录之外的文件。
• 缓存可防止在多次运行中重复提交相同的文件，并存储在用户目录（~/.hybrid_analysis_submitter/）中。
• 脚本对每个 HTTP 请求使用 120 秒超时。
• 缓存文件存储在专用目录中，不会与扫描内容混在一起。

故障排除

许可证

本脚本按“原样”提供，仅用于教育和安全分析目的。请负责任地使用，并遵守 Hybrid Analysis 服务条款。

免责声明

向第三方沙箱提交文件可能会暴露潜在的敏感内容。请确保在上传前拥有分享这些文件的权利。