⚡ AegisMCP — Cloudflare for AI Agents

Zero-trust security gateway for Model Context Protocol (MCP) AI systems.

AegisMCP sits between your AI agents and the world, intercepting every tool call, filesystem access, network request, and shell command — enforcing your security policies in real time, with a tamper-proof cryptographic audit trail and a cinematic SOC dashboard.

What Is AegisMCP?

Modern AI agents are powerful — and dangerous. They can:

• Read your SSH private keys
• Exfiltrate API credentials to external servers
• Execute destructive shell commands (rm -rf /)
• Perform Server-Side Request Forgery (SSRF) against cloud metadata APIs
• Be jailbroken via prompt injection to override their system instructions

AegisMCP is the firewall layer that stops all of this, without changing a single line of your agent code.

Your AI Agent
     │
     ▼  (every tool call intercepted)
┌─────────────────────────────────────┐
│          AegisMCP Gateway           │
│                                     │
│  ┌──────────────┐  ┌─────────────┐  │
│  │ Policy Engine│  │ Threat Score│  │
│  └──────────────┘  └─────────────┘  │
│  ┌──────────────┐  ┌─────────────┐  │
│  │  VFS Sandbox │  │ Audit Ledger│  │
│  └──────────────┘  └─────────────┘  │
└─────────────────────────────────────┘
     │
     ▼  (allowed traffic only)
External Services (OpenAI, GitHub, Stripe…)

Features

| Capability | Description | |---|---| | MCP Proxy | Intercepts all tool calls via a transparent HTTP proxy on port 4000 | | Policy Engine | YAML-driven rules: domain allowlists, path blocks, rate limits, shell guards | | Credential Vault | AES-256 encrypted secret storage — agents never see raw credentials | | Threat Scoring | Every request is scored 0–100; HIGH/CRITICAL threats are auto-blocked | | Prompt Integrity | Detects jailbreaks, context overrides, and credential exfiltration prompts | | Filesystem Sandbox | Agents can only read/write inside the designated workspace root | | Network Egress | Allowlist-only network access; blocks SSRF, metadata endpoints, private IPs | | Shell Guard | Blocks dangerous shell commands (rm -rf, pipe-to-bash, etc.) | | PII Guard | Detects SSNs, credit cards, email addresses in request/response bodies | | Audit Ledger | Tamper-proof SHA-256 hash-chain stored in SQLite — cryptographic integrity | | SOC Dashboard | Real-time Vite/React security operations center at http://localhost:5173 | | Demo Mode | 3-minute cinematic attack simulation for hackathon demos |

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AegisMCP Stack                          │
│                                                                 │
│   ┌───────────┐    ┌───────────┐    ┌──────────────────────┐   │
│   │  AI Agent │───▶│ MCP Server│───▶│   Proxy Server :4000 │   │
│   │ (Claude,  │    │ (stdio)   │    │                      │   │
│   │  GPT-4,…) │    └───────────┘    │ ┌────────────────┐   │   │
│   └───────────┘                     │ │ Policy Engine  │   │   │
│                                     │ ├────────────────┤   │   │
│   ┌───────────────────────────┐     │ │ Threat Scoring │   │   │
│   │      CLI  (aegis *)       │     │ ├────────────────┤   │   │
│   │  init │ start │ verify    │     │ │ VFS Sandbox    │   │   │
│   └───────────────────────────┘     │ ├────────────────┤   │   │
│                                     │ │ Prompt Guard   │   │   │
│   ┌───────────────────────────┐     │ └────────────────┘   │   │
│   │   SOC Dashboard  :5173    │     └──────────┬───────────┘   │
│   │  (Vite + React + Framer)  │                │               │
│   └───────────────────────────┘     ┌──────────▼───────────┐   │
│                                     │   Audit Ledger       │   │
│   ┌───────────────────────────┐     │   (SQLite + SHA-256) │   │
│   │   Credential Vault        │     └──────────────────────┘   │
│   │   (AES-256 encrypted)     │                                 │
│   └───────────────────────────┘                                 │
└─────────────────────────────────────────────────────────────────┘

Component Breakdown

| Component | Path | Purpose | |---|---|---| | src/cli/ | CLI entry | aegis command suite | | src/proxy/ | HTTP proxy | Intercepts all agent tool calls | | src/policy/ | Policy engine | YAML rule evaluation + threat scoring | | src/audit/ | Audit service | SHA-256 hash-chain ledger | | src/vault/ | Credential vault | Encrypted secret storage | | src/mcp/ | MCP server | Tool registration for AI agents | | src/shared/ | Utilities | Logger, errors, helpers | | src/dashboard/ui/ | React SOC dashboard | Real-time security visualization |

Threat Model

Protected Against

| Threat | Vector | AegisMCP Defense | |---|---|---| | Credential Theft | Agent reads .env, ~/.ssh/id_rsa | VFS Sandbox — path isolation | | Prompt Injection | Malicious user input overrides system instructions | Prompt Integrity scanner | | Secret Exfiltration | Agent POSTs API keys to external server | Network Egress allowlist | | SSRF | Agent queries 169.254.169.254 (AWS metadata) | Blocked subnet list | | Dangerous Shell | Agent executes rm -rf / or curl | bash | Shell Guard keyword filter | | SQL Injection | Agent submits malicious DB query | SQL Guard pattern scanner | | PII Leakage | SSN/CC numbers in agent response | PII Guard detector | | Rate Abuse | Agent loops indefinitely consuming API quota | Sliding-window rate limiter | | Unlisted Tool Use | Agent calls unauthorized MCP tool | Tool Allowlist enforcement |

Security Assumptions

1. AegisMCP runs with the same OS privileges as the agent. It is a proxy-layer control, not an OS-kernel sandbox. Pair with OS-level restrictions (Docker, seccomp) for defense-in-depth.
2. The policy file (policy.yaml) is trusted. Keep it in version control and restrict write access.
3. The audit ledger (audit.db) proves tampering detection, not prevention. It cannot stop an attacker with direct SQLite write access — use filesystem ACLs.
4. Cryptographic hashing is SHA-256 (FIPS 180-4). Collision resistance is computationally infeasible under current threat models.
5. The credential vault is in-memory by default. For production, integrate with system keychain or HashiCorp Vault.

Developer Setup Guide

Prerequisites

• Node.js ≥ 20.x
• npm ≥ 10.x
• Git

1. Clone the Repository

git clone https://github.com/your-org/aegismcp.git
cd aegismcp

2. Install Dependencies

# Backend dependencies
npm install

# Dashboard dependencies
cd src/dashboard/ui
npm install
cd ../../..

3. Initialize the Workspace

# Creates .aegis/, policy.yaml, and .env template
npm run aegis -- init

4. Configure Your Environment

# Copy and fill in your values
cp .env.example .env

Edit .env:

PORT=4000
DASHBOARD_PORT=3000
LOG_LEVEL=info
DATABASE_URL=.aegis/audit.db
POLICY_FILE=policy.yaml

5. Add Credentials (Optional)

npm run aegis -- add-secret --key OPENAI_API_KEY --service openai

6. Start the Dashboard

cd src/dashboard/ui
npm run dev
# → http://localhost:5173

7. Start the Security Gateway

# In a new terminal from project root:
npm run aegis:start
# → Proxy on http://localhost:4000

8. Verify Audit Integrity

npm run aegis -- verify-ledger

CLI Reference

aegis init              Initialize a new AegisMCP workspace
aegis add-secret        Securely store a credential in the vault
aegis list-services     List registered proxy services
aegis verify-ledger     Cryptographically verify audit log integrity
aegis start             Start the full AegisMCP security stack

aegis init

Creates the .aegis/ directory, writes a default policy.yaml, creates a .env template, and initializes the SQLite audit ledger.

aegis add-secret --key KEY [--service SERVICE]

Interactively prompts for a secret value and stores it encrypted in the vault. The raw value is never written to disk.

$ aegis add-secret --key OPENAI_API_KEY --service openai
✓ Secret "OPENAI_API_KEY" stored successfully!

aegis list-services

Displays all services registered in the policy allow-list, their endpoints, and how many credentials are associated.

aegis verify-ledger

Walks the entire SHA-256 hash chain in the audit SQLite database and reports whether any event has been tampered with.

$ aegis verify-ledger
✓ Audit ledger integrity: VERIFIED
  Chain status: INTACT
  Tamper-proof: YES — no breaks detected

aegis start

Runs the full 7-step startup sequence:

1. Load configuration
2. Initialize and verify audit database
3. Load and validate security policies
4. Verify audit ledger hash-chain integrity
5. Start MCP proxy server on port 4000
6. Start MCP stdio tool server
7. Dashboard available at http://localhost:5173

Sample Policies

Strict Policy (Production)

allowedDomains:
  - api.openai.com

allowedMethods:
  - POST

blockedPaths:
  - /

rateLimits:
  requestsPerMinute: 10

filesystem:
  sandboxRoot: ./workspace
  denyPatterns: ["**/*"]   # deny everything except sandbox

promptIntegrity:
  enabled: true
  blockJailbreaks: true

Development Policy (Permissive)

allowedDomains:
  - api.openai.com
  - api.anthropic.com
  - api.github.com
  - localhost

allowedMethods:
  - GET
  - POST
  - PUT
  - DELETE

rateLimits:
  requestsPerMinute: 300

promptIntegrity:
  enabled: false

Financial Services Policy

allowedDomains:
  - api.openai.com
  - api.stripe.com
  - api.plaid.com

piiDataGuard:
  enabled: true
  detectPatterns:
    - ssn: '\b\d{3}-\d{2}-\d{4}\b'
    - creditCard: '\b\d{4}[\s-]\d{4}[\s-]\d{4}[\s-]\d{4}\b'
  action: BLOCK_AND_REDACT

rateLimits:
  requestsPerMinute: 30

Demo Scenarios

The SOC dashboard includes a Demo Mode tab with 6 pre-built attack simulations:

| # | Scenario | Attack Type | Risk | Verdict | |---|---|---|---|---| | 1 | Safe Baseline | Normal document query | 8 | ✅ Allowed | | 2 | Credential Theft | .env file access via fs.readFile | 94 | 🚫 Blocked | | 3 | SSH Key Access | ~/.ssh/id_rsa private key read | 98 | 🚫 Blocked | | 4 | Secret Exfiltration | Outbound POST to evil-hacker.com | 89 | 🚫 Blocked | | 5 | Dangerous Shell | rm -rf workspace deletion | 99 | 🚫 Blocked | | 6 | Unauthorized API | SSRF → AWS metadata 169.254.169.254 | 74 | 🚫 Blocked |

Each demo scenario features:

• Typewriter console showing live agent reasoning
• Policy evaluation log printing rule matches in real time
• BLOCKED status with animated red glow on the interceptor panel
• Cross-tab shortcuts to Attack Replay and AI Explainer
• Dashboard sync — risk meter, topology graph, activity feed, and incident card all update live

Project Structure

aegismcp/
├── src/
│   ├── index.ts              # Main entry + 7-step boot sequence
│   ├── cli/
│   │   └── index.ts          # aegis CLI (init, add-secret, list-services, …)
│   ├── proxy/
│   │   ├── index.ts          # Express proxy server
│   │   ├── types.ts
│   │   └── middleware/
│   │       ├── proxy.ts      # Core intercept + policy evaluation
│   │       ├── correlation.ts
│   │       ├── logging.ts
│   │       ├── rateLimiter.ts
│   │       └── security.ts
│   ├── policy/
│   │   ├── engine.ts         # Policy evaluation engine
│   │   ├── types.ts          # Zod schemas
│   │   └── index.ts
│   ├── audit/
│   │   ├── index.ts          # AuditService + hash chain
│   │   ├── database.ts       # SQLite wrapper
│   │   ├── hasher.ts         # SHA-256 event hashing
│   │   ├── types.ts
│   │   └── migrations/
│   │       └── 001-initial-schema.ts
│   ├── vault/
│   │   ├── index.ts          # VaultService (credential store)
│   │   ├── crypto.ts         # AES-256 encryption helpers
│   │   ├── database.ts       # Vault persistence
│   │   └── types.ts
│   ├── mcp/
│   │   ├── server.ts         # MCP tool server
│   │   ├── types.ts
│   │   └── index.ts
│   ├── shared/
│   │   ├── logger.ts
│   │   └── errors.ts
│   └── dashboard/
│       └── ui/               # Vite + React SOC dashboard
│           └── src/
│               ├── App.tsx
│               ├── components/
│               │   ├── DemoMode.tsx       # Cinematic demo engine
│               │   ├── AttackReplay.tsx   # Interactive incident timeline
│               │   ├── AIExplainabilityPanel.tsx
│               │   ├── PolicyPlayground.tsx
│               │   ├── ThreatCenter.tsx
│               │   ├── ActivityFeed.tsx
│               │   ├── LiveEventStream.tsx
│               │   ├── IncidentCard.tsx
│               │   ├── RiskMeter.tsx
│               │   ├── HeroFlowViz.tsx
│               │   └── SecurityBadge.tsx
│               └── data/
│                   └── attackScenarios.ts  # 7 attack scenario definitions
├── policy.yaml               # Security policy configuration
├── package.json
├── tsconfig.json
└── README.md

Security Best Practices

1. Run AegisMCP as an unprivileged user — create a dedicated aegis system account.
2. Mount the filesystem read-only except for the workspace sandbox directory.
3. Set file ACLs on policy.yaml so only the aegis account can read it.
4. Enable audit log forwarding to a SIEM (Splunk, Datadog, etc.) via the webhook integration.
5. Rotate credentials stored in the vault regularly — use aegis add-secret to update them.
6. Use Docker or a VM to isolate the agent process from the host network.
7. Review the audit ledger daily with aegis verify-ledger as part of your SOC routine.

License

ISC — see LICENSE for details.

Built for the AI security era. Cloudflare for AI Agents.