<div align="center"> # AEGIS ### The firewall for AI agents. **Every tool call. Intercepted. Classified. Blocked — before it executes.** <br> [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/agentguard-aegis/) [](https://www.npmjs.com/package/@justinnn/agentguard) [](https://github.com/Justin0504/Aegis/pkgs/container/aegis-gateway) [](https://github.com/Justin0504/Aegis/actions) </div> <br> > Your agent just called `DROP TABLE users` because the prompt said "clean up old records." > > Your agent just exfiltrated 2GB because "the user asked for a report." > > Your agent just ran `rm -rf /` because the model hallucinated a tool name. > > **These are not hypotheticals.** Every agent framework lets AI decide which tools to call, with what arguments, at machine speed. There is no human in the loop. There is no undo button. > > AEGIS is the missing layer: a **pre-execution firewall** that sits between your agent and its tools, classifies every call in real time, enforces policies, blocks violations, and creates a cryptographically signed audit trail — all with **one line of code and zero changes to your agent.** <br> <div align="center"> <img src="docs/images/dashboard-overview.png" alt="AEGIS Compliance Cockpit" width="820"> <br> _{The AEGIS Compliance Cockpit — real-time monitoring across all your agents.} </div> --- ## Demo <div align="center"> **A real Claude-powered research assistant, fully integrated with AEGIS.**<br> Watch it trace tool calls, block SQL injection, detect PII, and pause for human approval — live. <img src="docs/images/readme_demo2.gif" alt="Live agent demo" width="820"> <br> **The Compliance Cockpit: traces, policies, cost tracking, sessions, approvals.** <img src="docs/images/readme_demo1.gif" alt="Dashboard walkthrough" width="820"> </div> --- ## Quick Start **3 commands. 30 seconds. Full protection.** ```bash git clone https://github.com/Justin0504/Aegis cd Aegis docker compose up -d ``` | Service | URL | What it does | |---------|-----|--------------| | **Compliance Cockpit** | [localhost:3000](http://localhost:3000) | Dashboard — traces, policies, approvals, costs | | **Gateway API** | [localhost:8080](http://localhost:8080) | Policy engine — classifies, checks, blocks | Then add **one line** to your agent: ```python import agentguard agentguard.auto("http://localhost:8080", agent_id="my-agent") # Your existing code — completely unchanged import anthropic client = anthropic.Anthropic() response = client.messages.create(model="claude-sonnet-4-20250514", tools=[...], messages=[...]) ``` Or **zero lines** — just set an environment variable: ```bash AGENTGUARD_URL=http://localhost:8080 python your_agent.py ``` That's it. Every tool call is now classified, policy-checked, and cryptographically signed — **before** execution. --- ## Why AEGIS? Every agent observability tool (LangFuse, Helicone, Arize) tells you **what happened**. AEGIS **prevents it from happening.** | | LangFuse | Helicone | Arize | **AEGIS** | |--|----------|----------|-------|-----------| | Observability dashboard | ✅ | ✅ | ✅ | ✅ | | **Pre-execution blocking** | ❌ | ❌ | ❌ | ✅ | | **Human-in-the-loop approvals** | ❌ | ❌ | ❌ | ✅ | | **Zero-config tool classification** | ❌ | ❌ | ❌ | ✅ | | **Cryptographic audit trail** | ❌ | ❌ | ❌ | ✅ | | **Kill switch** | ❌ | ❌ | ❌ | ✅ | | **Natural language policy editor** | ❌ | ❌ | ❌ | ✅ | | **MCP server for Claude Desktop** | ❌ | ❌ | ❌ | ✅ | | **Slack / PagerDuty alerts** | ❌ | ❌ | ❌ | ✅ | | Self-hostable, MIT-licensed | ✅ | ❌ | ❌ | ✅ | --- ## How it works ``` Your agent calls a tool │ ▼ SDK intercepts at the LLM response level ┌────────────────────────────────────────────────┐ │ AEGIS Gateway │ │ │ │ ① Classify (SQL? file? network? shell?) │ │ ② Evaluate (injection? exfil? traversal?) │ │ ③ Decide allow / block / pending │ └──────────┬─────────────────────────────────────┘ │ ┌──────┴──────────────┐ │ │ allow pending ──► Human reviews in Cockpit │ │ │ ▼ └──── allow ────┘ Tool executes │ │ block ▼ │ Ed25519 signed ▼ SHA-256 hash-chained AgentGuardBlockedError Stored in Cockpit (agent gets the reason) ``` **Zero-config classification** — works on any tool name, any argument shape: | Your tool call | AEGIS detects | How | |----------------|---------------|-----| | `run_query(sql="SELECT...")` | `database` | SQL keyword in args | | `my_tool(path="/etc/passwd")` | `file` | Sensitive path pattern | | `do_thing(url="http://...")` | `network` | URL in args | | `helper(cmd="rm -rf /")` | `shell` | Command injection signal | | `custom_fn(prompt="ignore previous...")` | `prompt-injection` | Known attack pattern | --- ## Key Features ### Pre-Execution Blocking AEGIS doesn't just log — it **stops dangerous tool calls before they execute**. ```python agentguard.auto( "http://localhost:8080", blocking_mode=True, # pause HIGH/CRITICAL calls for human review human_approval_timeout_s=300, # auto-block after 5 min with no decision ) ``` <table> <tr> <td width="50%"> **SQL injection — blocked instantly** <img src="docs/images/block.png" alt="Blocked SQL injection" width="100%"> </td> <td width="50%"> **High-risk action — awaiting human approval** <img src="docs/images/pending.png" alt="Pending approval" width="100%"> </td> </tr> </table> The agent pauses. You open the Cockpit, inspect the exact arguments, and click **Allow** or **Block**. The agent resumes in under a second. ```python from agentguard import AgentGuardBlockedError try: response = client.messages.create(...) except AgentGuardBlockedError as e: print(f"Blocked: {e.tool_name} — {e.reason} ({e.risk_level})") ``` ### Policy Engine Five policies ship by default. Create more in plain English — the AI assistant generates the JSON schema for you. | Policy | Risk | What it catches | |--------|------|-----------------| | SQL Injection Prevention | HIGH | `DROP`, `DELETE`, `TRUNCATE` in database tools | | File Access Control | MEDIUM | Path traversal (`../`), `/etc/`, `/root/` | | Network Access Control | MEDIUM | HTTP (non-HTTPS) requests | | Prompt Injection Detection | CRITICAL | "ignore previous instructions" patterns | | Data Exfiltration Prevention | HIGH | Large payloads to external endpoints | > *"Block all file deletions outside the /tmp directory"* → Describe button → policy created instantly. ### Compliance Cockpit <table> <tr> <td width="50%"> **Forensic trace detail** <img src="docs/images/trace.png" alt="Trace details" width="100%"> </td> <td width="50%"> **Policy management** <img src="docs/images/policies.png" alt="Policies" width="100%"> </td> </tr> <tr> <td width="50%"> **Token cost tracking** <img src="docs/images/cost.png" alt="Cost tracking" width="100%"> </td> <td width="50%"> **Session grouping** <img src="docs/images/session.png" alt="Sessions" width="100%"> </td> </tr> </table> **Everything you need in one dashboard:** - **Live Feed** — every tool call as it happens, with risk badges - **Approvals** — one-click allow/block for pending checks - **Agent Baseline** — 7-day behavioral profile per agent - **Anomaly Detection** — automatic flagging of spikes, error bursts, unusual patterns - **PII Detection** — auto-redacts SSN, email, phone, credit card, API keys - **Cost Tracking** — token usage and USD cost across 40+ models - **Alert Rules** — Slack, PagerDuty, or webhook on violations/cost spikes - **Forensic Export** — PDF compliance reports and CSV audit bundles - **Kill Switch** — auto-revoke agents after N violations ### Cryptographic Audit Trail Every trace is: - **Ed25519 signed** — per-agent keypair, cryptographically verifiable - **SHA-256 hash-chained** — each trace commits to the previous, tamper-evident - **Immutable** — any modification breaks the chain, detectable by any third party This isn't just logging. This is **court-admissible evidence** that your AI agents operated within policy. --- ## SDK Support **9 Python frameworks. JavaScript/TypeScript. Go. All auto-patched, zero code changes.** <table> <tr> <td> **Python** — `pip install agentguard-aegis` | Framework | Status | |-----------|--------| | Anthropic | ✅ auto-patched | | OpenAI | ✅ auto-patched | | LangChain / LangGraph | ✅ auto-patched | | CrewAI | ✅ auto-patched | | Google Gemini | ✅ auto-patched | | AWS Bedrock | ✅ auto-patched | | Mistral | ✅ auto-patched | | LlamaIndex | ✅ auto-patched | | smolagents | ✅ auto-patched | </td> <td> **JavaScript / TypeScript** — `npm install @justinnn/agentguard` ```typescript import agentguard from '@justinnn/agentguard' agentguard.auto('http://localhost:8080', { agentId: 'my-agent', blockingMode: true, }) // Existing code unchanged ``` **Go** — `go get github.com/Justin0504/Aegis/packages/sdk-go` ```go guard := agentguard.Auto() defer guard.Close() result, err := guard.Wrap("query_db", args, func() (any, error) { return db.Query("SELECT ...") }, ) ``` Zero external dependencies. Standard library only. </td> </tr> </table> --- ## Integrations ### Claude Desktop (MCP) Ask Claude about your agents directly: ```json { "mcpServers": { "aegis": { "url": "ws://localhost:8080/mcp-audit" } } } ``` > *"What did agent X do in the last hour?"* → Claude queries AEGIS and tells you. Available tools: `query_traces`, `list_violations`, `get_agent_stats`, `list_policies` ### OpenTelemetry Forward every trace to Datadog, Grafana, Jaeger, or any OTLP-compatible collector: ```bash OTEL_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node dist/server.js ``` Each span carries: `aegis.agent_id`, `aegis.risk_level`, `aegis.blocked`, `aegis.cost_usd`, `aegis.pii_detected` ### Alerting Threshold-based alerts delivered to **Slack**, **PagerDuty**, or custom **webhooks** when violations, cost spikes, or anomalies are detected. --- ## Fine-Tuning Not everything needs to be blocked. Precision controls for production: ```python agentguard.auto( "http://localhost:8080", block_threshold="HIGH", # only block HIGH and CRITICAL (default) allow_tools=["read_file"], # whitelist specific tools allow_categories=["network"], # whitelist entire categories audit_only=True, # log everything, block nothing tool_categories={ # override auto-classification "my_query_runner": "database", "send_email": "communication", }, ) ``` --- ## Architecture ``` packages/ gateway-mcp/ Express + SQLite gateway (policy engine, classifier, PII, cost, OTEL) sdk-python/ Python SDK — 9 frameworks auto-patched sdk-js/ TypeScript SDK — Anthropic, OpenAI, LangChain, Vercel AI sdk-go/ Go SDK — zero dependencies, stdlib only core-schema/ Shared Zod schemas (trace format, risk levels, approval status) cli/ CLI tool — agentguard status|traces|costs|policies|kill-switch apps/ compliance-cockpit/ Next.js dashboard (8 tabs, live feed, approvals, forensic export) demo/ live-agent/ Real Claude-powered demo agent with chat UI (FastAPI) showcase_agent.py Multi-step feature demonstration script ``` **Tech Stack**: Node.js 20, Express, SQLite, Next.js 14, React 18, TailwindCSS, Python 3.10+, Go 1.21+ --- ## Deployment ### Docker Compose (recommended) ```bash docker compose up -d # production docker compose -f docker-compose.dev.yml up # development (hot-reload) ``` ### Manual ```bash # Gateway cd packages/gateway-mcp && npm install && npm run build && node dist/server.js # Cockpit cd apps/compliance-cockpit && npm install && npm run build && npm start # Agent pip install agentguard-aegis ``` ### Cloud Pre-configured for **Render** (`render.yaml`), **Railway** (`railway.json`), and **Kubernetes** (`kubernetes/`). ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `GATEWAY_PORT` | `8080` | Gateway listen port | | `DB_PATH` | `./agentguard.db` | SQLite database path | | `OTEL_ENABLED` | `false` | Enable OpenTelemetry export | | `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:8080` | Cockpit → Gateway URL | --- ## Try the Demo Agent A real Claude-powered research assistant with its own chat UI, fully integrated with AEGIS: ```bash # Prerequisites: gateway on :8080, cockpit on :3000 cd demo/live-agent pip install -r requirements.txt export ANTHROPIC_API_KEY=sk-ant-... python app.py ``` Open [localhost:8501](http://localhost:8501) and follow the guided prompts: 1. **Search for AI trends** → traces appear in Live Feed, cost tracked 2. **Read Q1 revenue data** → file access tracing, session grouping 3. **Query top customers** → safe SQL execution (ALLOW) 4. **SQL injection attempt** → blocked instantly (BLOCK) 5. **Analyze text with SSN** → PII auto-detected and flagged 6. **Send a report** → blocking mode, requires human approval in Cockpit --- ## Contributing Issues and PRs welcome. Development setup: ```bash git clone https://github.com/Justin0504/Aegis && cd Aegis docker compose -f docker-compose.dev.yml up # hot-reload enabled ``` --- <div align="center"> **MIT Licensed** · No telemetry · No data leaves your infrastructure · Self-hosted Built by [Justin](https://github.com/Justin0504) </div>