Rikune

Rikune es un servidor MCP para ingeniería inversa de ejecutables de Windows y formatos binarios relacionados. Combina la ingesta de muestras, el triaje estático, la recuperación de funciones asistida por Ghidra, herramientas especializadas impulsadas por complementos, gestión de artefactos y ejecución opcional en tiempo de ejecución aislado de Windows detrás de una interfaz de Protocolo de Contexto de Modelo.

El flujo de trabajo actual del servidor orientado a IA se organiza alrededor de una superficie de puerta de enlace mínima:

1. Usar workflow.search para clasificar perfiles, flujos de trabajo y capacidades especializadas que coinciden con el tipo de archivo y el objetivo del usuario.
2. Usar workflow.run action=request_upload para la carga de archivos del host, o dejar que workflow.search dirija a clientes heredados a herramientas de compatibilidad de ingesta de muestras ocultas.
3. Usar workflow.run action=start con el sample_id devuelto.
4. Usar workflow.run action=status y workflow.run action=promote para monitorear y profundizar en la ejecución por etapas.
5. Usar artifact.read para artefactos completos persistidos cuando la salida compacta del flujo de trabajo no es suficiente.

sample.*, workflow.analyze.*, workflow.triage, tools.discover y task.status permanecen registrados para compatibilidad o inspección de bajo nivel, pero los nuevos clientes deberían preferir workflow.search, workflow.run y artifact.read.

Al conectarse a través de la puerta de enlace remota rikune-agent, los clientes MCP ven nombres de transporte estables: workflow_search, workflow_run, artifact_read, rikune_tool_call y los controles rikune_connection_*. rikune_connection_refresh actualiza solo la caché interna de capacidades ascendentes; no expande la lista de herramientas MCP. Use rikune_tool_call solo después de que workflow_search identifique una subherramienta de analizador interna específica que no esté cubierta por las puertas de enlace principales de flujo de trabajo o artefactos.

Qué Proporciona Rikune

• Servidor MCP stdio para clientes de IA y tiempos de ejecución de agentes.
• API HTTP opcional y panel para cargas, descargas, comprobaciones de estado, eventos SSE y acceso a artefactos.
• Espacios de trabajo de muestras basados en SHA-256 con archivos originales duraderos, directorios de caché, artefactos de análisis y sesiones de carga.
• Persistencia basada en SQLite para muestras, análisis, trabajos, evidencia, artefactos, lotes, sesiones de depuración y telemetría del programador.
• Arquitectura de complementos con 111 complementos integrados y descubrimiento de complementos externos.
• Superficie de herramientas progresiva: la puerta de enlace predeterminada orientada a IA es intencionalmente pequeña; workflow.search utiliza el tipo de muestra, hallazgos y metadatos de perfil para enrutar hacia capacidades especializadas sin exponer todas las herramientas por adelantado.
• Análisis estático y enriquecimiento para PE, ELF, Mach-O, APK/DEX, Office, firmware, UEFI/SMM, CUDA PTX/CUBIN/fatbin, cadenas, YARA, SBOM, firmas, empaquetadores, .NET, Go, Rust y más.
• Integración de Ghidra, Rizin, RetDec, angr, Capstone, Graphviz, Qiling, PANDA, Speakeasy, Wine, Frida y tiempo de ejecución dinámico cuando estén disponibles.
• Instalación de backend Docker impulsada por complementos con niveles predeterminado, opcional, investigación, tiempo de ejecución, GPU, BYO y sidecar para herramientas de ingeniería inversa respaldadas por trabajadores.
• División opcional Analizador/Tiempo de ejecución para ejecución en vivo de Windows a través de un Agente Host de Windows, Sandbox de Windows o VM Hyper-V.
• Puertas de política para ejecución en vivo, acceso a red, carga externa y descompilación masiva.

Inicio Rápido

Analizador Docker Estático

Docker estático es el valor predeterminado más seguro. No ejecuta muestras.

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

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

Equivalente manual:

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 Híbrido + Tiempo de Ejecución de Windows

El modo híbrido ejecuta el Analizador en Docker y delega el trabajo en vivo de Windows a un Agente Host de Windows. El Agente Host puede iniciar Windows Sandbox bajo demanda o controlar una VM Hyper-V configurada.

.\rikune.ps1 install -Profile hybrid -InstallRuntime

Desde Linux/macOS con un host de tiempo de ejecución de Windows remoto:

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

Conectar un cliente MCP no inicia Windows Sandbox ni ejecuta una muestra. El trabajo de tiempo de ejecución en vivo solo comienza cuando una herramienta lo solicita explícitamente, como runtime.debug.session.start, runtime.debug.command, sandbox.execute o una etapa de ejecución dinámica promovida.

Desarrollo Nativo

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

El paquete raíz requiere Node.js 22 o superior. Algunos subpaquetes de tiempo de ejecución pueden ejecutarse en versiones anteriores de Node, pero el desarrollo del repositorio y la CLI raíz publicada deben usar Node 22+.

Flujo de Puerta de Enlace Principal

Búsqueda y Carga

Comience con workflow.search siempre que el flujo de trabajo, tipo de archivo o backend solicitado no esté claro. Clasifica perfiles coincidentes y devuelve indicaciones compactas de preparación/enrutamiento sin activar herramientas especializadas ocultas.

Para archivos del host, llame a workflow.run action=request_upload, publique los bytes sin procesar en la URL de carga devuelta, luego lea sample_id de la respuesta HTTP. sample.request_upload y sample.ingest son ayudantes de compatibilidad, no la ruta normal orientada a IA.

Para implementaciones de analizador remoto o rikune-agent, establezca API_PUBLIC_BASE_URL, RIKUNE_API_PUBLIC_BASE_URL o RIKUNE_ANALYZER_PUBLIC_URL en la base de la API HTTP accesible por el cliente, por ejemplo http://159.195.136.226:18080. Las sesiones de carga luego devuelven valores upload_url / status_url públicos en lugar de URLs localhost locales del contenedor. La puerta de enlace remota también normaliza las URLs de carga localhost de analizadores antiguos a su punto final de analizador configurado.

Si la API HTTP está habilitada, POST /api/v1/samples sigue disponible para integraciones que no sean MCP. La ingesta exitosa devuelve un sample_id; el análisis debe usar sample_id, no una ruta local, después de la importación.

Iniciar Análisis

Llame a workflow.run action=start con el sample_id. La primera etapa realiza un perfil rápido y crea o reutiliza una ejecución de análisis. El plan_id devuelto se asigna a la ejecución de análisis persistida.

Promover Etapas

Use workflow.run action=promote para solicitar etapas más profundas. El pipeline actualmente modela estas etapas:

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

El trabajo de larga duración se pone en cola a través del sistema de trabajos. Consulte el estado compacto de las etapas con workflow.run action=status.

workflow.run action=status es la vista principal de la ejecución por etapas. Las cargas útiles grandes de etapas históricas pueden podarse con una advertencia de nivel superior; use artifact.read para artefactos completos. task.status es una vista de compatibilidad de cola/proceso sin procesar e incluye telemetría de memoria external_active_* para subprocesos del analizador.

Revisar Resultados

Superficies de seguimiento útiles:

• workflow.search
• workflow.run
• analysis.context.get
• artifact.read, además de ayudantes de artefactos de compatibilidad como artifact.list, artifact.diff y artifact.download
• report.summarize, report.generate, workflow.summarize
• workflow.semantic_name_review
• workflow.function_explanation_review
• workflow.module_reconstruction_review
• , y para inspección de compatibilidad/depuración

Arquitectura

La ruta de código actual es:

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

Los módulos centrales del servidor residen en src/core/:

Algunos archivos de nivel raíz como src/server.ts, src/tool-registry.ts y src/plugins.ts siguen siendo reenviadores de compatibilidad. El nuevo código debe apuntar a src/core/*.

Planos de Implementación

Los modos de tiempo de ejecución se configuran a través de runtime.mode o variables de entorno:

• disabled: sin delegación de tiempo de ejecución.
• manual: conectar a un punto final de tiempo de ejecución proporcionado.
• remote-sandbox: delegar a un Agente Host de Windows.
• auto-sandbox: el analizador nativo de Windows lanza Windows Sandbox localmente.

Los analizadores Docker/WSL deben usar remote-sandbox, no auto-sandbox.

Sistema de Complementos

Rikune actualmente incluye 111 complementos integrados bajo src/plugins/<id>/. Los complementos pueden registrar herramientas, declarar dependencias, exponer esquemas de configuración, participar en hooks del ciclo de vida, proporcionar metadatos de Docker y declarar herramientas limitadas respaldadas por trabajadores a través de metadatos workerBackend.

El conjunto de trabajadores fronterizos mantiene herramientas solo de plan como superficies de triaje y transferencia, luego agrega herramientas de ejecución explícitas junto a ellas. restringer.deobfuscation.run, jsimplifier.pipeline.run, jsir.cascade.normalize, gtirb.ir.generate, remill.lift.run, manifold.fact.extract, qbdi.trace.run y culifter.gpu.artifact.inventory exponen contratos de trabajadores a través de workflow.search, plugin.list, tool.help y tool.readiness; tools.discover sigue siendo un portal de compatibilidad de bajo nivel. El descubrimiento y la preparación siguen siendo pasivos: informan metadatos del backend y orientación de configuración sin iniciar REstringer, JSIMPLIFIER, JSIR/CASCADE, GTIRB, Remill, Manifold, QBDI, controladores GPU, Node/V8, navegadores o instrumentación de tiempo de ejecución.

La generación de Docker lee metadatos systemDeps y de empaquetado de trabajadores directamente. Las imágenes predeterminadas instalan envoltorios estáticos de bajo riesgo como REstringer, JSIMPLIFIER, Manifold, WABT y validación LIEF; los perfiles opcionales pueden habilitar rutas estáticas JSIR/CASCADE, JSVMP, GTIRB, radare2 y Triton; los backends pesados/de tiempo de ejecución/GPU/sensibles a licencias permanecen protegidos por perfil, 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

La carga de complementos se controla mediante PLUGINS:

PLUGINS=*                 # todos los integrados
PLUGINS=pe-analysis,yara  # complementos seleccionados
PLUGINS=-dynamic          # todos excepto dinámicos

Use estas herramientas MCP en tiempo de ejecución:

• workflow.search
• workflow.run
• plugin.list
• plugin.enable
• plugin.disable
• tools.discover y tool.readiness para inspección de compatibilidad/depuración de bajo nivel

Consulte docs/PLUGINS.md y packages/plugin-sdk/README.md.

API HTTP

Cuando api.enabled es verdadero, el servidor de archivos integrado expone:

La autenticación por clave API, limitación de tasa, encabezados de seguridad y CORS limitado son manejados por la capa HTTP.

Prerrequisitos

Línea base mínima de desarrollo:

• Node.js 22+
• npm
• Python 3.11+ recomendado para trabajadores y scripts de análisis
• Docker 20.10+ y Docker Compose v2 para perfiles Docker
• Java 21+ para versiones modernas de Ghidra
• Ghidra para análisis de funciones respaldado por descompilador
• Windows 10/11 Pro, Enterprise o soporte de VM equivalente para rutas de tiempo de ejecución de Windows Sandbox y Hyper-V

Las herramientas opcionales son específicas de cada complemento. Ejecute system.health, system.setup.guide, tool.readiness y plugin.list para ver qué falta en un entorno determinado.

Estructura del Proyecto

src/
  index.ts                    entrada principal del servidor
  core/                       servidor MCP, registro, ejecutor, orquestación de complementos
  core/tool-registry/         fragmentos de registro de herramientas/prompt/recursos integrados
  tools/                      implementaciones de herramientas principales
  workflows/                  flujos de trabajo de análisis por etapas, triaje, reconstrucción, revisión
  analysis/                   estado de ejecución y ejecutor de tareas en segundo plano
  plugins/                    111 complementos integrados
  persistence/                persistencia SQLite y de espacio de trabajo
  sample/                     finalización de muestras e inspección del espacio de trabajo
  storage/                    artefactos, cargas, retención
  runtime-client/             cliente de delegación de tiempo de ejecución del lado del analizador
  worker/                     orquestación de trabajadores Ghidra y Python
packages/
  plugin-sdk/                 SDK público de complementos
  shared/                     tipos de contratos de tiempo de ejecución y herramientas
  runtime-node/               ejecutor de tiempo de ejecución aislado
  windows-host-agent/         agente host de Windows Sandbox / Hyper-V
workers/                      scripts de trabajadores Python y reglas YARA
docker/                       plantillas Dockerfile generadas y archivos de perfil
docs/                         documentación de arquitectura, complementos, tiempo de ejecución, implementación
tests/                        pruebas unitarias, de integración y e2e

Comandos de Desarrollo

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

Verificaciones enfocadas útiles:

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

Configuración del Cliente MCP

Compilación local:

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

Paquete publicado:

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

Almacenamiento

Por defecto, Rikune almacena datos persistentes bajo la raíz de Rikune a nivel de usuario. Los instaladores Docker suelen mapear esa raíz a un directorio host como D:\Docker\rikune.

Subdirectorios comunes:

• samples/
• artifacts/
• uploads/
• cache/
• logs/
• archivo de base de datos SQLite
• registro de auditoría JSONL

Los espacios de trabajo de muestras se agrupan por SHA-256 para evitar colisiones de rutas y preservar originales inmutables.

Límites de Seguridad

Rikune está diseñado para el análisis de malware y binarios no confiables, pero no es un límite de seguridad mágico por sí mismo.

• El modo Docker estático debe ser el predeterminado para análisis rutinarios.
• La ejecución en vivo de Windows debe ocurrir dentro de Windows Sandbox o una VM aislada.
• El Nodo de tiempo de ejecución rechaza el inicio inseguro a menos que se anule explícitamente.
• Las acciones peligrosas están protegidas por PolicyGuard.
• La ejecución de comandos utiliza APIs de procesos estructuradas y validación de comandos en lista blanca.
• No ejecute muestras desconocidas en una estación de trabajo host fuera del modelo de aislamiento de tiempo de ejecución.

Consulte SECURITY.md y TROUBLESHOOTING.md.

Mapa de Documentación

• INSTALL.md: Guía del instalador Docker en chino.
• DEPLOYMENT.md: Perfiles de implementación y topología de tiempo de ejecución.
• docs/ARCHITECTURE.md: Arquitectura de código actual.
• docs/PLUGINS.md: Lista de complementos, conceptos del SDK, ciclo de vida, descubrimiento.
• docs/ANALYSIS-RUNTIME.md: Modelo de ejecución de análisis y tiempo de ejecución por etapas.
• docs/ASYNC-JOB-PATTERN.md: Patrón de trabajos asíncronos y sondeo.
• docs/MIGRATION-ASYNC.md: Notas de migración para flujos de trabajo asíncronos por etapas.
• docs/DYNAMIC-RUNTIME-ROADMAP.md: Hoja de ruta y estado del tiempo de ejecución dinámico.
• CONTRIBUTING.md: Flujo de desarrollo y contribución.
• packages/plugin-sdk/README.md: Paquete de creación de complementos.
• workers/README.md: Contrato de trabajador Python.

Licencia

MIT