Aegis-SSH-MCP

Aegis-SSH-MCP

Dale a los agentes de IA acceso SSH seguro y limitado sin entregarles una shell.

Aegis-SSH-MCP es un puente pequeño nativo de MCP que permite a un agente de IA ejecutar comandos aprobados en hosts Linux a través de SSH.

Está diseñado para personas que quieren flujos de trabajo de infraestructura agénticos, pero no quieren dar a una IA acceso terminal sin restricciones.

Aegis se sitúa entre tu cliente MCP y tus servidores. Comprueba cada comando solicitado contra tus reglas, abre una sesión SSH de corta duración solo cuando el comando está permitido, devuelve el resultado y se desconecta.

Aegis no reemplaza SSH, los permisos de Linux, sudo ni el endurecimiento del host. Te ayuda a mantener esos controles al mando mientras ofrece a los clientes MCP una forma más segura de interactuar con sistemas reales.

Enlaces rápidos:

• Inicio rápido
• Cómo funciona
• Conceptos clave
• Modelo de seguridad
• Ejemplo de cliente: LibreChat
• Documentación

¿Qué problema resuelve Aegis?

Los agentes de IA son útiles cuando pueden inspeccionar registros, comprobar servicios, mirar contenedores o ejecutar comandos operativos rutinarios.

La versión peligrosa de eso es simple:

Dale al agente acceso SSH y espera que se comporte.

Aegis adopta un enfoque más seguro:

Dale al agente una herramienta MCP limitada que solo pueda ejecutar comandos que hayas aprobado.

Eso significa que un agente puede hacer cosas como comprobar el estado de Docker, leer registros o ejecutar diagnósticos sin recibir una shell persistente, una pseudo-terminal, reenvío del agente SSH ni estado de sesión oculto.

Buen ajuste

Aegis es útil cuando quieres:

• conectar un cliente MCP a hosts Linux a través de SSH
• permitir que los agentes ejecuten un pequeño conjunto de comandos operativos
• mantener el acceso a comandos limitado al host y basado en reglas
• auditar lo que el agente intentó hacer
• preservar tu modelo de seguridad existente de SSH, Linux, sudo y host

Lo que Aegis no es

Aegis es intencionalmente limitado.

No es un reemplazo de SSH, permisos de Linux, sudo, IAM, RBAC, endurecimiento del host ni el juicio humano.

No:

• dar a los agentes una shell persistente
• crear estado de sesión oculto
• proporcionar sandboxing completo a nivel de sistema operativo
• aprobar comandos mediante un flujo de trabajo humano
• convertir MCP en una plataforma completa de automatización de infraestructura

Eso es por diseño.

Aegis hace un solo trabajo:

Le da a un cliente MCP una forma controlada y auditable de ejecutar comandos SSH aprobados -- y deja el resto de tu modelo de seguridad intacto.

Inicio rápido

La forma recomendada de ejecutar Aegis es con el docker-compose.yml incluido.

Requisitos previos:

• Docker Compose
• un cliente MCP con soporte SSE
• un host Linux accesible
• una clave SSH o contraseña para un usuario remoto con privilegios mínimos

Por defecto, Aegis expone MCP sobre SSE en:

http://localhost:8443

Los perfiles de reglas iniciales están incluidos en rules/. Conserva o copia esos perfiles al implementar; el inicio rápido solo requiere que agregues configuraciones de host y credenciales SSH.

1. Crea las carpetas locales

Crea estas carpetas junto a docker-compose.yml si aún no existen:

./configs
./keys
./certs # only needed if you enable HTTPS

El repositorio ya incluye ./rules con perfiles de reglas iniciales.

2. Agrega una clave SSH

Coloca la clave privada SSH que Aegis debe usar en keys/.

Mantén los permisos de la clave estrictos y usa un usuario SSH dedicado con privilegios mínimos cuando sea posible.

3. Agrega una configuración de host

Crea configs/docker.json:

{
  "alias": "docker",
  "host_ip": "192.168.1.10",
  "ssh_port": 22,
  "ssh_user": "ops",
  "auth_method": "key",
  "key_path": "/keys/docker_ed25519",
  "rule_profile": "docker-readonly",
  "timeout_seconds": 30,
  "host_key_fingerprint": "SHA256:replace-this-with-your-real-host-key",
  "api_keys": [
    "change-me-docker-key"
  ]
}

Las partes importantes son:

• alias: el nombre amigable para este host
• ssh_user: el usuario Linux con el que Aegis se conecta
• key_path: la ruta de la clave privada dentro del contenedor
• rule_profile: las reglas de comandos que usa este host
• host_key_fingerprint: fija la clave de host SSH
• api_keys: tokens de portador permitidos para acceder al endpoint de este host

4. Inicia Aegis

docker compose pull
docker compose up -d
docker compose logs -f aegis-ssh-mcp

5. Conecta tu cliente MCP

Usa este endpoint SSE:

http://localhost:8443/mcp/docker/sse

Envía el token de portador configurado en configs/docker.json:

Authorization: Bearer change-me-docker-key

Puedes probar la accesibilidad con curl:

curl -i -N \
  -H "Authorization: Bearer change-me-docker-key" \
  http://localhost:8443/mcp/docker/sse

Un token válido debería devolver 200 OK y mantener el flujo SSE abierto.

Opcional: compilar desde el código fuente

git clone https://github.com/sparksbenjamin/Aegis-SSH-MCP.git
cd Aegis-SSH-MCP
go build -o aegis-ssh-mcp .

Cómo funciona

Para cada solicitud de comando, Aegis sigue el mismo flujo básico:

1. El cliente MCP le pide a Aegis que ejecute un comando.
2. Aegis verifica el token de portador para ese endpoint de host.
3. Aegis analiza el comando.
4. Aegis rechaza comportamientos inseguros de shell como encadenamiento, redirecciones y sustitución de comandos.
5. Aegis verifica el comando contra el perfil de reglas asignado al host.
6. Si el comando está permitido, Aegis abre una sesión SSH no interactiva nueva.
7. Aegis ejecuta el comando, captura el resultado, registra el intento y se desconecta.

No se entrega una shell persistente al agente.

+-------------------+
| MCP Client / LLM  |
| Claude / OpenAI   |
| LibreChat / SSE   |
+---------+---------+
          |
          | MCP over HTTP/SSE or stdio
          |
+---------v---------+
| Aegis-SSH-MCP     |
|-------------------|
| Bearer Auth       |
| Rule Validation   |
| Audit Logging     |
| Host Isolation    |
| Ephemeral SSH     |
+---------+---------+
          |
          | Standard SSH
          |
+---------v---------+
| Remote Linux Host |
|-------------------|
| SSH Permissions   |
| sudo Policies     |
| auditd/journald   |
| Host Security     |
+-------------------+

Conceptos clave

Las configuraciones pueden ser hosts fijos o perfiles dinámicos

Cada archivo JSON en configs/ describe un host remoto fijo o un perfil SSH dinámico.

Una configuración de host fijo crea:

• un endpoint MCP
• una herramienta SSH limitada al host
• un perfil de reglas asignado
• un límite de token de portador para SSE

Por ejemplo, un host con alias docker se convierte en:

/mcp/docker/sse

Si un agente necesita acceso a dos hosts, agrega Aegis dos veces en el cliente MCP: un endpoint y un token por alias de host.

Un perfil dinámico usa el mismo motor de reglas y ejecución SSH, pero la llamada a la herramienta MCP proporciona el host:

{
  "config_type": "dynamic",
  "alias": "linux-dynamic",
  "ssh_user": "ops",
  "auth_method": "key",
  "key_path": "/keys/linux-dynamic.pem",
  "rule_profile": "readonly-safe",
  "api_keys": [
    "change-me-linux-dynamic-key"
  ]
}

Ese perfil crea aegis_ssh_linux-dynamic con dos argumentos requeridos:

{
  "host": "192.168.1.42",
  "command": "uptime"
}

Las reglas deciden qué puede ejecutarse

Cada host apunta a un perfil de reglas:

"rule_profile": "docker-readonly"

Los perfiles de reglas viven en rules/ y definen qué formas de comando están permitidas o bloqueadas antes de intentar SSH.

Los perfiles iniciales incluyen:

• readonly-safe
• debian-readonly
• debian-ops
• ubuntu-readonly
• ubuntu-ops
• rhel-readonly
• rhel-ops
• proxmox-readonly
• proxmox-ops
• docker-readonly
• docker-ops
• systemd-ops
• kubernetes-readonly
• network-diagnostics
• logs-readonly
• package-readonly

La validación ocurre antes de SSH

Aegis valida los comandos antes de conectarse al host remoto.

El flujo de validación es:

1. Analiza el comando en ejecutable y argumentos.
2. Rechaza características de control de shell como redirecciones, encadenamiento y sustitución de comandos.
3. Permite solo un conjunto limitado de filtros de pipeline seguros.
4. Aplica comprobaciones de lista negra de ejecutable, argumento y comando completo.
5. Aplica comprobaciones de lista blanca de ejecutable, argumento y comando completo.
6. Intenta SSH solo si el comando pasa la validación.

Modelo de seguridad

Aegis usa defensa en profundidad. No es una capa de seguridad mágica; son varias fronteras más pequeñas trabajando juntas.

Postura de producción recomendada:

• usa usuarios SSH dedicados con privilegios mínimos
• fija las claves de host SSH con host_key_fingerprint
• usa primero perfiles de reglas limitados
• habilita TLS o ejecuta detrás de un proxy inverso de confianza
• rota los tokens de portador regularmente
• recopila los registros de Aegis de forma centralizada
• mantén la política de sudo explícita y mínima

Para el modelo de amenazas más profundo, consulta docs/security.md.

Configuraciones opcionales del host

Las configuraciones de host también pueden incluir:

• stealth_mode: devuelve una respuesta falsa de apariencia normal para comandos bloqueados
• fake_response: respuesta personalizada usada cuando stealth_mode está habilitado
• redaction_enabled: enmascara la salida coincidente antes de devolver los resultados
• redaction_patterns: patrones de regex usados para la redacción de salida
• host_key_fingerprint: fijación de clave de host SSH recomendada

Ejemplo de cliente: LibreChat

mcpSettings:
  allowedDomains:
    - "192.168.100.184"

mcpServers:
  aegis-docker:
    type: sse
    url: "http://192.168.100.184:8443/mcp/docker/sse"
    headers:
      Authorization: "Bearer change-me-docker-key"
    timeout: 120000
    initTimeout: 30000

Documentación

El README está pensado para ayudarte a entender y probar Aegis rápidamente. La documentación más profunda está aquí:

• docs/security.md: modelo de amenazas, lógica de validación, manejo de pipelines, endurecimiento de contenedores y comportamiento de sesiones SSH
• docs/config.md: campos de configuración de host, comportamiento de recarga en caliente, alias, claves API y rutas de claves
• docs/rules.md: diseño de perfiles de reglas, listas blancas, listas negras, restricciones de argumentos y perfiles iniciales
• docs/FAQ.md: preguntas frecuentes y notas operativas
• docs/tech-specs/aegis-ssh-mcp-tech-spec.md: detalles de implementación más profundos
• docs/readme-authoring.md: guía de redacción del README para este repositorio

Capturas de pantalla

Estado del proyecto

Aegis tiene una API en etapa temprana y un runtime operativo.

Las capacidades actuales incluyen:

• MCP sobre HTTP/SSE
• MCP sobre stdio
• configuración multi-host
• validación de comandos basada en reglas
• registro de auditoría
• autenticación con clave SSH
• autenticación con contraseña
• fijación de huella de host
• ejecución SSH efímera por solicitud
• runtime de contenedor distroless sin shell endurecido
• redacción opcional de salida
• recarga en caliente para cambios de configuración y reglas

Soporte y contribuciones

Para errores, preguntas de configuración o comentarios operativos, abre un issue en este repositorio.

Mantenedor principal: @sparksbenjamin

Las contribuciones son bienvenidas, especialmente en torno a:

• interoperabilidad de clientes MCP
• mejoras en la validación de reglas
• observabilidad
• endurecimiento de implementación
• soporte de transporte
• pruebas y validación

Hasta que se publique una guía de contribución dedicada, abrir un issue antes de un cambio grande es la mejor manera de alinearse en la dirección.

Licencia

MIT License