Aegis-SSH-MCP

Aegis-SSH-MCP

Dê a agentes de IA acesso SSH seguro e limitado sem entregar a eles um shell.

Aegis-SSH-MCP é uma pequena ponte nativa de MCP que permite a um agente de IA executar comandos aprovados em hosts Linux via SSH.

Ele foi criado para pessoas que desejam fluxos de trabalho de infraestrutura agênticos, mas não querem dar a uma IA acesso irrestrito ao terminal.

Aegis fica entre seu cliente MCP e seus servidores. Ele verifica cada comando solicitado contra suas regras, abre uma sessão SSH de curta duração apenas quando o comando é permitido, retorna o resultado e desconecta.

Aegis não substitui SSH, permissões Linux, sudo ou endurecimento de host. Ele ajuda você a manter esses controles no comando enquanto oferece aos clientes MCP uma forma mais segura de interagir com sistemas reais.

Links rápidos:

• Início rápido
• Como funciona
• Conceitos principais
• Modelo de segurança
• Exemplo de cliente: LibreChat
• Documentação

Que problema o Aegis resolve?

Agentes de IA são úteis quando podem inspecionar logs, verificar serviços, olhar containers ou executar comandos operacionais de rotina.

A versão perigosa disso é simples:

Dê ao agente acesso SSH e espere que ele se comporte bem.

Aegis adota uma abordagem mais segura:

Dê ao agente uma ferramenta MCP restrita que só pode executar comandos que você aprovou.

Isso significa que um agente pode fazer coisas como verificar o status do Docker, ler logs ou executar diagnósticos sem receber um shell persistente, um pseudo-terminal, encaminhamento de agente SSH ou estado de sessão oculto.

Boa adequação

Aegis é útil quando você quer:

• conectar um cliente MCP a hosts Linux via SSH
• permitir que agentes executem um pequeno conjunto de comandos operacionais
• manter o acesso a comandos restrito por host e baseado em regras
• auditar o que o agente tentou fazer
• preservar seu modelo de segurança existente de SSH, Linux, sudo e host

O que o Aegis não é

Aegis é intencionalmente limitado.

Ele não substitui SSH, permissões Linux, sudo, IAM, RBAC, endurecimento de host ou julgamento humano.

Ele não:

• fornece a agentes um shell persistente
• cria estado de sessão oculto
• fornece sandboxing completo em nível de sistema operacional
• aprova comandos por meio de um fluxo de trabalho humano
• transforma MCP em uma plataforma completa de automação de infraestrutura

Isso é proposital.

Aegis faz um único trabalho:

Ele dá a um cliente MCP uma forma controlada e auditável de executar comandos SSH aprovados — e mantém o restante do seu modelo de segurança intacto.

Início rápido

A forma recomendada de executar o Aegis é com o docker-compose.yml incluído.

Pré-requisitos:

• Docker Compose
• um cliente MCP com suporte a SSE
• um host Linux acessível
• uma chave SSH ou senha para um usuário remoto com privilégios mínimos

Por padrão, o Aegis expõe MCP via SSE em:

http://localhost:8443

Perfis de regras iniciais estão incluídos em rules/. Mantenha ou copie esses perfis ao implantar; o início rápido só exige que você adicione configurações de host e credenciais SSH.

1. Crie as pastas locais

Crie estas pastas ao lado de docker-compose.yml se elas ainda não existirem:

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

O repositório já inclui ./rules com perfis de regras iniciais.

2. Adicione uma chave SSH

Coloque a chave privada SSH que o Aegis deve usar em keys/.

Mantenha as permissões da chave restritas e use um usuário SSH dedicado com privilégios mínimos sempre que possível.

3. Adicione uma configuração de host

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

As partes importantes são:

• alias: o nome amigável para este host
• ssh_user: o usuário Linux com o qual o Aegis se conecta
• key_path: o caminho da chave privada dentro do container
• rule_profile: as regras de comando que este host usa
• host_key_fingerprint: fixa a chave de host SSH
• api_keys: tokens bearer permitidos para acessar este endpoint de host

4. Inicie o Aegis

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

5. Conecte seu cliente MCP

Use este endpoint SSE:

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

Envie o token bearer configurado em configs/docker.json:

Authorization: Bearer change-me-docker-key

Você pode testar a acessibilidade com curl:

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

Um token válido deve retornar 200 OK e manter o stream SSE aberto.

Opcional: compilar a partir do código-fonte

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

Como funciona

Para cada solicitação de comando, o Aegis segue o mesmo fluxo básico:

1. O cliente MCP pede ao Aegis para executar um comando.
2. O Aegis verifica o token bearer para aquele endpoint de host.
3. O Aegis analisa o comando.
4. O Aegis rejeita comportamentos inseguros de shell, como encadeamento, redirecionamentos e substituição de comandos.
5. O Aegis verifica o comando contra o perfil de regras atribuído ao host.
6. Se o comando for permitido, o Aegis abre uma nova sessão SSH não interativa.
7. O Aegis executa o comando, captura o resultado, registra a tentativa e desconecta.

Nenhum shell persistente é entregue ao 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     |
+-------------------+

Conceitos principais

Configurações podem ser hosts fixos ou perfis dinâmicos

Cada arquivo JSON em configs/ descreve um host remoto fixo ou um perfil SSH dinâmico.

Uma configuração de host fixo cria:

• um endpoint MCP
• uma ferramenta SSH restrita ao host
• um perfil de regras atribuído
• um limite de token bearer para SSE

Por exemplo, um host com alias docker se torna:

/mcp/docker/sse

Se um agente precisar de acesso a dois hosts, adicione o Aegis duas vezes no cliente MCP: um endpoint e um token por alias de host.

Um perfil dinâmico usa o mesmo mecanismo de regras e execução SSH, mas a chamada da ferramenta MCP fornece o 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"
  ]
}

Esse perfil cria aegis_ssh_linux-dynamic com dois argumentos obrigatórios:

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

Regras decidem o que pode ser executado

Cada host aponta para um perfil de regras:

"rule_profile": "docker-readonly"

Os perfis de regras ficam em rules/ e definem quais formatos de comando são permitidos ou bloqueados antes que o SSH seja tentado.

Os perfis iniciais incluem:

• 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

A validação acontece antes do SSH

O Aegis valida comandos antes de se conectar ao host remoto.

O fluxo de validação é:

1. Analise o comando em executável e argumentos.
2. Rejeite recursos de controle de shell, como redirecionamentos, encadeamento e substituição de comandos.
3. Permita apenas um conjunto limitado de filtros de pipeline seguros.
4. Aplique verificações de lista negra para executável, argumentos e comando completo.
5. Aplique verificações de lista branca para executável, argumentos e comando completo.
6. Tente o SSH apenas se o comando passar na validação.

Modelo de segurança

O Aegis usa defesa em profundidade. Não é uma camada mágica de segurança; são várias fronteiras menores trabalhando juntas.

Postura recomendada para produção:

• use usuários SSH dedicados com privilégios mínimos
• fixe chaves de host SSH com host_key_fingerprint
• use perfis de regras restritos primeiro
• habilite TLS ou execute atrás de um proxy reverso confiável
• rotacione tokens bearer regularmente
• colete logs do Aegis centralmente
• mantenha a política de sudo explícita e mínima

Para o modelo de ameaças mais detalhado, veja docs/security.md.

Configurações opcionais de host

As configurações de host também podem incluir:

• stealth_mode: retorna uma resposta falsa de aparência normal para comandos bloqueados
• fake_response: resposta personalizada usada quando stealth_mode está habilitado
• redaction_enabled: mascara saídas correspondentes antes que os resultados sejam retornados
• redaction_patterns: padrões regex usados para redação de saída
• host_key_fingerprint: fixação recomendada de chave de host SSH

Exemplo 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

Documentação

O README foi feito para ajudar você a entender e experimentar o Aegis rapidamente. A documentação mais aprofundada está aqui:

• docs/security.md: modelo de ameaças, lógica de validação, tratamento de pipelines, endurecimento de container e comportamento de sessão SSH
• docs/config.md: campos de configuração de host, comportamento de recarga dinâmica, aliases, chaves de API e caminhos de chaves
• docs/rules.md: design de perfis de regras, listas brancas, listas negras, restrições de argumentos e perfis iniciais
• docs/FAQ.md: perguntas comuns e notas operacionais
• docs/tech-specs/aegis-ssh-mcp-tech-spec.md: detalhes mais aprofundados de implementação
• docs/readme-authoring.md: orientações de autoria de README para este repositório

Capturas de tela

Status do projeto

O Aegis tem uma API em estágio inicial e um runtime operacional.

As capacidades atuais incluem:

• MCP over HTTP/SSE
• MCP over stdio
• configuração multi-host
• validação de comandos baseada em regras
• registro de auditoria
• autenticação por chave SSH
• autenticação por senha
• fixação de impressão digital do host
• execução SSH efêmera por solicitação
• runtime de container distroless sem shell e endurecido
• redação opcional de saída
• recarga dinâmica para alterações de configuração e regras

Suporte e contribuições

Para bugs, dúvidas de configuração ou feedback operacional, abra uma issue neste repositório.

Mantenedor principal: @sparksbenjamin

Contribuições são bem-vindas, especialmente em relação a:

• interoperabilidade de clientes MCP
• melhorias na validação de regras
• observabilidade
• endurecimento de implantação
• suporte a transporte
• testes e validação

Até que um guia dedicado de contribuição seja publicado, abrir uma issue antes de uma mudança grande é a melhor forma de alinhar a direção.

Licença

Licença MIT