aegisgate-mcp

Prioridade de Configuração

A configuração é resolvida em ordem de maior para menor prioridade:

1. Flags de CLI — substituem tudo
2. Variáveis de ambiente — substituem o arquivo de configuração
3. Arquivo de configuração JSON (--config) — substitui os padrões embutidos
4. Padrões embutidos

Flags de CLI

Todas as flags de CLI têm equivalentes em variáveis de ambiente:

Arquivo de Configuração JSON

{
  "address": ":8081",
  "auth_token": "my-secret-token",
  "audit_log_path": "/var/log/mcp-audit.json",
  "max_sessions": 100,
  "max_connections": 1000,
  "rate_limit_rpm": 120,
  "exec_timeout_seconds": 30,
  "scan_responses": true,
  "block_on_pii": true,
  "block_on_secrets": true,
  "block_on_xss": true,
  "block_on_prompt_inject": true,
  "redact_enabled": true,
  "redact_pii": true,
  "redact_secrets": true,
  "redact_placeholder": "[REDACTED]",
  "tls_enabled": true,
  "tls_cert_file": "/etc/ssl/mcp/server.pem",
  "tls_key_file": "/etc/ssl/mcp/server.key",
  "tls_client_ca_file": "/etc/ssl/mcp/ca.pem",
  "tls_min_version": "1.3",
  "demo_tools": true
}

Modos de Transporte

Endpoints de Saúde

Quando --health-addr está definido, um listener HTTP separado fornece endpoints de observabilidade:

Papéis RBAC

AegisGate MCP impõe uma hierarquia de papéis de 4 níveis. Os papéis são ordenados: restricted < standard < privileged < admin.

A comparação de papéis usa AgentRole.AtLeast() — um agente privileged pode acessar qualquer ferramenta que exija standard ou restricted, mas não ferramentas que exijam admin.

Mecanismo de Políticas

O Mecanismo de Políticas avalia regras de permitir/negar antes de qualquer ferramenta ser executada. As regras suportam:

• Correspondência de nomes de ferramentas — nomes exatos e padrões curinga
• Condições de papel do agente — aplicar regras apenas a papéis específicos
• Limites de pontuação de risco — acionar em valores de RiskAbove
• Prioridades — regras de prioridade mais alta avaliadas primeiro
• Janelas de tempo — restringir ferramentas a intervalos de tempo específicos
• Padrões de parâmetros — corresponder aos parâmetros de chamada de ferramenta
• Ações — permitir, negar (com motivo), nível de log, modificadores de risco

Regras de Política Integradas

Carregadas via LoadDefaultPolicies():

Regras personalizadas podem ser adicionadas programaticamente:

server.AddPolicyRule(mcp.PolicyRule{
    ID:          "block-after-hours",
    Name:        "Block Dangerous Tools After Hours",
    Description: "No high-risk tools outside business hours",
    Condition: mcp.RuleCondition{
        ToolNames: []string{"shell_command", "file_delete"},
        TimeWindow: &mcp.TimeWindow{
            Start: "08:00",
            End:   "18:00",
        },
    },
    Action: mcp.RuleAction{
        Allow:      false,
        DenyReason: "High-risk tools only available during business hours",
        LogLevel:   "warn",
    },
    Priority: 75,
    Enabled:   true,
})

Análise de Cadeia

O Analisador de Cadeia rastreia sequências de chamadas de ferramentas dentro de uma sessão (janela deslizante de 20 chamadas) e sinaliza padrões suspeitos:

Quando qualquer sinalização é levantada, o risco da cadeia é definido como Alto e o evento é registrado no nível WARN com o ID da sessão, sinalizações e contagem de chamadas.

AegisGate MCP suporta assinatura de mensagens ECDSA P-256 para prevenir falsificação e adulteração de requisições. Os clientes assinam o JSON canônico de cada requisição (com os campos Signature e KeyID zerados) e incluem a assinatura no cabeçalho da requisição.

Configuração do Servidor

server, _ := mcp.NewSecuredMCPServer(cfg)

// Register a trusted client public key (SEC1 encoded)
server.AddTrustedKey("agent-001", clientPubKeySEC1)

Assinatura do Cliente (exemplo)

import (
    "crypto/ecdsa"
    "crypto/sha256"
    "crypto/rand"
    "encoding/hex"
)

func signRequest(privKey *ecdsa.PrivateKey, canonicalJSON []byte) string {
    hash := sha256.Sum256(canonicalJSON)
    sig, _ := ecdsa.SignASN1(rand.Reader, privKey, hash[:])
    return hex.EncodeToString(sig)
}

O servidor verifica a assinatura usando ecdsa.VerifyASN1 contra a chave pública confiável. Se nenhum KeyID ou Signature estiver presente, a verificação é ignorada — permitindo interoperabilidade com clientes não assinados enquanto impõe assinaturas para clientes que as fornecem.

Cobertura de Testes

Executando Testes

# Non-CGO test suite (heuristic-only, no ONNX)
CGO_ENABLED=0 go test ./... -count=1 -timeout 120s

# CGO test suite (full ML, requires libonnxruntime.so)
CGO_ENABLED=1 CGO_LDFLAGS="-L$(pwd)/lib/amd64 -lonnxruntime" go test ./... -count=1 -timeout 120s

# With race detector (CGO only — -race requires CGO)
CGO_ENABLED=1 CGO_LDFLAGS="-L$(pwd)/lib/amd64 -lonnxruntime" go test -race -count=1 -timeout 180s ./...

# Load/break/soak tests (behind build tag)
go test -tags=load -count=1 -timeout 120s -v ./...

# Benchmarks (regression tracking)
go test -bench=. -benchmem -benchtime=5s ./...

# Fuzz testing (run for 60 seconds per target)
go test -fuzz=FuzzHandleRequest -fuzztime=60s ./...

Características de Desempenho

Validadas via suíte de testes de carga (//go:build load):

AegisGate MCP tem zero dependências externas de módulos. O arquivo go.mod contém nenhuma diretiva require. Todo o código de terceiros (bindings ONNX Runtime, normalização Unicode, modelo de ML) é fornecido em internal/, lib/ e models/.

module github.com/aegisgatesecurity/aegisgate-mcp

go 1.26.9

// Zero external module dependencies (no `require` directives).
// All third-party code is vendored into internal/ — see NOTICE for details.

Componentes fornecidos (veja NOTICE para atribuição completa):

Por que isso importa:

• Implantação isolada — nenhum go mod download necessário, sem risco de cadeia de suprimentos
• Sem dependências transitivas — nada para auditar além do código fornecido
• Builds reproduzíveis — o binário é idêntico entre builds
• Superfície de ataque mínima — todo o código de terceiros é visível e auditável
• Compilação rápida — sem sobrecarga de resolução de dependências

Arquitetura

┌─────────────────────────────────────────────────────────────────────────┐
│                          AegisGate MCP Server                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  TCP Mode:                                                              │
│  ┌──────────┐    ┌──────────────┐    ┌───────────┐    ┌──────────────┐  │
│  │ TCP      │───▶│ Auth         │───▶│ Guardrails│───▶│ Response     │  │
│  │ Client   │    │ Middleware   │    │ (Rate +   │    │ Scan         │  │
│  │          │    │ (Token +     │    │  Chain)   │    │ (PII/Secrets │  │
│  │ (TLS/    │    │  Signature + │    │           │    │  /XSS/Inject)│  │
│  │  mTLS)   │    │  Session)    │    │           │    │              │  │
│  └──────────┘    └──────────────┘    └───────────┘    └──────┬───────┘  │
│                                                             │          │
│                                                             ▼          │
│  stdio Mode:                                    ┌──────────────────────┐ │
│  ┌──────────┐    (same security chain,          │   Request Handler    │ │
│  │ stdin /  │     stdin/stdout instead          │  ┌────────────────┐  │ │
│  │ stdout   │     of TCP)                      │  │  RBAC Check    │  │ │
│  └──────────┘                                  │  ├────────────────┤  │ │
│                                                 │  │  Policy Engine │  │ │
│                                                 │  ├────────────────┤  │ │
│                                                 │  │  Param Validate│  │ │
│                                                 │  ├────────────────┤  │ │
│                                                 │  │  Tool Registry │  │ │
│                                                 │  │  + Exec Timeout│  │ │
│                                                 │  └────────────────┘  │ │
│                                                 └──────────────────────┘ │
│                                                                         │
│  Health Endpoint (separate HTTP listener):                              │
│  ┌────────────────────────────────────────┐                             │
│  │  GET /healthz  → liveness              │                             │
│  │  GET /readyz   → readiness             │                             │
│  │  GET /stats    → server statistics     │                             │
│  └────────────────────────────────────────┘                             │
│                                                                         │
│  Audit Log: all MCP actions → file + in-memory (queryable)              │
└─────────────────────────────────────────────────────────────────────────┘

Fluxo de requisição:

1. Cliente TCP conecta (opcionalmente via TLS/mTLS) ou stdio envia JSON-RPC via stdin
2. Middleware de Autenticação valida token bearer/chave de API (tempo constante), verifica assinatura ECDSA, cria/valida sessão
3. Guardrails impõem limites de taxa, limites de sessão e executam análise de cadeia
4. Varredura de Resposta (validação de parâmetros pré-execução acontece no handler)
5. Handler de Requisição verifica permissões RBAC, avalia regras do Mecanismo de Políticas, valida parâmetros obrigatórios contra inputSchema, executa ferramenta com tempo limite
6. Varredura de Resposta (pós-execução) varre a saída da ferramenta para PII, segredos, XSS, injeção de prompt; redige se habilitado
7. Log de Auditoria registra a cadeia completa de ações

Suporte ao Protocolo MCP

AegisGate MCP implementa os seguintes métodos JSON-RPC (Protocolo MCP 2025-06-18):

Gerenciamento de sessão HTTP Streamable (v1.2.2+):

• POST /mcp com initialize → a resposta inclui o cabeçalho Mcp-Session-Id
• POST /mcp com solicitações subsequentes → deve incluir o cabeçalho Mcp-Session-Id
• DELETE /mcp com o cabeçalho Mcp-Session-Id → encerra a sessão (204 No Content)
• Sessões expiram após 30 minutos de inatividade

O AegisGate MCP atende qualquer ambiente onde agentes de IA interagem com ferramentas — desde plataformas SaaS em nuvem até pipelines de dados empresariais e redes de plantas OT/ICS. As mesmas 21 camadas de segurança se aplicam independentemente do contexto de implantação.

Implantações Gerais

• SaaS em nuvem — protege recursos de IA voltados ao usuário contra injeção de prompt e exfiltração de dados
• Acesso a dados empresariais — aplica RBAC e auditoria de logs em consultas a bancos de dados conduzidas por agentes
• Automação CI/CD — restringe o que pipelines assistidos por IA podem executar
• Redes isoladas (air-gapped) — zero dependências significa que o servidor funciona sem acesso à internet

Ambientes OT/ICS

Em um ambiente OT/ICS, o AegisGate MCP fica entre agentes de IA e ferramentas de infraestrutura crítica:

AI Agent (Claude, Cursor, custom)
    │
    ▼
┌──────────────────┐
│  AegisGate MCP   │  ← 22 security layers
│  (TLS/mTLS)      │
└────────┬─────────┘
         │
    ┌────┼────┬────┬────┐
    ▼    ▼    ▼    ▼    ▼
  SCADA  PLC  Hist  Tag  Log
  Read  Status Query DB  Analyzer

Cenários típicos de implantação:

• Agente de monitoramento somente leitura — função restricted, pode consultar status SCADA e dados de histórico, mas não pode emitir comandos
• Agente de manutenção — função standard, pode ler arquivos e pesquisar código durante solução de problemas
• Agente de operações — função privileged, pode interagir com a maioria das ferramentas, mas não pode executar comandos de shell
• Agente administrador — função admin, acesso total para janelas de manutenção autorizadas

Recursos de segurança particularmente relevantes para OT/ICS:

• TLS/mTLS criptografa todo o tráfego na rede da planta
• Políticas de janela de tempo restringem ferramentas de alto risco a janelas de manutenção
• Análise de cadeia detecta se um agente lê dados sensíveis de processo e depois tenta uma gravação externa na rede (exfiltração)
• Auditoria de logs fornece uma cadeia completa de custódia para conformidade (NERC CIP, IEC 62443)
• Operação isolada (air-gapped) — zero dependências significa que o servidor pode ser implantado em redes isoladas sem acesso à internet