Aegis 🛡️

A Blast-Radius Auditor for AI Agents Track 03: Enterprise AI & Workplace Automation — NitroStack Hackathon

Aegis is a Model Context Protocol (MCP) server built on NitroStack that audits the combined effective permissions of an AI agent across all connected tools. It deterministically detects toxic capability combinations and data-exfiltration vectors before deployment — at zero LLM token cost.

🔴 Live server: https://aegis-6a6d76ee-teamx-srmist.app.nitrocloud.ai/mcp — connect it to Claude, ChatGPT, or NitroStack Studio and try the walkthrough below for real.

📋 Table of Contents

• The Problem

• See It Work

• System Architecture

• Detection & Remediation Lifecycle

• Tool & Capability Registry

• Toxic-Combination Policy Rules

• MCP Interface Reference

• Try It Yourself

• Quickstart

• FAQ

• Project Structure

Related MCP server: AgentWard

🏆 The Problem

Enterprises connect AI agents to dozens of tools — Gmail, Dropbox, Postgres databases, Slack, filesystem execution. Each integration gets approved individually on its own merits, but nobody audits what the agent can do when tools are combined.

  ┌────────────────┐        ┌────────────────┐
  │  Dropbox MCP   │        │   Gmail MCP    │
  │ (Read Private) │        │ (Send External)│
  └───────┬────────┘        └───────┬────────┘
          │                         │
          └───────────┬─────────────┘
                       ▼
         ┌─────────────────────────┐
         │      Support Agent      │
         └────────────┬────────────┘
                       ▼
   🚨 TOXIC COMBINATION: DATA EXFILTRATION PATH

This isn't hypothetical — it's how the Supabase MCP leak happened (an agent with legitimate database read access was steered via prompt injection into exfiltrating private records through an external channel), how the postmark-mcp supply-chain compromise turned an ordinary "send email" tool into a covert BCC-to-attacker exfiltration path, and the exact mechanism behind documented tool-poisoning attacks, where malicious instructions hidden in a tool's own description hijack agent behavior without ever calling an obviously malicious endpoint. Individually-reasonable permissions become dangerous the moment they're combined, and nothing in the stack today computes that union before it's exploited.

📸 See It Work

Real, live-rendered screenshots — the actual widgets, fed the actual output of get_capability_graph / detect_attack_paths after connecting gmail + dropbox to one agent.

The graph — dangerous capability paths render in red:

The alert — severity, affected tools, and one-click remediation:

After clicking Fix, apply_policy_fix disconnects every tool supplying the sink capability and the graph goes back to riskScore: 0 — no attack paths, clean state.

📐 System Architecture

flowchart TD
    subgraph Host["Chat Host / Client"]
        Client["User / AI Agent Host\n(NitroStudio, ChatGPT, Claude)"]
    end

    subgraph MCP["Aegis MCP Server (NitroStack)"]
        Tools["Governance Tools Controller\n(connect_tool, get_capability_graph,\ndetect_attack_paths, apply_policy_fix)"]
        Guard["OAuthGuard\n(scaffolded, opt-in via OAUTH_REQUIRED —\nopen by default for the hackathon build)"]
        Resources["Resource Server\n(aegis://policies)"]
        Prompts["Prompt Controller\n(explain_attack_path)"]

        Guard -. wraps connect_tool only .-> Tools
    end

    subgraph Engine["Deterministic Engine — 0 Tokens"]
        Registry["Tool Capability Registry\n(gmail, dropbox, postgres, slack,\nfilesystem, calendar)"]
        Store["Per-Agent Connected-Tool Store\n(in-memory)"]
        Union["Effective Capability Union\n(getEffectiveCapabilities)"]
        Detector["Policy Rule Matcher\n(detectAttackPaths)"]

        Registry --> Store --> Union --> Detector
    end

    subgraph UI["NitroStack Widgets"]
        GraphWidget["capability-graph\n(live risk graph)"]
        AlertWidget["attack-path-alert\n(severity + one-click Fix)"]
    end

    subgraph LLM["Groq Explanation Layer — only LLM spend"]
        Groq["Llama 3.1 8B Instant\ncached by SHA-256(ruleId + sorted(viaTools))"]
    end

    Client -->|STDIO / HTTP JSON-RPC| Tools
    Tools --> Engine
    Detector -->|risk score + danger edges| GraphWidget
    Detector -->|threat path list| AlertWidget
    Prompts -->|only on a detected path, cache miss| Groq
    Groq -->|plain-English finding| Client
    AlertWidget -->|Fix click| Tools

🔄 Detection & Remediation Lifecycle

flowchart LR
    A["1. Connect Gmail"] -->|connect_tool| B["READ_PRIVATE_DATA + SEND_EXTERNAL"]
    B --> C["🟢 SAFE — riskScore 0"]
    C --> D["2. Connect Dropbox"]
    D -->|connect_tool| E["+ WRITE_DATA"]
    E --> F["Detector checks policy table"]
    F -->|source+sink both present| G["🚨 exfiltration DETECTED"]
    G --> H["3. Render widgets"]
    H -->|get_capability_graph| I["Graph edge turns RED — riskScore 1"]
    H -->|explain_attack_path| J["Groq: plain-English summary"]
    I --> K["4. Remediate"]
    K -->|apply_policy_fix| L["Every tool supplying the sink\ncapability is disconnected"]
    L --> M["Status cleared — riskScore 0"]

🛠️ Tool & Capability Registry

🎯 Toxic-Combination Policy Rules

Both tables are just data (TOOL_REGISTRY and POLICY_RULES) — adding a 7th tool or a 4th rule is a one-line change, not new logic.

🔌 MCP Interface Reference

Tools

• connect_tool — connects a tool (gmail, dropbox, postgres, slack, filesystem, calendar) to an agent. Wrapped in OAuthGuard (scaffolded — enforced only if OAUTH_REQUIRED=true is set; open by default for local/demo use).

• get_capability_graph — @Widget('capability-graph'). Returns nodes, danger edges, active attack paths, and risk score.

• detect_attack_paths — @Widget('attack-path-alert'). Runs the deterministic rule engine.

• apply_policy_fix — disconnects every tool supplying a detected rule's sink capability.

Resource

• aegis://policies — the toxic-combination policy table as JSON.

Prompt

• explain_attack_path — takes agentId + ruleId, returns a plain-English explanation via Groq (llama-3.1-8b-instant). Only fires on an already-detected path, cached by SHA-256(ruleId + sorted(viaTools)) — this is the only step in the entire system that spends a token.

MCP surface map

flowchart LR
    Agent(("🛡️ Aegis"))

    Agent --> T1["🔧 connect_tool"]
    Agent --> T2["🔧 get_capability_graph"]
    Agent --> T3["🔧 detect_attack_paths"]
    Agent --> T4["🔧 apply_policy_fix"]
    Agent --> R1["📄 aegis://policies"]
    Agent --> P1["💬 explain_attack_path"]

    T2 -.renders.-> W1["🎨 capability-graph widget"]
    T3 -.renders.-> W2["🎨 attack-path-alert widget"]

▶️ Try It Yourself

Every step below works against the live server — no local setup needed. Connect https://aegis-6a6d76ee-teamx-srmist.app.nitrocloud.ai/mcp to Claude (Settings → Connectors → Add custom connector) or ChatGPT (Developer Mode → Plugins → Add), or point NitroStack Studio at this repo locally, then walk through the same scenario the screenshots above were taken from:

1. Connect a tool. "Connect gmail to demo-agent." → connect_tool fires. One tool, nothing alarming yet.

2. Connect a second tool. "Now connect dropbox to demo-agent." → the agent can now both read private data and send it externally.

3. See the risk. "Show me its capability graph." → get_capability_graph renders — the exfiltration edge is red. This step is pure deterministic rule matching: zero LLM tokens spent to catch it.

4. Get a plain-English explanation. "What does this mean?" → explain_attack_path fires — the only step in the whole system that calls an LLM, and only because a rule already matched.

5. Fix it. "Fix it." → apply_policy_fix disconnects every tool supplying the dangerous capability. The graph goes back to riskScore: 0.

Use any agentId you like — it's just an in-memory key, not a real account.

🚀 Quickstart (run it locally)

git clone https://github.com/prince-rai88/aegis-mcp.git
cd aegis-mcp
npm install
cp .env.example .env   # add GROQ_API_KEY — free at console.groq.com
npm run dev

Verify without any GUI:

bash scripts/test-mcp.sh

Or connect NitroStack Studio → Add Server → Nitro Project → select this folder, then run through the walkthrough above against your local server instead of the live one.

❓ FAQ

Why deterministic rules instead of having the model decide what's risky? Because then the audit trail is "the model thought so." Detection here is a fixed rule table (source capability → sink capability), so every flag is reproducible and explainable without re-running an LLM.

Does this scale beyond 6 tools and 3 rules? TOOL_REGISTRY and the policy rules are both just data — adding a 7th tool or a 4th rule is a one-line addition, not new logic.

What does the LLM actually do, then? Only explain_attack_path, only after a rule has already fired, cached by SHA-256(ruleId + sorted(viaTools)) so the same finding is never re-explained twice.

📁 Project Structure

aegis-mcp/
├── src/
│   ├── app.module.ts                  # NitroStack root module
│   ├── index.ts                       # Server bootstrap
│   ├── modules/governance/            # Security governance engine
│   │   ├── capability.ts              # Capability model + TOOL_REGISTRY
│   │   ├── detector.ts                # 0-token deterministic detector
│   │   ├── policies.ts                # Toxic-combination policy rules
│   │   ├── oauth.guard.ts             # Scaffolded OAuth guard
│   │   ├── governance.tools.ts        # The 4 MCP tools
│   │   ├── governance.resources.ts    # aegis://policies
│   │   ├── governance.prompts.ts      # Groq explanation prompt
│   │   └── governance.module.ts
│   └── widgets/app/
│       ├── capability-graph/          # Capability graph widget
│       └── attack-path-alert/         # Attack path alert widget
├── docs/screenshots/                  # Real rendered widget screenshots
├── scripts/
│   ├── test-mcp.sh                    # Stdio JSON-RPC smoke test
│   └── preview-widgets.html           # Local widget preview, no Studio needed
└── README.md

📜 License

MIT