aegisgate-mcp

Configuration Priority

Configuration is resolved in order of highest to lowest priority:

1. CLI flags — override everything
2. Environment variables — override config file
3. JSON config file (--config) — overrides built-in defaults
4. Built-in defaults

CLI Flags

All CLI flags have environment variable equivalents:

JSON Config File

{
  "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
}

Transport Modes

Health Endpoints

When --health-addr is set, a separate HTTP listener provides observability endpoints:

RBAC Roles

AegisGate MCP enforces a 4-tier role hierarchy. Roles are ordered: restricted < standard < privileged < admin.

Role comparison uses AgentRole.AtLeast() — a privileged agent can access any tool that requires standard or restricted, but not tools that require admin.

Policy Engine

The Policy Engine evaluates allow/deny rules before any tool executes. Rules support:

• Tool name matching — exact names and wildcard patterns
• Agent role conditions — apply rules only to specific roles
• Risk score thresholds — trigger on RiskAbove values
• Priorities — higher-priority rules evaluated first
• Time windows — restrict tools to specific time ranges
• Parameter patterns — match against tool call parameters
• Actions — allow, deny (with reason), log level, risk modifiers

Built-in Policy Rules

Loaded via LoadDefaultPolicies():

Custom rules can be added programmatically:

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

Chain Analysis

The Chain Analyzer tracks sequences of tool calls within a session (rolling window of 20 calls) and flags suspicious patterns:

When any flag is raised, the chain risk is set to High and the event is logged at WARN level with the session ID, flags, and call count.

AegisGate MCP supports ECDSA P-256 message signing to prevent request forgery and tampering. Clients sign the canonical JSON of each request (with Signature and KeyID fields zeroed out) and include the signature in the request header.

Server Setup

server, _ := mcp.NewSecuredMCPServer(cfg)

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

Client Signing (example)

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

The server verifies the signature using ecdsa.VerifyASN1 against the trusted public key. If no KeyID or Signature is present, verification is skipped — allowing interoperability with unsigned clients while enforcing signatures for clients that provide them.

Test Coverage

Running Tests

# 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 ./...

Performance Characteristics

Validated via the load test suite (//go:build load):

AegisGate MCP has zero external module dependencies. The go.mod file contains no require directives. All third-party code (ONNX Runtime bindings, Unicode normalization, ML model) is vendored into internal/, lib/, and 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.

Vendored components (see NOTICE for full attribution):

Why this matters:

• Air-gapped deployment — no go mod download needed, no supply chain risk
• No transitive dependencies — nothing to audit beyond vendored code
• Reproducible builds — the binary is identical across builds
• Minimal attack surface — all third-party code is visible and auditable
• Fast compilation — no dependency resolution overhead

Architecture

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

Request flow:

1. TCP Client connects (optionally over TLS/mTLS) or stdio sends JSON-RPC via stdin
2. Auth Middleware validates bearer token/API key (constant-time), verifies ECDSA signature, creates/validates session
3. Guardrails enforce rate limits, session limits, and run chain analysis
4. Response Scan (pre-execution parameter validation happens in handler)
5. Request Handler checks RBAC permissions, evaluates Policy Engine rules, validates required parameters against inputSchema, executes tool with timeout
6. Response Scan (post-execution) scans tool output for PII, secrets, XSS, prompt injection; redacts if enabled
7. Audit Log records the complete action chain

MCP Protocol Support

AegisGate MCP implements the following JSON-RPC methods (MCP Protocol 2025-06-18):

Streamable HTTP session management (v1.2.2+):

• POST /mcp with initialize → response includes Mcp-Session-Id header
• POST /mcp with subsequent requests → must include Mcp-Session-Id header
• DELETE /mcp with Mcp-Session-Id header → terminates session (204 No Content)
• Sessions expire after 30 minutes of inactivity

AegisGate MCP serves any environment where AI agents interact with tools — from cloud SaaS platforms to enterprise data pipelines to OT/ICS plant networks. The same 21 security layers apply regardless of deployment context.

General Deployments

• Cloud SaaS — protect user-facing AI features from prompt injection and data exfiltration
• Enterprise data access — enforce RBAC and audit logging on agent-driven database queries
• CI/CD automation — restrict what AI-assisted pipelines can execute
• Air-gapped networks — zero dependencies means the server runs with no internet access

OT/ICS Environments

In an OT/ICS environment, AegisGate MCP sits between AI agents and critical infrastructure tools:

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

Typical deployment scenarios:

• Read-only monitoring agent — restricted role, can query SCADA status and historian data but cannot issue commands
• Maintenance agent — standard role, can read files and search code during troubleshooting
• Operations agent — privileged role, can interact with most tools but cannot execute shell commands
• Admin agent — admin role, full access for authorized maintenance windows

Security features particularly relevant to OT/ICS:

• TLS/mTLS encrypts all traffic on the plant network
• Time-window policies restrict high-risk tools to maintenance windows
• Chain analysis detects if an agent reads sensitive process data then attempts an external network write (exfiltration)
• Audit logging provides a complete chain of custody for compliance (NERC CIP, IEC 62443)
• Air-gapped operation — zero dependencies means the server can be deployed on isolated networks with no internet access