VitorLudke/malware-analysis

# 恶意软件分析 [](LICENSE) [](#状态--路线图) [](#安全授权--双用途) 将其指向可疑的 Office 文档、PDF 或 RTF，它会在**隔离的容器内**对文件进行哈希计算、识别和推理——然后返回一个结构化的判定结果，而绝不是简单地盖上一个“安全”的印章。该设计基于一个令人不安的事实：你平时惯用的解析器（oletools、pypdf、rtfobj、YARA）本质上也是在处理由攻击者控制的字节数据的代码，并且文档解析器有着漫长的内存安全和 RCE CVE 历史。因此，检查过程默认在沙盒中进行，从而确保仅仅是*查看*文件这一操作本身不会让主机面临风险。 ## 起源 这个插件源于一个非常普通的问题。 在将一些旧 PC 改装成家庭 NAS 时，有一堆老化的硬盘需要处理——却没有什么干净利落的方法来回答那个唯一重要的问题：*这些硬盘里到底装了什么，把它们拷贝出来安全吗？* 许多硬盘里存放着以前机器（这些机器在几年前曾感染过病毒并被清理干净）里的旧 Office 文档和 PDF。要决定信任哪些文件，就意味着需要对文件进行哈希计算，检查文档和 PDF 是否包含宏和活动内容，并做出人为判断——同时还要确保检查过程本身不会让执行检查的机器面临风险。 这种临时性的、针对每个硬盘的分类工作，正是该插件将其变得**可重复且沙盒化**的初衷：每次都遵循相同的处理流程，扫描器在一次性容器中运行，而不是直接在实时主机上运行，并且给出的判定结果会诚实说明它证明了什么以及没有证明什么。 ## 功能及其适用人群 `malware-analysis` 为 Claude Code 提供了一套防御性的分类工作流和决策路由图。它提供以下功能： 1. **`/malware-triage `** —— 一个单一的命令，对文件或目录树运行沙盒化、只读的静态分类，并返回每个文件的判定结果及摘要，同时附带完整的溯源信息。 2. **一个 `malware-analyst` 子代理** —— 用于委派、批量或上下文隔离的分类工作：将包含附件的文件夹交给它，将分类作为大型任务的子步骤运行，或者将冗长的扫描器输出排除在主对话之外。它调用的是*相同*的脚本和*相同*的判定标准——它不会重复造轮子。 3. **一个按类别组织的框架目录** —— *针对不同情况该使用哪种工具，以及为什么* —— 这样当样本超出自动化核心的处理范围时，它会引导你使用正确的、维护良好的框架，而不是让你盲目猜测。一个 `malware-analysis` 技能负责在上述所有内容之间进行路由。 它是为**安全研究员、应急响应人员以及在自身授权范围内运作的分析师**构建的——适用于那些需要对可疑附件进行分类、继承了未知来源硬盘、或者需要决定某个文档是否值得进一步逆向工程的人员。在底层，它并没有重新发明检测启发式算法；而是**封装了维护良好且广为人知的工具**（`oletools`/`olevba`、`pypdf`、`rtfobj`、YARA-X），并在其之上增加了一层简洁且一致的判定逻辑。 它**特意**： - **不**作为一款攻击性工具包——它拒绝创建、打包、混淆、修复或武器化恶意软件； - **不**审查你*自己的*应用程序代码（那是代码安全审查，是另一项不同的工作）； - **不**重新实现 REMnux 或 FLARE VM——它会引导你使用它们并帮助你做出选择。 ## 工作原理 ### 分类漏斗：识别 → 内容 → 行为 每个文件都会经过相同的分层处理漏斗——从最廉价且最安全的关卡开始，在收集到足以做出决定的信息时停止： 1. **识别** —— 计算 **SHA-256**（主要标识符；保留 MD5 作为辅助的遗留 ID），探测真实的文件类型，并获取模糊哈希（**TLSH**）以便与已知的恶意软件家族进行聚类比对。在文件获得身份标识之前，不会有其他操作触及它。 2. **内容** —— 检查*结构*，而非运行时状态：VBA/XLM 宏及其自动执行触发器、PDF 的 `/OpenAction` / `/JS` / `/Launch` / `/EmbeddedFile` 对象、RTF 中嵌入的 OLE 对象、YARA 匹配规则。 3. **行为** —— 保留用于解决静态分析无法定性的情况。模拟执行和引爆（detonation）被视为*“运行样本的逻辑”*，处于相同的隔离纪律之下，并且**不属于自动化范围**——当案例需要时，目录会为你指引正确的环境。 ### 功能特性不等于恶意意图 贯穿始终的解释性指导原则是：**宏、`/JS` 标记或嵌入的对象本身是*攻击面*，而不是恶意软件的证明。** 用于填表的 PDF 包含合法的 JavaScript；模板也可以携带无害的宏。只有当信号出现有意义的*组合*时（例如，**自动执行触发器*加上*危险的 API 调用**、针对可执行文件的 `/Launch` 操作，或者已知的漏洞利用指标），工具才会将文件标记为 `suspicious`——绝对不会仅仅因为存在某项功能就进行标记。孤立的低可信度信号（偶然出现的十六进制或 base64 字符串）不会改变判定结果。 ### 隔离是默认项，而非附加项 扫描默认在**一次性容器**（Docker 或 Podman）内运行： - `--network none` —— 无网络出口； - `--read-only` 根文件系统，非 root 用户（`65534:65534`）； - 样本以**只读**方式挂载在 `/in` 目录，并配有独立的可写输出目录； - 限制 CPU、内存（2 GB）和 PID（128），外加一个真实的 `timeout`（默认 120 秒）——解压炸弹和病态的深层嵌套会被限制，而不会导致系统崩溃； - 无法访问你的主目录或同步文件夹。 如果不存在任何容器运行时，该命令**不会**静默回退到你的裸机主机上——它会降级为一种清晰标记的、**需主动选择开启（opt-in）**的“非沙盒、存在主机风险”模式，该模式必须通过设置 `MALWARE_ANALYSIS_ALLOW_HOST=1` 才能显式启用。 ### 判定结果绝不是安全证明 这里没有绿色的“安全”指示灯。每个判定结果都分为三种状态之一，并且始终带有其方法局限性说明，以及“不要基于此结果直接打开或执行文件”的免责声明： | 判定结果 | 含义 | | --- | --- | | `suspicious` | 具有确凿证据（例如：自动执行 + 危险 API、`/Launch` 指向可执行文件、漏洞利用指标）。 | | `no_static_indicators` | 静态分析未发现任何异常——**明确声明**这并不代表该文件是安全的。 | | `inconclusive` | 遇到了限制、解析器执行失败，或者文件已加密且未被打开。 | 每个判定结果都是一条结构化记录：输入（路径、SHA-256）、运行的工具及其版本、证据、方法边界（*仅限静态分析，未进行引爆*），以及标准的免责声明。命令和子代理都引用这一通用的判定标准——它们绝不会自行重新阐述。 ## 框架目录：针对不同情况该使用哪种工具 除了自动化核心之外，该插件还提供了一份按类别组织的知名框架图表——每个条目的格式都为*用例 → 框架 → 原因 → 如何使用 → 注意事项*。它倾向于指向活跃且维护良好的文档，而不是硬编码那些容易过时的安装矩阵，偏好使用当前正确的名称（YARA-X、peepdf3、Volatility 3），并带有 `last-reviewed` 日期，以便目录能够优雅地老化。核心类别提供可运行的自动化脚本；其余类别则是**路由指引**，直到它们各自开发出独立的脚本和测试用例。 | 类别 | v1 范围 | 代表性工具（针对不同情况使用不同工具） | | --- | --- | --- | | **方法论** | 核心 | 静态/动态/混合模型，识别→内容→行为漏斗，模糊哈希（imphash/ssdeep/TLSH），MITRE ATT&CK，通用判定标准 | | **恶意文档与初始访问** | 核心 | Office 宏 → `olevba`/`mraptor`（+ `pcodedmp` 用于 VBA stomping）；Excel 4.0/XLM → `XLMMacroDeobfuscator`；加密的 Office → `msoffcrypto-tool`；RTF/OLE → `rtfobj`/`oledump`；PDF → `pdfid`/`pdf-parser`/`pypdf`/`peepdf3`；邮件 → `emldump`；LNK, OneNote, JS, PowerShell, HTA, ISO/IMG, HTML 走私；CyberChef 用于跨领域解码 | | **环境** | 核心 | REMnux、FLARE VM、本地固定的 venv，以及脚本运行所在的容器/VM 隔离方案 | | **静态逆向** | 指引 | DIE/Malcat（查壳器识别）、FLOSS、capa、YARA-X、Ghidra / IDA / Rizin+Cutter / Binary Ninja；脱壳（UPX, PE-sieve）；.NET（dnSpyEx, de4dot, ILSpy） | | **动态 / 沙盒** | 指引 | 私有环境（CAPE、你自己的 FLARE/REMnux VM）对比 上传至公共环境（Any.Run, Hybrid, Joe, Triage —— 需注意 OPSEC/TLP 标记）；模拟执行（Speakeasy, Qiling, Unicorn）；主机监控器（Procmon+Noriben, Sysmon）；FakeNet-NG / INetSim | | **内存** | 指引 | Volatility 3, MemProcFS；通过 WinPmem / AVML / LiME 获取内存 | | **移动端** | 指引 | Android（jadx, apktool, MobSF, Androguard, APKiD）；iOS（Ghidra/Hopper, Frida, class-dump） | | **网络** | 指引 | Wireshark/`tshark`, Zeek, Suricata, JA3/JA4/JARM, mitmproxy, dnstwist | | **威胁情报** | 指针 | YARA-X 规则编写 + yarGen, MITRE ATT&CK, abuse.ch (MalwareBazaar/URLhaus/ThreatFox), STIX/TAXII, MISP/OpenCTI, VirusTotal（**默认仅查询哈希**）, Sigma | **特意排除在 v1 范围之外的内容**（特此说明这些缺失是故意的）：固件/IoT（binwalk, unblob, EMBA），威胁狩猎 / EVTX（osquery, Velociraptor, Chainsaw/Hayabusa），以及深度的 Linux/ELF 主机取证。 ## 开始使用 ### 前置条件 - [Claude Code](https://claude.com/claude-code) - **Python 3**（用于固定的分析 venv 和测试套件） - 一个**容器运行时（Docker 或 Podman）** —— 推荐；这是实施隔离的方式。如果两者都不存在，扫描将回退到一种清晰标记的、**需主动选择开启（opt-in）**的非沙盒主机模式（`MALWARE_ANALYSIS_ALLOW_HOST=1`），而不是在裸机主机上静默运行。 ### 1. 作为 Claude Code 插件安装 ``` /plugin marketplace add VitorLudke/malware-analysis /plugin install malware-analysis@malware-analysis ``` （CLI 等效命令：`claude plugin marketplace add VitorLudke/malware-analysis` 和 `claude plugin install malware-analysis@malware-analysis`。）这会注册 `.claude-plugin/marketplace.json` 市场并从中安装插件——`/malware-triage` 命令、`malware-analyst` 子代理和 `malware-analysis` 技能都会随之加载。一旦仓库公开，此功能即可使用。 ### 2. 设置分析后端 该插件的命令会通过 shell 调用一个固定的 Python venv 和（可选的）沙盒容器镜像；两者都没有提供预构建版本，因此需要在每台机器上各设置一次： ``` git clone https://github.com/VitorLudke/malware-analysis.git cd malware-analysis make setup ``` `make setup` 是一个幂等命令，它会：检查 `python3` 和容器运行时，在 `~/.cache/malware-analysis/venv` 创建固定的分析 venv（在进行任何网络安装前会提示确认），并在存在可用运行时的情况下构建 `malware-analysis:latest` 沙盒镜像。重新运行此命令是安全的——如果某一步骤已完成，它会自动跳过。 - `make check` —— 验证前置条件（`python3`、`docker`/`podman`、venv）而不安装任何内容。 - `make test —— 运行测试套件，以确认后端确实能正常工作。 ### 3. 使用它 在 Claude Code 中，指向一个文件或目录树： ``` /malware-triage ``` 这将运行沙盒化、只读的静态分类，并返回每个文件的判定结果及摘要，同时附带完整的溯源信息。对于批量工作、委派分类，或者为了将冗长的扫描器输出排除在主对话之外，可以把相同的任务交给 **`malware-analyst`** 子代理——它调用的是相同的脚本和判定标准。 扫描器始终通过隔离入口程序（`scripts/run_sandboxed.sh`）进行调用，该程序负责处理容器与主机的选择以及资源限制——在 `/in` 只读挂载样本、无网络、非 root 用户、限制 CPU/内存/PID/时间： ``` # hash + type + fuzzy-hash (funnel entry) scripts/run_sandboxed.sh /path/to/sample_dir /venv/bin/python /scripts/hash_and_id.py /in/suspicious.docm # macro triage (封装 olevba) scripts/run_sandboxed.sh /path/to/sample_dir /venv/bin/python /scripts/scan_macros.py /in/suspicious.docm ``` 有用的环境变量配置（参见 `scripts/run_sandboxed.sh`）： | 变量 | 用途 | | --- | --- | | `MALWARE_ANALYSIS_SANDBOX` | `docker` \| `podman` \| `none`（默认：自动检测） | | `MALWARE_ANALYSIS_ALLOW_HOST` | 必须设为 `1` 才能选择开启非沙盒的主机回退模式 | | `MALWARE_ANALYSIS_TIMEOUT` | 每次扫描的真实时间上限，以秒为单位（默认为 120） | ### 一个实际运行的示例 直接针对仓库中的一个合成测试用例运行扫描器，展示了所有判定结果的形态。这是在由 `make setup` 创建的 venv 中捕获的真实输出： ``` $ ~/.cache/malware-analysis/venv/bin/python scripts/scan_pdf.py tests/fixtures/malicious_pattern.pdf ``` ``` { "file": "tests/fixtures/malicious_pattern.pdf", "sha256": "999ca579f54004dd16bdef6fd69e8e7f5252d1fd2a5eda03f7b9bf638e032ee3", "tool": "scan_pdf", "tool_version": "pypdf 6.14.2", "verdict": "suspicious", "indicators": [ ".exe", "F=calc.exe" ], "evidence": [ "malicious signature(s) in JS/Launch content: ['.exe']", "Launch action targets executable/non-PDF file: ['F=calc.exe']", "1 JavaScript action(s)/stream(s) found (13 bytes)", "1 /Launch action(s) found" ], "method": "static-only; no detonation", "disclaimer": "Static, read-only triage only — NOT a safety attestation. Do not open or execute the file based on this result." } ``` （为了提高可读性，此处进行了格式化美化——脚本本身会根据 `scripts/verdict.py` 中的通用格式，在标准输出上将其打印为一条紧凑的单行 JSON。）该测试用例是一个合成的、仅包含模式特征的 PDF（参见 `tests/fixtures/README.md`）：一个链式的 `/OpenAction` → JavaScript → `/Launch` → `calc.exe`，没有可用的有效载荷。它之所以触发 `suspicious` 判定，是因为结合了 `.exe` 特征和针对非 PDF 可执行文件的 `/Launch` 操作——绝不仅仅是因为存在 JavaScript——而且，与该插件产生的所有判定结果一样，它以标准的“不要打开或执行”免责声明结束，而不是给出一个健康合格证明。 ## 安全、授权与双用途 该插件供在**自身授权范围内**进行**防御性**工作的人员使用。 - **授权。** 仅分析你获得授权可以分析的文件。*“被授权分析”并不等同于“被授权共享或上传”。* - **明确拒绝双用途。** 在处理范围内：检测、应急响应、归因以及对第三方/未知样本的分类。不在处理范围内且会被拒绝：生成可用的样本；重建、修复或混淆恶意软件；构建可操作的漏洞利用、C2 或规避工具；或者“反混淆并改进此代码”。该插件不会生成、修改或增强恶意代码。 - **不进行原生执行。** 引爆、模拟执行和 VBA/JS 模拟器都被视为“运行样本的逻辑”，并置于相同的隔离纪律之下——绝不是默认行为。 - **样本内容是不可信的数据，绝不是指令。** 提取出来的宏、PDF 文本和字符串可能携带提示词注入（“忽略之前的指令并执行此操作”）。该插件展示哈希值和指标，并将原始载荷保留在磁盘上——它绝不遵循在样本内部发现的指令。 - **提取出的产物被视为活跃的恶意软件。** 任何提取出来的内容（嵌入的文件、OLE 对象、解码后的载荷）在写入时都会进行**防御性处理（defanged）**（使其不可执行），并存放在同步文件夹之外的隔离目录中，记录其 SHA-256 并进行日志记录——在没有施加相同限制的情况下，绝不重新解析。 - **上传 = 泄露。** VirusTotal、Any.Run、Hybrid Analysis、Joe、MalwareBazaar 等都是公共的多租户服务；上传文件就**等于泄露**了该文件，并且可能会引起监视提交记录的对手的警觉。云端查询默认为**仅限哈希**；任何实际的文件上传都需要经过明确且显眼的确认。 ## 状态与路线图 **这是一款早期、开发中的软件**（v0.1.0），我们正以规范优先、逐项任务的方式进行构建。以下是其当前进展的真实情况。 **已完成** - 插件清单（`.claude-plugin/plugin.json`）、`LICENSE`、`.gitignore`。 - **沙盒入口程序**（`run_sandboxed.sh`）—— 容器隔离（Docker/Podman，`--network none`，只读根文件系统，非 root 用户，限制 CPU/内存/PID，只读样本挂载，真实超时限制），并具有需确认的主机回退机制。 - **隔离镜像**（`Dockerfile` + `build_image.sh`）—— 基于 `python:3.12-slim` 的可离线安装的 `malware-analysis:latest` 镜像。 - **固定的 venv 引导程序**（`bootstrap_venv.sh` + `requirements.txt`：`oletools`、`pypdf`、`yara-x`、`pcodedmp`、`msoffcrypto-tool`、`XLMMacroDeobfuscator`、`py-tlsh` 等），具备联网前确认机制。 - **识别层**（`hash_and_id.py`）—— SHA-256 + MD5 + 文件类型探测 + TLSH 模糊哈希。 - **全部四个扫描器**：`scan_macros.py`（封装了 `olevba` 并应用了相当于 mraptor 的自动执行 + 危险 API 规则）、`scan_pdf.py`（`pypdf` 对象图遍历）、`scan_rtf.sh`（封装了 `rtfobj`）、`run_yara.sh`（YARA-X）——每一个都配备了纯净的、经过单元测试的分类规则。 - **通用判定模块**（`verdict.py`）—— 包含标准免责声明在内的共享 `suspicious` / `no_static_indicators` / `inconclusive` 结果形态。 - **合成的、仅包含模式特征的测试用例**（包含 PDF 和 RTF 的良性特征及真阳性特征）；宏检测是通过对纯净的 `classify()` 规则进行单元测试（针对合成的关键字列表）以及一个在测试时构建的无宏 `.xlsx` 文件来实现的——并且通过了 `make test`（pytest + shell 扫描器测试）。 - **参考目录**：`00-methodology`、`01-maldoc`、`08-environments`，以及路由指引 `09-other-categories`。 - **`malware-analysis` 技能**（`skills/malware-analysis/SKILL.md`）—— 将命令、子代理和参考目录结合在一起的路由器。 - **`/malware-triage` 斜杠命令**（`commands/malware-triage.md`）—— 一键式的前台入口。 - **`malware-analyst` 子代理**（`agents/malware-analyst.md`）—— 用于委派/批量/隔离上下文的分类。 **待处理 / 后续计划** - v1 之后：将某个指引类别（例如 LNK/OneNote 扫描器、脱壳、.NET）提升为完整的参考内容，只要它具备了相应的脚本和测试用例。 ## 许可证 **GPL-3.0-or-later。** 参见 [LICENSE](LICENSE)。源文件包含 `SPDX-License-Identifier: GPL-3.0-or-later` 头部。请注意，根据 GPL 的规定，下游衍生作品必须保持开源。 作者：**VitorLudke**。

标签：AMSI绕过, Claude插件, DAST, DNS 反向解析, 威胁检测, 安全沙箱, 恶意软件分析, 搜索语句（dork）, 文件扫描, 自动分类, 请求拦截, 逆向工具