Rikune

Rikune ist ein MCP-Server für das Reverse Engineering von Windows-Ausführungsdateien und verwandten Binärformaten. Er kombiniert Sample-Aufnahme, statische Triage, Ghidra-gestützte Funktionswiederherstellung, plugin-gesteuerte Spezialwerkzeuge, Artefaktverwaltung und optionale isolierte Windows-Laufzeitausführung hinter einer Model Context Protocol-Schnittstelle.

Der aktuelle KI-orientierte Server-Workflow ist um eine minimale Gateway-Oberfläche organisiert:

Verwende workflow.search, um passende Profile, Workflows und spezialisierte Fähigkeiten für den Dateityp und das Benutzerziel zu bewerten.
Verwende workflow.run action=request_upload für das Hochladen von Host-Dateien, oder lasse workflow.search Legacy-Clients auf versteckte Sample-Aufnahme-Kompatibilitätswerkzeuge verweisen.
Verwende workflow.run action=start mit der zurückgegebenen sample_id.
Verwende workflow.run action=status und workflow.run action=promote, um den gestuften Durchlauf zu überwachen und zu vertiefen.
Verwende artifact.read für vollständige persistierte Artefakte, wenn die kompakte Workflow-Ausgabe nicht ausreicht.

sample.*, workflow.analyze.*, workflow.triage, tools.discover und task.status bleiben für Kompatibilität oder Low-Level-Inspektion registriert, aber neue Clients sollten workflow.search, workflow.run und artifact.read bevorzugen.

Bei Verbindung über das Remote-rikune-agent-Gateway sehen MCP-Clients stabile Transportnamen: workflow_search, workflow_run, artifact_read, rikune_tool_call und die rikune_connection_*-Steuerungen. rikune_connection_refresh aktualisiert nur den internen Upstream-Fähigkeits-Cache; es erweitert nicht die MCP-Werkzeugliste. Verwende rikune_tool_call nur, nachdem workflow_search ein bestimmtes internes Analysator-Subwerkzeug identifiziert hat, das nicht durch die primären Workflow- oder Artefakt-Gateways abgedeckt wird.

Was Rikune bietet

MCP-stdio-Server für KI-Clients und Agenten-Laufzeiten.
Optionale HTTP-API und Dashboard für Uploads, Downloads, Health-Checks, SSE-Ereignisse und Artefaktzugriff.
SHA-256-basierte Sample-Arbeitsbereiche mit dauerhaften Originaldateien, Cache-Verzeichnissen, Analyse-Artefakten und Upload-Sitzungen.
SQLite-gestützte Persistenz für Samples, Analysen, Jobs, Beweise, Artefakte, Batches, Debug-Sitzungen und Scheduler-Telemetrie.
Plugin-Architektur mit 111 integrierten Plugins und externer Plugin-Erkennung.
Progressive Werkzeugoberfläche: das standardmäßige KI-Gateway ist bewusst klein; workflow.search verwendet Sample-Typ, Ergebnisse und Profilmetadaten, um zu spezialisierten Fähigkeiten weiterzuleiten, ohne alle Werkzeuge vorab zu exponieren.
Statische Analyse und Anreicherung für PE, ELF, Mach-O, APK/DEX, Office, Firmware, UEFI/SMM, CUDA PTX/CUBIN/fatbin, Strings, YARA, SBOM, Signaturen, Packer, .NET, Go, Rust und mehr.
Ghidra-, Rizin-, RetDec-, angr-, Capstone-, Graphviz-, Qiling-, PANDA-, Speakeasy-, Wine-, Frida- und dynamische Laufzeitintegration, sofern verfügbar.
Plugin-gesteuerte Docker-Backend-Installation mit Standard-, Optional-, Research-, Runtime-, GPU-, BYO- und Sidecar-Stufen für Worker-gestützte Reverse-Engineering-Werkzeuge.
Optionale Analyzer/Runtime-Aufteilung für Live-Windows-Ausführung über einen Windows Host Agent, Windows Sandbox oder Hyper-V-VM.
Policy-Gates für Live-Ausführung, Netzwerkzugriff, externe Uploads und Bulk-Decompilation.

Schnellstart

Statischer Docker-Analyzer

Statisches Docker ist die sicherste Standardeinstellung. Es führt keine Samples aus.

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

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

Manuelles Äquivalent:

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-Laufzeit

Der Hybrid-Modus führt den Analyzer in Docker aus und delegiert Live-Windows-Arbeiten an einen Windows Host Agent. Der Host Agent kann Windows Sandbox bei Bedarf starten oder eine konfigurierte Hyper-V-VM steuern.

.\rikune.ps1 install -Profile hybrid -InstallRuntime

Von Linux/macOS mit einem entfernten Windows-Runtime-Host:

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

Das Verbinden eines MCP-Clients startet weder Windows Sandbox noch führt es ein Sample aus. Live-Runtime-Arbeiten beginnen nur, wenn ein Werkzeug dies explizit anfordert, z.B. runtime.debug.session.start, runtime.debug.command, sandbox.execute oder eine hochgestufte dynamische Ausführungsstufe.

Native Entwicklung

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

Das Root-Paket benötigt Node.js 22 oder neuer. Einige Runtime-Subpakete können auf älteren Node-Versionen laufen, aber die Repository-Entwicklung und die veröffentlichte Root-CLI sollten Node 22+ verwenden.

Primärer Gateway-Ablauf

Suche und Upload

Beginne mit workflow.search, wann immer der angeforderte Workflow, Dateityp oder das Backend unklar ist. Es bewertet passende Profile und gibt kompakte Bereitschafts-/Routing-Hinweise zurück, ohne versteckte Spezialwerkzeuge zu aktivieren.

Für Host-Dateien rufe workflow.run action=request_upload auf, POSTe die rohen Bytes an die zurückgegebene Upload-URL und lies dann sample_id aus der HTTP-Antwort. sample.request_upload und sample.ingest sind Kompatibilitätshilfen und nicht der normale KI-orientierte Pfad.

Für Remote-Analyzer- oder rikune-agent-Bereitstellungen setze API_PUBLIC_BASE_URL, RIKUNE_API_PUBLIC_BASE_URL oder RIKUNE_ANALYZER_PUBLIC_URL auf die für den Client erreichbare HTTP-API-Basis, z.B. http://159.195.136.226:18080. Upload-Sitzungen geben dann öffentliche upload_url-/status_url-Werte anstelle von containerlokalen localhost-URLs zurück. Das Remote-Gateway normalisiert auch Localhost-Upload-URLs von älteren Analyzern auf seinen konfigurierten Analyzer-Endpunkt.

Wenn die HTTP-API aktiviert ist, ist POST /api/v1/samples weiterhin für Nicht-MCP-Integrationen verfügbar. Erfolgreiche Aufnahme gibt eine sample_id zurück; die Analyse sollte nach dem Import die sample_id und nicht einen lokalen Pfad verwenden.

Starte die Analyse

Rufe workflow.run action=start mit der sample_id auf. Die erste Stufe führt ein schnelles Profil durch und erstellt oder verwendet eine Analyseausführung wieder. Die zurückgegebene plan_id ist der persistierten Analyseausführung zugeordnet.

Stufen fördern

Verwende workflow.run action=promote, um tiefere Stufen anzufordern. Die Pipeline modelliert derzeit diese Stufen:

fast_profile
enrich_static
function_map
reconstruct
semantic_reviews
dynamic_plan
dynamic_execute
summarize

Langlaufende Arbeiten werden über das Job-System in die Warteschlange gestellt. Frage den kompakten Stufenstatus mit workflow.run action=status ab.

workflow.run action=status ist die primäre Ansicht für gestufte Ausführungen. Große Payloads historischer Stufen können mit einer Top-Level-Warnung gekürzt werden; verwende artifact.read für vollständige Artefakte. task.status ist eine rohe Queue/Prozess-Kompatibilitätsansicht und enthält external_active_*-Speichertelemetrie für Analyzer-Subprozesse.

Ergebnisse prüfen

Nützliche Folgemaßnahmen:

workflow.search
workflow.run
analysis.context.get
artifact.read, sowie Kompatibilitäts-Artefakt-Hilfen wie artifact.list, artifact.diff und artifact.download
report.summarize, report.generate, workflow.summarize
workflow.semantic_name_review
workflow.function_explanation_review
workflow.module_reconstruction_review
tool.help, und für Kompatibilitäts-/Debug-Inspektion

Architektur

Der aktuelle Codepfad ist:

src/index.ts
  -> loadConfig()
  -> WorkspaceManager / DatabaseManager / PolicyGuard / CacheManager / StorageManager / JobQueue
  -> optional RuntimeClient oder Windows-Sandbox-Bootstrap
  -> registerAllTools()
  -> MCP stdio server

Core-Server-Module befinden sich unter src/core/:

Einige Root-Level-Dateien wie src/server.ts, src/tool-registry.ts und src/plugins.ts bleiben Kompatibilitäts-Weiterleitungen. Neuer Code sollte auf src/core/* abzielen.

Bereitstellungsebenen

Runtime-Modi werden über runtime.mode oder Umgebungsvariablen konfiguriert:

disabled: keine Runtime-Delegation.
manual: Verbindung zu einem bereitgestellten Runtime-Endpunkt.
remote-sandbox: Delegiert an einen Windows Host Agent.
auto-sandbox: Windows-nativer Analyzer startet Windows Sandbox lokal.

Docker/WSL-Analyzer sollten remote-sandbox verwenden, nicht auto-sandbox.

Plugin-System

Rikune enthält derzeit 111 integrierte Plugins unter src/plugins/<id>/. Plugins können Werkzeuge registrieren, Abhängigkeiten deklarieren, Konfigurationsschemata bereitstellen, an Lebenszyklus-Hooks teilnehmen, Docker-Metadaten bereitstellen und Worker-gestützte Werkzeuge über workerBackend-Metadaten deklarieren.

Die Worker-Suite der Grenzfläche behält Plan-nur-Werkzeuge als Triage- und Übergabeoberflächen bei und fügt explizite Ausführungswerkzeuge daneben hinzu. restringer.deobfuscation.run, jsimplifier.pipeline.run, jsir.cascade.normalize, gtirb.ir.generate, remill.lift.run, manifold.fact.extract, qbdi.trace.run und culifter.gpu.artifact.inventory setzen Worker-Verträge über workflow.search, plugin.list, tool.help und tool.readiness aus; tools.discover bleibt ein Low-Level-Kompatibilitätsportal. Erkennung und Bereitschaft bleiben passiv: sie melden Backend-Metadaten und Setup-Anleitungen, ohne REstringer, JSIMPLIFIER, JSIR/CASCADE, GTIRB, Remill, Manifold, QBDI, GPU-Treiber, Node/V8, Browser oder Runtime-Instrumentierung zu starten.

Die Docker-Generierung liest Plugin-systemDeps und Worker-Packaging-Metadaten direkt. Standard-Images installieren risikoarme statische Wrapper wie REstringer, JSIMPLIFIER, Manifold, WABT und LIEF-Validierung; optionale Profile können JSIR/CASCADE, JSVMP, GTIRB, radare2 und Triton-artige statische Routen aktivieren; schwere/Runtime/GPU/lizenzsensitive Backends bleiben profilgesteuert, BYO oder 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

Das Laden von Plugins wird durch PLUGINS gesteuert:

PLUGINS=*                 # alle integrierten
PLUGINS=pe-analysis,yara  # ausgewählte Plugins
PLUGINS=-dynamic          # alle außer dynamische

Verwende diese MCP-Werkzeuge zur Laufzeit:

workflow.search
workflow.run
plugin.list
plugin.enable
plugin.disable
tools.discover und tool.readiness für Low-Level-Kompatibilitäts-/Debug-Inspektion

Siehe docs/PLUGINS.md und packages/plugin-sdk/README.md.

HTTP-API

Wenn api.enabled wahr ist, stellt der eingebettete Dateiserver Folgendes bereit:

API-Key-Authentifizierung, Ratenbegrenzung, Sicherheitsheader und eingeschränktes CORS werden von der HTTP-Ebene behandelt.

Voraussetzungen

Minimale Entwicklungsbasis:

Node.js 22+
npm
Python 3.11+ empfohlen für Worker und Analysescripts
Docker 20.10+ und Docker Compose v2 für Docker-Profile
Java 21+ für moderne Ghidra-Versionen
Ghidra für Decompiler-gestützte Funktionsanalyse
Windows 10/11 Pro, Enterprise oder entsprechende VM-Unterstützung für Windows Sandbox und Hyper-V-Runtime-Pfade

Optionale Werkzeuge sind plugin-spezifisch. Führe system.health, system.setup.guide, tool.readiness und plugin.list aus, um zu sehen, was in einer bestimmten Umgebung fehlt.

Projektstruktur

src/
  index.ts                    Haupt-Server-Einstieg
  core/                       MCP-Server, Registry, Ausführer, Plugin-Orchestrierung
  core/tool-registry/         Integrierte Werkzeug-/Prompt-/Ressourcen-Registrierungsausschnitte
  tools/                      Kern-Werkzeugimplementierungen
  workflows/                  Gestufte Analyse, Triage, Rekonstruktion, Überprüfungs-Workflows
  analysis/                   Laufzustand und Hintergrund-Task-Runner
  plugins/                    111 integrierte Plugins
  persistence/                SQLite und Arbeitsbereich-Persistenz
  sample/                     Sample-Finalisierung und Arbeitsbereichsinspektion
  storage/                    Artefakte, Uploads, Aufbewahrung
  runtime-client/             Analyzer-seitiger Runtime-Delegationsclient
  worker/                     Ghidra- und Python-Worker-Orchestrierung
packages/
  plugin-sdk/                 Öffentliches Plugin-SDK
  shared/                     Runtime- und Werkzeugvertragstypen
  runtime-node/               Isolierter Runtime-Ausführer
  windows-host-agent/         Windows Sandbox / Hyper-V Host Agent
workers/                      Python-Worker-Scripts und YARA-Regeln
docker/                       Generierte Dockerfile-Vorlagen und Profildateien
docs/                         Architektur-, Plugin-, Runtime-, Bereitstellungsdokumente
tests/                        Unit-, Integrations- und E2E-Tests

Entwicklungsbefehle

npm install
npm run build
npm test
npm run typecheck
npm run validate
npm run docker:generate:all

Nützliche gezielte Prüfungen:

npm run test:unit
npm run test:integration
npm run test:e2e
npm run build:runtime

MCP-Client-Konfiguration

Lokaler 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"]
    }
  }
}

Veröffentlichtes Paket:

npm install -g rikune
rikune
rikune docker-stdio
rikune agent

Speicherung

Standardmäßig speichert Rikune persistente Daten unter dem Benutzer-Rikune-Root. Docker-Installer mappen diesen Root normalerweise auf ein Host-Verzeichnis wie D:\Docker\rikune.

Häufige Unterverzeichnisse:

samples/
artifacts/
uploads/
cache/
logs/
SQLite-Datenbankdatei
Audit-Log-JSONL

Sample-Arbeitsbereiche werden nach SHA-256 aufgeteilt, um Pfadkollisionen zu vermeiden und unveränderliche Originale zu erhalten.

Sicherheitsgrenzen

Rikune ist für Malware- und unvertraute Binäranalyse ausgelegt, aber es ist selbst keine magische Sicherheitsgrenze.

Der statische Docker-Modus sollte der Standard für Routine-Analysen sein.
Live-Windows-Ausführung muss innerhalb von Windows Sandbox oder einer isolierten VM erfolgen.
Runtime Node verweigert unsicheren Start, sofern nicht explizit überschrieben.
Gefährliche Aktionen werden durch PolicyGuard geschützt.
Die Befehlsausführung verwendet strukturierte Prozess-APIs und eine Whitelist-basierte Befehlsvalidierung.
Führe keine unbekannten Samples auf einem Host-Arbeitsplatz außerhalb des Runtime-Isolationsmodells aus.

Siehe SECURITY.md und TROUBLESHOOTING.md.

Dokumentationskarte

INSTALL.md: Docker-Installer-Anleitung auf Chinesisch.
DEPLOYMENT.md: Bereitstellungsprofile und Runtime-Topologie.
docs/ARCHITECTURE.md: Aktuelle Code-Architektur.
docs/PLUGINS.md: Plugin-Liste, SDK-Konzepte, Lebenszyklus, Erkennung.
docs/ANALYSIS-RUNTIME.md: Gestuftes Runtime- und Analyse-Ausführungsmodell.
docs/ASYNC-JOB-PATTERN.md: Asynchrones Job- und Polling-Muster.
docs/MIGRATION-ASYNC.md: Migrationshinweise für gestufte asynchrone Workflows.
docs/DYNAMIC-RUNTIME-ROADMAP.md: Runtime-Roadmap und Status.
CONTRIBUTING.md: Entwicklungs- und Beitragsablauf.
packages/plugin-sdk/README.md: Plugin-Autorisierungspaket.
workers/README.md: Python-Worker-Vertrag.

Lizenz

MIT

MCP-Server-Wrapper	`src/core/server.ts`
MCP-Werkzeug-/Prompt-/Ressourcen-Registry	`src/core/mcp-registry.ts`
Werkzeugausführung, -validierung, -haken	`src/core/tool-executor.ts`
Registry-Orchestrierung	`src/core/tool-registry.ts`
Integrierte Registry-Ausschnitte	`src/core/tool-registry/*.ts`
Plugin-Manager-Fassade	`src/core/plugins.ts`
Plugin-Erkennung/-Laden	`src/core/plugin-orchestrator.ts`
Progressive Werkzeugexposition	`src/core/tool-surface-manager.ts`

Analyzer	MCP-stdio-Server, HTTP-API, Speicher, Jobs, statische Werkzeuge, Plugin-Orchestrierung	`src/index.ts`, `src/core/*`
Runtime Node	Isolierter Aufgabenausführer innerhalb von Sandbox oder VM	`packages/runtime-node/*`
Windows Host Agent	Startet/stoppt Windows Sandbox oder Hyper-V Runtime und stellt Runtime-Steuerungsendpunkte bereit	`packages/windows-host-agent/*`
Agent Gateway	MCP-Gateway/Proxy für Analyzer/Runtime-Verbindungsverwaltung	`src/rikune-agent-gateway.ts`

`/dashboard` und `/`	Dashboard-Benutzeroberfläche
`/api/v1/health`	Lebendigkeit
`/api/v1/ready`	Bereitschaft über Datenbank, Warteschlange, Runtime und Plugin-Backends hinweg
`/api/v1/events`	SSE-Ereignisse
`/api/v1/samples`	Direkter Sample-Upload
`/api/v1/samples/:id`	Sample-Metadaten
`/api/v1/samples/:id/download`	Original-Sample-Download
`/api/v1/artifacts`	Artefakt-Auflistung
`/api/v1/artifacts/:id`	Artefakt lesen/löschen
`/api/v1/uploads/:token`	Dauerhafte Upload-Sitzung POST/Status

Beliebteste

rikune