rootpilot-ssh-diagnose

rootpilot-ssh-diagnose

Esta é a versão open-source, traga-seu-próprio-LLM do RootPilot. O produto completo adiciona diagnóstico calibrado (89,7% em 29 cenários padrão de falha, zero alarmes falsos em hosts saudáveis), autodiagnóstico acionado por alertas, histórico e gerenciamento multi-host → rootpilotx.com · repositório de implantação: rootpilot-release

Um servidor MCP que permite que qualquer cliente MCP — Claude Desktop, Claude Code ou o seu próprio — colete com segurança diagnósticos somente leitura dos seus servidores via SSH. Ele reúne evidências de uma lista fixa de comandos somente leitura; seu modelo faz o raciocínio. O servidor nunca executa nada fora da lista e nunca faz alterações nos seus hosts.

Por quê

Quando um servidor se comporta mal, você acaba acessando via SSH e executando os mesmos vinte comandos — df -h, docker ps, dmesg | grep -i oom, free -m — e depois analisando a saída. Este servidor transforma isso em uma conversa: seu LLM solicita exatamente a evidência de que precisa, recebe uma saída estruturada e com segredos removidos, e raciocina sobre a causa raiz. Você mantém o controle; nada sai da sua máquina, exceto o SSH para seus próprios hosts.

Modelo de segurança (leia isto primeiro)

• Lista de permissões somente leitura. Existem exatamente 38 comandos integrados (get_whitelist lista todos). Não há ferramenta que execute um comando arbitrário — nem mesmo com um prompt de confirmação. Cada comando apenas inspeciona o estado.
• O único valor injetável é um nome de contêiner, validado contra ^[a-zA-Z0-9_.-]+$ antes de ser colocado em um comando. web; rm -rf / é rejeitado, não escapado.
• Segredos são removidos da saída antes de chegar ao seu modelo: segredos KEY=value, tokens Bearer/Basic, formatos de chave sk-/ghp_/AKIA…, blocos de chave privada PEM e credenciais incorporadas em URLs. Valores de ambiente docker inspect são limpos.
• Tempo limite por comando (15s) e truncamento de saída protegem contra travamentos e sobrecargas.
• Credenciais permanecem locais. As definições de host ficam em um arquivo que você controla; senhas nunca são registradas em logs.

Configuração em 30 segundos

Adicione o servidor ao seu cliente MCP. Para Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "rootpilot-ssh-diagnose": {
      "command": "npx",
      "args": ["-y", "@rootpilot/mcp-ssh-diagnose"],
      "env": {
        "RP_HOSTS": "/Users/me/.rootpilot-mcp/hosts.json"
      }
    }
  }
}

Em seguida, crie hosts.json (veja hosts.example.json):

[
  { "name": "prod-1", "host": "1.2.3.4", "port": 22, "user": "rootpilot",
    "auth": { "type": "key", "keyPath": "~/.ssh/rootpilot_key" } },
  { "name": "prod-2", "host": "10.0.0.5", "user": "ops",
    "auth": { "type": "password", "password": "..." } }
]

Reinicie seu cliente. Pergunte a ele: "Diagnostique prod-1" (ou execute o prompt diagnose-host).

Use uma conta com privilégios mínimos. Crie um usuário SSH dedicado somente leitura para diagnósticos, em vez de reutilizar o root. Os comandos apenas leem o estado, mas a conta deve refletir isso.

Ferramentas

ferramenta	argumentos	o que faz
list_hosts	probe?	Lista hosts configurados; com probe, também testa a acessibilidade SSH
get_whitelist	—	Retorna todos os 38 comandos (chave, finalidade, modelo) para que você e o modelo possam auditar exatamente o que pode ser executado
collect	host, keys[] (≤8), container?	Executa comandos específicos da lista de permissões e retorna saída com segredos removidos e truncada
collect_base	host	Atalho: a visão geral básica (docker_ps, df, df_inode, free, uptime, dmesg_oom, docker_daemon)
container_deep_dive	host, container	Atalho: docker_logs, docker_inspect (com segredos removidos), container_state, docker_stats para um contêiner

Dois prompts são integrados: diagnose-host (análise de causa raiz com foco em evidências) e health-check (uma varredura leve).

Configuração

variável de ambiente	padrão	finalidade
RP_HOSTS	—	Caminho para seu hosts.json (obrigatório)
RP_PROBE_URL	https://cloudflare.com	Destino para as sondas de conectividade de saída / DNS
RP_NO_PROMO	—	Defina como 1 para silenciar a indicação de uma linha para o produto completo

Como funciona

  your MCP client (the LLM)
        │  "collect df, docker_ps, dmesg_oom from prod-1"
        ▼
  rootpilot-ssh-diagnose  ──ssh──▶  your server
        │  renders a whitelisted template, runs it read-only,
        │  redacts secrets, truncates, returns structured output
        ▼
  the LLM reasons about root cause from the evidence

O servidor deliberadamente não faz análise própria — sem chamada LLM integrada, sem orquestração em várias rodadas. Esse limite é o ponto central: é um coletor de evidências limpo e auditável. O diagnóstico calibrado (decidir quais evidências coletar para qual sintoma, em rodadas de acompanhamento, avaliado contra uma biblioteca de cenários de falha) é o que o produto completo RootPilot faz.

Perguntas frequentes

Isso alguma vez altera meu servidor? Não. Cada comando é somente leitura e não há ferramenta de comando arbitrário. A lista completa de permissões está visível via get_whitelist.

Para onde vão meus dados? Para lugar nenhum, exceto SSH entre este servidor (executando na sua máquina) e seus hosts. A saída dos comandos vai para o modelo do seu cliente MCP. Sem telemetria.

Qual LLM ele usa? Nenhum próprio — é traga-o-seu. Qualquer modelo que seu cliente MCP execute faz o raciocínio.

Ele pode gerenciar servidores Windows ou hosts de salto? Não na v1. Ele tem como alvo hosts Linux via SSH direto.

Qual é a diferença em relação ao RootPilot? Este coleta evidências; você (ou seu modelo) as interpreta ad hoc. O RootPilot adiciona diagnóstico calibrado, autodiagnóstico acionado por alertas, histórico por host ("prontuário médico") e gerenciamento multi-host. Veja rootpilotx.com.

Desenvolvimento

npm install
npm run build      # compile to dist/
npm test           # whitelist / injection / redaction / timeout tests
npm run typecheck

Licença

MIT — veja LICENSE.