aegisgate-mcp

Prioridad de configuración

La configuración se resuelve en orden de mayor a menor prioridad:

1. Indicadores CLI — anulan todo
2. Variables de entorno — anulan el archivo de configuración
3. Archivo de configuración JSON (--config) — anula los valores predeterminados integrados
4. Valores predeterminados integrados

Indicadores CLI

Todos los indicadores CLI tienen equivalentes de variables de entorno:

Archivo de Configuración 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 Salud

Cuando --health-addr está configurado, un listener HTTP separado proporciona endpoints de observabilidad:

Roles RBAC

AegisGate MCP aplica una jerarquía de roles de 4 niveles. Los roles están ordenados: restricted < standard < privileged < admin.

La comparación de roles utiliza AgentRole.AtLeast() — un agente privileged puede acceder a cualquier herramienta que requiera standard o restricted, pero no a herramientas que requieran admin.

Motor de Políticas

El Motor de Políticas evalúa reglas de permitir/denegar antes de que se ejecute cualquier herramienta. Las reglas soportan:

• Coincidencia de nombres de herramientas — nombres exactos y patrones comodín
• Condiciones de rol de agente — aplicar reglas solo a roles específicos
• Umbrales de puntuación de riesgo — activar en valores de RiskAbove
• Prioridades — las reglas de mayor prioridad se evalúan primero
• Ventanas de tiempo — restringir herramientas a rangos de tiempo específicos
• Patrones de parámetros — coincidir con parámetros de llamadas a herramientas
• Acciones — permitir, denegar (con motivo), nivel de registro, modificadores de riesgo

Reglas de Política Integradas

Cargadas mediante LoadDefaultPolicies():

Se pueden agregar reglas personalizadas programáticamente:

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álisis de Cadena

El Analizador de Cadenas rastrea secuencias de llamadas a herramientas dentro de una sesión (ventana móvil de 20 llamadas) y marca patrones sospechosos:

Cuando se levanta cualquier flag, el riesgo de la cadena se establece en Alto y el evento se registra en el nivel WARN con el ID de sesión, flags y recuento de llamadas.

AegisGate MCP soporta firma de mensajes ECDSA P-256 para prevenir falsificación y manipulación de solicitudes. Los clientes firman el JSON canónico de cada solicitud (con los campos Signature y KeyID puestos a cero) e incluyen la firma en el encabezado de la solicitud.

Configuración del Servidor

server, _ := mcp.NewSecuredMCPServer(cfg)

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

Firma del Cliente (ejemplo)

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)
}

El servidor verifica la firma usando ecdsa.VerifyASN1 contra la clave pública de confianza. Si no hay KeyID o Signature presente, la verificación se omite — permitiendo interoperabilidad con clientes sin firma mientras se aplican firmas para clientes que las proporcionan.

Cobertura de Pruebas

Ejecución de Pruebas

# 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 Rendimiento

Validadas mediante el conjunto de pruebas de carga (//go:build load):

AegisGate MCP tiene cero dependencias de módulos externos. El archivo go.mod contiene sin directivas require. Todo el código de terceros (enlaces ONNX Runtime, normalización Unicode, modelo ML) está incluido en internal/, lib/ y 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 incluidos (ver NOTICE para atribución completa):

Por qué esto importa:

• Despliegue aislado — no se necesita go mod download, sin riesgo de cadena de suministro
• Sin dependencias transitivas — nada que auditar más allá del código incluido
• Compilaciones reproducibles — el binario es idéntico entre compilaciones
• Superficie de ataque mínima — todo el código de terceros es visible y auditable
• Compilación rápida — sin sobrecarga de resolución de dependencias

Arquitectura

┌─────────────────────────────────────────────────────────────────────────┐
│                          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)              │
└─────────────────────────────────────────────────────────────────────────┘

Flujo de solicitudes:

1. Cliente TCP se conecta (opcionalmente sobre TLS/mTLS) o stdio envía JSON-RPC mediante stdin
2. Middleware de Autenticación valida token bearer/clave API (tiempo constante), verifica firma ECDSA, crea/valida sesión
3. Guardarraíles aplican límites de tasa, límites de sesión y ejecutan análisis de cadena
4. Escaneo de Respuesta (la validación de parámetros previa a la ejecución ocurre en el handler)
5. Manejador de Solicitudes verifica permisos RBAC, evalúa reglas del Motor de Políticas, valida parámetros requeridos contra inputSchema, ejecuta herramienta con tiempo de espera
6. Escaneo de Respuesta (post-ejecución) escanea la salida de la herramienta en busca de PII, secretos, XSS, inyección de prompts; redacta si está habilitado
7. Registro de Auditoría registra la cadena de acciones completa

Soporte de Protocolo MCP

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

Gestión de sesiones HTTP transmisible (v1.2.2+):

• POST /mcp con initialize → la respuesta incluye el encabezado Mcp-Session-Id
• POST /mcp con solicitudes posteriores → debe incluir el encabezado Mcp-Session-Id
• DELETE /mcp con el encabezado Mcp-Session-Id → finaliza la sesión (204 Sin Contenido)
• Las sesiones expiran después de 30 minutos de inactividad

AegisGate MCP sirve en cualquier entorno donde los agentes de IA interactúan con herramientas — desde plataformas SaaS en la nube hasta pipelines de datos empresariales y redes de plantas OT/ICS. Las mismas 21 capas de seguridad se aplican independientemente del contexto de despliegue.

Despliegues Generales

• SaaS en la nube — protege las funciones de IA orientadas al usuario contra inyección de prompts y exfiltración de datos
• Acceso a datos empresariales — aplica RBAC y registro de auditoría en consultas de bases de datos impulsadas por agentes
• Automatización CI/CD — restringe lo que los pipelines asistidos por IA pueden ejecutar
• Redes aisladas — cero dependencias significa que el servidor se ejecuta sin acceso a internet

Entornos OT/ICS

En un entorno OT/ICS, AegisGate MCP se sitúa entre los agentes de IA y las herramientas de infraestructura crítica:

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

Escenarios de despliegue típicos:

• Agente de monitoreo de solo lectura — rol restricted, puede consultar el estado de SCADA y datos del historial pero no puede emitir comandos
• Agente de mantenimiento — rol standard, puede leer archivos y buscar código durante la resolución de problemas
• Agente de operaciones — rol privileged, puede interactuar con la mayoría de las herramientas pero no puede ejecutar comandos de shell
• Agente administrador — rol admin, acceso completo para ventanas de mantenimiento autorizadas

Características de seguridad particularmente relevantes para OT/ICS:

• TLS/mTLS cifra todo el tráfico en la red de la planta
• Políticas de ventana de tiempo restringen herramientas de alto riesgo a ventanas de mantenimiento
• Análisis de cadena detecta si un agente lee datos de procesos sensibles y luego intenta una escritura de red externa (exfiltración)
• Registro de auditoría proporciona una cadena completa de custodia para cumplimiento (NERC CIP, IEC 62443)
• Operación aislada — cero dependencias significa que el servidor puede desplegarse en redes aisladas sin acceso a internet