hybridanalysis

用于 Hybrid Analysis (Falcon Sandbox) API v2 的 Python 库和 CLI

## 概述 **hybridanalysis** 是一个 Python 工具包，用于通过 [API v2](https://hybrid-analysis.com/docs/api/v2) 向 [Hybrid Analysis](https://hybrid-analysis.com) (Falcon Sandbox) 服务提交样本并执行查询。它提供了一个**同步**和 一个**异步**客户端（具有相同的接口）、一个功能齐全的 **CLI**，以及一个类型化的 异常层次结构 — 涵盖了所有十个 API 标签下当前所有的（未废弃的）endpoint。 ### 主要特性 | 特性 | 描述 | |---------|-------------| | **全 API 覆盖** | 涵盖 `feed`、`key`、`overview`、`quick-scan`、`submit`、`report`、`search`、`file-collection`、`abuse-reports`、`system` 下所有当前的 v2 endpoint | | **同步 + 异步** | `HybridAnalysisClient` (httpx) 和 `AsyncHybridAnalysisClient` (httpx async) 拥有相同的方法 | | **CLI + 库** | 既可作为 `hybridanalysis` 命令行工具使用，也可作为 Python 包使用 | | **强大的搜索** | 支持按 domain、host/IP、URL、恶意软件家族、tag、MITRE ATT&CK 技术、hash 相似度等进行查询 | | **文件提交** | 支持完整的 sandbox 和 quick-scan multipart 上传 | | **多种输出格式** | 用于分析结果的 JSON、token 效率高的 TOON 以及 SARIF 2.1.0 (`--format`) | | **灵活的配置** | 支持环境变量或本地 TOML 文件 | ### 支持的接口 ``` Clients HybridAnalysisClient (sync), AsyncHybridAnalysisClient (async) Tags feed · key · overview · quick-scan · submit · report search · file-collection · abuse-reports · system Downloads sample, pcap, certificate, dropped files, memory strings (bytes/text) Config HYBRIDANALYSIS env var · ~/.config/hybridanalysis/config.toml Errors AuthenticationError · NotFoundError · RateLimitError · APIError NetworkError · ConfigError (all subclass HybridAnalysisError) ``` ## 安装 ### 从源码安装 ``` git clone https://github.com/seifreed/hybridanalysis.git cd hybridanalysis python3.14 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e ".[dev]" ``` ## 配置 API key 按以下顺序解析： 1. `HYBRIDANALYSIS` 环境变量。 2. 本地 TOML 文件 — `./.hybridanalysis.toml` 或 `~/.config/hybridanalysis/config.toml`： [hybridanalysis] api_key = "your-api-key" # base_url = "https://hybrid-analysis.com/api/v2" # 可选 # user_agent = "Falcon Sandbox" # 可选 # timeout = 60 # 可选，单位秒 每个字段也有相应的环境变量，且优先级高于配置文件： `HYBRIDANALYSIS_URL`、`HYBRIDANALYSIS_USER_AGENT` 和 `HYBRIDANALYSIS_TIMEOUT`。 ## 快速开始 ``` export HYBRIDANALYSIS="your-api-key" # 系统 / 关键信息 hybridanalysis system version hybridanalysis key current # 提交样本并轮询其报告 hybridanalysis submit file sample.exe environment_id=160 hybridanalysis report summary ``` ## 用法 ### 命令行界面 ``` # 查找 hash（任意格式 -> SHA256）及其报告 hybridanalysis search hash # 按行为 / 基础设施搜索 hybridanalysis search terms host=8.8.8.8 hybridanalysis search terms vx_family=nemucod verdict=5 hybridanalysis search terms uses_technique=T1055 # 提交进行分析 hybridanalysis submit file sample.exe environment_id=160 hybridanalysis quick-scan file sample.exe --scan-type all # 下载 binary artifacts（到文件，或在省略 --out 时输出到 stdout） hybridanalysis report pcap --out capture.pcap hybridanalysis overview sample --out sample.gz ``` `--api-key`、`--base-url` 和 `--config` 会覆盖已解析的配置。 `python -m hybridanalysis` 可作为 `hybridanalysis` 命令的替代方案。 ### 输出格式 每个返回 JSON 的命令都接受 `-f` / `--format`： ``` hybridanalysis overview get --format toon # token-efficient JSON hybridanalysis report summary --format sarif # SARIF 2.1.0 findings ``` | 格式 | 适用命令 | 描述 | |--------|--------------|-------------| | `json` | 所有命令（默认） | 带缩进的 JSON。 | | `toon` | 所有命令 | [TOON](https://github.com/toon-format/toon) — 一种紧凑、无损的 JSON 编码方式，使用的 token 更少。 | | `sarif` | 分析命令（`feed`、`overview`、`search`、`quick-scan`、`report`） | SARIF 2.1.0：`verdict` 和每个 `signatures[]` 条目都会转换为结果，其级别由 verdict / 威胁级别推导而来。artifact 位置取自命令的 SHA256 / report-id 参数。 | ### 命令组 | 命令 | 描述 | |---------|-------------| | `hybridanalysis system` | 实例版本、环境、操作脚本、统计信息、配置、队列 | | `hybridanalysis key` | API key 信息和提交配额 | | `hybridanalysis feed` | 最近的沙箱执行和 quick-scan 订阅源 | | `hybridanalysis overview` | 针对 SHA256 的汇总报告（+ 样本下载） | | `hybridanalysis search` | Hash 查找和多字段词条搜索 | | `hybridanalysis quick-scan` | 对文件/URL 进行 quick-scan 及结果检索 | | `hybridanalysis submit` | 对文件、URL 和丢弃文件进行 sandbox 提交 | | `hybridanalysis report` | 报告状态/摘要和 artifact 下载 | | `hybridanalysis file-collection` | 创建、搜索和管理文件集合 | | `hybridanalysis abuse-reports` | 请求删除报告；已移除 hash 的订阅源 | ## Python 库 ### 同步 ``` from hybridanalysis import HybridAnalysisClient with HybridAnalysisClient.from_env() as client: print(client.system.version()) # Submit a file and poll its report submitted = client.submit.file("sample.exe", environment_id="160") job_id = submitted["job_id"] print(client.report.state(job_id)) print(client.report.summary(job_id)) # Download binary artifacts (returned as bytes) pcap = client.report.pcap(job_id) # Search (verdict is numeric 1-5, 5 = malicious) client.search.terms(filetype="peexe", verdict="5") ``` ### 异步 ``` import asyncio from hybridanalysis import AsyncHybridAnalysisClient async def main(): async with AsyncHybridAnalysisClient.from_env() as client: print(await client.system.version()) results = await asyncio.gather(*(client.overview.get(h) for h in hashes)) asyncio.run(main()) ``` 错误会引发 `HybridAnalysisError` 的子类：`AuthenticationError`、 `NotFoundError`、`RateLimitError`、`APIError`、`NetworkError` 和 `ConfigError`。 ## 环境要求 - Python 3.14+ - 有关依赖和扩展功能，请参阅 [pyproject.toml](pyproject.toml) ## 许可证 本项目基于 MIT 许可证授权。请参阅 [LICENSE](LICENSE)。 **致谢** - 作者：**Marc Rivero López** | [@seifreed](https://github.com/seifreed) - 代码仓库：[github.com/seifreed/hybridanalysis](https://github.com/seifreed/hybridanalysis)

_{为实用的恶意软件分析和安全自动化而构建}

标签：API客户端, DAST, 异步编程, 恶意软件分析, 文档结构分析, 沙箱, 计算机取证, 运行时操纵, 逆向工具