Ozer0x777/Heimdall

# Heimdall — 恶意软件分析流水线 **阿斯加德的守望者** | v1.0.0 | 作者：Ozer0x777 全自动多沙箱恶意软件分析流水线。并行提交文件或 SHA-256 哈希至 VirusTotal、MalwareBazar、Hybrid Analysis、JoeSandbox 和 Any.run，然后将判定结果汇总到 CSV、HTML 和/或 STIX 2.1 报告中。 ## 功能 | 功能 | 详情 | |---|---| | **多沙箱** | VirusTotal v3、MalwareBazar、Hybrid Analysis、JoeSandbox、Any.run | | **哈希优先** | 上传前查找 SHA-256 — 避免重复提交 | | **并行处理** | `ThreadPoolExecutor` — 所有 API 同时运行 | | **本地 YARA** | 离线扫描 `.yar/.yara` 规则，容忍无效规则 | | **行为 IOCs** | 从 VT 提取 IP、域名、URL、互斥锁 (`--vt-iocs`) | | **STIX 2.1** | 导出指标、网络 observable 及其关系的 bundle | | **MISP** | 在 MISP 实例上创建事件或添加属性 | | **SQLite 缓存** | 按 SHA-256 缓存结果（避免重复查询） | | **监控模式** | 实时监控文件夹 (`--watch`) | | **禁止上传模式** | 仅进行哈希查找，不发送任何文件 (`--no-upload`) | | **获取 MalwareBazar** | 按家族下载真实样本 (`--fetch-mb`) — 自动解密 AES ZIP | | **断路器** | 按 API 隔离 — CLOSED → OPEN → HALF-OPEN，避免级联故障 | | **带抖动的上限退避** | 遇到限流 429 → 指数等待 ±10 %，最长 5 分钟 | | **崩溃恢复** | 轮询前持久化 Joe webids — 无损恢复 | | **恢复 JoeSandbox** | 恢复轮询挂起的提交 (`--resume-joe`) | | **TOML/JSON 配置** | 所有选项均可通过文件配置 (`--config`) | | **聚合判定** | `aggregate_verdict(verdicts, threshold)` → 全局判定 + 置信度 | | **Slack Webhook** | 检测到威胁时自动告警 (`--webhook`) | ## 安装 ``` git clone https://github.com/Ozer0x777/Heimdall.git cd Heimdall pip install -e ".[dev]" ``` 在根目录创建一个 `.env` 文件： ``` VIRUS_TOTAL_API_KEY=votre_clé MALWARE_BAZAR_API_KEY=votre_clé HYBRID_ANALYSIS_API_KEY=votre_clé JOE_SANDBOX_API_KEY=votre_clé ANY_RUN_API_KEY=votre_clé ``` ## 使用方法 ### 分析文件 ``` heimdall --files sample.exe malware.dll heimdall --files ./samples/ --html --vt-iocs heimdall --files ./samples/ --stix iocs.json --output results.csv ``` ### 查找哈希 ``` heimdall --hashes abc123...64chars another_sha256... ``` ### 禁止上传模式（仅查找哈希） ``` heimdall --files ./samples/ --no-upload --yara ./rules/ ``` ### 实时监控 ``` heimdall --watch /quarantine/ --html --webhook https://hooks.slack.com/... ``` ### YARA — 下载规则 ``` heimdall --download-rules # toutes les sources heimdall --download-rules signature-base elastic # sources spécifiques ``` ### 本地 YARA 扫描 ``` heimdall --files ./samples/ --yara ./rules/ --html ``` ### VirusTotal 行为 IOCs ``` heimdall --files sample.exe --vt-iocs --stix iocs.json ``` ### 下载并分析 MalwareBazar 样本 ``` # 每个家族最多下载 25 个 samples，然后对其进行分析 heimdall --fetch-mb Emotet RedLine AsyncRAT LockBit \ --limit 25 --html --stix iocs.json --vt-iocs --threshold 1 # 自定义目标文件夹 heimdall --fetch-mb AgentTesla --limit 10 --samples-dir /tmp/samples --html ``` AES-256 加密的 ZIP 压缩包（密码为 `infected`）会通过 `pyzipper` 自动解密。需要在 `.env` 中配置 `MALWARE_BAZAR_API_KEY`。 ### 恢复 JoeSandbox 轮询 ``` heimdall --resume-joe results.csv --html --stix iocs.json ``` ### 使用配置文件 ``` cp heimdall.toml.example heimdall.toml heimdall --files ./samples/ --config heimdall.toml ``` ### 置信度阈值 ``` heimdall --files ./samples/ --threshold 2 # 2 APIs doivent confirmer ``` ### MISP ``` heimdall --files ./samples/ \ --misp-url https://misp.example.com \ --misp-key VOTRE_CLE_API ``` ## CLI 选项 | 选项 | 描述 | |---|---| | `--files PATH...` | 要分析的文件或文件夹 | | `--hashes SHA256...` | 要查找的 SHA-256 哈希 | | `--watch DIR` | 持续监控文件夹 | | `--download-rules [SRC...]` | 下载开源 YARA 规则 | | `--fetch-mb FAMILY...` | 按家族下载 MalwareBazar 样本并分析 | | `--limit N` | `--fetch-mb` 每个家族的最大样本数（默认：25） | | `--samples-dir DIR` | 样本存储文件夹（默认：`./samples`） | | `--resume-joe CSV` | 恢复 JoeSandbox 轮询（挂起/超时） | | `--config FILE` | TOML 或 JSON 配置文件 | | `--apis API...` | 要使用的 API（默认：all） | | `--threshold N` | 确认所需的最少 API 数量（默认：1） | | `--no-upload` | 仅查找哈希 — 不上传文件 | | `--vt-iocs` | 从 VT 行为中提取 IP/域名 | | `--wait-joe` | 等待 JoeSandbox 判定结果（阻塞） | | `--yara RULES_DIR` | YARA 规则文件夹 | | `--rules-dir DIR` | `--download-rules` 的目标路径 | | `--output CSV` | 输出的 CSV 文件（默认：results.csv） | | `--html` | 生成 HTML 报告 | | `--stix FILE` | 生成 STIX 2.1 bundle | | `--webhook URL` | 用于告警的 Slack webhook URL | | `--misp-url URL` | MISP 实例的 URL | | `--misp-key TOKEN` | MISP API 密钥 | | `--misp-event-id ID` | 现有的 MISP 事件 ID | | `--cache-db PATH` | SQLite 数据库（默认：heimdall_cache.db） | | `--no-cache` | 禁用缓存 | | `--dry-run` | 模拟运行，不调用 API | | `--include EXT...` | 按扩展名过滤（如 `.exe .dll`） | | `--exclude EXT...` | 排除特定扩展名 | | `--verbose` / `--quiet` | 日志级别 | | `--log-file PATH` | 日志文件 | | `--version` | 显示版本号 | ## 项目结构 ``` Heimdall/ ├── heimdall/ │ ├── __init__.py # version export │ ├── __main__.py # python -m heimdall │ ├── config.py # constantes, dataclasses, load/apply config │ ├── cache.py # SQLite cache │ ├── utils.py # sha256_file, detect_filetype, aggregate_verdict │ ├── yara_tools.py # YARA download, compile, scan │ ├── apis.py # tous les connecteurs API + resume_joe │ ├── output.py # CSV, HTML, STIX, webhook, MISP, print_summary │ ├── analysis.py # _build_row, analyze_files/hashes, watch_directory │ ├── fetcher.py # MalwareBazar downloader (AES ZIP, --fetch-mb) │ └── main.py # CLI argparse + dispatch ├── tests/ │ └── test_heimdall.py # 70 tests unitaires (0 appels réseau) ├── heimdall.toml.example ├── requirements.txt ├── pyproject.toml └── .pylintrc ``` ## 测试 ``` pytest tests/ -v ``` 83 个测试覆盖：`aggregate_verdict`、`sha256_file`、SQLite 缓存、`load_config`、`apply_config`、`_vt_parse`、`_ha_normalize`、`write_csv`、`write_stix`、`write_html`、`send_webhook`、`query_virustotal`、`fetch_vt_iocs`、`_poll_joe`、`resume_joe`、`CircuitBreaker`、`resolve_joe_pending`、`_recompute_verdict`。 ## 可用的 YARA 源 | 名称 | 描述 | |---|---| | `signature-base` | Neo23x0 / Florian Roth — 业界标杆 | | `elastic` | Elastic Security — 由 Elastic SIEM 团队维护 | | `reversinglabs` | ReversingLabs — 高级恶意软件检测 | ## 许可证 MIT — Ozer0x777

标签：DAST, Python, Python安全, 威胁情报, 开发者工具, 恶意软件分析, 无后门, 自动化分析, 跨站脚本, 逆向工具