MCP server for reverse engineering Windows executables and binary formats. Combines static triage, Ghidra-assisted function recovery, plugin-driven tooling, artifact management, and optional isolated Windows runtime execution.
Rikune is an MCP server for reverse engineering Windows executables and related binary formats. It combines sample intake, static triage, Ghidra-assisted function recovery, plugin-driven specialist tooling, artifact management, and optional isolated Windows runtime execution behind a Model Context Protocol interface.
The current AI-facing server workflow is organized around a minimal gateway surface:
workflow.search to rank matching profiles, workflows, and specialist capabilities for the file type and user goal.workflow.run action=request_upload for host-file upload, or let workflow.search point legacy clients to hidden sample-intake compatibility tools.workflow.run action=start with the returned sample_id.workflow.run action=status and workflow.run action=promote to monitor and deepen the staged run.artifact.read for full persisted artifacts when compact workflow output is not enough.sample.*, workflow.analyze.*, workflow.triage, tools.discover, and task.status remain registered for compatibility or low-level inspection, but new clients should prefer workflow.search, workflow.run, and artifact.read.
When connecting through the remote rikune-agent gateway, MCP clients see stable transport names:
workflow_search, workflow_run, artifact_read, rikune_tool_call, and the
rikune_connection_* controls. rikune_connection_refresh updates the internal upstream
capability cache only; it does not expand the MCP tool list. Use rikune_tool_call only after
workflow_search identifies a specific internal analyzer subtool that is not covered by the
primary workflow or artifact gateways.
workflow.search uses sample type, findings, and profile metadata to route toward specialist capabilities without exposing every tool up front.Static Docker is the safest default. It does not execute samples.
.\rikune.ps1 install -Profile static -DataRoot "D:\Docker\rikune"
./rikune.sh install --profile static --data-root "$HOME/.rikune"
Manual equivalent:
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 mode runs the Analyzer in Docker and delegates live Windows work to a Windows Host Agent. The Host Agent can start Windows Sandbox on demand or control a configured Hyper-V VM.
.\rikune.ps1 install -Profile hybrid -InstallRuntime
From Linux/macOS with a remote Windows runtime host:
./rikune.sh install --profile hybrid --windows-host <windows-host> --windows-user <windows-user>
Connecting an MCP client does not start Windows Sandbox or run a sample. Live runtime work only starts when a tool explicitly requests it, such as runtime.debug.session.start, runtime.debug.command, sandbox.execute, or a promoted dynamic execution stage.
npm install
npm run build
npm test
node dist/index.js
The root package requires Node.js 22 or newer. Some runtime subpackages can run on older Node versions, but repository development and the published root CLI should use Node 22+.
Start with workflow.search whenever the requested workflow, file type, or backend is unclear. It ranks matching profiles and returns compact readiness/routing hints without activating hidden specialist tools.
For host files, call workflow.run action=request_upload, POST raw bytes to the returned upload URL, then read sample_id from the HTTP response. sample.request_upload and sample.ingest are compatibility helpers rather than the normal AI-facing path.
For remote analyzer or rikune-agent deployments, set API_PUBLIC_BASE_URL, RIKUNE_API_PUBLIC_BASE_URL, or RIKUNE_ANALYZER_PUBLIC_URL to the client-reachable HTTP API base, for example http://159.195.136.226:18080. Upload sessions then return public upload_url / status_url values instead of container-local localhost URLs. The remote gateway also normalizes localhost upload URLs from older analyzers to its configured analyzer endpoint.
If the HTTP API is enabled, POST /api/v1/samples is still available for non-MCP integrations. Successful intake returns a sample_id; analysis should use sample_id, not a local path, after import.
Call workflow.run action=start with the sample_id. The first stage performs a fast profile and creates or reuses an analysis run. The returned plan_id maps to the persisted analysis run.
Use workflow.run action=promote to request deeper stages. The pipeline currently models these stages:
fast_profileenrich_staticfunction_mapreconstructsemantic_reviewsdynamic_plandynamic_executesummarizeLong-running work is queued through the job system. Poll compact staged state with workflow.run action=status.
workflow.run action=status is the primary staged-run view. Large historical stage payloads may be pruned with a top-level warning; use artifact.read for full artifacts. task.status is a raw queue/process compatibility view and includes external_active_* memory telemetry for analyzer subprocesses.
Useful follow-up surfaces:
workflow.searchworkflow.runanalysis.context.getartifact.read, plus compatibility artifact helpers such as artifact.list, artifact.diff, and artifact.downloadreport.summarize, report.generate, workflow.summarizeworkflow.semantic_name_reviewworkflow.function_explanation_reviewworkflow.module_reconstruction_reviewtool.help, tool.readiness, and tools.discover for compatibility/debug inspectionThe current code path is:
src/index.ts
-> loadConfig()
-> WorkspaceManager / DatabaseManager / PolicyGuard / CacheManager / StorageManager / JobQueue
-> optional RuntimeClient or Windows sandbox bootstrap
-> registerAllTools()
-> MCP stdio server
Core server modules live under src/core/:
| Area | Current file |
|---|---|
| MCP server wrapper | src/core/server.ts |
| MCP tool/prompt/resource registry | src/core/mcp-registry.ts |
| Tool execution, validation, hooks | src/core/tool-executor.ts |
| Registry orchestration | src/core/tool-registry.ts |
| Built-in registry slices | src/core/tool-registry/*.ts |
| Plugin manager facade | src/core/plugins.ts |
| Plugin discovery/loading | src/core/plugin-orchestrator.ts |
| Progressive tool exposure | src/core/tool-surface-manager.ts |
Some root-level files such as src/server.ts, src/tool-registry.ts, and src/plugins.ts remain compatibility forwarders. New code should target src/core/*.
| Plane | Purpose | Key code |
|---|---|---|
| Analyzer | MCP stdio server, HTTP API, storage, jobs, static tools, plugin orchestration | src/index.ts, src/core/* |
| Runtime Node | Isolated task executor inside sandbox or VM | packages/runtime-node/* |
| Windows Host Agent | Starts/stops Windows Sandbox or Hyper-V runtime and exposes runtime control endpoints | packages/windows-host-agent/* |
| Agent Gateway | MCP gateway/proxy for analyzer/runtime connection management | src/rikune-agent-gateway.ts |
Runtime modes are configured through runtime.mode or environment variables:
disabled: no runtime delegation.manual: connect to a supplied runtime endpoint.remote-sandbox: delegate to a Windows Host Agent.auto-sandbox: Windows-native analyzer launches Windows Sandbox locally.Docker/WSL analyzers should use remote-sandbox, not auto-sandbox.
Rikune currently includes 111 built-in plugins under src/plugins/<id>/. Plugins can register tools, declare dependencies, expose configuration schema, participate in lifecycle hooks, provide Docker metadata, and declare bounded Worker-backed tools through workerBackend metadata.
The frontier Worker suite keeps plan-only tools as triage and handoff surfaces, then adds explicit execution tools beside them. restringer.deobfuscation.run, jsimplifier.pipeline.run, jsir.cascade.normalize, gtirb.ir.generate, remill.lift.run, manifold.fact.extract, qbdi.trace.run, and culifter.gpu.artifact.inventory expose Worker contracts through workflow.search, plugin.list, tool.help, and tool.readiness; tools.discover remains a low-level compatibility portal. Discovery and readiness remain passive: they report backend metadata and setup guidance without starting REstringer, JSIMPLIFIER, JSIR/CASCADE, GTIRB, Remill, Manifold, QBDI, GPU drivers, Node/V8, browsers, or runtime instrumentation.
Docker generation reads plugin systemDeps and Worker packaging metadata directly. Default images install low-risk static wrappers such as REstringer, JSIMPLIFIER, Manifold, WABT, and LIEF validation; optional profiles can enable JSIR/CASCADE, JSVMP, GTIRB, radare2, and Triton-style static routes; heavy/runtime/GPU/license-sensitive backends remain profile-gated, BYO, or 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
Plugin loading is controlled by PLUGINS:
PLUGINS=* # all built-ins
PLUGINS=pe-analysis,yara # selected plugins
PLUGINS=-dynamic # all except dynamic
Use these MCP tools at runtime:
workflow.searchworkflow.runplugin.listplugin.enableplugin.disabletools.discover and tool.readiness for low-level compatibility/debug inspectionWhen api.enabled is true, the embedded file server exposes:
| Endpoint | Purpose |
|---|---|
/dashboard and / | Dashboard UI |
/api/v1/health | Liveness |
/api/v1/ready | Readiness across database, queue, runtime, and plugin backends |
/api/v1/events | SSE events |
/api/v1/samples | Direct sample upload |
/api/v1/samples/:id | Sample metadata |
/api/v1/samples/:id/download | Original sample download |
/api/v1/artifacts | Artifact listing |
/api/v1/artifacts/:id | Artifact read/delete |
/api/v1/uploads/:token | Durable upload session POST/status |
API key auth, rate limiting, security headers, and limited CORS are handled by the HTTP layer.
Minimum development baseline:
Optional tools are plugin-specific. Run system.health, system.setup.guide, tool.readiness, and plugin.list to see what is missing in a given environment.
src/
index.ts main server entry
core/ MCP server, registry, executor, plugin orchestration
core/tool-registry/ built-in tool/prompt/resource registration slices
tools/ core tool implementations
workflows/ staged analysis, triage, reconstruction, review workflows
analysis/ run state and background task runner
plugins/ 111 built-in plugins
persistence/ SQLite and workspace persistence
sample/ sample finalization and workspace inspection
storage/ artifacts, uploads, retention
runtime-client/ analyzer-side runtime delegation client
worker/ Ghidra and Python worker orchestration
packages/
plugin-sdk/ public plugin SDK
shared/ runtime and tool contract types
runtime-node/ isolated runtime executor
windows-host-agent/ Windows Sandbox / Hyper-V host agent
workers/ Python worker scripts and YARA rules
docker/ generated Dockerfile templates and profile files
docs/ architecture, plugin, runtime, deployment docs
tests/ unit, integration, and e2e tests
npm install
npm run build
npm test
npm run typecheck
npm run validate
npm run docker:generate:all
Useful focused checks:
npm run test:unit
npm run test:integration
npm run test:e2e
npm run build:runtime
Local build:
{
"mcpServers": {
"rikune": {
"command": "node",
"args": ["D:/Playground/windows-exe-decompiler-mcp-server/dist/index.js"],
"env": {
"API_ENABLED": "true",
"API_PORT": "18080",
"API_PUBLIC_BASE_URL": "http://127.0.0.1:18080",
"PLUGINS": "*"
}
}
}
}
Docker stdio:
{
"mcpServers": {
"rikune": {
"command": "docker",
"args": ["exec", "-i", "rikune-analyzer", "node", "dist/index.js"]
}
}
}
Published package:
npm install -g rikune
rikune
rikune docker-stdio
rikune agent
By default Rikune stores persistent data under the user-level Rikune root. Docker installers usually map that root to a host directory such as D:\Docker\rikune.
Common subdirectories:
samples/artifacts/uploads/cache/logs/Sample workspaces are bucketed by SHA-256 to avoid path collisions and preserve immutable originals.
Rikune is designed for malware and untrusted binary analysis, but it is not a magic safety boundary by itself.
PolicyGuard.See SECURITY.md and TROUBLESHOOTING.md.
MIT