t-bench/Malware-analysis-sandbox

# 恶意软件分析沙箱 本仓库是一个用于 Windows 上可疑文件的实用静态分析沙箱。目前的基线重点关注以下四个方面： 1. 可疑文件的安全本地静态分类（分诊）——绝不执行任何样本。 2. 可解释、可辩护的风险评分，分析人员可以据此向评估人员进行讲解。 3. 证据处理功能：监管链元数据和防篡改报告。 4. 以 STIX 2.1 格式导出调查结果，供威胁情报平台使用。 它有意设计为轻依赖，因此您可以在干净的分析工作站上运行它，而无需立即引入庞大的工具链。 ## 当前功能 - 计算 `MD5`、`SHA1` 和 `SHA256` - 提取 ASCII 和 UTF-16LE 字符串 - 测量文件的整体熵和分块熵 - 通过 magic bytes 识别常见文件类型 - 解析核心 PE 头字段和节元数据 - 提取更丰富的分析数据，例如 URL、域名、IP、电子邮件、注册表路径、文件路径、命令行、互斥锁名称、可疑导入、附加数据和 PE 节异常 - 根据 IANA TLD 列表验证提取的域名和电子邮件地址，确保导入名（如 `ADVAPI32.dll`）不会被误认为是域名 - 行业标准的 `imphash`（与 `pefile`/VirusTotal 匹配，包括 ws2_32/oleaut32 的序号解析） - 检测加壳工具（UPX、MPRESS、ASPack、Petite、VMProtect、Themida）和自解压安装程序（NSIS、Inno Setup、7-Zip/WinRAR/cabinet SFX），并据此调整熵值的权重 - 生成可解释的风险评分：列出每条触发的规则及其权重，这些条目的总和即为报告的评分 - 在每份报告中记录监管链元数据（分析人员、来源、获取时间、分析主机、工具版本） - 使用防篡改的 SHA-256 摘要密封每份报告，可通过 `verify-report` 进行校验 - 使用 minisign (Ed25519) 对报告进行签名，将完整性扩展到作者身份；`verify-report --pubkey` 可同时校验两者 - 将调查结果导出为 STIX 2.1 bundle（在分析时使用 `--stix` 或之后使用 `export-stix`） - 将调查结果导出为 MISP event（在分析时使用 `--misp` 或之后使用 `export-misp`） - 直接从 PE 安全目录中标记 Authenticode 签名的存在 - 安装 `yara-python` 后可选进行 YARA 扫描（通过配置中的 `--yara-rules` 或 `yara_rules_path` 指定规则集路径） - 启动无需依赖的 `tkinter` GUI 进行交互式分析 - 通过 `--verbose`/`--quiet` 进行结构化的 `stderr` 日志记录 - 通过配置中的 `--max-size-mb` 或 `max_sample_size_mb` 进行样本大小限制 ## 项目布局 ``` . |-- CHANGELOG.md |-- README.md |-- configs/ | `-- sandbox.example.json |-- docs/ | `-- architecture.md |-- pyproject.toml |-- scripts/ |-- src/malware_analysis_sandbox/ | |-- analysis/ | |-- cli.py | |-- config.py | |-- gui.py | |-- models.py | |-- pipeline.py | |-- reporting.py | `-- stix_export.py `-- tests/ ``` ## 快速开始 ### 1. 创建虚拟环境 ``` python -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install -e . ``` ### 2. 创建本地配置 ``` malware-sandbox init-config ``` 这会写入 `configs/sandbox.local.json`。请保留该文件，用于存储特定于工作站的值，例如报告目录、分析人员姓名和 YARA 规则集路径。 ### 3. 启动 GUI ``` malware-sandbox gui ``` ### 4. 从 CLI 分析样本 ``` malware-sandbox analyze .\samples\suspicious.bin --config .\configs\sandbox.local.json --analyst "T. Bench" --source "case-1234" ``` ### 5. 验证报告是否被篡改 ``` malware-sandbox verify-report .\reports\_suspicious.bin.json ``` ### 6. 将调查结果导出为 STIX 2.1 或 MISP event ``` malware-sandbox analyze .\samples\suspicious.bin --stix .\reports\suspicious.stix.json --misp .\reports\suspicious.misp.json # 或者，从现有报告中： malware-sandbox export-stix .\reports\_suspicious.bin.json malware-sandbox export-misp .\reports\_suspicious.bin.json ``` MISP event 会将样本哈希标记为 `to_ids`，但对于静态提取的网络 IOC 则保留为非 `to_ids` 状态，并附带说明性注释——在启用检测之前请对其进行审查。 ### 7. 对报告进行签名，将完整性扩展到作者身份 安装一次 minisign（`winget install jedisct1.minisign`），生成密钥对（`minisign -G`），然后执行： ``` # 在分析时签名，或之后： malware-sandbox analyze .\samples\suspicious.bin --sign malware-sandbox sign-report .\reports\_suspicious.bin.json # 当提供 public key 时，verification 会检查 digest 和 signature： malware-sandbox verify-report .\reports\_suspicious.bin.json --pubkey $env:USERPROFILE\.minisign\minisign.pub ``` 签名后会在报告旁边生成一个独立的 `.minisig` 文件。之所以选择 minisign 而不是 Sigstore，是因为分析工作站通常受到网络限制；而 minisign 支持完全离线验证。如果报告是在无人值守的情况下签名的，请使用 `minisign -G -W` 生成未加密的密钥，并妥善保护该密钥文件。 ## GUI 工作流 GUI 是一个轻量级的桌面层，使用了与 CLI 相同的分析流水线。 - 选择一个样本文件。 - 可选择一个配置 JSON 文件。 - 可选择一个报告目录覆盖项。 - 点击 `Analyze Sample` 生成 JSON 报告并预览。 - `Summary` 显示分类汇总（监管链块、评分明细），并带有样式化的标题。 - `Evidence` 是一个按类别（IOC、能力、PE 事实、节、导入）分组的可折叠树，确保长列表易于浏览。 - `JSON Preview` 显示原始报告。 - `Assessment` 面板包含一个颜色编码的风险横幅（根据级别显示为红/黄/绿）、一个“为什么是这个评分”的表格（列出每条触发的规则及其权重），以及行为叙述。 - 在应用程序内部使用 `Create Local Config` 写入特定于工作站的配置文件。 - 如果您需要当前显示 JSON 的副本，请使用 `Save JSON Preview As...`。 侧边栏被特意标记为静态推断。它并不宣称提供运行时遥测数据。 ## 可解释的评分 报告的 `indicators.score_breakdown` 列出了对评分有贡献的每一条规则： ``` Score Breakdown - + 18 Network Communication: 36 matching string(s) (base 14 + evidence bonus 4) - + 8 2 suspicious API import(s) in the PE import table - + 8 5 PE structural heuristic(s) flagged = 88 ``` 评分具备加壳感知能力：当检测到自解压安装程序（NSIS、Inno Setup、SFX 归档文件）时，会将高熵值视为预期的压缩 payload 数据，其权重从 10 降至 2。而真正的加壳工具签名（UPX、VMProtect 等）则会增加权重。报告的 `risk_score` 始终是这些明细条目的封顶总和。 ## 报告契约 报告包含 `schema_version`（目前为 `1.0`），并由 [schemas/report-v1.schema.json](schemas/report-v1.schema.json) 描述；测试流程会根据该架构验证每份流水线报告。分类结果位于一个稳定的顶层 `verdict` 块中： ``` "verdict": { "risk_score": 88, "raw_score": 88, "risk_level": "Critical", "summary": "Static evidence suggests critical analyst interest. ...", "score_breakdown": [ {"rule": "network_communication", "points": 18, "detail": "..."} ] } ``` `risk_score` 始终是 `score_breakdown` 的封顶总和。使用者应依赖于 `schema_version` 并容忍额外字段；破坏性的结构变更会提升主版本号。 ## 监管链与报告完整性 每份报告都包含一个 `custody` 块：分析人员（来自 `--analyst`、配置或 OS 用户）、来源（`--source`）、获取时间戳（`--acquired` 或文件的创建时间——会记录其依据）、分析主机、工具版本以及样本 SHA-256。 每份写入的报告都会使用一个 `integrity` 块进行密封：这是一个基于所有其他字段的规范 JSON 计算出的 SHA-256 摘要。`malware-sandbox verify-report` 会重新计算该摘要，如果不匹配则以非零状态退出。这证明了报告在写入后未被篡改；但这并不能证明作者身份——如果需要证明作者身份，请将其与签名或 WORM 存储结合使用。 ## 配置 从 `configs/sandbox.example.json` 开始。重要的键包括： - `reports_dir`：写入静态分析 JSON 的目录。 - `strings_min_length`：提取字符串的最小长度。 - `entropy_chunk_size`：计算分块熵的字节窗口。 - `max_sample_size_mb`：工具将读取的样本上限（MB）。 - `yara_rules_path`：YARA 规则文件或目录的可选路径。 - `analyst`：监管链块的默认分析人员姓名。 - `default_source`：监管链块的默认样本来源。 - `defang_iocs` / `suppress_benign_strings`：输出格式的默认设置。 现有配置中遗留的 `vm` 段落将被忽略并发出警告。 ## 构建 EXE 安装可选的构建依赖并运行 PowerShell 构建脚本： ``` python -m pip install -e .[build] powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Build-Exe.ps1 ``` 可执行文件将写入 `dist\MalwareAnalysisSandbox.exe`。 ## 安全模型 此工具仅执行静态分析。它绝不执行样本，并且早期版本中存在的 VM 引爆规划器已被移除。请使用常规的恶意软件处理规范来处理样本：将它们存储在专用目录中，谨慎设置实时的 AV 排除项，并且不要双击样本。 已知的 IOC 注意事项：一些已注册的 TLD 与文件扩展名（`.zip`、`.md`、`.sh`）冲突，因此带有这些扩展名的文件名可能仍然会显示为域名。STIX 指示器列表反映了报告中按类型划分的预览上限。 ## AI 工作流 本仓库的结构设计使得 AI agent 能够快速重新介入： - 阅读 `README.md` 了解当前的行为和工作流程。 - 阅读 `CHANGELOG.md` 获取面向机器的变更和升级历史。 - 阅读 `docs/architecture.md` 了解组件边界和预期的扩展点。

标签：DAST, DNS 反向解析, PE文件分析, 云安全监控, 威胁情报, 开发者工具, 恶意软件分析, 网络信息收集, 逆向工具, 静态分析