rikune

Servidor MCP para engenharia reversa de executáveis Windows e formatos binários. Combina triagem estática, recuperação de funções assistida por Ghidra, ferramentas orientadas a plugins, gerenciamento de artefatos e execução opcional em runtime Windows isolada.

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.

Equivalente manual:

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.

Do Linux/macOS com um host Windows remoto:

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

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
• tool.help, tool.readiness e tools.discover para inspeção de compatibilidade/depuração

Arquitetura

O caminho de código atual é:

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.

O carregamento de plugins é controlado por PLUGINS:

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

Comandos de Desenvolvimento

Verificações focadas úteis:

Configuração do Cliente MCP

Build local:

Docker stdio:

Pacote publicado:

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