9ith4b/malware-binary-analysis

# Malware Binary Analysis Skill 面向 Claude Code 和 Codex 的恶意二进制分析 Skill。它以 IDA Pro + [IDASQL](https://github.com/allthingsida/idasql) 为主要分析环境，提供可恢复的功能遍历、证据管理、Payload 提取、多阶段执行建模和报告生成流程。 这个项目解决的不是“反编译一个入口函数”，而是如何在复杂、多文件、可能加壳或分阶段执行的恶意代码中，持续回答以下问题： - 样本到底执行了哪些功能，是否仍有遗漏？ - 每项结论由哪段代码、哪个文件偏移或哪次工具输出支撑？ - 解密、解压、释放和注入产生的 Payload 之间是什么关系？ - Claude Code 与 Codex 如何在不依赖聊天记忆的情况下继续同一个 Case？ - 如何同时写出普通读者能理解、专业人员能复现的分析报告？ 支持两个工作流： - `analysis`：执行完整分析。 - `report`：根据已经记录的分析证据生成最终报告。 ## 主要能力 - 从入口、函数、字符串、导入、导出、资源、回调和间接调用等视角交叉遍历程序功能。 - 使用工作队列和覆盖率门禁降低功能遗漏。 - 使用 `FACT`、`INFERENCE`、`HYPOTHESIS`、`REFUTED` 和证据定位降低幻觉。 - 将分析笔记、状态、IDASQL 查询结果和提取文件分开保存。 - 自动记录解密、解压、释放、下载、内存映射等 Payload 血缘关系。 - 将主样本、shellcode、DLL、释放文件和注入载荷组织为执行 Stage。 - 根据实际执行 Stage 顺序生成报告，而不是根据文件分析顺序生成报告。 - 使用分页上下文、工作项摘要和 Stage 摘要限制上下文膨胀。 - 支持 Claude Code 和 Codex 在不并发写入的前提下继续同一个分析 Case。 - 报告正文采用“做了什么 → 如何实现 → 紧邻代码截图”的连续叙事方式。 - 将密码、密钥材料、派生公式、边界标记、路径、命令和 C2 等关键常量写入正文。 - 使用 draw.io 生成可编辑的执行流程、攻击链和 Artifact 血缘图。 ## 工作流概览 样本 / IDA 数据库 │ ▼ IDASQL 身份确认与多视角发现 │ ▼ 工作队列 + 覆盖率门禁 + 证据记录 │ ├── 解密 / 解压 / 释放 ──► Artifact 血缘图 │ └── 进程 / DLL / Shellcode 执行 ──► Stage 执行图 │ ▼ 按真实执行顺序生成分析报告 Artifact 表示不可变的文件或字节内容；Stage 表示某个 Artifact 在特定进程、入口和触发条件下的一次执行。二者分开建模，可以避免把“文件提取顺序”误写成“攻击执行顺序”。 ## 目录结构 malware-binary-analysis/ ├── SKILL.md ├── README.md ├── agents/ │ └── openai.yaml ├── assets/ │ ├── analysis-note-template.md │ ├── report-template.md │ ├── section-summary-template.md │ └── stage-summary-template.md ├── references/ │ ├── agent-compatibility.md │ ├── analysis-workflow.md │ ├── context-management.md │ ├── evidence-state-protocol.md │ ├── idasql-workflow.md │ ├── multi-stage-analysis.md │ ├── payload-extraction.md │ ├── report-workflow.md │ └── report-writing-method.md └── scripts/ ├── case_manager.py ├── stage_graph.py └── validate_compatibility.py ## 前置条件 ### 创建和检查 Case - Python 3.10 或更高版本。 - `case_manager.py`、`stage_graph.py` 和兼容性校验器仅使用 Python 标准库。 ### 执行真实二进制分析 - IDA Pro 可从当前环境启动。 - [IDASQL](https://github.com/allthingsida/idasql) 已安装，且 `idasql --version` 执行成功。 - 推荐安装 [IDASQL Skills](https://github.com/allthingsida/idasql-skills)。 - 需要反编译结果时，应具有可用的 Hex-Rays Decompiler。 - 报告需要绘图时，应配置 draw.io 工具、MCP 服务或经过授权的本地 CLI。 如果 IDA 或 IDASQL 不可用，Agent 只能初始化和检查 Case，不能把可执行 Stage 标记为已经分析。 不要在宿主机直接运行未知样本。动态执行、调试、仿真或引爆必须位于经过明确授权的隔离环境中。 ## 安全边界 - 默认优先静态分析，不会自动运行、调试或引爆未知样本。 - 未经明确授权，不会把样本、哈希或提取内容上传到第三方服务。 - 如果 IDA 或 IDASQL 不可用，只允许创建或检查 Case，不能把可执行 Stage 标记为分析完成。 - 动态执行必须由用户明确授权，并在隔离环境中进行。 - 同一个 `case-root` 同一时间只允许一个 Agent 写入，避免状态和证据互相覆盖。 ## 安装 本 Skill 对 Claude Code 和 Codex 使用同一个目录。开发期间推荐通过目录链接安装，避免两份副本逐渐不一致。 先克隆仓库： git clone https://github.com/9ith4b/malware-binary-analysis.git cd malware-binary-analysis ### Windows：同时安装到 Claude Code 和 Codex 在 PowerShell 中执行。修改 `$SkillSource`，使其指向本 Skill 的实际目录。目标目录必须尚不存在。 $SkillSource = (Resolve-Path ".").Path $ClaudeSkills = Join-Path $env:USERPROFILE ".claude\skills" $CodexBase = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" } $CodexSkills = Join-Path $CodexBase "skills" New-Item -ItemType Directory -Force -Path $ClaudeSkills | Out-Null New-Item -ItemType Directory -Force -Path $CodexSkills | Out-Null New-Item -ItemType Junction ` -Path (Join-Path $ClaudeSkills "malware-binary-analysis") ` -Target $SkillSource New-Item -ItemType Junction ` -Path (Join-Path $CodexSkills "malware-binary-analysis") ` -Target $SkillSource ### Linux/macOS：同时安装到 Claude Code 和 Codex 将 `/absolute/path/malware-binary-analysis` 替换为 Skill 的绝对路径： SKILL_SOURCE="/absolute/path/malware-binary-analysis" CODEX_SKILLS="${CODEX_HOME:-$HOME/.codex}/skills" mkdir -p "$HOME/.claude/skills" "$CODEX_SKILLS" ln -s "$SKILL_SOURCE" "$HOME/.claude/skills/malware-binary-analysis" ln -s "$SKILL_SOURCE" "$CODEX_SKILLS/malware-binary-analysis" ### Claude Code 项目级安装 如果只希望当前项目使用该 Skill，可将整个目录复制或链接到： /.claude/skills/malware-binary-analysis/ 该目录内必须直接包含 `SKILL.md`： /.claude/skills/malware-binary-analysis/SKILL.md Claude Code 官方支持项目级 `.claude/skills/` 和个人级 `~/.claude/skills/` Skill。 ### 使用复制方式安装 也可以把完整目录复制到对应的 `skills` 目录。复制时必须保留 `SKILL.md`、`scripts/`、`references/`、`assets/` 和 `agents/`。 复制安装后，每次更新都要完整替换两边的安装副本。不要只复制 `SKILL.md`。 ## 安装验证 从 Skill 源目录执行： python .\scripts\validate_compatibility.py --skill-root . python .\scripts\case_manager.py --help python .\scripts\stage_graph.py --help idasql --version Linux/macOS 可使用： python3 ./scripts/validate_compatibility.py --skill-root . python3 ./scripts/case_manager.py --help python3 ./scripts/stage_graph.py --help idasql --version 兼容性校验成功时会输出： { "valid": true, "targets": [ "claude-code", "codex" ], "errors": [] } 安装完成后启动一个新的 Claude Code 或 Codex 会话。如果 Claude Code 会话启动时还不存在顶层 `.claude/skills` 目录，应重启 Claude Code。 ## 使用方法 ### 快速开始 分析一个新样本： Claude Code: /malware-binary-analysis analysis [case-root] Codex: $malware-binary-analysis analysis [case-root] 从已经闭环的 Case 生成报告： Claude Code: /malware-binary-analysis report Codex: $malware-binary-analysis report ### 使用 Claude Code 分析样本 /malware-binary-analysis analysis "D:\samples\suspicious.exe" "D:\cases\suspicious" ### 使用 Codex 分析样本 $malware-binary-analysis analysis "D:\samples\suspicious.exe" "D:\cases\suspicious" `case-root` 用于保存整个分析任务。如果目录中已经存在有效状态，Agent 会恢复现有分析，而不是重新开始。 ### 使用 Claude Code 生成报告 /malware-binary-analysis report "D:\cases\suspicious" ### 使用 Codex 生成报告 $malware-binary-analysis report "D:\cases\suspicious" 报告只能根据 `analysis_raw/` 中已经保存的证据生成。状态文件可以证明覆盖情况，但不能代替报告证据。 ## IDASQL 连接方式 Skill 支持 IDASQL CLI、本地 HTTP、MCP 和 IDA GUI 插件方式。 ### Headless CLI idasql -s ... ### 交互式 CLI idasql -s -i ### HTTP idasql -s --http ### MCP idasql -s --mcp 连接后，Agent 会先查询 `binary` 表确认当前 IDA 数据库身份，并在不确定表结构时使用 `PRAGMA table_xinfo(...)`，不会猜测 IDASQL 字段。 每个可执行 Artifact 都必须关联独立、可识别的 IDA 数据库。shellcode 还需要记录架构、入口偏移、假定加载基址和映射方式。 ## Case 输出 典型分析 Case： / ├── analysis_raw/ │ ├── *.md │ └── idasql/ │ ├── queries/ │ └── results/ ├── analysis_state/ │ ├── state.json │ ├── coverage.md │ ├── artifacts/ │ ├── stages/ │ ├── relationships/ │ └── stage_summaries/ ├── analysis_extract/ └── analysis_report/ ├── report.md └── figures/ - `analysis_raw/`：分析笔记、IDASQL 查询、结果和其他中间证据。 - `analysis_state/`：工作队列、覆盖率、Artifact、Stage 和执行关系。 - `analysis_extract/`：从样本中提取或重构的 Payload。 - `analysis_report/`：最终报告、代码截图和 draw.io 图形。 ## 报告写作方法 最终报告同时服务两类读者： - 普通读者不查看反编译代码，也能通过正文理解样本做了什么、攻击如何展开以及可能造成什么影响。 - 逆向分析人员可以根据 Artifact、Stage、IDB、函数地址、实现顺序和紧邻截图快速复现结论。 每个详细行为小节遵循同一顺序： 1. 先用自然语言说明功能和影响。 2. 顺着功能描述解释代码如何实现，包括触发条件、输入来源、解析或解密过程、关键分支、API/指令链、输出和失败路径。 3. 在常量真正影响行为的位置写出密码、种子、实际密钥派生公式、标记、路径、命令、端口、时间间隔或 IOCTL。 4. 紧接着放置能够支撑这段说明的 IDA 代码截图。 5. 图片标题写明它证明的结论，并标注 Artifact、Stage、IDB、函数名和 VA/RVA。 正文在隐藏全部截图后仍应完整可读；专业人员只查看实现语句、截图、标题和地址时仍应能够复现。详细规范见 [`references/report-writing-method.md`](references/report-writing-method.md)。 报告所需流程图或攻击链图必须保留可编辑的 `.drawio` 源文件，并将 PNG/SVG 导出到 `analysis_report/figures/`。图中保持颜色、形状和方向一致，避免文字溢出与连线交叉。 ## 分析恢复和跨 Agent 交接 Claude Code 和 Codex 可以继续同一个 Case，但不能同时写入同一个 `case-root`。 切换 Agent 前： 1. 完成或明确延期当前工作项。 2. 保存分析笔记、摘要、证据 ID 和报告标签。 3. 保存并重新查询 IDASQL 中的重命名、注释和类型修改。 4. 执行 Case 和 Stage 图的 `status`。 5. 执行当前图版本的校验。 切换后，只需把 `case-root` 交给另一个 Agent。接收方应从状态文件和确定性工作队列恢复，不应依赖上一段聊天记录。 ## 手动状态检查 将 `` 和 `` 替换为实际路径： python "/scripts/case_manager.py" status --case-root "" python "/scripts/case_manager.py" next-item --case-root "" python "/scripts/stage_graph.py" status --case-root "" python "/scripts/stage_graph.py" validate --case-root "" --mode analysis python "/scripts/case_manager.py" validate --case-root "" --mode analysis 报告前执行： python "/scripts/stage_graph.py" validate --case-root "" --mode report python "/scripts/case_manager.py" validate --case-root "" --mode report ## 常见问题 ### Skill 没有被 Claude Code 发现 - 确认路径为 `.claude/skills/malware-binary-analysis/SKILL.md` 或 `~/.claude/skills/malware-binary-analysis/SKILL.md`。 - 确认没有多嵌套一层同名目录。 - 如果 `.claude/skills` 是会话启动后才创建的，重启 Claude Code。 - 直接输入 `/malware-binary-analysis` 检查是否能够调用。 ### Skill 没有被 Codex 发现 - 确认路径为 `$CODEX_HOME/skills/malware-binary-analysis/SKILL.md`。 - 未设置 `CODEX_HOME` 时，检查 `~/.codex/skills/malware-binary-analysis/SKILL.md`。 - 确认整个 Skill 目录都已安装，而不是只有 `SKILL.md`。 - 启动新的 Codex 会话后再次调用。 ### 找不到 Python 依次尝试： python3 python py -3 使用能够运行 `scripts/case_manager.py --help` 的 Python 3.10+ 解释器。 ### 找不到 IDASQL - 确认 IDA Pro 已正确安装。 - 确认 IDASQL 位于其要求的安装位置。 - 执行 `idasql --version`。 - 如果仅缺少 IDASQL，Case 可以初始化，但可执行 Stage 不能通过完成校验。 ### 报告无法通过校验 常见原因： - 仍有未分析或未延期的工作项； - 没有完成苏格拉底式问题闭环； - 可执行 Artifact 没有关联 IDA 数据库； - Stage 没有摘要、原始笔记或证据； - Stage 图在最后一次修改后没有重新校验； - 报告中仍存在未填写的模板占位符； - 缺少主题摘要或 draw.io 图形。 ## 进一步文档 - [Skill 核心约束](SKILL.md) - [Claude Code/Codex 兼容规范](references/agent-compatibility.md) - [IDASQL 工作流](references/idasql-workflow.md) - [完整分析流程](references/analysis-workflow.md) - [证据和状态协议](references/evidence-state-protocol.md) - [上下文管理](references/context-management.md) - [多阶段分析](references/multi-stage-analysis.md) - [Payload 提取](references/payload-extraction.md) - [报告流程](references/report-workflow.md) - [报告写作方法](references/report-writing-method.md)

标签：AI辅助分析, Claude Code, DAST, DNS 反向解析, IDA Pro, 云资产清单, 恶意软件分析, 网络信息收集, 自动化分析, 跨站脚本, 逆向工具, 逆向工程