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/: