Rikune

Rikune 是一个面向 Windows EXE 和多格式二进制逆向的 MCP Server。它把样本导入、静态初筛、Ghidra 辅助函数恢复、插件化专业工具、artifact 管理，以及可选的隔离 Windows 运行时执行统一暴露给 MCP 客户端。

当前面向 AI 客户端的主路径是最小 gateway surface：

用 workflow.search 根据文件类型、样本画像和用户目标搜索并排序 workflow / specialist capabilities。
宿主机文件上传用 workflow.run action=request_upload；旧客户端需要直接导入时，再由 workflow.search 指向隐藏的 sample-intake compatibility 工具。
拿到 sample_id 后，用 workflow.run action=start 创建或复用 staged analysis run。
用 workflow.run action=status 查询状态，用 workflow.run action=promote 推进更深阶段。
紧凑输出不够时，用 artifact.read 读取完整持久化 artifact。

sample.*、workflow.analyze.*、workflow.triage、tools.discover 和 task.status 仍保留为兼容或低层检查入口；新客户端应优先使用 workflow.search、workflow.run 和 artifact.read。

通过远程 rikune-agent gateway 连接时，MCP 客户端看到的是固定 transport 名称： workflow_search、workflow_run、artifact_read、rikune_tool_call，以及 rikune_connection_* 控制入口。rikune_connection_refresh 只更新内部上游能力缓存，不会扩展 MCP tool list。只有当 workflow_search 明确识别到某个 primary workflow / artifact gateway 覆盖不到的内部 analyzer subtool 时，才使用 rikune_tool_call 调用。

核心能力

MCP stdio server，可直接接入支持 MCP 的 AI 客户端。
可选 HTTP API 和 dashboard，用于上传、下载、健康检查、SSE 事件和 artifact 访问。
按 SHA-256 分桶的样本工作区，保存原始样本、缓存、Ghidra/.NET 输出和报告。
SQLite 持久化 samples、analysis runs、jobs、evidence、artifacts、batches、debug sessions 和 scheduler telemetry。
111 个内置插件，支持第三方插件自动发现。
渐进式工具暴露：默认面向 AI 的入口刻意保持很小；workflow.search 根据样本类型、发现结果和 profile metadata 路由到相关专业能力，而不是一次暴露所有工具。
覆盖 PE、ELF、Mach-O、APK/DEX、Office、firmware、UEFI/SMM、CUDA PTX/CUBIN/fatbin、strings、YARA、SBOM、签名、packer、.NET、Go、Rust 等静态分析。
可集成 Ghidra、Rizin、RetDec、angr、Capstone、Graphviz、Qiling、PANDA、Speakeasy、Wine、Frida 等后端。
插件驱动的 Docker backend 自动安装，支持 default、optional、research、runtime、GPU、BYO 和 sidecar 分层。
可选 Analyzer/Runtime 分离架构，通过 Windows Host Agent、Windows Sandbox 或 Hyper-V VM 执行真实 Windows 运行时任务。
对 live execution、网络访问、外部上传、批量反编译等危险能力做策略门控。

快速开始

Static Docker Analyzer

默认推荐 static profile。它不会执行样本，适合日常静态分析。

.\rikune.ps1 install -Profile static -DataRoot "D:\Docker\rikune"

./rikune.sh install --profile static --data-root "$HOME/.rikune"

手工等价流程：

npm install
npm run build
npm run docker:generate:all
docker compose --env-file .docker-runtime.env -f docker-compose.analyzer.yml up -d --build analyzer

Hybrid Docker + Windows Runtime

Hybrid profile 在 Docker 中运行 Analyzer，把真实 Windows 执行委托给 Windows Host Agent。Host Agent 可按需启动 Windows Sandbox，也可以控制预配置的 Hyper-V VM。

.\rikune.ps1 install -Profile hybrid -InstallRuntime

Linux/macOS analyzer + 远程 Windows runtime host：

./rikune.sh install --profile hybrid --windows-host <windows-host> --windows-user <windows-user>

连接 MCP 客户端不会启动 Sandbox，也不会运行样本。只有 runtime.debug.session.start、runtime.debug.command、sandbox.execute 或 promoted dynamic execution stage 这类显式 live runtime 工具才会触发运行时。

Native 开发

npm install
npm run build
npm test
node dist/index.js

根包要求 Node.js 22 或更新版本。部分 runtime 子包仍能在较旧 Node 上运行，但仓库开发、根 CLI 和发布包以 Node 22+ 为基线。

主要 Gateway 流程

搜索与上传

不确定 workflow、文件类型或后端时，先调用 workflow.search。它会被动排序匹配的 profile / workflow / specialist tool，并返回紧凑的 readiness 与 routing hint，不会自动激活隐藏工具或启动后端。

宿主机文件上传调用 workflow.run action=request_upload，向返回的 upload URL POST 原始字节，然后从 HTTP 响应读取 sample_id。sample.request_upload 和 sample.ingest 是兼容 helper，不是普通 AI-facing 主路径。

远程 analyzer 或 rikune-agent 部署时，设置 API_PUBLIC_BASE_URL、RIKUNE_API_PUBLIC_BASE_URL 或 RIKUNE_ANALYZER_PUBLIC_URL 为客户端可访问的 HTTP API base，例如 http://159.195.136.226:18080。这样上传会话会返回公网/内网可访问的 upload_url / status_url，而不是容器内部的 localhost 地址。远程 gateway 也会把旧 analyzer 返回的 localhost 上传地址归一化到已配置的 analyzer endpoint。

启用 HTTP API 时，非 MCP 集成仍可直接 POST /api/v1/samples。导入成功后会返回 sample_id；后续分析应使用 sample_id，不要继续依赖本地文件路径。

启动分析

用 workflow.run action=start 传入 sample_id。第一阶段会执行 fast profile，并创建或复用 analysis run。返回的 plan_id 映射到持久化 analysis run。

推进阶段

workflow.run action=promote 用于推进更深阶段。当前阶段模型包括：

fast_profile
enrich_static
function_map
reconstruct
semantic_reviews
dynamic_plan
dynamic_execute
summarize

长任务会进入 JobQueue。用 workflow.run action=status 轮询紧凑 staged state。

workflow.run action=status 是主要 staged-run 视图。历史阶段结果过大时会裁剪，并在顶层 warnings 中说明；需要完整内容时用 artifact.read 读取持久化 artifact。task.status 是原始队列/进程兼容视图，并包含 analyzer 子进程的 external_active_* 内存遥测。

阅读结果

常用后续工具：

workflow.search
workflow.run
analysis.context.get
artifact.read，以及兼容 artifact helper：artifact.list、artifact.diff、artifact.download
report.summarize、report.generate、workflow.summarize
workflow.semantic_name_review
workflow.function_explanation_review
workflow.module_reconstruction_review
tool.help、tool.readiness 和 tools.discover 用于兼容/调试检查

架构概览

当前启动链路：

src/index.ts
  -> loadConfig()
  -> WorkspaceManager / DatabaseManager / PolicyGuard / CacheManager / StorageManager / JobQueue
  -> 可选 RuntimeClient 或 Windows sandbox bootstrap
  -> registerAllTools()
  -> MCP stdio server

核心 server 代码位于 src/core/：

模块	当前文件
MCP server wrapper	`src/core/server.ts`
MCP tool/prompt/resource registry	`src/core/mcp-registry.ts`
工具执行、校验、hooks	`src/core/tool-executor.ts`
注册编排	`src/core/tool-registry.ts`
内置注册切片	`src/core/tool-registry/*.ts`
PluginManager facade	`src/core/plugins.ts`
插件发现和加载	`src/core/plugin-orchestrator.ts`
渐进式工具面	`src/core/tool-surface-manager.ts`

src/server.ts、src/tool-registry.ts、src/plugins.ts 等根级文件是兼容 forwarder。新代码应优先引用 src/core/*。

部署平面

平面	作用	关键代码
Analyzer	MCP stdio、HTTP API、存储、任务队列、静态工具、插件编排	`src/index.ts`、`src/core/*`
Runtime Node	隔离环境内的任务执行器	`packages/runtime-node/*`
Windows Host Agent	启停 Windows Sandbox 或 Hyper-V runtime	`packages/windows-host-agent/*`
Agent Gateway	Analyzer/runtime 连接管理和 MCP 代理	`src/rikune-agent-gateway.ts`

运行时模式：

disabled：禁用 runtime delegation。
manual：连接指定 runtime endpoint。
remote-sandbox：委托给 Windows Host Agent。
auto-sandbox：Windows 原生 Analyzer 本地启动 Windows Sandbox。

Docker/WSL analyzer 应使用 remote-sandbox，不要使用 auto-sandbox。

插件系统

内置插件位于 src/plugins/<id>/，当前共 111 个。插件可以注册工具、声明依赖、暴露配置 schema、参与生命周期 hooks，并给 Docker 生成器提供安装元数据，也可以通过 workerBackend metadata 声明受限 Worker-backed 工具。

frontier Worker 套件保留 plan-only 工具作为 triage 和 handoff surface，再在旁边新增显式执行工具。restringer.deobfuscation.run、jsimplifier.pipeline.run、jsir.cascade.normalize、jsvmp.bytecode.recover、gtirb.ir.generate、remill.lift.run、manifold.fact.extract、qbdi.trace.run 和 culifter.gpu.artifact.inventory 会通过 workflow.search、plugin.list、tool.help、tool.readiness 暴露 Worker contract；tools.discover 保留为低层兼容入口。Discovery 和 readiness 保持 passive：只报告 backend metadata 和 setup guidance，不启动 REstringer、JSIMPLIFIER、JSIR/CASCADE、JSVMP、GTIRB、Remill、Manifold、QBDI、GPU driver、Node/V8、browser 或 runtime instrumentation。

Docker 生成器直接读取插件 systemDeps 和 Worker packaging metadata。默认镜像安装低风险静态 wrapper，例如 REstringer、JSIMPLIFIER、Manifold、WABT 和 LIEF validation；optional profile 可启用 JSIR/CASCADE、JSVMP、GTIRB、radare2、Triton 等静态路线；heavy/runtime/GPU/license-sensitive backend 保持 profile-gated、BYO 或 sidecar。

node scripts/generate-docker.mjs --dry-run
node scripts/generate-docker.mjs --profile=full --backend-profile=optional
node scripts/generate-docker.mjs --all-profiles --dry-run

PLUGINS 控制启动时加载范围：

PLUGINS=*                 # 加载全部内置插件
PLUGINS=pe-analysis,yara  # 只加载指定插件
PLUGINS=-dynamic          # 加载除 dynamic 外的全部插件

运行时管理工具：

workflow.search
workflow.run
plugin.list
plugin.enable
plugin.disable
tools.discover 和 tool.readiness 用于低层兼容/调试检查

详见 docs/PLUGINS.md 和 packages/plugin-sdk/README.md。

最受欢迎

rikune