Rikune

Rikune è un server MCP per il reverse engineering di eseguibili Windows e formati binari correlati. Combina acquisizione di campioni, triage statico, recupero funzioni assistito da Ghidra, strumenti specialistici guidati da plugin, gestione degli artefatti ed esecuzione opzionale in ambiente Windows isolato tramite un'interfaccia Model Context Protocol.

Il flusso di lavoro attuale del server rivolto all'IA è organizzato attorno a una superficie gateway minima:

1. Usa workflow.search per confrontare profili, flussi di lavoro e capacità specialistiche corrispondenti al tipo di file e all'obiettivo dell'utente.
2. Usa workflow.run action=request_upload per il caricamento di file dall'host, oppure lascia che workflow.search indirizzi i client legacy verso strumenti di compatibilità per l'acquisizione di campioni nascosti.
3. Usa workflow.run action=start con il sample_id restituito.
4. Usa workflow.run action=status e workflow.run action=promote per monitorare e approfondire l'esecuzione a fasi.
5. Usa artifact.read per ottenere artefatti completi persistiti quando l'output compatto del flusso di lavoro non è sufficiente.

sample.*, workflow.analyze.*, workflow.triage, tools.discover e task.status rimangono registrati per compatibilità o ispezione di basso livello, ma i nuovi client dovrebbero preferire workflow.search, workflow.run e artifact.read.

Quando ci si connette tramite il gateway remoto rikune-agent, i client MCP vedono nomi di trasporto stabili: workflow_search, workflow_run, artifact_read, rikune_tool_call e i controlli rikune_connection_*. rikune_connection_refresh aggiorna solo la cache interna delle capacità upstream; non espande l'elenco degli strumenti MCP. Usa rikune_tool_call solo dopo che workflow_search identifica uno specifico sottostrumento di analisi interna non coperto dal flusso di lavoro primario o dai gateway degli artefatti.

Cosa offre Rikune

• Server MCP stdio per client AI e runtime di agenti.
• API HTTP opzionale e dashboard per caricamenti, download, controlli di integrità, eventi SSE e accesso agli artefatti.
• Workspace per campioni basati su SHA-256 con file originali durevoli, directory cache, artefatti di analisi e sessioni di caricamento.
• Persistenza basata su SQLite per campioni, analisi, job, prove, artefatti, batch, sessioni di debug e telemetria dello scheduler.
• Architettura a plugin con 111 plugin integrati e scoperta di plugin esterni.
• Superficie strumentale progressiva: il gateway predefinito rivolto all'IA è volutamente piccolo; workflow.search utilizza il tipo di campione, i risultati e i metadati del profilo per instradare verso capacità specialistiche senza esporre tutti gli strumenti in anticipo.
• Analisi statica e arricchimento per PE, ELF, Mach-O, APK/DEX, Office, firmware, UEFI/SMM, CUDA PTX/CUBIN/fatbin, stringhe, YARA, SBOM, firme, packer, .NET, Go, Rust e altro.
• Integrazione con Ghidra, Rizin, RetDec, angr, Capstone, Graphviz, Qiling, PANDA, Speakeasy, Wine, Frida e runtime dinamico dove disponibile.
• Installazione backend Docker basata su plugin con livelli predefinito, opzionale, ricerca, runtime, GPU, BYO e sidecar per strumenti di reverse engineering supportati da worker.
• Separazione opzionale Analyzer/Runtime per esecuzione live di Windows tramite Windows Host Agent, Windows Sandbox o VM Hyper-V.
• Gate di policy per esecuzione live, accesso alla rete, caricamento esterno e decompilazione bulk.

Avvio rapido

Analyzer Docker statico

Il Docker statico è l'impostazione predefinita più sicura. Non esegue campioni.

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

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

Equivalente manuale:

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

Docker ibrido + Runtime Windows

La modalità ibrida esegue l'Analyzer in Docker e delega il lavoro live di Windows a un Windows Host Agent. L'Host Agent può avviare Windows Sandbox su richiesta o controllare una VM Hyper-V configurata.

.\rikune.ps1 install -Profile hybrid -InstallRuntime

Da Linux/macOS con un host runtime Windows remoto:

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

La connessione di un client MCP non avvia Windows Sandbox né esegue un campione. Il lavoro live del runtime inizia solo quando uno strumento lo richiede esplicitamente, ad esempio runtime.debug.session.start, runtime.debug.command, sandbox.execute o una fase di esecuzione dinamica promossa.

Sviluppo nativo

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

Il pacchetto root richiede Node.js 22 o superiore. Alcuni sottopacchetti runtime possono funzionare su versioni Node precedenti, ma lo sviluppo del repository e la CLI root pubblicata dovrebbero usare Node 22+.

Flusso gateway primario

Ricerca e caricamento

Inizia con workflow.search ogni volta che il flusso di lavoro, il tipo di file o il backend richiesto non sono chiari. Confronta i profili corrispondenti e restituisce suggerimenti compatti di prontezza/instradamento senza attivare strumenti specialistici nascosti.

Per i file host, chiama workflow.run action=request_upload, invia i byte grezzi tramite POST all'URL di upload restituito, quindi leggi sample_id dalla risposta HTTP. sample.request_upload e sample.ingest sono helper di compatibilità, non il normale percorso rivolto all'IA.

Per deploy di analyzer remoti o rikune-agent, imposta API_PUBLIC_BASE_URL, RIKUNE_API_PUBLIC_BASE_URL o RIKUNE_ANALYZER_PUBLIC_URL sulla base URL HTTP raggiungibile dal client, ad esempio http://159.195.136.226:18080. Le sessioni di upload restituiranno quindi valori upload_url / status_url pubblici invece di URL localhost locali al container. Il gateway remoto normalizza anche gli URL di upload localhost provenienti da analyzer più vecchi al proprio endpoint analyzer configurato.

Se l'API HTTP è abilitata, POST /api/v1/samples è ancora disponibile per integrazioni non MCP. L'acquisizione riuscita restituisce un sample_id; l'analisi dovrebbe usare sample_id, non un percorso locale, dopo l'importazione.

Avvia analisi

Chiama workflow.run action=start con sample_id. La prima fase esegue un profilo veloce e crea o riutilizza un'esecuzione di analisi. Il plan_id restituito mappa all'esecuzione di analisi persistita.

Promuovi fasi

Usa workflow.run action=promote per richiedere fasi più approfondite. La pipeline attualmente modella queste fasi:

• fast_profile
• enrich_static
• function_map
• reconstruct
• semantic_reviews
• dynamic_plan
• dynamic_execute
• summarize

Il lavoro a lunga esecuzione viene accodato tramite il sistema di job. Controlla lo stato compatto delle fasi con workflow.run action=status.

workflow.run action=status è la vista principale dell'esecuzione a fasi. I payload delle fasi storiche di grandi dimensioni possono essere potati con un avviso principale; usa artifact.read per artefatti completi. task.status è una vista raw di coda/processo per compatibilità e include la telemetria di memoria external_active_* per i sottoprocessi dell'analyzer.

Rivedi risultati

Superfici di follow-up utili:

• workflow.search
• workflow.run
• analysis.context.get
• artifact.read, più helper di compatibilità per artefatti come artifact.list, artifact.diff e artifact.download
• report.summarize, report.generate, workflow.summarize
• workflow.semantic_name_review
• workflow.function_explanation_review
• workflow.module_reconstruction_review
• tool.help, e per ispezione di compatibilità/debug

Architettura

Il percorso del codice attuale è:

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

I moduli core del server risiedono in src/core/:

Alcuni file a livello root come src/server.ts, src/tool-registry.ts e src/plugins.ts rimangono forwarder di compatibilità. Il nuovo codice dovrebbe puntare a src/core/*.

Piani di deploy

Le modalità runtime sono configurate tramite runtime.mode o variabili d'ambiente:

• disabled: nessuna delega runtime.
• manual: connessione a un endpoint runtime fornito.
• remote-sandbox: delega a un Windows Host Agent.
• auto-sandbox: analyzer nativo Windows avvia Windows Sandbox localmente.

Gli analyzer Docker/WSL dovrebbero usare remote-sandbox, non auto-sandbox.

Sistema di plugin

Rikune include attualmente 111 plugin integrati in src/plugins/<id>/. I plugin possono registrare strumenti, dichiarare dipendenze, esporre schema di configurazione, partecipare a hook del ciclo di vita, fornire metadati Docker e dichiarare strumenti supportati da Worker limitati tramite metadati workerBackend.

La suite Worker frontier mantiene gli strumenti solo-piano come superfici di triage e passaggio, quindi aggiunge strumenti di esecuzione espliciti accanto ad essi. restringer.deobfuscation.run, jsimplifier.pipeline.run, jsir.cascade.normalize, gtirb.ir.generate, remill.lift.run, manifold.fact.extract, qbdi.trace.run e culifter.gpu.artifact.inventory espongono contratti Worker tramite workflow.search, plugin.list, tool.help e tool.readiness; tools.discover rimane un portale di compatibilità di basso livello. Scoperta e prontezza rimangono passive: riportano metadati backend e indicazioni di configurazione senza avviare REstringer, JSIMPLIFIER, JSIR/CASCADE, GTIRB, Remill, Manifold, QBDI, driver GPU, Node/V8, browser o strumentazione runtime.

La generazione Docker legge direttamente i metadati systemDeps dei plugin e di packaging Worker. Le immagini predefinite installano wrapper statici a basso rischio come REstringer, JSIMPLIFIER, Manifold, WABT e validazione LIEF; i profili opzionali possono abilitare rotte statiche JSIR/CASCADE, JSVMP, GTIRB, radare2 e Triton; i backend pesanti/runtime/GPU/soggetti a licenza rimangono profilati, BYO o 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

Il caricamento dei plugin è controllato da PLUGINS:

PLUGINS=*                 # tutti i plugin integrati
PLUGINS=pe-analysis,yara  # plugin selezionati
PLUGINS=-dynamic          # tutti tranne dynamic

Usa questi strumenti MPC in esecuzione:

• workflow.search
• workflow.run
• plugin.list
• plugin.enable
• plugin.disable
• tools.discover e tool.readiness per ispezione di compatibilità/debug di basso livello

Vedi docs/PLUGINS.md e packages/plugin-sdk/README.md.

API HTTP

Quando api.enabled è true, il server file embedded espone:

Autenticazione tramite chiave API, limitazione della velocità, header di sicurezza e CORS limitato sono gestiti dal layer HTTP.

Prerequisiti

Base di sviluppo minima:

• Node.js 22+
• npm
• Python 3.11+ consigliato per worker e script di analisi
• Docker 20.10+ e Docker Compose v2 per profili Docker
• Java 21+ per versioni moderne di Ghidra
• Ghidra per analisi funzioni basata su decompilatore
• Windows 10/11 Pro, Enterprise o supporto VM equivalente per percorsi runtime Windows Sandbox e Hyper-V

Gli strumenti opzionali sono specifici del plugin. Esegui system.health, system.setup.guide, tool.readiness e plugin.list per vedere cosa manca in un determinato ambiente.

Struttura del progetto

src/
  index.ts                    punto di ingresso principale del server
  core/                       server MCP, registro, esecutore, orchestrazione plugin
  core/tool-registry/         sezioni di registrazione strumenti/prompt/risorse integrate
  tools/                      implementazioni strumenti core
  workflows/                  flussi di lavoro di analisi a fasi, triage, ricostruzione, revisione
  analysis/                   stato esecuzione ed esecutore attività in background
  plugins/                    111 plugin integrati
  persistence/                persistenza SQLite e workspace
  sample/                     finalizzazione campione e ispezione workspace
  storage/                    artefatti, caricamenti, conservazione
  runtime-client/             client di delega runtime lato analyzer
  worker/                     orchestrazione worker Ghidra e Python
packages/
  plugin-sdk/                 SDK plugin pubblico
  shared/                     tipi contratto runtime e strumenti
  runtime-node/               esecutore runtime isolato
  windows-host-agent/         agente host Windows Sandbox / Hyper-V
workers/                      script worker Python e regole YARA
docker/                       template Dockerfile generati e file di profilo
docs/                         documentazione architettura, plugin, runtime, deploy
tests/                        test unit, integrazione e e2e

Comandi di sviluppo

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

Controlli mirati utili:

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

Configurazione client MCP

Build locale:

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

Pacchetto pubblicato:

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

Storage

Per impostazione predefinita, Rikune archivia i dati persistenti sotto la root Rikune a livello utente. Gli installer Docker di solito mappano quella root su una directory host come D:\Docker\rikune.

Sottodirectory comuni:

• samples/
• artifacts/
• uploads/
• cache/
• logs/
• File database SQLite
• JSONL registro audit

I workspace dei campioni sono raggruppati per SHA-256 per evitare collisioni di percorso e preservare originali immutabili.

Confini di sicurezza

Rikune è progettato per l'analisi di malware e binari non fidati, ma non è di per sé un confine di sicurezza magico.

• La modalità Docker statica dovrebbe essere l'impostazione predefinita per l'analisi di routine.
• L'esecuzione live di Windows deve avvenire all'interno di Windows Sandbox o di una VM isolata.
• Runtime Node rifiuta avvii non sicuri a meno che non venga esplicitamente sovrascritto.
• Le azioni pericolose sono protette da PolicyGuard.
• L'esecuzione dei comandi utilizza API di processo strutturate e convalida dei comandi in whitelist.
• Non eseguire campioni sconosciuti su una workstation host al di fuori del modello di isolamento runtime.

Vedi SECURITY.md e TROUBLESHOOTING.md.

Mappa della documentazione

• INSTALL.md: Guida all'installazione Docker in cinese.
• DEPLOYMENT.md: Profili di deploy e topologia runtime.
• docs/ARCHITECTURE.md: Architettura del codice corrente.
• docs/PLUGINS.md: Elenco plugin, concetti SDK, ciclo di vita, scoperta.
• docs/ANALYSIS-RUNTIME.md: Modello di esecuzione runtime e analisi a fasi.
• docs/ASYNC-JOB-PATTERN.md: Pattern di job asincrono e polling.
• docs/MIGRATION-ASYNC.md: Note di migrazione per flussi di lavoro asincroni a fasi.
• docs/DYNAMIC-RUNTIME-ROADMAP.md: Roadmap runtime e stato.
• CONTRIBUTING.md: Flusso di sviluppo e contribuzione.
• packages/plugin-sdk/README.md: Pacchetto per la creazione di plugin.
• workers/README.md: Contratto worker Python.

Licenza

MIT