AEGIS

The firewall for AI agents.

Every tool call. Intercepted. Classified. Blocked — before it executes.

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 tamper-evident audit trail with hash chaining and optional signing support — all with one line of code and zero changes to your agent.

_{The AEGIS Compliance Cockpit — real-time monitoring across all your agents.}

---

Demo

A real Claude-powered research assistant, fully integrated with AEGIS.
Watch it trace tool calls, block SQL injection, detect PII, and pause for human approval — live.

The Compliance Cockpit: traces, policies, cost tracking, sessions, approvals.

---

Quick Start

3 commands. 30 seconds. Full protection.

git clone https://github.com/Justin0504/Aegis
cd Aegis
docker compose up -d

Service	URL	What it does
Compliance Cockpit	localhost:3000	Dashboard — traces, policies, approvals, costs
Gateway API	localhost:8080	Policy engine — classifies, checks, blocks

Then add one line to your agent:

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=[...])

For supported Python integrations, importing agentguard once is enough to enable auto-instrumentation:

python -c "import agentguard; agentguard.auto('http://localhost:8080', agent_id='my-agent')"

That's it. Every tool call is now classified, policy-checked, and recorded in a tamper-evident audit trail 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
      ▼                                │
  Optional signing                    ▼
  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.

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
)

SQL injection — blocked instantly

High-risk action — awaiting human approval

The agent pauses. You open the Cockpit, inspect the exact arguments, and click Allow or Block. The agent resumes in under a second.

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

Forensic trace detail	Policy management
Token cost tracking	Session grouping

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:

• Optional Ed25519 signing — available in the Python SDK for cryptographically verifiable traces
• 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. It is a tamper-evident audit record for reviewing how your AI agents operated within policy.

---

SDK Support

9 Python frameworks. JavaScript/TypeScript. Go. All auto-patched, zero code changes.

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

JavaScript / TypeScript — npm install @justinnn/agentguard 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 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.

---

Integrations

Claude Desktop (MCP)

Ask Claude about your agents directly:

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

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:

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)

docker compose up -d                              # production
docker compose -f docker-compose.dev.yml up       # development (hot-reload)

Manual

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

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

git clone https://github.com/Justin0504/Aegis && cd Aegis
docker compose -f docker-compose.dev.yml up    # hot-reload enabled

---

MIT Licensed · Self-hostable · Infrastructure-first · Designed to keep sensitive agent workflows under your control

Built by Justin