ThreatSense

针对 Windows PE 文件的恶意软件分诊与事件响应规划。

🌐 在线演示

## 功能简介 ThreatSense 接收单个 **可疑的 Windows PE 文件**（`.exe`、`.dll`、`.sys`）——即你怀疑是恶意软件但尚未确认的样本——支持通过 **SHA-256 哈希** 或 **直接上传** 提交。随后，它会回答两个问题：*这是什么，我该如何应对？* 得出结论是系统的全部职责：提交的文件被视为 **嫌疑人**，而不是被假定有罪——它完全有可能被判定为 **良性 (Benign)**，或者被归类为五种恶意软件类别之一，并附带相应的威胁级别和响应计划。 它从三个方面收集证据： - 对 PE 文件本身进行 **静态分析**（结构、导入、字符串、加壳）——并且，对于被本地 EMBER 数据集覆盖的哈希查询，还会提供 **基于 EMBER 的 Capa 能力和 ATT&CK 证据**（在上传-only路径中无法使用此增强功能）。 - **机器学习模型**，用于预测恶意软件类别。 - **VirusTotal**，用于获取声誉、沙箱行为和已知指标。 然后，它会通过一个映射到 [MITRE ATT&CK](https://attack.mitre.org/) 技术和 [MITRE D3FEND](https://d3fend.mitre.org/) 对抗措施的 **规则引擎** 来处理这些证据，并生成两样东西： - 📋 **事件响应行动计划 (IRAP)** —— 一个可以导出为 JSON 的分步响应计划。 - 📄 **完整报告** —— 渲染为 PDF，你可以在浏览器中阅读或转交他人。 两者基于同一分析生成，因此结果始终保持一致。 ## 快速开始 ThreatSense 可以在 **macOS、Linux 和 Windows** 上运行。你需要 **Python 3.12**。PDF 渲染使用 WeasyPrint，这需要一些系统图形库（GTK/Pango）——安装脚本会为你自动安装它们，包括 Windows 上的 MSYS2/GTK。 ``` # macOS / Linux ./setup.sh ./run.sh ``` ``` # Windows ./setup.ps1 ./run.ps1 ``` 或者直接在 IDE 中打开 `app.py` 并运行——在任何平台上，它都会使用项目的虚拟环境重新启动自身，从而确保 ML 依赖项始终可用。应用程序会在本地端口上的浏览器中打开，并将你引导至分析页面。 首次使用？可以通过 [`WALKTHROUGH.md`](WALKTHROUGH.md) 了解操作流程，并尝试 [`docs/demo-hashes.json`](docs/demo-hashes.json) 中已知可用的样本。 ## 独特之处 大多数工具在得出像 *"恶意：47/72"* 这样的结论后就停止了。而最困难的部分——决定具体该 *做什么* ——则留给了你。ThreatSense 涵盖了这最后一步，并在执行过程中遵循以下三个规则： - **对已知信息保持诚实。** 如果证据不足，它会如实相告，而不是随意猜测。 - **结果可复现。** 相同的 PE 文件始终生成相同的计划。没有任何随机性。 - **过程透明。** 每一项建议都可以追溯到特定的规则、技术和来源。不使用 AI 凭空捏造响应步骤。 ## 功能特性 - 🔬 **PE 静态分析** —— 哈希、节区、导入、字符串、加壳和签名数据（通过 `pefile`）。 - 🧩 **基于 EMBER 的 Capa 增强** —— 对于被本地 EMBER 数据集覆盖的哈希查询，增加源自 Capa 的能力和 ATT&CK 证据（在上传-only路径中不可用）。 - 🧠 **ML 类别分类** —— LightGBM 模型将 PE 文件分为六个类别（以 Random Forest 作为备选）。 - 🌐 **VirusTotal v3 增强** —— 声誉、行为、ATT&CK 技术和相关指标。 - ⚙️ **35 条规则的响应引擎** —— 将 ATT&CK 技术映射到 MITRE D3FEND 对抗措施以及具体的、分组好的响应动作。 - 📊 **威胁评分** —— 综合行为、类别、VT 共识和规避信号得出的分诊分数。 - 📋 **IRAP + PDF 报告** —— 由一次分析生成的机器可读计划和人类可读报告。 - 🕓 **本地历史记录** —— 每次运行都会保存到你可以浏览的本地数据库中。 - 🖥️ **Web UI** —— 打开浏览器，粘贴哈希，即可完成。 ## 架构 ThreatSense 作为一条 **插桩的、分阶段的流水线** 运行。每个阶段都会丰富一条单独的、具有强类型的证据记录，并被独立监控（状态 + 耗时），同时允许在某个阶段退出而不导致整个运行崩溃。 ``` flowchart TB IN["Input
SHA-256 hash  ·  PE upload (.exe / .dll / .sys)"] subgraph ACQ["① Evidence acquisition"] direction LR S["Static analyzer · pefile
imports · sections · strings
packing · signing
+ EMBER-backed Capa ATT&CK (hash path)"] M["ML classifier · LightGBM
6-category prediction
+ confidence"] V["VirusTotal v3
reputation · behavior
MITRE trees · IOC relationships"] end NORM["Normalized evidence record — ThreatSenseAnalysis
coverage mode: full / vt_thin / vt_down_capa / static_minimal"] subgraph DEC["② Decision"] direction LR R["Rule engine · 35 deterministic rules
evidence → ATT&CK technique + D3FEND countermeasure
→ phased response actions"] T["Threat scorer
behavior · category · VT · evasion
→ mode-aware triage score"] end OUT["IRAP (JSON)  ·  Analysis report (PDF)"] DB[("SQLite history")] IN --> S & M & V S & M & V --> NORM NORM --> R & T R & T --> OUT OUT --> DB ``` ### 设计原则 - **单一事实来源** —— IRAP、PDF 报告和存储的历史记录均派生自同一个规范化的 `ThreatSenseAnalysis` 记录，因此这三者绝不会发生冲突。 - **确定性决策** —— 规则 *仅* 基于观察到的证据触发，且相同的输入必定产生相同的计划。绝不要求模型凭空捏造响应步骤。 - **优雅降级** —— 当某个来源缺失时（未知的哈希、VirusTotal 不可用），流水线会记录降级的 *覆盖模式* 并继续运行，而不是直接失败。 - **逐阶段插桩** —— 每个获取阶段都会单独跟踪其状态和耗时，然后呈现在分析元数据中，以实现完全的可追溯性。 更多细节：[`docs/architecture.md`](docs/architecture.md) 和 [`docs/methodology.md`](docs/methodology.md)。 ## 对部分证据保持诚实 有时并非所有数据源都可用——某个哈希可能在本地未知，或者 VirusTotal 可能宕机。ThreatSense 没有选择掩盖这一点，而是根据实际掌握的证据为每份分析打上标签： | 模式 | 含义 | |------|---------------| | `full` | 静态分析、ML 和丰富的 VirusTotal 数据——全部可用。 | | `vt_thin` | VirusTotal 中有该文件，但行为或本地数据有限。 | | `vt_down_capa` | VirusTotal 不可用，但基于 EMBER 的 Capa ATT&CK 证据支撑了分析。 | | `static_minimal` | 只能进行本地静态分析。 | ## 配置 设置来自环境变量（支持使用 `.env` 文件）。复制 [`.env.example`](.env.example) 即可开始。 | 变量 | 用途 | |----------|---------------| | `VT_API_KEY` | 你的 VirusTotal API key。如果没有提供，将跳过 VT 增强并优雅地降级分析。 | | `THREATSENSE_EMBER_DATA_DIR` | 可选的本地数据集文件夹（默认为 `./PE`）。 | | `THREATSENSE_VT_CACHE_DIR` | VirusTotal 响应的缓存位置（默认为 `./.cache/vt`）。 | | `PORT` | 要使用的端口（填 `0` 表示自动选择空闲端口）。 | | `THREATSENSE_AUTO_SHUTDOWN` | 设为 `1` 以启用演示自动关闭行为。 | ## 产出结果 **IRAP** 是一个包含六个部分的 JSON 计划：元数据与证据覆盖范围、分类与威胁级别、检测到的技术、失陷指标 (IOC)、建议操作以及参考资料。操作按响应阶段分组，并引用了相关的防御框架。 它为你提供的是 *指导，而不是命令*。ThreatSense 不会直接扔给你一个要运行的脚本，因为来自沙箱的文件路径和进程 ID 等细节与你实际的生产环境并不匹配。（[Schema →](docs/irap-schema.md)） **报告** 是经过排版的 PDF 版同源分析，可直接在浏览器中预览。 ## 模型 ThreatSense 内置了经过训练的 **LightGBM** 分类器（并以 **Random Forest** 作为备选）。 | | LightGBM | Random Forest | |--|----------|---------------| | Accuracy | 93.25% | 91.5% | | Macro F1 | 0.78 | 0.75 | - **六个类别：** Ransomware、Trojan、Worm、Spyware/Stealer、Backdoor/RAT、Benign。 - **训练基于** EMBER2024 风格的特征（8,000 个训练 / 2,000 个测试样本）。 该模型增加了类别上下文；响应计划由规则引擎执行。训练代码位于 [`colab/train_model.py`](colab/train_model.py) —— 详细信息请参阅 [`docs/ml-training-summary.md`](docs/ml-training-summary.md)。 ## 项目布局 ``` app.py # Web app: routes, API, uploads, PDF preview threatsense/ # The analysis engine static_analyzer.py # parse the PE file ember_adapter.py # read dataset records + extract features ml_classifier.py # predict the category vt_client.py # VirusTotal client + evidence cleanup rule_engine.py # ATT&CK → response actions scorer.py # threat score irap_generator.py # build the IRAP report_generator.py # render the PDF database.py # local history pipeline.py # ties it all together rules/rules.json # the 35-rule catalog models/ # trained model files website/ # web frontend (Next.js) docs/ # how everything works colab/ # model training notebook ``` 像历史数据库和 VT 缓存这样的本地文件会在你运行程序时自动创建。分析上传的 PE 文件不需要这些文件。 ## 范围与局限性 ThreatSense 的侧重点非常明确。请牢记以下边界： - **仅支持 Windows PE 文件**（`.exe`、`.dll`、`.sys`）。 - **行为数据来自 VirusTotal**，程序内置没有沙箱。 - **仅哈希查询** 依赖于本地数据的可用性以及 VT 状态。 - 该模型是一个 **经过验证的原型** —— 更多训练可以进一步提升其性能。 - 威胁评分是一个 **分诊信号，而** 不是完整的企业级严重性评级。它不了解你的资产、业务影响或恢复成本——这种判断仍然取决于你。 - 建议是 **指导，而不是可以直接运行的命令**。 - 它是一个用于 **分析和演示** 的工具，而不是 EDR、agent 或 SOAR 平台。 完整说明：[`docs/limitations.md`](docs/limitations.md)。 ## 文档 | 文档 | 主题 | |-----|-------| | [architecture.md](docs/architecture.md) | 组件与数据流 | | [methodology.md](docs/methodology.md) | 分析方法与证据来源 | | [rule-engine.md](docs/rule-engine.md) | 响应规则的工作原理 | | [threat-scoring.md](docs/threat-scoring.md) | 评分的构建方式 | | [irap-schema.md](docs/irap-schema.md) | 响应计划的结构 | | [ml-training-summary.md](docs/ml-training-summary.md) | 模型训练 | | [evaluation-summary.md](docs/evaluation-summary.md) | 模型验证 | | [limitations.md](docs/limitations.md) | 范围与未来工作 | ## 负责任的使用 ThreatSense 会处理真实的、可能具有恶意的 PE 文件，并会呈现真实的指标。在被证明无害之前，请将提交的每个样本都视为活跃的恶意软件：在妥善隔离的环境中处理它，并将输出视为决策支持——而不是自动修复方案。 ## 数据与致谢 ThreatSense 的分类器基于 [**EMBER2024**](https://github.com/FutureComputing4AI/EMBER2024) 数据集进行训练，并使用了其 `thrember` 特征提取器，这两者均由 FutureComputing4AI 在 Apache-2.0 许可证下发布。如果你在此项目或其模型的基础上进行构建，请同时引用 EMBER2024 的作者：

BibTeX

``` @inproceedings{joyce2025ember, title={EMBER2024 - A Benchmark Dataset for Holistic Evaluation of Malware Classifiers}, author={Robert J. Joyce and Gideon Miller and Phil Roth and Richard Zak and Elliott Zaresky-Williams and Hyrum Anderson and Edward Raff and James Holt}, year={2025}, booktitle={Proceedings of the 31st ACM SIGKDD Conference on Knowledge Discovery and Data Mining}, } ```

## 许可证 在 [MIT License](LICENSE) 下发布。

标签：Apex, DAST, DNS 反向解析, PE文件分析, 云安全监控, 威胁情报, 库, 应急响应, 开发者工具, 恶意软件分析, 无线安全, 机器学习, 逆向工具, 静态分析