Rikune

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:

1. Use workflow.search to rank matching profiles, workflows, and specialist capabilities for the file type and user goal.

2. Use workflow.run action=request_upload for host-file upload, or let workflow.search point legacy clients to hidden sample-intake compatibility tools.

3. Use workflow.run action=start with the returned sample_id.

4. Use workflow.run action=status and workflow.run action=promote to monitor and deepen the staged run.

5. Use 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.

What Rikune Provides

• MCP stdio server for AI clients and agent runtimes.

• Optional HTTP API and dashboard for uploads, downloads, health checks, SSE events, and artifact access.

• SHA-256 based sample workspaces with durable original files, cache directories, analysis artifacts, and upload sessions.

• SQLite-backed persistence for samples, analyses, jobs, evidence, artifacts, batches, debug sessions, and scheduler telemetry.

• Plugin architecture with 111 built-in plugins and external plugin discovery.

• Progressive tool surface: the default AI-facing gateway is intentionally small; workflow.search uses sample type, findings, and profile metadata to route toward specialist capabilities without exposing every tool up front.

• Static analysis and enrichment for PE, ELF, Mach-O, APK/DEX, Office, firmware, UEFI/SMM, CUDA PTX/CUBIN/fatbin, strings, YARA, SBOM, signatures, packers, .NET, Go, Rust, and more.

• Ghidra, Rizin, RetDec, angr, Capstone, Graphviz, Qiling, PANDA, Speakeasy, Wine, Frida, and dynamic-runtime integration where available.

• Plugin-driven Docker backend installation with default, optional, research, runtime, GPU, BYO, and sidecar tiers for worker-backed reverse-engineering tools.

• Optional Analyzer/Runtime split for live Windows execution through a Windows Host Agent, Windows Sandbox, or Hyper-V VM.

• Policy gates for live execution, network access, external upload, and bulk decompilation.

Related MCP server: PCM

Quick Start

Static Docker Analyzer

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 Docker + Windows Runtime

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.

Native Development

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+.

Primary Gateway Flow

Search And Upload

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.

Start Analysis

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.

Promote Stages

Use workflow.run action=promote to request deeper stages. The pipeline currently models these stages:

• fast_profile

• enrich_static

• function_map

• reconstruct

• semantic_name_review

• semantic_explain_review

• semantic_module_review

• dynamic_plan

• dynamic_execute

• summarize

Long-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.

Review Results

Useful follow-up surfaces:

• workflow.search

• workflow.run

• analysis.context.get

• artifact.read, plus compatibility artifact helpers such as artifacts.list, artifacts.diff, and artifact.download

• report.summarize, report.generate, workflow.summarize

• workflow.semantic_name_review

• workflow.function_explanation_review

• workflow.module_reconstruction_review

• tool.help, tool.readiness, and tools.discover for compatibility/debug inspection

analysis.claims.apply records evidence-backed AI or imported findings as append-only inferred Claim Ledger revisions. Natural-language discovery can return the precise hidden result tool:analysis.claims.apply without activating sibling plugin tools. Analyst revisions are intentionally fail-closed: there is no MCP or HTTP path that can self-assign a reviewer or terminal status. A future operator boundary must use signed review intents before trusted decisions are enabled.

Agent Case Workspace

Rikune keeps deterministic Analyzer Artifacts separate from Agent-authored investigation context:

Analyzer Artifact (eligible Evidence)
  -> analysis.claims.apply (inferred Claim Ledger)
  -> analysis.case.checkpoint / analysis.case.snapshot (immutable Case state)
  -> analysis.context.pack (deterministic, token-bounded context)
  -> workflow.summarize (final digest with separate Evidence and Context)

analysis_claim_set, analysis_case_state, summary, and report Artifacts are context-only. They cannot become Claim evidence or enter summary source_artifact_refs. AI and imported producers can write only inferred Claims; trusted analyst review remains fail-closed.

Each Case is isolated by case_id. analysis.context.pack and workflow.summarize auto-select a sole Case, but fail closed when multiple Cases exist without an explicit selector. Once selected, Claim context is restricted to that Case's active_claim_ids; if Case state exists but cannot be trusted, Claims are withheld instead of falling back to the sample-wide Ledger. Active IDs are resolved newest-to-oldest through an integrity-checked scan capped at 512 Claim Set Artifacts and 128 MiB; a missing ID, broken chain, or exhausted budget withholds the entire Case Claim view. Incremental Context markers are also bound to case_id and cannot be reused across Cases.

Persisted summary reuse is guarded by a versioned fingerprint over the resolved synthesis mode, every scope/session selector, non-context source Artifact metadata, persisted Evidence/Function/Analysis/Run/RunStage state, selected Claim/Case markers, and integrity-review state. Source Artifact files are streamed through SHA-256 validation before reuse. Legacy digests without a compatible fingerprint are rebuilt instead of being reused.

Claim and Case writers serialize through a heartbeat-backed SQLite CAS lease before taking their owner-identified filesystem locks. Stale takeover is conditional on the observed owner and heartbeat, while malformed/foreign-host filesystem locks use identity-checked recovery. Writers reassert lease ownership before the final rename, then atomically fence the Artifact row insert on the current owner token. Before creating locks or JSON artifacts, workspace writes validate the configured canonical root and reject symlink-replaced shard or sample directories.

The reproducible benign CrackMe acceptance script runs passive ELF, hardening, strings, Claim, Case, Context, and deterministic summary steps by default. --deep additionally enables Ghidra:

npm run test:agent-case:e2e -- \
  --container <running-rikune-container> \
  --binary /fixtures/complex_crackme

See tests/fixtures/crackmes/README.md for fixture build and isolated-execution rules.

Architecture

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

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/*.

Deployment Planes

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.

Plugin System

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.search

• workflow.run

• plugin.list

• plugin.enable

• plugin.disable

• tools.discover and tool.readiness for low-level compatibility/debug inspection

See docs/PLUGINS.md and packages/plugin-sdk/README.md.

HTTP API

When api.enabled is true, the embedded file server exposes:

API key auth, rate limiting, security headers, and limited CORS are handled by the HTTP layer.

Prerequisites

Minimum development baseline:

• Node.js 22+

• npm

• Python 3.11+ recommended for workers and analysis scripts

• Docker 20.10+ and Docker Compose v2 for Docker profiles

• Java 21+ for modern Ghidra releases

• Ghidra for decompiler-backed function analysis

• Windows 10/11 Pro, Enterprise, or equivalent VM support for Windows Sandbox and Hyper-V runtime paths

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.

Project Layout

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

Development Commands

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 test:agent-case:e2e -- --help
npm run build:runtime

MCP Client Configuration

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

Storage

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/

• SQLite database file

• audit log JSONL

Sample workspaces are bucketed by SHA-256 to avoid path collisions and preserve immutable originals.

Security Boundaries

Rikune is designed for malware and untrusted binary analysis, but it is not a magic safety boundary by itself.

• Static Docker mode should be the default for routine analysis.

• Live Windows execution must happen inside Windows Sandbox or an isolated VM.

• Runtime Node refuses unsafe startup unless explicitly overridden.

• Dangerous actions are guarded by PolicyGuard.

• Command execution uses structured process APIs and allowlisted command validation.

• Do not run unknown samples on a host workstation outside the runtime isolation model.

See SECURITY.md and TROUBLESHOOTING.md.

Documentation Map

• INSTALL.md: Docker installer guide in Chinese.

• DEPLOYMENT.md: deployment profiles and runtime topology.

• docs/ARCHITECTURE.md: current code architecture.

• docs/PLUGINS.md: plugin list, SDK concepts, lifecycle, discovery.

• docs/ANALYSIS-RUNTIME.md: staged runtime and analysis execution model.

• docs/ASYNC-JOB-PATTERN.md: async job and polling pattern.

• docs/MIGRATION-ASYNC.md: migration notes for staged async workflows.

• docs/DYNAMIC-RUNTIME-ROADMAP.md: runtime roadmap and status.

• CONTRIBUTING.md: development and contribution flow.

• packages/plugin-sdk/README.md: plugin authoring package.

• workers/README.md: Python worker contract.

License

MIT