AegisGate

AegisGate

> English | [中文](README_zh.md)

Open-source security gateway for LLM API calls — sits between your AI agents/apps and upstream LLM providers, enforcing security policies on both request and response sides.

What is AegisGate?

AegisGate is a self-hosted, pipeline-based security proxy designed to protect LLM API traffic. Point your application's baseUrl at the gateway, and it automatically applies PII redaction, prompt injection detection, dangerous command blocking, and output sanitization before forwarding to the real upstream model.

Key Features

• Prompt Injection Protection — Multi-layer detection: regex patterns, optional semantic review (gray-zone gated: AEGIS_ENABLE_SEMANTIC_MODULE + AEGIS_SEMANTIC_SERVICE_URL + AEGIS_SEMANTIC_GRAY_LOW/HIGH), Unicode/encoding attack detection, typoglycemia defense
• PII / Secret Redaction — 50+ pattern categories covering API keys, tokens, credit cards, SSNs, crypto wallet addresses/seed phrases, medical records, and infrastructure identifiers
• Dangerous Response Sanitization — Automatic obfuscation of high-risk LLM outputs (shell commands, SQL injection payloads, HTTP smuggling) with configurable security levels (low/medium/high)
• OpenAI-Compatible + Anthropic Messages API — Drop-in routes for /v1/chat/completions, /v1/responses, /v1/messages, and the generic proxy; works with OpenAI-compatible providers and Anthropic-compatible Messages upstreams
• Anthropic ↔ OpenAI Protocol Conversion — Token-based compat mode converts Anthropic /v1/messages requests to OpenAI /v1/responses on the fly, enabling Claude Code / Anthropic SDK to talk to OpenAI-compatible upstreams (GPT-5.4, etc.) without code changes
• MCP & Agent SKILL Support — Integrates with Cursor, Claude Code, Codex, Windsurf and other AI coding agents via Model Context Protocol
• Token-Based Routing — Route requests to multiple upstream providers through a single gateway with per-token upstream mapping and whitelist controls
• Web Management Console — Built-in admin UI for configuration, token management, security rules CRUD, key rotation, and real-time request statistics
• Flexible Deployment — Docker Compose one-click deploy, supports SQLite/Redis/PostgreSQL backends, Caddy TLS termination

Use Cases

• Protect sensitive data from leaking to LLM providers (PII, API keys, internal URLs)
• Detect and block prompt injection attacks in real-time across your AI agent fleet
• Centralize security policy instead of implementing protections in every AI application
• Audit LLM interactions with structured logging, risk scoring, and dangerous content tracking
• Secure MCP tool calls — guard against malicious tool invocations and privilege escalation

How It Compares

| Feature | AegisGate | LLM Guard | Rebuff | Prompt Armor | |---------|-----------|-----------|--------|--------------| | Self-hosted gateway proxy | Yes | Library only | API service | API service | | Request + Response filtering | Both sides | Both sides | Request only | Request only | | OpenAI-compatible drop-in | Yes | No | No | No | | Built-in PII redaction | 50+ patterns | Yes | No | No | | Web management UI | Yes | No | No | Dashboard | | MCP / Agent SKILL support | Yes | No | No | No | | Token-based multi-upstream routing | Yes | N/A | N/A | N/A | | No external API dependency | Yes (core filters local; semantic service optional) | Yes | No (OpenAI) | No | | Bilingual (EN/ZH) | Yes | English | English | English |

> Quick start: create cliproxyapi_default and sub2api-deploy_sub2api-network first, then run docker compose up -d --build — gateway runs on port 18080, admin UI login at http://localhost:18080/__ui__/login

Architecture

flowchart LR
    subgraph Clients
        A1[AI Agent / Cursor / Claude Code]
        A2[Web App / API Client]
    end

    subgraph AegisGate["AegisGate Security Gateway"]
        direction TB
        MW[Token Router & Middleware]

        subgraph ReqPipeline["Request Pipeline"]
            R1[PII Redaction50+ patterns]
            R2[Exact-Value RedactionAPI keys, secrets]
            R3[Request Sanitizerinjection & leak detection]
            R4[RAG Poison Guard]
        end

        subgraph RespPipeline["Response Pipeline"]
            S1[Injection Detectorregex patterns]
            S2[Anomaly Detectorencoding & command patterns]
            S3[Privilege Guard]
            S4[Tool Call Guard]
            S5[Restoration &Post-Restore Guard]
            S6[Output Sanitizerblock / sanitize / pass]
        end
        SR[Semantic Review (Gray Zone)optional service call]

        MW --> ReqPipeline
    end

    subgraph Upstream["Upstream LLM Providers"]
        U1[OpenAI / Claude / Gemini]
        U2[Self-hosted LLM]
        U3[Any OpenAI-compatible API]
    end

    A1 & A2 -->|"baseUrl → gateway"| MW
    ReqPipeline -->|filtered request| U1 & U2 & U3
    U1 & U2 & U3 -->|raw response| RespPipeline
    RespPipeline -->|optional gray-zone review| SR
    SR -->|sanitized response| A1 & A2

Frequently Asked Questions

What is AegisGate? AegisGate is an open-source, self-hosted security gateway that sits between your AI applications and LLM API providers. It inspects and filters both requests and responses in real-time, protecting against prompt injection, PII leakage, and dangerous LLM outputs.

How does AegisGate detect prompt injection? AegisGate uses a multi-layer approach: (1) bilingual regex patterns for known injection techniques (direct injection, system prompt exfiltration, typoglycemia obfuscation), (2) an optional semantic-review stage that is gray-zone gated by AEGIS_SEMANTIC_GRAY_LOW/HIGH (enabled by AEGIS_ENABLE_SEMANTIC_MODULE, service-backed via AEGIS_SEMANTIC_SERVICE_URL), and (3) Unicode/encoding attack detection for invisible characters, bidirectional control abuse, and multi-stage encoded payloads.

Does AegisGate work with OpenAI, Claude, and other LLM providers? Yes. AegisGate provides an OpenAI-compatible API (/v1/chat/completions, /v1/responses) and a token-based generic HTTP proxy (/v2/__gw__/t//..., with x-target-url + AEGIS_V2_TARGET_ALLOWLIST). Applications that support a custom baseUrl can use the OpenAI-compatible routes as a drop-in proxy, and HTTP tooling can use the v2 token route when a generic proxy is needed. It has been verified with OpenAI, Claude (via compatible proxies), Gemini, and any OpenAI-compatible API.

What data does AegisGate redact? Over 50 PII pattern categories including: API keys and tokens (OpenAI, AWS, GitHub, Slack), credit card numbers, SSNs, email addresses, phone numbers, crypto wallet addresses and seed phrases, medical record numbers, IP addresses, internal URLs, and infrastructure identifiers. Custom exact-value redaction is also supported for arbitrary secrets.

Can I use AegisGate with AI coding agents like Cursor, Claude Code, or Codex? Yes. AegisGate supports MCP (Model Context Protocol) and Agent SKILL integration. Point your agent's baseUrl to the gateway and it will transparently filter all LLM traffic. See [SKILL.md](SKILL.md) for agent-specific setup instructions.

How does AegisGate handle dangerous LLM responses? Responses are scored by multiple filters (injection detector, anomaly detector, privilege guard, tool call guard). Based on the cumulative risk score and configurable security level (low/medium/high), the gateway either passes the response through, sanitizes dangerous fragments (replacing them with safe markers), or blocks the entire response. Streaming responses are checked incrementally and can be terminated mid-stream.

Does AegisGate require an external AI service for detection? Not for baseline protection. Regex-based detection, redaction, response sanitization, and routing safeguards run locally. The optional semantic-review stage is gray-zone gated (by AEGIS_SEMANTIC_GRAY_LOW/HIGH); when enabled, the gateway queries AEGIS_SEMANTIC_SERVICE_URL only for gray-zone cases. If the URL is empty, those gray-zone cases record semantic_service_unconfigured and continue without semantic escalation. The repository still ships local TF-IDF assets and training scripts for offline experiments (not wired into the default gateway path).

How do I deploy AegisGate? The recommended method is Docker Compose. With the stock docker-compose.yml, create the referenced external networks first (cliproxyapi_default and sub2api-deploy_sub2api-network), then run docker compose up -d --build. The gateway runs on port 18080 with a built-in web management console at /__ui__/login. It supports SQLite (default), Redis, or PostgreSQL as storage backends. For production, place Caddy or nginx in front for TLS termination.

Getting Started

Docker Compose (Recommended)

git clone https://github.com/ax128/AegisGate.git
cd AegisGate
# The stock compose file references these external Docker networks by default.
# Create them first, or override/remove those network attachments for your setup.
docker network create cliproxyapi_default || true
docker network create sub2api-deploy_sub2api-network || true
docker compose up -d --build

Health check: curl http://127.0.0.1:18080/health

Readiness check: curl http://127.0.0.1:18080/ready

Admin UI login: http://localhost:18080/__ui__/login

Notes:

• The stock docker-compose.yml is not a fully standalone "single container only" compose file: it joins external Docker networks for CLIProxyAPI and Sub2API by default.
• The same compose file also sets AEGIS_DOCKER_UPSTREAMS=8317:cli-proxy-api,8080:sub2api,3000:aiclient2api. These startup-injected Docker service mappings take precedence over numeric host-port fallback for the same token.

Local Development (No Docker)

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,semantic]"
uvicorn aegisgate.core.gateway:app --host 127.0.0.1 --port 18080

Upstream Integration

AegisGate is a standalone security proxy layer — it does not manage upstream services. Upstreams run independently per their own documentation; client requests pass through the gateway.

Verified Upstreams

| Upstream | Description | Default Port | |----------|-------------|-------------| | CLIProxyAPI | OAuth multi-account LLM proxy (Claude/Gemini/OpenAI) | 8317 | | Sub2API | AI API subscription platform (Claude/Gemini/Antigravity) | 8080 | | AIClient-2-API | Multi-source AI client proxy (Gemini CLI/Codex/Kiro/Grok) | 3000 | | Any OpenAI-compatible API | — | — |

Scenario 1: Co-located Deployment (gateway and upstream on same server)

AegisGate supports two same-host patterns:

• Host port routing: numeric token routes such as /v1/__gw__/t/8317/... resolve to http://:8317/v1 when AEGIS_ENABLE_LOCAL_PORT_ROUTING=true. The stock Docker compose enables this by default; bare-metal deployments must enable it explicitly.
• Docker service mapping: when AEGIS_DOCKER_UPSTREAMS is set, startup injects token -> service-name mappings such as 8317 -> http://cli-proxy-api:8317/v1. These mappings override numeric host-port fallback for the same token.

Host-port routing shape:

Client → http://:18080/v1/__gw__/t/{port}/... → localhost:{port}/v1/...

| Upstream | Client Base URL | |----------|----------------| | CLIProxyAPI | http://:18080/v1/__gw__/t/8317 | | Sub2API | http://:18080/v1/__gw__/t/8080 | | AIClient-2-API | http://:18080/v1/__gw__/t/3000 |

• Authorization: Bearer is passed through to upstream transparently
• Multiple upstreams can be used simultaneously
• For host-port routing, no token registration is required
• Supports filter mode suffixes: token__redact (redaction only) or token__passthrough (full passthrough)
• token__passthrough still keeps the OpenAI compatibility layer: gateway-only fields are stripped before forwarding, and Chat/Responses parameter compatibility is preserved
• Security default: numeric port tokens (1024–65535, e.g. /v1/__gw__/t/8317/...) are treated as internal-only. For public clients, register a random token (recommended) or enable request HMAC auth; override with AEGIS_ALLOW_PUBLIC_NUMERIC_TOKENS=true.
• Security default: token__passthrough is treated as internal-only because it disables all filters; override with AEGIS_ALLOW_PUBLIC_PASSTHROUGH_MODE=true (dangerous).

Docker-specific notes:

• The stock compose file already injects 8317:cli-proxy-api, 8080:sub2api, and 3000:aiclient2api via AEGIS_DOCKER_UPSTREAMS.
• Those injected mappings only work if the AegisGate container can resolve and reach the upstream service name on a shared Docker network.
• The stock compose file ships external network attachments for CLIProxyAPI and Sub2API only. If you want 3000:aiclient2api to work as a Docker service mapping, add the appropriate network wiring yourself or override/remove that mapping and use host-port routing instead.

Scenario 2: Remote Upstream

For remote upstreams, register a token binding via API:

curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://remote-upstream.example.com/v1","gateway_key":""}'

Use the returned token: http://:18080/v1/__gw__/t/

Scenario 3: Caddy + TLS for Public Access

Client → https://api.example.com/v1/__gw__/t//... → Caddy → AegisGate:18080 → localhost:8317

For public access, prefer a random registered token. Numeric port tokens and __passthrough are blocked for public/non-internal clients by default.

See [Caddyfile.example](Caddyfile.example) for the complete configuration.

Core Capabilities

API Endpoints

• OpenAI-compatible (full security pipeline): POST /v1/chat/completions, POST /v1/responses
• Anthropic Messages: POST /v1/messages — full security pipeline; supports native pass-through to Anthropic-compatible upstreams, or protocol conversion to OpenAI Responses via token compat mode
• v2 Generic HTTP Proxy: ANY /v2/__gw__/t//... — requires x-target-url, and the target host must also be present in AEGIS_V2_TARGET_ALLOWLIST because empty allowlist is fail-closed
• Generic pass-through: POST /v1/{subpath} — forwards any other /v1/ path to upstream; by default it still runs the v1 request/response safety pipeline, and only __passthrough or upstream whitelist bypass skips filtering
• Relay-compatible endpoint: POST /relay/generate — disabled by default; enable with AEGIS_ENABLE_RELAY_ENDPOINT=true. This endpoint maps relay-style payloads to /v1/chat/completions and requires internal x-upstream-base and gateway-key headers

Compatibility notes:

• If a client accidentally sends a Responses-style payload (input) to /v1/chat/completions, AegisGate forwards it upstream as /v1/responses but converts the result back to Chat Completions JSON/SSE for the client.
• If a client accidentally sends a Chat-style payload (messages) to /v1/responses, AegisGate applies the inverse compatibility mapping and returns Responses-shaped output.
• benign or low-risk /v1/chat/completions and /v1/responses outputs should stay in their native client schema. When response-side sanitization is needed, AegisGate keeps operator-visible risk marking in existing aegisgate metadata and audit paths instead of switching to a whole-response fallback envelope.
• For direct /v1/messages, sanitized non-stream JSON responses preserve Anthropic-native type/message/content[] structure and keep risk marks in the existing aegisgate metadata and audit paths instead of returning a sanitized_text wrapper.
• For direct /v1/messages streaming, sanitized responses keep Anthropic-native SSE events, replace only dangero

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ax128
• Source: ax128/AegisGate
• License: MIT
• Homepage: https://github.com/ax128/AegisGate

Install and usage instructions live in the source repository linked above.