Last-emo-boy/rikune
GitHub: Last-emo-boy/rikune
这是一个面向 LLM 的 Windows 逆向工程 MCP 服务器，集成了 Ghidra、Frida 等工具，提供从静态分类到代码重构的自动化分析能力。
Stars: 120 | Forks: 18
# Rikune
中文版：[`README_zh.md`](./README_zh.md)
一个用于 Windows 逆向工程的 MCP 服务器。它将 PE 分类、基于 Ghidra 的检查、DLL/COM 分析、运行时证据摄取、Rust/.NET 恢复、类源码重构以及 LLM 辅助审查作为可重用的 MCP 工具暴露给任何支持工具调用的 LLM。
## 功能亮点
- 通用 Windows PE 覆盖：EXE、DLL、面向 COM 的库、Rust 原生样本和 .NET 程序集均拥有专门的分析或恢复路径。
- 恢复优先设计：当 Ghidra 函数提取为空或降级时，服务器可以继续进行 `.pdata` 解析、边界恢复、符号恢复和导入函数定义。
- 可观测的 Ghidra 运行：命令日志、运行时日志、分阶段进度、项目/日志根目录以及解析后的 Java 异常摘要均通过高级输出呈现。
- 运行时感知重构：静态证据、追踪导入、内存快照和语义审查产物均可关联回重构和报告工作流。
- LLM 辅助审查层：函数命名、函数解释和模块重构审查作为结构化的 MCP 流程暴露，而非即席提示。
- 队列友好编排：持久化的分阶段运行是主要的工作流模型，而低级队列作业仍可用于原始执行检查。
- 完整的 Linux 分析镜像：Docker 发行版现在除了基础的 Ghidra/capa/DIE/FLOSS 栈外，还捆绑了 Graphviz、Rizin、YARA-X、UPX、Wine/winedbg、Frida CLI、Qiling、angr、PANDA 绑定和 RetDec。
- **分阶段非阻塞流水线**：分析被组织成显式阶段（`fast_profile`、`enrich_static`、`function_map`、`reconstruct`、`dynamic_plan`、`dynamic_execute`、`summarize`），具有优先预览工具契约和持久化的运行状态以便重用。
- **HTTP 文件服务器**：嵌入在端口 18080 上的 HTTP API，用于直接样本上传、产物下载以及带 API 密钥认证的上传会话管理。
- **Web 仪表板**：位于 `http://localhost:18080/dashboard` 的暗黑主题实时监控仪表板 —— 显示所有工具、插件、样本、配置诊断、系统资源和 SSE 事件流。
- **Server-Sent Events (SSE)**：位于 `/api/v1/events` 的实时事件流，用于分析进度、样本摄取和服务器状态变化。
- **高级分析工具**：节级熵分析、混淆检测（CFF、不透明谓词、字符串加密、.NET 特定）、静态污点追踪、智能脱壳指导、自动生成的 Frida 挂钩脚本以及 Sigma 检测规则生成。
## 分阶段分析管道的新功能
此版本引入了统一的非阻塞分析模式，以防止 MCP 请求在大型或昂贵样本上超时：
- `workflow.analyze.start` 启动或重用持久化的分阶段分析运行。仅 `fast_profile` 阶段内联执行；较重的阶段默认排队。
- `workflow.analyze.status` 查询聚合运行状态，包括延迟作业、已完成阶段和可重用的产物引用。
- `workflow.analyze.promote` 将现有运行提升到更深层阶段，而无需重新运行已完成的工作。
- 重型工具（`strings.extract`、`binary.role.profile`、`analysis.context.link`、`crypto.identify`）现在在深层排队执行之前提供显式有界预览模式。
- `workflow.summarize` 消费持久化的运行状态和阶段产物，而不是重新运行隐藏的重型分析。
- 覆盖范围包络字段（`coverage_level`、`completion_state`、`coverage_gaps`、`upgrade_paths`）提供机器可读的分析边界和下一步指导。
- 运行/报告表面现在暴露 `recovery_state`、`recoverable_stages`、`evidence_state`、`provenance_visibility` 和 `persisted_state_visibility`，以便客户端可以判断哪些内容被重用、延迟或中断。
- 调度器感知状态现在暴露 `execution_bucket`、`cost_class`、`worker_family`、`budget_deferral_reason`、`warm_reuse` 和 `cold_start`，以便客户端可以判断工作为何被接纳、延迟或重用。
- 内存感知状态还在接纳、延迟或中断重型工作时暴露 `expected_rss_mb`、`current_rss_mb`、`peak_rss_mb`、`memory_limit_mb` 和 `control_plane_headroom_mb`。
- 大样本完整证据现在可以作为有界内联摘要加上 `chunk_manifest` 和持久化的分块产物返回，而不是单一的整体负载。
- 预览辅助器现在更喜欢池化热执行用于静态 Python 辅助器和 `Rizin` 预览检查，而 `Ghidra` 仍保持在隔离的深度归因通道上。
主要运行时文档：
- [分析运行时](./docs/ANALYSIS-RUNTIME.md)
- [异步作业模式](./docs/ASYNC-JOB-PATTERN.md)
- [迁移到分阶段运行时](./docs/MIGRATION-ASYNC.md)
### 解释优先的图表面
支持图功能的工具现在旨在帮助 AI 代理和分析人员解释发现为何存在，而不是装饰报告。
- `workflow.summarize` 和 `report.summarize` 呈现有界解释图产物，而不是依赖大型内联图负载。
- `code.function.cfg` 是主要的本地导航图表面；Mermaid 和 DOT 是相同有界图语义上的序列化器选择。
- `graphviz.render` 是现有图产物的渲染器/导出辅助器，而非主要分析工作流。
- 解释图输出现在区分 `observed`（已观察）、`correlated`（已关联）和 `inferred`（已推断）内容，并带有来源和省略标记。
### 主要与兼容表面
将工具表面视为角色范围：
- 主要编排：`workflow.analyze.start`、`workflow.analyze.status`、`workflow.analyze.promote`、`workflow.summarize`
- 兼容外观：`workflow.triage`、`task.status`、`report.summarize`
- 仅导出表面：`report.generate`
- 渲染器/导出辅助器：`graphviz.render`
当同时存在主要和兼容表面时，请优先使用主要分阶段运行时路径。
### 推荐调用模式
**用于快速分类：**
```
workflow.analyze.start(sample_id, goal='triage')
→ Returns fast_profile stage result inline
→ Check coverage_gaps and upgrade_paths for next steps
```
**用于深度分析：**
```
workflow.analyze.start(sample_id, goal='reverse')
→ Returns queued status with job_id
→ Poll workflow.analyze.status(run_id) until completed
→ Promote to deeper stages as needed
```
**用于大型或超大样本：**
```
workflow.analyze.start(sample_id, goal='triage')
→ workflow.analyze.status(run_id)
→ workflow.analyze.promote(run_id, through_stage='enrich_static')
→ workflow.analyze.status(run_id)
→ workflow.analyze.promote(run_id, through_stage='function_map')
→ workflow.summarize(sample_id, through_stage='final')
```
对于大型样本，请保留 `report.summarize(detail_level='compact')`。当样本层过大不适合安全内联报告时，运行时现在会将 `detail_level='full'` 降级回 compact。
**用于摘要：**
```
workflow.summarize(sample_id, through_stage='final')
→ Automatically consumes any existing analysis run state
→ Returns compact analyst-facing summary
```
## 静态分类基础的新功能
此版本在深度逆向工程之前增加了更强的首遍静态分析层：
- `static.capability.triage` 使用 `capa` 风格的行为分类来回答样本似乎能够做什么，而不仅仅是它包含什么字符串或导入。
- `pe.structure.analyze` 将 `pefile` 和 `LIEF` 风格的结构解析合并为一个具有后端特定细节块的规范 PE 摘要。
- `compiler.packer.detect` 添加了编译器、保护程序和打包器归因，并在 Detect It Easy 不可用时进行设置感知降级。
- `workflow.triage`、`report.summarize` 和 `report.generate` 现在直接消费这些结果，包括产物来源、静态范围选择和比较/基线支持。
## 典型分析流程
### 快速分类
1. `sample.ingest`
2. `static.capability.triage`
3. `pe.structure.analyze`
4. `compiler.packer.detect`
5. `workflow.triage`
6. `report.summarize`
### 困难原生恢复
1. `ghidra.analyze`
2. `workflow.function_index_recover`
3. `workflow.reconstruct`
### LLM 辅助优化
1. `workflow.reconstruct`
2. `workflow.semantic_name_review`
3. `workflow.function_explanation_review`
4. `workflow.module_reconstruction_review`
## 此服务器的用途
该项目旨在成为一个可重用的逆向工程工具表面，而不是一堆一次性本地脚本。
它旨在帮助 MCP 客户端：
- 快速分类 Windows PE 样本
- 检查导入、导出、字符串、打包器、运行时提示和二进制角色
- 在可用时使用 Ghidra 进行反编译、CFG、搜索和重构
- 在 Ghidra 函数提取失败时恢复可用的函数索引
- 在缺少 Java、Python 额外组件或 Ghidra 时呈现可操作的设置指导
- 在分析失败时暴露更丰富的 Ghidra 诊断、命令日志和阶段/进度元数据
- 关联静态证据、运行时追踪、内存快照和语义审查产物
- 导出类源码重构输出，并支持可选的构建和线束验证
## 核心能力领域
### 样本和静态分析
- `sample.ingest`
- `sample.profile.get`
- `static.capability.triage`
- `pe.structure.analyze`
- `compiler.packer.detect`
- `pe.fingerprint`
- `pe.imports.extract`
- `pe.exports.extract`
- `pe.pdata.extract`
- `dll.export.profile`
- `com.role.profile`
- `strings.extract`
- `strings.floss.decode`
- `yara.scan`
- `runtime.detect`
- `packer.detect`
- `binary.role.profile`
- `system.setup.guide`
### Ghidra 和函数分析
- `ghidra.health`
- `ghidra.analyze`
- `code.functions.list`
- `code.functions.rank`
- `code.functions.search`
- `code.function.decompile`
- `code.function.disassemble`
- `code.function.cfg`
- `code.functions.reconstruct`
### Rust 和困难原生样本的恢复
- `code.functions.smart_recover`
- `pe.symbols.recover`
- `code.functions.define`
- `rust_binary.analyze`
- `workflow.function_index_recover`
### .NET 和托管检查
- `dotnet.metadata.extract`
- `dotnet.types.list`
- `dotnet.reconstruct.export`
### 运行时证据和报告
- `dynamic.dependencies`
- `sandbox.execute`
- `dynamic.trace.import`
- `dynamic.memory.import`
- `dynamic.auto_hook` - 基于静态证据的自动 Frida 挂钩生成
- `dynamic.memory_dump` - 带模式扫描的运行时内存转储
- `attack.map`
- `ioc.export`
- `report.summarize`
- `report.generate`
- `artifacts.list`
- `artifact.read`
- `artifacts.diff`
- `tool.help`
### Android / APK 分析
- `apk.structure.analyze` - APK manifest、权限、组件提取
- `apk.packer.detect` - APK 打包器/混淆器检测
- `dex.decompile` - 通过 jadx 进行 DEX 到 Java 的反编译
- `dex.classes.list` - DEX 类/方法枚举
### 符号执行 & CrackMe
- `symbolic.explore` - 基于 angr 的符号执行
- `keygen.verify` - Keygen/许可证验证（Qiling/angr）
- `constraint.solve` - Z3/angr 约束求解器
### 恶意软件分析
- `malware.config.extract` - 恶意软件配置提取
- `malware.classify` - 家族分类（YARA + capa + 行为）
- `c2.extract` - C2 基础设施提取
### 跨平台 & 可视化
- `elf.macho.parse` - 通过 Rizin 进行 ELF/Mach-O 头/节解析
- `rizin.diff` - 二进制差异比较（函数/基本块级别）
- `cfg.visualize` - 控制流图可视化（DOT/SVG/JSON）
- `timeline.correlate` - 多源事件时间线关联
- `cross_module.xref` - 跨模块交叉引用分析
- `kb.search` - 知识库语义搜索
### 高级分析
- `entropy.analyze` - 节级 Shannon 熵，带打包/加密分类
- `obfuscation.detect` - 检测 CFF、不透明谓词、字符串加密、导入混淆、反反汇编、.NET 混淆
- `taint.track` - 静态污点追踪：源/汇 API 映射、污点路径枚举、风险分类
- `unpack.guide` - 针对 UPX、Themida、VMProtect、.NET Reactor、ConfuserEx、ASPack、PECompact 的智能脱壳指导
- `frida.script.generate` - 基于分析证据自动生成 Frida 挂钩脚本（加密、网络、文件 I/O、注册表、进程、反调试、内存）
- `sigma.rule.generate` - 基于样本证据自动生成 Sigma 检测规则（进程创建、文件事件、注册表、网络、DNS、镜像加载）
### 语义审查和重构
- `code.function.rename.prepare`（弃用，使用 `llm.analyze`）
- `code.function.rename.review`（已弃用，使用 `llm.analyze`）
- `code.function.rename.apply`（已弃用，使用 `llm.analyze`）
- `code.function.explain.prepare`（已弃用，使用 `llm.analyze`）
- `code.function.explain.review`（已弃用，使用 `llm.analyze`）
- `code.function.explain.apply`（已弃用，使用 `llm.analyze`）
- `code.module.review.prepare`（已弃用，使用 `llm.analyze`）
- `code.module.review`（已弃用，使用 `llm.analyze`）
- `code.module.review.apply`（已弃用，使用 `llm.analyze`）
- `code.reconstruct.plan`
- `code.reconstruct.export`
### LLM 辅助分析（新增）
- `llm.analyze` - 统一的 LLM 分析接口（取代已弃用的 3 步工具）
- `task: 'summarize'` - 简洁摘要
- `task: 'explain'` - 清晰解释
- `task: 'recommend'` - 可操作建议
- `task: 'review'` - 批判性审查
## 高级工作流
这些是 MCP 客户端的主要编排入口点。
### `workflow.triage`
PE 样本的快速首遍分类外观。当您想要由分阶段运行模型支持的受控 `fast_profile` 视图时使用此功能。
**重要提示**：将此视为兼容性视图，而不是深度静态分析已完成的证明。对于更深层次的工作，请使用 `workflow.analyze.promote` 或 `workflow.analyze.status`。
### `workflow.deep_static`
用于深度分析和排名的长时间静态管道。支持异步作业模式。
**注意**：对于主要的非阻塞客户端流，请优先使用 `workflow.analyze.start` 加上 `workflow.analyze.promote`。仅在需要原始作业详细信息时使用 `task.status`。
### `workflow.reconstruct`
主要的高级重构工作流。
**注意**：对于编排和重用，请优先使用分阶段运行模型。`workflow.reconstruct` 仍然是一个深度工作流表面，但 `workflow.analyze.status` 应该是您的首选进度查找。
## 运行与作业模型
服务器现在有两个不同的层：
- **运行层**：`workflow.analyze.start/status/promote`
- **作业层**：`task.status/task.cancel/task.sweep`
首选客户端流程：
**示例：**
```
const start = await workflow.analyze.start({ sample_id: '...', goal: 'reverse' })
const runId = start.data.run_id
await workflow.analyze.promote({ run_id: runId, through_stage: 'function_map' })
const status = await workflow.analyze.status({ run_id: runId })
```
**文档：**
- [分析运行时](docs/ANALYSIS-RUNTIME.md)
- [异步作业模式指南](docs/ASYNC-JOB-PATTERN.md)
- [迁移指南](docs/MIGRATION-ASYNC.md)
- 基于角色感知预检为原生 Rust、DLL 和面向 COM 的样本调整导出策略
- 当 Java、Ghidra 或可选依赖项未就绪时返回结构化设置指导
- 为排队和前台运行呈现面向阶段的进度元数据
- 在结果中携带运行时和语义来源
### `workflow.function_index_recover`
用于困难原生二进制文件的高级恢复链：
- `code.functions.smart_recover`
- `pe.symbols.recover`
- `code.functions.define`
当 Ghidra 分析存在但函数提取为空或降级时使用此功能。
### `workflow.semantic_name_review`
用于外部 LLM 客户端的高级语义命名审查工作流。它可以准备证据，在可用时通过 MCP 采样请求模型审查，应用接受的名称，并可选择刷新重构/导出输出。当导出刷新运行时，工作流现在携带与 `workflow.reconstruct` 相同的 `ghidra_execution` 摘要，包括项目根目录、日志根目录、命令/运行时日志路径、进度阶段和解析的 Java 异常上下文。
### `workflow.function_explanation_review`
用于外部 LLM 客户端的高级解释工作流。它可以准备证据，请求结构化解释，应用它们，并可选择重新运行重构/导出。导出刷新结果也呈现 `ghidra_execution`，因此重度解释的审查链仍然暴露 Ghidra 项目/日志上下文和进度元数据。
### `workflow.module_reconstruction_review`
用于外部 LLM 客户端的高级模块审查工作流。它可以准备重构的模块以供审查，在可用时通过 MCP 采样请求结构化模块优化，应用接受的模块摘要和指导，并可选择刷新重构/导出输出。当导出刷新运行时，工作流还携带 `ghidra_execution`，因此模块级审查链像重构和函数级审查工作流一样暴露 Ghidra 项目/日志上下文和进度元数据。
## 通用恢复模型
此服务器不假设 Ghidra 始终能够正确恢复函数。
对于困难的原生样本，尤其是 Rust、Go 或高度优化的二进制文件，恢复路径为：
1. `ghidra.analyze`
2. 如果 Ghidra 后置脚本提取失败，使用 `pe.pdata.extract`
3. 使用 `code.functions.smart_recover` 恢复候选函数边界
4. 使用 `pe.symbols.recover` 恢复名称
5. 使用 `code.functions.define` 导入恢复的边界
6. 继续执行 `code.functions.list`、`code.functions.rank`、`code.functions.reconstruct` 或 `workflow.reconstruct`
这意味着 `function_index` 就绪状态与 `decompile` 和 `cfg` 就绪状态分开跟踪。
## 证据范围、语义范围和可重放性
大多数高级工具支持显式范围控制，以便客户端可以在所有历史记录和当前会话之间进行选择。
运行时证据选择：
- `evidence_scope=all`
- `evidence_scope=latest`
- `evidence_scope=session` 并附带 `evidence_session_tag`
语义命名 / 解释 / 模块审查选择：
- `semantic_scope=all`
- `semantic_scope=latest`
- `semantic_scope=session` 并附带 `semantic_session_tag`
还支持通过以下方式进行感知比较的输出：
- `compare_evidence_scope`
- `compare_evidence_session_tag`
- `compare_semantic_scope`
- `compare_semantic_session_tag`
这允许 MCP 客户端不仅询问“当前结果是什么？”，还可以询问“与以前的证据或语义审查会话相比有什么变化？”
静态分析产物选择：
- `static_scope=all`
- `static_scope=latest`
- `static_scope=session` 并附带 `static_session_tag`
静态基线比较：
- `compare_static_scope`
- `compare_static_session_tag`
## LLM 审查层
此服务器支持多个结构化审查层，供具有工具调用和可选采样的 MCP 客户端使用：
- 函数命名审查
- 函数解释审查
- 模块重构审查
每一层遵循相同的模式：
1. 准备结构化证据包
2. 可选地请求连接的 MCP 客户端通过采样执行受控审查
3. 将接受的结果应用为稳定的语义产物
4. 针对显式语义范围重新运行重构/导出/报告工作流
## 异步作业模型
长时间运行的工作流支持排队执行和后台完成：
- `workflow.deep_static`
- `workflow.reconstruct`
- `workflow.semantic_name_review`
- `workflow.function_explanation_review`
- `workflow.module_reconstruction_review`
将这些与以下内容一起使用：
- `task.status`
- `task.cancel`
- `task.sweep`
排队的工作流响应和 `task.status` 包括 `polling_guidance`，但主要的分阶段编排表面仍然是 `workflow.analyze.status`。
当长时间运行的阶段排队/运行时，MCP 客户端应首先优先考虑运行级状态，并且仅为了原始队列详细信息时才回退到 `task.status`。
## 环境引导和设置指导
如果客户端在配置 Python、动态分析额外组件或 Ghidra 之前开始使用服务器，请使用：
- `system.health`
- `dynamic.dependencies`
- `ghidra.health`
- `system.setup.guide`
这些返回结构化的设置操作和所需的用户输入，以便 MCP 客户端可以明确要求：
- `python -m pip install ...`
- `JAVA_HOME`
- `GHIDRA_PATH` / `GHIDRA_INSTALL_DIR`
- `GHIDRA_PROJECT_ROOT` / `GHIDRA_LOG_ROOT`
- `CAPA_RULES_PATH`
- `DIE_PATH`
- 可选的动态分析额外组件，如 Speakeasy/Frida 依赖项
- Docker 全栈额外组件，如 Graphviz/Rizin/YARA-X/UPX/Wine/Qiling/angr/PANDA/RetDec
### Frida 动态插桩（可选）
用于运行时 API 追踪和行为分析，安装 Frida：
```
pip install frida frida-tools
```
**环境变量**（可选 - 当 `frida` 在 PATH 中时自动检测）：
- `FRIDA_SERVER_PATH` - 用于 USB/远程设备分析的 Frida 服务器二进制文件路径
- `FRIDA_DEVICE` - 用于 USB 设备选择的设备 ID 或 "usb"（默认：本地生成）
**预构建脚本** 包含在 `src/plugins/frida/scripts/` 中：
- `api_trace.js` - 带参数日志记录的 Windows API 追踪
- `string_decoder.js` - 运行时字符串解密
- `anti_debug_bypass.js` - 反调试检测中和
- `crypto_finder.js` - 加密 API 检测
- `file_registry_monitor.js` - 文件/注册表操作跟踪
有关使用示例，请参阅 [`docs/EXAMPLES.md`](./docs/EXAMPLES.md#场景 -9-frida-运行时 instrumentation)。
## 当前开发状态
### 最新版本：v1.0.0-beta.3
**稳定功能**（生产就绪）：
- PE 分类和静态分析（`static.capability.triage`、`pe.structure.analyze`、`compiler.packer.detect`）
- 具有完全执行可见性的 Ghidra 支持检查
- DLL/COM 分析（`dll.export.profile`、`com.role.profile`）
- Rust 和 .NET 恢复路径
- 带有 LLM 辅助审查层的类源码重构
- 运行时证据摄取和关联
- Android/APK 分析（`apk.structure.analyze`、`dex.decompile`、`dex.classes.list`、`apk.packer.detect`）
- 符号执行和 CrackMe 工具（`symbolic.explore`、`keygen.verify`、`constraint.solve`）
- 恶意软件分析（`malware.config.extract`、`malware.classify`、`c2.extract`）
- 跨平台二进制解析（`elf.macho.parse`、`rizin.diff`）
- 可视化和关联（`cfg.visualize`、`timeline.correlate`、`cross_module.xref`、`kb.search`）
- Frida 动态插桩（`frida.runtime.instrument`、`frida.script.inject`、`frida.trace.capture`）
- 带有 REST API 的 HTTP 文件服务器（端口 18080）—— 样本上传、产物 CRUD、SSE 事件
- 位于 `http://localhost:18080/dashboard` 的 **Web 仪表板** —— 工具、插件、样本、配置、系统的实时监控
- 带有 56 个内置插件的 **插件 SDK**，支持热加载/卸载和第三方自动发现
- **生产基础设施**：速率限制、配置验证、分页、重试、批量分析、SBOM 生成
- **SSE 实时事件**：用于实时分析进度流传输的 Server-Sent Events
### 完整服务清单（Docker）
在 Docker 中运行时（`docker-compose up -d`），容器暴露：
| 服务 | 访问方式 | 描述 |
|---------|--------|-------------|
| MCP 服务器 | stdio (`docker exec -i`) | 222 个工具、3 个提示、16 个资源，供 LLM 客户端使用 |
| HTTP API | `http://localhost:18080/api/v1/*` | 用于样本、产物、上传、健康状况、SSE 的 REST API |
| Web 仪表板 | `http://localhost:18080/dashboard` | 实时监控 SPA（8 个选项卡，暗黑主题） |
| SSE 事件 | `http://localhost:18080/api/v1/events` | 用于分析事件的实时事件流 |
| 仪表板 API | `http://localhost:18080/api/v1/dashboard/*` | 支持仪表板的 12 个 JSON 端点 |
### 内置插件（56 个）
| 插件 | ID | 工具数 | 描述 |
|--------|----|-------|-------------|
| Android / APK | `android` | 4 | APK manifest、DEX 反编译、打包器检测 |
| angr | `angr` | 1 | 符号执行引擎 |
| API Hash | `api-hash` | 2 | Shellcode API 哈希解析 |
| APK Smali | `apk-smali` | 3 | APK Smali 反汇编和分析 |
| 批量分析 | `batch` | 3 | 批量样本处理 |
| 行为优先 | `behavior-first` | 3 | 行为分析优先级 |
| 二进制差异 | `binary-diff` | 2 | 二比较和修补 |
| Capstone | `capstone` | 2 | 反汇编引擎集成 |
| 代码分析 | `code-analysis` | 19 | CFG、反编译、交叉引用、代码模式 |
| CrackMe 自动化 | `crackme` | 4 | 验证位置、符号执行、修补、keygen |
| 跨模块分析 | `cross-module` | 3 | 跨二进制比较、调用图、DLL 依赖树 |
| 调试会话 | `debug-session` | 9 | GDB/LLDB 调试会话管理 |
| 深度脱壳 | `deep-unpack` | 3 | 带仿真的多层脱壳 |
| Detect It Easy | `die` | 2 | 编译器、打包器和保护程序检测 |
| .NET 反编译 | `dotnet-decompile` | 2 | .NET 程序集反编译 |
| .NET Reactor | `dotnet-reactor` | 4 | .NET 混淆分析和去混淆 |
| 动态分析 | `dynamic` | 7 | 自动 Frida 挂钩、追踪归因、内存转储 |
| ELF/Mach-O | `elf-macho` | 4 | 跨平台二进制解析 |
| 固件 | `firmware` | 3 | 固件提取和分析 |
| Frida 插桩 | `frida` | 4 | 运行时插桩、脚本注入、追踪捕获 |
| Ghidra 集成 | `ghidra` | 2 | 无头 Ghidra 分析和健康检查 |
| Go 分析 | `go-analysis` | 3 | Go 二进制分析和符号恢复 |
| Graphviz | `graphviz` | 1 | 使用 DOT 进行图可视化 |
| 主机关联 | `host-correlation` | 1 | 主机级产物关联 |
| 知识库 | `kb-collaboration` | 8 | 函数签名匹配、分析模板 |
| 恶意软件分析 | `malware` | 4 | C2 提取、配置解析、家族分类 |
| 托管 Fake C2 | `managed-fake-c2` | 1 | 用于受控分析的 Fake C2 服务器 |
| 托管 IL XRefs | `managed-il-xrefs` | 2 | .NET IL 交叉引用分析 |
| 托管沙箱 | `managed-sandbox` | 1 | 托管沙箱执行环境 |
| 内存取证 | `memory-forensics` | 6 | 内存转储分析、Volatility 集成 |
| 元数据 | `metadata` | 1 | 二进制元数据提取 |
| 可观测性 | `observability` | 1 | 工具调用挂钩追踪和指标 |
| Office 分析 | `office-analysis` | 3 | Office 文档宏和 OLE 分析 |
| PANDA | `panda` | 1 | PANDA 记录/重放分析 |
| PCAP 分析 | `pcap-analysis` | 3 | 网络数据包捕获分析 |
| PE 分析 | `pe-analysis` | 6 | PE 结构、导入、导出、指纹、pdata、符号恢复 |
| PE 签名 | `pe-signature` | 2 | PE 数字签名验证 |
| Qiling | `qiling` | 1 | 使用 Qiling 进行二进制仿真 |
| 报告 | `reporting` | 3 | 报告生成和导出 |
| RetDec | `retdec` | 1 | RetDec 反编译后端 |
| Rizin | `rizin` | 1 | Rizin 反汇编后端 |
| 运行时去混淆 | `runtime-deobfuscate` | 4 | 带仿真的运行时去混淆 |
| SBOM | `sbom` | 1 | 软件物料清单生成 |
| 相似性 | `similarity` | 2 | 二进制相似性和匹配 |
| Speakeasy | `speakeasy` | 3 | 基于 Speakeasy 的仿真分析 |
| 静态分类 | `static-triage` | 17 | 能力分类、PE 结构、编译器/打包器检测 |
| 字符串 | `strings` | 2 | 高级字符串提取和分析 |
| 威胁情报 | `threat-intel` | 3 | ATT&CK 映射和 IOC 导出 |
| 脱壳 | `unpacking` | 2 | 打包器检测和脱壳 |
| UPX | `upx` | 1 | UPX 脱壳后端 |
| 可视化 | `visualization` | 3 | HTML 报告、行为时间线、数据流图 |
| VM 分析 | `vm-analysis` | 10 | VM/仿真器检测和分析 |
| 漏洞扫描器 | `vuln-scanner` | 2 | 漏洞模式扫描和摘要 |
| Wine | `wine` | 1 | 通过 Wine 执行 Windows PE |
| YARA | `yara` | 3 | YARA 规则扫描和生成 |
| YARA-X | `yara-x` | 1 | YARA-X 下一代规则引擎 |
插件通过 `PLUGINS` 环境变量控制（`*` = 全部，`android,malware` = 特定，`-dynamic` = 排除）。请参阅 [`docs/PLUGINS.md`](./docs/PLUGINS.md)。
### 开发中（Beta 后路线图）
对于新的静态分类基础，最常见的可选要求是：
- `flare-capa`
- `pefile`
- `lief`
- 由 `CAPA_RULES_PATH` 引用的已下载 capa 规则包
- 由 `DIE_PATH` 引用的 Detect It Easy CLI
Docker 镜像现在默认捆绑静态分析栈：
- `flare-capa`
- 位于 `/usr/local/bin/capa` 的容器本地 `capa` CLI 包装器
- 位于 `/opt/capa-rules` 的捆绑 `capa-rules`
- 位于 `/opt/capa-sigs` 的捆绑 `capa` 签名
- 使用稳定的 `3.10 Debian 12` 软件包的位于 `/usr/bin/diec` 的捆绑 Detect It Easy CLI
对于 Ghidra 12.0.4，服务器需要 Java 21+，并将通过以下方式报告显式 Java 兼容性提示：
- `ghidra.health`
- `system.health`
- `system.setup.guide`
对于 Docker 部署，这意味着 Java 21+ JDK，而不仅仅是 JRE。容器化运行时应同时暴露 `java` 和 `javac`。
当 Ghidra 命令失败时，服务器现在会持久化命令日志，并在可用时持久化 Ghidra 运行时日志。标准化诊断包括 Java 异常摘要和修复提示，而不仅仅是返回 `exit code 1`。
捆绑的 `src/plugins/ghidra/scripts/` 目录是从已安装的包或存储库根目录解析的，而不是从当前工作目录解析。这可以防止当从不同文件夹启动服务器时出现 `ExtractFunctions.py` / `ExtractFunctions.java` 查找失败。
## Ghidra 执行可见性
高级输出现在呈现结构化的 `ghidra_execution` 块，而不是将 Ghidra 细节隐藏在通用的成功/失败状态后面。
您现在可以看到：
- 选择了哪个分析记录
- 结果是来自最佳就绪分析还是仅来自最新尝试
- 项目路径、项目根目录和日志根目录
- 持久化的命令日志和运行时日志
- 函数提取状态和脚本名称
- 分阶段进度元数据
- 当 Ghidra 失败时的解析 Java 异常摘要
此摘要通过以下方式呈现：
- `workflow.reconstruct`
- 当导出刷新运行时的 `workflow.semantic_name_review`
- 当导出刷新运行时的 `workflow.function_explanation_review`
- 当导出刷新运行时的 `workflow.module_reconstruction_review`
- `report.summarize`
- `report.generate`
## 架构
服务器使用一个**集中式工具注册表**（`src/tool-registry.ts`），在一个地方导入并连接 31 个核心 MCP 工具、3 个提示和 16 个资源。
另外 191 个工具由 56 个内置插件注册，使总数达到 222 个 MCP 工具。
入口点（`src/index.ts`）保持在 90 行以下。
所有 56 个工具类别 —— 从 PE 分析和漏洞扫描到 Android、Malware、Frida、Ghidra 和调试会话 —— 都作为**插件**进行管理，可以通过 `PLUGINS` 环境变量切换（默认：全部启用）。
请参阅 [docs/PLUGINS.md](./docs/PLUGINS.md)。
其他基础设施：
| 组件 | 文件 | 用途 |
|-----------|------|---------|
| 安全命令执行 | `src/safe-command.ts` | 白名单验证的、基于数组的命令调用 —— 防止 shell 注入 |
| Python 进程池 | `src/worker/python-process-pool.ts` | 并发限制的工作器池（`MAX_PYTHON_WORKERS` 环境变量） |
| 流式进度 | `src/streaming-progress.ts` | 用于长时间运行工具的 MCP `notifications/progress` |
| MCP 资源 | `src/tool-registry.ts` | 8 个 Frida + 8 个 Ghidra 脚本可通过 `resources/list` 发现 |
| HTTP 文件服务器 | `src/api/file-server.ts` | REST API（端口 18080），用于样本上传、产物 CRUD、SSE 事件和仪表板 |
| Web 仪表板 | `src/api/dashboard/index.html` | 位于 `/dashboard` 的暗黑主题 SPA —— 工具、插件、样本、配置、系统信息 |
| 仪表板 API | `src/api/routes/dashboard-api.ts` | 12 个 JSON 端点（`/api/v1/dashboard/*`）支持 Web 仪表板 |
| SSE 事件 | `src/api/sse-events.ts` | 用于实时分析进度和服务器状态的 Server-Sent Events |
| 速率限制器 | `src/api/rate-limiter.ts` | HTTP API 的请求速率限制 |
| 配置验证器 | `src/config-validator.ts` | 验证运行时配置并通过仪表板呈现诊断信息 |
| CI 安全扫描 | `.github/workflows/ci.yml` | npm audit + pip-audit + CodeQL SAST |
| 结构化日志 | `src/logger.ts` | Pino JSON 日志记录、子记录器、审计事件 |
完整详情：[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
## 项目布局
```
bin/ npm CLI entrypoint
dist/ compiled TypeScript output
src/ TypeScript MCP server source
index.ts Entry point (~90 lines)
server.ts MCPServer class (tools, prompts, resources)
tool-registry.ts Centralised tool/prompt/resource registration
plugins.ts Plugin framework (56 built-in + auto-discovery)
safe-command.ts Command injection prevention
config-validator.ts Runtime config validation with diagnostics
logger.ts Pino structured logging
analysis/ Analysis orchestration modules
plugins/
frida/scripts/ Frida instrumentation scripts (also MCP resources)
ghidra/scripts/ Ghidra helper scripts used by the server
static-triage/helpers/ .NET metadata helper project (DotNetMetadataProbe)
artifacts/ Artifact management and storage
constants/ Shared constants
ghidra/ Ghidra integration helpers
llm/ LLM prompt and review modules
prompts/ MCP prompt definitions
sample/ Sample ingestion and management
storage/ Storage layer abstractions
utils/ Shared utility modules
worker/ Python process pool and worker management
tools/ Core tool definitions and handlers (31 files)
plugins/ Plugin directory (56 built-in plugins)
sdk.ts Plugin contract and shared types
android/ Android/APK analysis plugin
angr/ Symbolic execution plugin
api-hash/ API hash resolution plugin
apk-smali/ APK Smali analysis plugin
batch/ Batch sample processing plugin
behavior-first/ Behavioral analysis plugin
binary-diff/ Binary comparison plugin
capstone/ Disassembly engine plugin
code-analysis/ CFG, decompilation, and code patterns plugin
crackme/ CrackMe automation plugin
cross-module/ Cross-binary analysis plugin
debug-session/ GDB/LLDB debug session plugin
deep-unpack/ Multi-layer unpacking plugin
die/ Detect It Easy plugin
dotnet-decompile/ .NET decompilation plugin
dotnet-reactor/ .NET deobfuscation plugin
dynamic/ Dynamic analysis plugin
elf-macho/ Cross-platform binary parsing plugin
firmware/ Firmware analysis plugin
frida/ Frida instrumentation plugin
ghidra/ Ghidra integration plugin
go-analysis/ Go binary analysis plugin
graphviz/ Graph visualization plugin
host-correlation/ Host artifact correlation plugin
kb-collaboration/ Knowledge base plugin
malware/ Malware analysis plugin
managed-fake-c2/ Fake C2 server plugin
managed-il-xrefs/ .NET IL cross-reference plugin
managed-sandbox/ Managed sandbox plugin
memory-forensics/ Memory forensics plugin
metadata/ Metadata extraction plugin
observability/ Tool call tracing plugin
office-analysis/ Office document analysis plugin
panda/ PANDA record/replay plugin
pcap-analysis/ PCAP network analysis plugin
pe-analysis/ PE binary analysis plugin
pe-signature/ PE signature verification plugin
qiling/ Qiling emulation plugin
reporting/ Report generation plugin
retdec/ RetDec decompilation plugin
rizin/ Rizin disassembly plugin
runtime-deobfuscate/ Runtime deobfuscation plugin
sbom/ SBOM generation plugin
similarity/ Binary similarity plugin
speakeasy/ Speakeasy emulation plugin
static-triage/ Static capability triage plugin
strings/ String extraction plugin
threat-intel/ Threat intelligence plugin
unpacking/ Packer detection and unpacking plugin
upx/ UPX unpacking plugin
visualization/ Reporting and visualization plugin
vm-analysis/ VM/emulator detection plugin
vuln-scanner/ Vulnerability pattern detection plugin
wine/ Wine PE execution plugin
yara/ YARA rule scanning plugin
yara-x/ YARA-X next-gen plugin
api/
file-server.ts HTTP API server (port 18080)
rate-limiter.ts Request rate limiting
auth-middleware.ts API key authentication
sse-events.ts Server-Sent Events for real-time streaming
dashboard/index.html Web dashboard SPA (dark theme, 8 tabs)
routes/
health.ts Health check endpoint
dashboard-api.ts Dashboard JSON API (12 endpoints)
tests/ unit and integration tests (212 test files)
workers/ Python workers, YARA rules, dynamic helpers
packages/plugin-sdk/ Standalone Plugin SDK npm package
docs/ Documentation
ARCHITECTURE.md Internal architecture guide
PLUGINS.md Plugin system guide
DOCKER.md Docker deployment guide (with service inventory)
API-FILE-SERVER.md HTTP API usage guide
API-REFERENCE.md Complete API reference
QUALITY_EVALUATION.md Evaluation checklist for release readiness
```
## 先决条件
### 选项 1：Docker（推荐 - 零配置）
运行 MCP 服务器并预装所有依赖项的最简单方法：
```
# 构建 Docker 镜像（10-15 分钟，约 2.5GB）
docker build -t rikune:latest .
# 或者从 registry 拉取（发布后）
# docker pull ghcr.io/last-emo-boy/rikune:latest
# 使用 Docker Compose 运行
docker-compose up -d mcp-server
# 或者直接运行
docker run --rm -i \
--network=none \
-v ./samples:/samples:ro \
-v ~/.rikune/workspaces:/app/workspaces \
rikune:latest
```
有关完整的 Docker 文档，请参阅 [`docs/DOCKER.md`](./docs/DOCKER.md)。
默认 Docker 镜像现在是一个完整的 Linux 端分析栈。除了基础的 `Ghidra`、`capa`、`Detect It Easy`、`FLOSS`、`legacy YARA` 和 `Speakeasy` 组件外，它还捆绑了：
- `Graphviz`、`Rizin`、`YARA-X`、`UPX`、`RetDec`
- `frida-tools`、`Wine`、`winedbg`、`Qiling`（隔离解释器）、`angr`、`pandare`
重要注意事项：
- `Qiling` 仍需要通过 `QILING_ROOTFS` 外部挂载 Windows rootfs。
- `Wine` 和 `winedbg` 是有用的 Linux 托管用户模式辅助器，不是完整的 Windows 桌面调试替代品。
- `RetDec` 是一个重型后端，应优先消费产物，而不是返回超大的内联负载。
### 选项 2：本地安装
必需：
- Node.js 18+
- npm 9+
- Python 3.9+
可选但强烈推荐：
- Ghidra，用于原生反编译和 CFG 功能
- .NET SDK，用于 `dotnet.metadata.extract`
- Clang，用于重构导出验证
- 来自 [`requirements.txt`](./requirements.txt) 的 Python 包
- 来自 [`workers/requirements.txt`](./workers/requirements.txt) 的 Python worker 包
## 本地开发
### 选项 1：Docker 开发（推荐）
```
# 构建镜像
npm run docker:build
# 测试工具链
npm run docker:test
# 进入容器进行调试
npm run docker:run
# 清理 Docker 资源
npm run docker:clean
```
### 选项 2：原生开发
安装 JavaScript 依赖项：
```
npm install
```
安装 Python worker 依赖项：
```
python -m pip install -r requirements.txt
python -m pip install -r workers/requirements.txt
python -m pip install -r workers/requirements-dynamic.txt
```
构建：
```
npm run build
```
运行测试：
```
npm test
```
本地启动：
```
npm start
```
## MCP 客户端配置
### 通用 stdio 配置
```
{
"mcpServers": {
"rikune": {
"command": "node",
"args": ["/absolute/path/to/repo/dist/index.js"],
"cwd": "/absolute/path/to/repo",
"env": {
"GHIDRA_PATH": "C:/path/to/ghidra",
"GHIDRA_INSTALL_DIR": "C:/path/to/ghidra"
}
}
}
}
```
### Docker Compose 加 `docker exec`
对于单容器部署模型，使用 `docker compose up -d mcp-server` 启动守护进程一次，并将 MCP 客户端指向正在运行的容器：
```
{
"mcpServers": {
"rikune": {
"command": "docker",
"args": [
"exec",
"-i",
"rikune",
"node",
"dist/index.js"
],
"env": {
"NODE_ENV": "production",
"PYTHONUNBUFFERED": "1",
"WORKSPACE_ROOT": "/app/workspaces",
"DB_PATH": "/app/data/database.db",
"CACHE_ROOT": "/app/cache",
"GHIDRA_PROJECT_ROOT": "/ghidra-projects",
"GHIDRA_LOG_ROOT": "/ghidra-logs"
},
"timeout": 300000
}
}
}
```
在此部署中，主机端文件上传应使用 `sample.request_upload` 和返回的 `http://localhost:18080/api/v1/uploads/` URL，而不是尝试将主机文件系统路径传递到容器化的 worker 中。
### 本地安装辅助器
- GitHub Copilot：COPILOT_INSTALLATION.md`](./COPILOT_INSTALLATION.md)
相关文档：
- [`COPILOT_INSTALLATION.md`](./COPILOT_INSTALLATION.md)
- [`docs/ANALYSIS-COVERAGE.md`](./docs/ANALYSIS-COVERAGE.md)
## 持久化存储
默认情况下，运行时状态存储在用户配置文件下，而不是当前工作目录下：
- Windows 工作区根目录：`%USERPROFILE%/.rikune/workspaces`
- SQLite 数据库：`%USERPROFILE%/.rikune/data/database.db`
- 文件缓存：`%USERPROFILE%/.rikune/cache`
- 审计日志：`%USERPROFILE%/.rikune/audit.log`
- Ghidra 项目根目录：`%ProgramData%/.rikune/ghidra-projects`
- Ghidra 日志根目录：`%ProgramData%/.rikune/ghidra-logs`
- 捆绑的 Ghidra 脚本：从已安装的包根目录解析
您可以使用环境变量或用户配置文件覆盖这些设置：
- `%USERPROFILE%/.rikune/config.json`
- `WORKSPACE_ROOT`
- `DB_PATH`
- `CACHE_ROOT`
- `AUDIT_LOG_PATH`
- `GHIDRA_PROJECT_ROOT`
- `GHIDRA_LOG_ROOT`
## 样本摄取说明
对于本地 IDE 客户端，如 VS Code 或 Copilot，请优先使用本地文件路径：
```
{
"tool": "sample.ingest",
"arguments": {
"path": "E:/absolute/path/to/sample.exe"
}
}
```
仅当客户端无法访问与服务器相同的文件系统时才使用 `bytes_b64`。
## 加密样本和调试感知分析
对于可疑或已确认的加密二进制文件，请优先使用分阶段脱壳/调试路径，而不是立即进行深度重构：
```
workflow.analyze.start
-> workflow.analyze.status
-> workflow.analyze.promote(dynamic_plan)
-> workflow.analyze.status
-> workflow.analyze.promote(dynamic_execute)
-> workflow.summarize
```
重要的运行时字段：
- `packed_state`
- `unpack_state`
- `unpack_confidence`
- `unpack_plan`
- `debug_state`
- `debug_session`
- `diff_digests` / `unpack_debug_diffs`
实用指导：
- `upx.inspect(test|list)` 是一个安全的脱壳探测
- `upx.inspect(decompress)` 是 UPX 风格样本的有界转换路径
- `breakpoint.smart` 和 `trace.condition` 仅用于规划，有助于构建持久化的调试会话
- `frida.trace.capture` 和 `wine.run` 仍然是手动或批准门控的执行表面
- `workflow.summarize` 和 `report.summarize(detail_level='compact')` 应优先考虑脱壳/调试差异摘要，而不是原始转储或追踪树
## 发布到 npm
发布的包包括：
- 编译后的 `dist/`
- `bin/` 中的 CLI 入口点
- Python workers 和 YARA 规则
- Ghidra 辅助脚本
- .NET 元数据辅助器源代码
- MCP 客户端安装脚本
它排除：
- 测试
- 本地工作区
- 缓存
- 生成的报告
- 临时文档和内部进度说明
发布前检查清单：
1. 更新 [`package.json`](./package.json) 中的版本。
2. 运行 `npm run release:check`。
3. 检查 `npm run pack:dry-run`。
4. 使用 `npm login` 登录。
5. 使用 `npm publish --access public` 发布。
此仓库中包含的 GitHub 自动化：
- [`ci.yml`](./.github/workflows/ci.yml)
- [`publish-npm.yml`](./.github/workflows/publish-npm.yml)
- [`dependabot.yml`](./.github/dependabot.yml)
对于 GitHub Actions 发布，请配置 `NPM_TOKEN` 仓库密钥。
## 安全边界
该项目用于分析工作流，而非实时的恶意软件操作。
当前优势：
- PE 分类和分类支持
- 逆向工程证据提取
- IOC 和 ATT&CK 导出
- 运行时证据导入和关联
- 类源码重构和审查
当前非目标：
- 复杂原生二进制文件的原始源代码恢复
- 仅从静态证据保证恶意软件家族归因
- 针对每个打包器的完全自动脱壳
- 在高度优化的代码中每个函数的高置信度语义恢复
## 贡献和发布流程
- 贡献者指南：[`CONTRIBUTING.md`](./CONTRIBUTING.md)
- 架构概览：[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
- 插件开发：[`docs/PLUGINS.md`](./docs/PLUGINS.md)
- 质量评估说明：[`docs/QUALITY_EVALUATION.md`](./docs/QUALITY_EVALUATION.md)
- 示例基准语料库：[`docs/examples/benchmark-corpus.example.json`](./docs/examples/benchmark-corpus.example.json)
- 安全策略：[`SECURITY.md`](./SECURITY.md)
## 使用发布的包
已发布的 npm 包现在最好被视为一个轻量级的 MCP 启动器，而 Docker 承载着繁重的逆向工程运行时。这将 npm 和 Docker 分开，但有意强绑定：
- `npm` / `npx` 提供面向客户端的可执行文件和版本化启动器
- `docker compose up -d mcp-server` 提供持久运行时、存储、上传 API 和工具链
这并**没有**删除现有的源代码检出或直接 Docker 客户端路径。如果您从克隆的仓库运行，`node dist/index.js` 和直接 `docker exec ... node dist/index.js` 仍然有效。
推荐的发布包流程：
1. 启动守护进程运行时一次：
```
docker compose up -d mcp-server
```
2. 将 MCP 客户端指向 npm 启动器：
```
{
"mcpServers": {
"rikune": {
"command": "npx",
"args": ["-y", "rikune", "docker-stdio"]
}
}
}
```
启动器的可选覆盖：
- `RIKUNE_DOCKER_CONTAINER`
- `RIKUNE_DOCKER_IMAGE`
对于本地克隆/原生模式，请继续使用本 README 中前面的示例，直接调用 `node /absolute/path/to/dist/index.js`。
## 许可证
在 MIT 许可证下发布。请参阅 [`LICENSE`](
标签：angr, Cloudflare Workers, COM组件分析, DAST, DLL分析, Docker分析环境, Docker支持, Frida, Ghidra自动化, LLM工具, MCP服务器, MITM代理, .NET反编译, OpenCanary, PE文件分析, Qiling, RESTful API, RetDec, Rizin, Rust逆向, SecList, Windows逆向工程, YARA-X, 二进制安全, 二进制漏洞分析, 云安全监控, 代码生成, 内存取证, 对称加密, 工作流编排, 恶意软件分析, 提示词优化, 文件上传, 渗透测试工具, 源码级重构, 符号恢复, 网络信息收集, 网络安全, 自动化审计, 自动化攻击, 请求拦截, 运行时取证, 逆向工具, 隐私保护, 静态分析