rootpilot-ssh-diagnose

Diagnósticos de servidor SSH de solo lectura: lista blanca de 38 comandos, con secretos redactados.

Documentación

rootpilot-ssh-diagnose

Esta es la versión de código abierto, trae-tu-propio-LLM de RootPilot. El producto completo añade diagnóstico calibrado (89.7% en 29 escenarios de fallo estándar, cero falsas alarmas en hosts saludables), auto-diagnóstico activado por alertas, historial y gestión multi-host → rootpilotx.com · repositorio de despliegue: rootpilot-release

Un servidor MCP que permite a cualquier cliente MCP — Claude Desktop, Claude Code, o el tuyo propio — recopilar de forma segura diagnósticos de solo lectura de tus servidores a través de SSH. Recopila evidencia de una lista blanca fija de comandos de solo lectura; tu modelo hace el razonamiento. El servidor nunca ejecuta nada fuera de la lista blanca y nunca realiza cambios en tus hosts.

Por qué

Cuando un servidor se comporta mal, terminas conectándote por SSH y ejecutando los mismos veinte comandos — df -h, docker ps, dmesg | grep -i oom, free -m — y luego revisando la salida. Este servidor convierte eso en una conversación: tu LLM solicita exactamente la evidencia que necesita, recibe salida estructurada y con secretos redactados, y razona sobre la causa raíz. Tú mantienes el control; nada sale de tu máquina excepto SSH hacia tus propios hosts.

Modelo de seguridad (léelo primero)

Lista blanca de solo lectura. Hay exactamente 38 comandos integrados (get_whitelist los lista todos). No existe ninguna herramienta que ejecute un comando arbitrario — ni siquiera con un mensaje de confirmación. Cada comando solo inspecciona el estado.
El único valor inyectable es un nombre de contenedor, validado contra ^[a-zA-Z0-9_.-]+$ antes de colocarse en un comando. web; rm -rf / se rechaza, no se escapa.
Los secretos se redactan de la salida antes de llegar a tu modelo: secretos de KEY=value, tokens de Bearer/Basic, formas de clave de sk-/ghp_/AKIA…, bloques de claves privadas PEM y credenciales incrustadas en URLs. Los valores de entorno de docker inspect se eliminan.
Tiempo de espera por comando (15s) y límite de salida protegen contra cuelgues e inundaciones.
Las credenciales permanecen locales. Las definiciones de hosts viven en un archivo que tú controlas; las contraseñas nunca se registran.

Configuración en 30 segundos

Añade el servidor a tu 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"
      }
    }
  }
}

Luego crea hosts.json (consulta 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": "..." } }
]

Reinicia tu cliente. Pregúntale: "Diagnostica prod-1" (o ejecuta el prompt diagnose-host).

Usa una cuenta de privilegios mínimos. Crea un usuario SSH dedicado de solo lectura para diagnósticos en lugar de reutilizar root. Los comandos solo leen estado, pero la cuenta debe reflejar eso.

Herramientas

herramienta	argumentos	qué hace
`list_hosts`	`probe?`	Lista los hosts configurados; con `probe`, también prueba la conectividad SSH
`get_whitelist`	—	Devuelve los 38 comandos (clave, propósito, plantilla) para que tú y el modelo puedan auditar exactamente qué puede ejecutarse
`collect`	`host`, `keys[]` (≤8), `container?`	Ejecuta comandos específicos de la lista blanca y devuelve salida redactada y truncada
`collect_base`	`host`	Atajo: la visión general base (`docker_ps`, `df`, `df_inode`, `free`, `uptime`, `dmesg_oom`, `docker_daemon`)
`container_deep_dive`	`host`, `container`	Atajo: `docker_logs`, `docker_inspect` (redactado), `container_state`, `docker_stats` para un contenedor

Dos prompts vienen integrados: diagnose-host (recorrido de causa raíz primero-evidencia) y health-check (un barrido ligero).

Configuración

variable de entorno	predeterminado	propósito
`RP_HOSTS`	—	Ruta a tu `hosts.json` (requerido)
`RP_PROBE_URL`	`https://cloudflare.com`	Destino para las sondas de conectividad saliente / DNS
`RP_NO_PROMO`	—	Establécelo en `1` para silenciar la indicación de una línea al producto completo

Cómo 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

El servidor deliberadamente no realiza análisis propio — sin llamada LLM integrada, sin orquestación de múltiples rondas. Ese límite es el punto: es un recolector de evidencia limpio y auditable. El diagnóstico calibrado (decidir qué evidencia extraer para qué síntoma, a través de rondas de seguimiento, puntuado contra una biblioteca de escenarios de fallo) es lo que hace el producto completo RootPilot.

Preguntas frecuentes

¿Alguna vez cambia mi servidor? No. Cada comando es de solo lectura y no existe una herramienta de comandos arbitrarios. La lista blanca completa es visible a través de get_whitelist.

¿A dónde van mis datos? A ningún lugar excepto SSH entre este servidor (que se ejecuta en tu máquina) y tus hosts. La salida de comandos va al modelo de tu cliente MCP. Sin telemetría.

¿Qué LLM usa? Ninguno propio — es trae-tu-propio. Cualquier modelo que ejecute tu cliente MCP hace el razonamiento.

¿Puede gestionar servidores Windows o hosts de salto? No en v1. Está dirigido a hosts Linux a través de SSH directo.

¿En qué se diferencia de RootPilot? Esto recopila evidencia; tú (o tu modelo) la interpretas ad hoc. RootPilot añade diagnóstico calibrado, auto-diagnóstico activado por alertas, historial por host ("historial médico") y gestión multi-host. Consulta rootpilotx.com.

Desarrollo

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

Licencia

MIT — consulta LICENSE.