Rikune

Rikune é um servidor MCP para engenharia reversa de executáveis Windows e formatos binários relacionados. Ele combina ingestão de amostras, triagem estática, recuperação de funções assistida por Ghidra, ferramentas especializadas orientadas por plugins, gerenciamento de artefatos e execução opcional em runtime Windows isolado por trás de uma interface Model Context Protocol.

O fluxo de trabalho atual do servidor voltado para IA é organizado em torno de uma superfície de gateway mínima:

1. Use workflow.search para classificar perfis, fluxos de trabalho e capacidades especializadas correspondentes para o tipo de arquivo e objetivo do usuário.
2. Use workflow.run action=request_upload para upload de arquivos do host, ou deixe workflow.search apontar clientes legados para ferramentas ocultas de compatibilidade de ingestão de amostras.
3. Use workflow.run action=start com o sample_id retornado.
4. Use workflow.run action=status e workflow.run action=promote para monitorar e aprofundar a execução em estágios.
5. Use artifact.read para artefatos completos persistidos quando a saída compacta do fluxo de trabalho não for suficiente.

sample.*, workflow.analyze.*, workflow.triage, tools.discover e task.status permanecem registrados para compatibilidade ou inspeção de baixo nível, mas novos clientes devem preferir workflow.search, workflow.run e artifact.read.

Ao conectar através do gateway remoto rikune-agent, os clientes MCP veem nomes de transporte estáveis: workflow_search, workflow_run, artifact_read, rikune_tool_call e os controles rikune_connection_*. rikune_connection_refresh atualiza apenas o cache interno de capacidade upstream; não expande a lista de ferramentas MCP. Use rikune_tool_call somente após workflow_search identificar uma subferramenta interna específica do analisador que não seja coberta pelos gateways primários de fluxo de trabalho ou artefato.

O que Rikune oferece

• Servidor MCP stdio para clientes de IA e runtimes de agente.
• API HTTP opcional e painel para uploads, downloads, verificações de integridade, eventos SSE e acesso a artefatos.
• Espaços de trabalho de amostras baseados em SHA-256 com arquivos originais duráveis, diretórios de cache, artefatos de análise e sessões de upload.
• Persistência baseada em SQLite para amostras, análises, trabalhos, evidências, artefatos, lotes, sessões de depuração e telemetria do agendador.
• Arquitetura de plugins com 111 plugins internos e descoberta de plugins externos.
• Superfície de ferramentas progressiva: o gateway padrão voltado para IA é intencionalmente pequeno; workflow.search usa tipo de amostra, descobertas e metadados de perfil para rotear para capacidades especializadas sem expor todas as ferramentas desde o início.
• Análise estática e enriquecimento para PE, ELF, Mach-O, APK/DEX, Office, firmware, UEFI/SMM, CUDA PTX/CUBIN/fatbin, strings, YARA, SBOM, assinaturas, packers, .NET, Go, Rust e muito mais.
• Integração com Ghidra, Rizin, RetDec, angr, Capstone, Graphviz, Qiling, PANDA, Speakeasy, Wine, Frida e runtime dinâmico quando disponível.
• Instalação de backend Docker orientada por plugins com níveis padrão, opcional, pesquisa, runtime, GPU, BYO e sidecar para ferramentas de engenharia reversa baseadas em workers.
• Divisão opcional Analisador/Runtime para execução Windows ao vivo através de um Windows Host Agent, Windows Sandbox ou VM Hyper-V.
• Portas de política para execução ao vivo, acesso à rede, upload externo e descompilação em massa.

Início Rápido

Analisador Docker Estático

O Docker estático é o padrão mais seguro. Ele não executa amostras.

.\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 + Runtime Windows

O modo híbrido executa o Analisador no Docker e delega trabalhos Windows ao vivo para um Windows Host Agent. O Host Agent pode iniciar o Windows Sandbox sob demanda ou controlar uma VM Hyper-V configurada.

.\rikune.ps1 install -Profile hybrid -InstallRuntime

Do Linux/macOS com um host Windows remoto:

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

Conectar um cliente MCP não inicia o Windows Sandbox nem executa uma amostra. O trabalho de runtime ao vivo só começa quando uma ferramenta o solicita explicitamente, como runtime.debug.session.start, runtime.debug.command, sandbox.execute ou um estágio de execução dinâmica promovido.

Desenvolvimento Nativo

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

O pacote raiz requer Node.js 22 ou mais recente. Alguns subpacotes de runtime podem ser executados em versões mais antigas do Node, mas o desenvolvimento do repositório e a CLI raiz publicada devem usar Node 22+.

Fluxo de Gateway Principal

Pesquisar e Enviar

Comece com workflow.search sempre que o fluxo de trabalho, tipo de arquivo ou backend solicitado não estiver claro. Ele classifica perfis correspondentes e retorna dicas compactas de prontidão/roteamento sem ativar ferramentas especializadas ocultas.

Para arquivos do host, chame workflow.run action=request_upload, faça POST dos bytes brutos para a URL de upload retornada e depois leia sample_id da resposta HTTP. sample.request_upload e sample.ingest são auxiliares de compatibilidade, não o caminho normal voltado para IA.

Para implantações de analisador remoto ou rikune-agent, defina API_PUBLIC_BASE_URL, RIKUNE_API_PUBLIC_BASE_URL ou RIKUNE_ANALYZER_PUBLIC_URL para a base da API HTTP acessível ao cliente, por exemplo http://159.195.136.226:18080. As sessões de upload então retornam valores públicos upload_url / status_url em vez de URLs localhost locais ao contêiner. O gateway remoto também normaliza URLs de upload localhost de analisadores mais antigos para seu endpoint configurado.

Se a API HTTP estiver habilitada, POST /api/v1/samples ainda está disponível para integrações não-MCP. A ingestão bem-sucedida retorna um sample_id; a análise deve usar sample_id, não um caminho local, após a importação.

Iniciar Análise

Chame workflow.run action=start com o sample_id. O primeiro estágio realiza um perfil rápido e cria ou reutiliza uma execução de análise. O plan_id retornado mapeia para a execução de análise persistida.

Promover Estágios

Use workflow.run action=promote para solicitar estágios mais profundos. O pipeline atualmente modela estes estágios:

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

Trabalhos de longa duração são enfileirados através do sistema de jobs. Consulte o estado compacto do estágio com workflow.run action=status.

workflow.run action=status é a visualização principal da execução em estágios. Grandes cargas úteis de estágios históricos podem ser podadas com um aviso no nível superior; use artifact.read para artefatos completos. task.status é uma visualização bruta de fila/processo para compatibilidade e inclui telemetria de memória external_active_* para subprocessos do analisador.

Revisar Resultados

Superfícies úteis de acompanhamento:

• workflow.search
• workflow.run
• analysis.context.get
• artifact.read, mais auxiliares de compatibilidade de artefato como 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
• , e para inspeção de compatibilidade/depuração

Arquitetura

O caminho de código atual é:

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

Módulos centrais do servidor ficam em src/core/:

Alguns arquivos de nível raiz como src/server.ts, src/tool-registry.ts e src/plugins.ts permanecem como encaminhadores de compatibilidade. Novo código deve ter como alvo src/core/*.

Planos de Implantação

Os modos de runtime são configurados através de runtime.mode ou variáveis de ambiente:

• disabled: nenhuma delegação de runtime.
• manual: conectar a um endpoint de runtime fornecido.
• remote-sandbox: delegar a um Windows Host Agent.
• auto-sandbox: analisador Windows nativo inicia Windows Sandbox localmente.

Analisadores Docker/WSL devem usar remote-sandbox, não auto-sandbox.

Sistema de Plugins

Rikune atualmente inclui 111 plugins internos em src/plugins/<id>/. Os plugins podem registrar ferramentas, declarar dependências, expor esquemas de configuração, participar de hooks de ciclo de vida, fornecer metadados Docker e declarar ferramentas limitadas baseadas em Worker através de metadados workerBackend.

O conjunto de Workers de fronteira mantém ferramentas apenas de plano como superfícies de triagem e transferência, depois adiciona ferramentas de execução explícitas ao lado delas. 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 expõem contratos de Worker através de workflow.search, plugin.list, tool.help e tool.readiness; tools.discover permanece um portal de compatibilidade de baixo nível. Descoberta e prontidão permanecem passivas: relatam metadados de backend e orientação de configuração sem iniciar REstringer, JSIMPLIFIER, JSIR/CASCADE, GTIRB, Remill, Manifold, QBDI, drivers GPU, Node/V8, navegadores ou instrumentação de runtime.

A geração do Docker lê systemDeps do plugin e metadados de empacotamento de Worker diretamente. Imagens padrão instalam wrappers estáticos de baixo risco como REstringer, JSIMPLIFIER, Manifold, WABT e validação LIEF; perfis opcionais podem habilitar rotas estáticas JSIR/CASCADE, JSVMP, GTIRB, radare2 e Triton; backends pesados/runtime/GPU/sensíveis a licença permanecem bloqueados por perfil, BYO ou 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

O carregamento de plugins é controlado por PLUGINS:

PLUGINS=*                 # todos os internos
PLUGINS=pe-analysis,yara  # plugins selecionados
PLUGINS=-dynamic          # todos exceto dinâmicos

Use estas ferramentas MCP em tempo de execução:

• workflow.search
• workflow.run
• plugin.list
• plugin.enable
• plugin.disable
• tools.discover e tool.readiness para inspeção de compatibilidade/depuração de baixo nível

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

API HTTP

Quando api.enabled é verdadeiro, o servidor de arquivos embutido expõe:

Autenticação por chave de API, limitação de taxa, cabeçalhos de segurança e CORS limitado são tratados pela camada HTTP.

Pré-requisitos

Linha de base mínima de desenvolvimento:

• Node.js 22+
• npm
• Python 3.11+ recomendado para workers e scripts de análise
• Docker 20.10+ e Docker Compose v2 para perfis Docker
• Java 21+ para lançamentos modernos de Ghidra
• Ghidra para análise de funções com suporte a descompilador
• Windows 10/11 Pro, Enterprise ou suporte VM equivalente para caminhos de runtime Windows Sandbox e Hyper-V

Ferramentas opcionais são específicas de plugin. Execute system.health, system.setup.guide, tool.readiness e plugin.list para ver o que está faltando em um determinado ambiente.

Layout do Projeto

src/
  index.ts                    entrada principal do servidor
  core/                       servidor MCP, registro, executor, orquestração de plugins
  core/tool-registry/         fatias de registro de ferramentas/prompts/recursos internas
  tools/                      implementações principais de ferramentas
  workflows/                  fluxos de trabalho de análise em estágios, triagem, reconstrução, revisão
  analysis/                   estado de execução e executor de tarefas em segundo plano
  plugins/                    111 plugins internos
  persistence/                persistência SQLite e workspace
  sample/                     finalização de amostra e inspeção de workspace
  storage/                    artefatos, uploads, retenção
  runtime-client/             cliente de delegação de runtime do lado do analisador
  worker/                     orquestração de workers Ghidra e Python
packages/
  plugin-sdk/                 SDK público de plugins
  shared/                     tipos de contrato de runtime e ferramenta
  runtime-node/               executor de runtime isolado
  windows-host-agent/         agente host Windows Sandbox / Hyper-V
workers/                      scripts de worker Python e regras YARA
docker/                       modelos Dockerfile gerados e arquivos de perfil
docs/                         documentação de arquitetura, plugin, runtime, implantação
tests/                        testes unitários, de integração e e2e

Comandos de Desenvolvimento

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

Verificações focadas úteis:

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

Configuração do Cliente MCP

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

Pacote publicado:

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

Armazenamento

Por padrão, o Rikune armazena dados persistentes sob a raiz do Rikune em nível de usuário. Instaladores Docker geralmente mapeiam essa raiz para um diretório host como D:\Docker\rikune.

Subdiretórios comuns:

• samples/
• artifacts/
• uploads/
• cache/
• logs/
• Arquivo de banco de dados SQLite
• Audit log JSONL

Os espaços de trabalho de amostras são agrupados por SHA-256 para evitar colisões de caminho e preservar originais imutáveis.

Limites de Segurança

O Rikune é projetado para análise de malware e binários não confiáveis, mas não é um limite de segurança mágico por si só.

• O modo Docker estático deve ser o padrão para análise de rotina.
• A execução Windows ao vivo deve acontecer dentro do Windows Sandbox ou de uma VM isolada.
• O Runtime Node recusa inicialização insegura a menos que explicitamente substituído.
• Ações perigosas são protegidas por PolicyGuard.
• A execução de comandos usa APIs de processo estruturadas e validação de comandos em lista de permissões.
• Não execute amostras desconhecidas em uma estação de trabalho host fora do modelo de isolamento de runtime.

Consulte SECURITY.md e TROUBLESHOOTING.md.

Mapa de Documentação

• INSTALL.md: Guia do instalador Docker em chinês.
• DEPLOYMENT.md: Perfis de implantação e topologia de runtime.
• docs/ARCHITECTURE.md: Arquitetura de código atual.
• docs/PLUGINS.md: Lista de plugins, conceitos do SDK, ciclo de vida, descoberta.
• docs/ANALYSIS-RUNTIME.md: Modelo de execução de runtime e análise em estágios.
• docs/ASYNC-JOB-PATTERN.md: Padrão de job assíncrono e polling.
• docs/MIGRATION-ASYNC.md: Notas de migração para fluxos de trabalho assíncronos em estágios.
• docs/DYNAMIC-RUNTIME-ROADMAP.md: Roteiro e status do runtime dinâmico.
• CONTRIBUTING.md: Fluxo de desenvolvimento e contribuição.
• packages/plugin-sdk/README.md: Pacote de criação de plugins.
• workers/README.md: Contrato de worker Python.

Licença

MIT