• See everything — Traces. Every agent session replays as a stepped waterfall: verdict per tool call, tokens + estimated cost per model call. Live follow, redacted replay, audit PDF.
• Control everything — permissions + JIT. Allow / deny / ask at agent runtime. Blocked tools become just-in-time requests: approve for 15 minutes, an hour, or one session — grants expire on their own.
• Audit the past — Instant Agent Audit. Opt-in scan of session history already on disk: destructive commands, plaintext secrets, estimated spend.
• Catch the threats — 72 rules + Guardian ML. OWASP LLM Top 10 + 28 agent-attack chains, detected while the agent is still running. Offline ML catches what regex misses. Details ↓
• Prove it — every tool call in a SHA-256 hash-chained log; blocked actions get a per-rule evidence ledger.
• Apache 2.0, no signup, 100% local — pip install and you're covered in 60 seconds. Nothing leaves your machine.

Works with every agent

开源与归属：AI Aegis 采用 Apache License 2.0。项目包含经许可演进的 上游代码和模型资产，法定版权、来源与变更说明统一记录在 NOTICE 与 LICENSE 中；产品界面、命令、配置和插件均使用 AI Aegis 标识。

AI Aegis (灵盾) 1.0.0 — AI 智能体的安全与可观测监控平台。

• 威胁检测：72 条规则 + Guardian ML 检测层，覆盖提示注入、数据泄露、越狱攻击等 OWASP LLM Top 10 威胁
• 工具权限治理：Allow / Deny / JIT 授权，为每个工具调用实时裁决
• 全链路审计：每次工具调用的 SHA-256 哈希链日志、事件回放、审计 PDF
• Agent 可观测：Trace 瀑布流、Agent 拓扑地图、成本追踪、规则与权限明细
• 中英文界面：一键切换，满足不同使用者习惯
• 支持 Claude Code / Codex / Copilot CLI / Cursor / OpenClaw 等主流 Agent

本版本基于 Apache-2.0 开源项目二次开发，版本历史见 CHANGELOG。

How It Works

Aegis protects your AI agents at three layers:

• Pre-install — the Skill Scanner checks agent skill packages for shell access, network calls, and hidden risks before you install them.
• Runtime — every tool call lands in a SHA-256 hash-chained audit log; prompts, responses, and natural-language tool inputs are scanned for injection, data leaks, and unauthorized access.
• Observe — the SIEM Forwarder ships threats + audits to your SOC in OCSF 1.3.0 (Splunk, Datadog, Sentinel, Chronicle, QRadar, OTLP, webhook, NDJSON). Metadata-only by default.

100% local — events only leave the machine when you configure a SIEM destination you control.

Quick Start

Step 1 — Install or download

pip install ai-aegis[app]
aegis-app --web

Or download the app: Windows · Linux · DEB · RPM · macOS

Step 2 — Open the app

Open http://localhost:8741 in your browser, or double-click the installed binary.

Step 3 — Connect your agent

Block Mode (only if you want to enforce blocking) — Toggle Block Mode on the dashboard. The proxy starts automatically and blocks threats before they reach the LLM. Adds ~10–50ms latency per request. Applies to both plugin and proxy integrations.

If the app fails to launch because ports 8741/8742 are already in use, use --port <port> of your choice — the proxy starts automatically on port+1. See Configuration for proxy or web/api port settings.

Open-source. 100% local by default. No API keys required.

Screenshots

All screenshots are from a local app instance.

🗺️ Agent Map & Traces

Agent Map — your whole fleet at a glance: device → harness → agent → tool, across tree / radial / mesh / Sankey views. Blocked calls pop red, secret-touching agents wear a lock. Click any node to drill into its trace.

Traces — a turn-by-turn waterfall of every tool call with its allow / block verdict, risk, and reason. Here a prompt-injection and a credential-exfiltration attempt are both caught and blocked.

Tool Call History — 305 calls, 158 blocked: bash rm -rf, gmail_send to attacker, use_aws_cli stopped

Dashboard — threat counts, cost metrics, and tool permission status

LLM Cost Tracker — per-agent spend, budgets, and token breakdown

Skill Scanner — static security analysis for AI agent skills

What You Get

Performance: Rule-based analysis (default) adds ~10–50ms per request. Optional AI analysis adds 1–3s depending on the model and provider — shown on the dashboard so you can measure it against your actual traffic. Tool-permission decisions (allow / block / log_only): see the Tool Permissions guide.

Works With Everything

Your AI Stack — LangChain · LlamaIndex · CrewAI · AutoGen · LangGraph · n8n · Dify · OpenClaw/ClawdBot — or any framework that makes HTTP calls to an LLM provider.

LLM Providers — OpenAI · Anthropic · Ollama · Groq · and any OpenAI-compatible API.

Run Anywhere — macOS / Linux / Windows · Docker & Kubernetes · AWS / GCP / Azure · VMs · Lambda / Workers / Vercel.

Agent Integrations

OpenClaw / ClawdBot

Native plugin with ZERO latency — runs inside the agent, no proxy needed. Install from the Integrations tab or curl -X POST http://localhost:8741/api/hooks/install. Enable block mode from the dashboard when you want to actively stop threats via proxy.

Full setup guide

Claude Code

First-class plugin for Anthropic's Claude Code CLI — PreToolUse enforces tool-permission rules (allow / deny / ask, cloud-syncable), PostToolUse writes a tamper-evident audit row + scans prose tool inputs, UserPromptSubmit catches direct prompt-injection. Optional one-line statusline emitter surfaces live findings next to model / cwd / git state. Loopback-only, fail-open.

Install — two options:

# Option A: via the app UI
# Open http://127.0.0.1:8741 → Integrations → Claude Code → Install Plugin

# Option B: via CLI
aegis-app --install-plugin claude-code
# Uninstall: aegis-app --uninstall-plugin claude-code

# Then, in your Claude Code session:
/reload-plugins

Full setup guide

What It Detects

Full coverage: OWASP LLM Top 10

AI Agent Attack Protection (28 new rules · 72 total)

Built from real attack chains observed against production agent frameworks:

• Tool Result Injection — injected instructions hidden inside MCP tool responses
• Multi-Agent Authority Spoofing — impersonating trusted agents in multi-agent pipelines
• Permission Scope Escalation — agents requesting more permissions than granted
• MCP Tool Call Injection — malicious payloads delivered through MCP tool calls
• Evasion techniques (22 rules) — zero-width characters, encoding tricks, roleplay framing, leetspeak, semantic inversion, emotional manipulation, and more

Optional ML Detection Layer — Aegis Guardian

Alongside the 72 regex rules, the app ships Aegis Guardian, a bundled stdlib-only semantic threat classifier. It runs in parallel with the rule engine and catches obfuscated, paraphrased, buried, or encoded attacks that literal patterns miss. The model is fully local and runs offline — no cloud round-trip and no prompt text leaves your machine.

Install — comes with the app. The inference code and verified model asset are included in the AI Aegis wheel, so a fresh install is immediately offline-capable. Updating ai-aegis updates the model with the application. Air-gapped deployments may override the asset path with AEGIS_GUARDIAN_RUNTIME.

On by default. Toggle it from Settings → Guardian ML Detection (default ON), or force it off globally with the AEGIS_ML_ENABLED=false environment flag. With Guardian disabled the regex rules keep running unchanged, and the layer is fail-open — any model error silently falls back to rules-only so it never breaks the analyze path.

What to expect when it's on. The model is pure Python (zero runtime ML dependencies, no GPU, no network). It analyzes in parallel with regex rules; long documents are windowed with bounded work. The loaded bundle version and availability are visible under Settings → Guardian ML Detection.

Device Identity

Every scan and audit row is stamped with a stable device_id so a customer running Aegis across several laptops or agents can answer "which agent blocked this, which laptop is tampered, which machine spent what?" — not just "one of my installs did this".

Why we need it. A solo developer runs one install. A SOC team runs five to fifty. When an audit chain breaks, or a spike of blocked gmail-send calls shows up, the useful first question is which machine. Without a per-device tag, the answer is "some install" — which is useless in a fleet. device_id pins every row to a specific machine so dashboards, alerts, and compliance reviews can slice by device.

How it's generated (src/aegis/app/utils/device_id.py):

1. Read the OS's existing stable machine identifier:
   • macOS → IOPlatformUUID via ioreg
   • Linux → /etc/machine-id (fallback /var/lib/dbus/machine-id)
   • Windows → HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid
2. SHA-256 hash it with a namespace prefix (aegis-device-v1:<raw>) and truncate to 24 hex chars → aegis-a1b2c3d4e5f6...
3. Cache the result in ~/Library/Application Support/ThreatMonitor/.device_id (0o600) so the OS fetch happens once per install.
4. If the OS refuses (rare: locked-down container, unusual Linux image), fall back to a random UUID cached to the same file.

Stability across reinstalls. The OS identifier outlives the app install — so uninstalling and reinstalling Aegis on the same machine gives you the same device_id. Wiping the app data dir AND having no readable OS ID is the only combination that generates a new one. A new physical machine always gets a new ID.

Security / privacy posture — what the customer should know:

In one sentence: device_id is a machine-identifier-per-install, derived locally, hashed before storage, never transmitted except with explicit user opt-in (Cloud Connect or SIEM Forwarder).

SIEM Forwarder

Stream every threat detection and tool-call audit into your own SIEM — Splunk HEC, Datadog, Microsoft Sentinel, Google Chronicle, IBM QRadar, an OpenTelemetry collector, a local NDJSON file, or any HTTPS endpoint that accepts JSON. Your data, your pipes.

Why this is safe to ship with zero monetization:

The allow-list is enforced at enqueue time by _assert_metadata_only(). Even if the forwarder code were tampered with, it can't add the forbidden fields back.

Supported destinations (one code path, OCSF 1.3.0 payload):

Configure in Connect → SIEM Forwarder. Add SIEM destination → pick type → paste URL + token → Test → Save. Tokens are stored 0o600 in the app data dir, never in SQLite.

📊 Starter dashboards included:

Each carries severity counters, events-over-time by severity, actor and MITRE-ish breakdowns, and a recent-high-severity log feed. MIT-licensed, AS-IS. Full install steps + field reference in docs/siem/README.md; trademark + upstream licenses in docs/siem/NOTICE.

Starter templates — import-test in your own stack and adjust queries / facets / sourcetypes before relying on them for production detections.

Reliability:

• Per-destination outbox with at-least-once delivery.
• A failing Datadog destination never blocks a healthy Splunk one.
• Per-destination circuit breaker backs off broken endpoints (1 min → 1 hour cap).
• Rows that fail 10 times are dropped (the health view shows the consecutive-failure count).

SIEM-side integrity verification. Every forwarded tool-call audit row carries its prev_hash and row_hash. Run a nightly search in your SIEM that rebuilds the chain — if a historic row has been tampered with on the local host, the forwarded evidence still tells the true story. That's the actual tamper evidence; the local chain alone is only the low bar.

Skill Scanner

Scan AI agent skills and tool packages before you install them. Aegis performs static analysis across 10 detection categories, assigns a risk score, and optionally runs an AI review to filter false positives.

┌──────────────────────────────────────────────────────────────────────┐
│                        Skill Scanner Flow                           │
│                                                                     │
│   ┌─────────────┐     ┌──────────────────┐     ┌────────────────┐  │
│   │  Skill Dir   │────>│  Static Analysis  │────>│  Risk Scoring  │  │
│   │  or URL      │     │  (10 categories)  │     │  LOW/MED/HIGH  │  │
│   └─────────────┘     └──────────────────┘     └───────┬────────┘  │
│                                                         │           │
│                              ┌───────────────────────── │           │
│                              v                          v           │
│                     ┌─────────────────┐     ┌────────────────────┐  │
│                     │  AI Review      │     │  Policy Engine     │  │
│                     │  (optional LLM) │     │  allow/block rules │  │
│                     │  FP filtering   │     │  trusted publishers│  │
│                     └────────┬────────┘     └─────────┬──────────┘  │
│                              │                        │             │
│                              v                        v             │
│                     ┌──────────────────────────────────────┐        │
│                     │  Verdict: PASS / WARN / BLOCK        │        │
│                     │  + detailed findings per category     │        │
│                     └──────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────────────┘

Detection Categories

AI-Powered Review

Enable AI analysis (OpenAI, Anthropic, Ollama, Azure, or Bedrock) to automatically review findings and filter false positives. The AI examines each finding in context and adjusts the risk level — reducing noise without hiding real threats.

Open Source

Aegis is fully open source. No cloud required. No accounts. No tracking. Run it, fork it, contribute to it.

Built for solo developers and small teams who ship AI agents without a security team or a FinOps budget. If you are building with LangChain, CrewAI, OpenClaw, or any agent framework — and you do not have someone watching your agent traffic and API spend — Aegis is for you.

Install

Option 1: pip

Requires: Python 3.9+ (MCP requires 3.10+)

pip install ai-aegis[app]
aegis-app --web

Option 2: Binary installers

No Python required. Download and run.

All Releases · SHA256 Checksums

Security: Only download installers from this official Gitee repository. Always verify SHA256 checksums before installation. Aegis is not responsible for binaries obtained from third-party sources.

macOS binary note: Only download from this official Gitee repository and verify the SHA256 checksum before installing. (Prefer pip? pip install ai-aegis[app] always works too.)

Other install options

Deploy to your own cloud (self-host)

Run the engine and managed-device control plane in your own server or cloud tenant with the included Docker Compose deployment. It provides real device enrollment, signed policy distribution and application receipts. See Self-hosted Control Plane, then point agents at the engine with AEGIS_ENGINE_ENDPOINT.

Configuration

Aegis writes aegis.yml to your app data directory on first run with sensible defaults.

The config path is printed at startup — ~/.local/share/aegis/threat-monitor/aegis.yml (Linux), ~/Library/Application Support/Aegis/ThreatMonitor/aegis.yml (macOS), %LOCALAPPDATA%/Aegis/ThreatMonitor/aegis.yml (Windows). Key settings (all editable from the dashboard, which writes back to this file):

server:   { host: 127.0.0.1, port: 8741 }        # change port if 8741 is taken
security: { block_mode: false, output_scan: true } # log/warn by default; flip block_mode to hard-stop
budget:   { daily_limit: 5.00, warn: true, block: true }  # USD/day; daily_limit null to disable
tools:    { enforcement: true }                   # apply allow/block tool rules
proxy:    { integration: openclaw, mode: multi-provider, host: 127.0.0.1, port: 8742 }
          # integration: openclaw | langchain | langgraph | crewai | hermes | ollama; port defaults to server.port + 1

MCP Policies — Cloud Sync (optional)

If your org distributes signed MCP tool-policy bundles from Aegis Cloud, enroll the device once and let the local app long-poll for updates.

1. Admin mints a token in the cloud admin UI (Onboarding → Invite users) and shares the install command.

2. User enrolls locally:

aegis-app enroll aet_<token>

The local app POSTs /api/v1/devices/enroll, persists org_id + signing key + auth credentials to ~/Library/Application Support/.credentials (macOS — equivalent path on Linux/Windows), and starts the cloud sync loop on next launch.

3. Set AEGIS_API_KEY for stable sync auth (recommended).

The local app accepts two auth methods on /policy/sync. The API key path is canonical — it eliminates the short-lived-JWT refresh fragility that can leave a device unable to sync if the refresh token goes stale.

export AEGIS_API_KEY=sk-<long-lived-key>

When both are present, the API key wins. device_id rides as X-Aegis-Device-Id on every request regardless of auth method; org_id is resolved server-side from the auth principal.

You can mint API keys in the cloud admin UI under Access Management. Set the env var in your shell profile or systemd service unit so it survives restarts.

4. Cloud Sync starts automatically — no further configuration needed. The local app already defaults to the production cloud endpoints. Override env vars exist for self-hosted / on-prem deployments only.

Synced rules are read-only on the device — authoring lives in the cloud admin. The MCP Policies page (sidebar → Configure → MCP Policies) shows verification status, applied policies + rules, and a Sync Now button for manual refresh.

Pointing Your Agent at the Proxy

For LangChain, CrewAI, Ollama, and other non-OpenClaw frameworks, point your application to Aegis's proxy instead of the provider's API. OpenClaw/ClawdBot users only need this when block mode is enabled.

set OPENAI_BASE_URL=http://localhost:8742/openai/v1
set ANTHROPIC_BASE_URL=http://localhost:8742/anthropic

$env:OPENAI_BASE_URL="http://localhost:8742/openai/v1"
$env:ANTHROPIC_BASE_URL="http://localhost:8742/anthropic"

[Environment]::SetEnvironmentVariable(
  "OPENAI_BASE_URL",
  "http://localhost:8742/openai/v1",
  "User"
)

export OPENAI_BASE_URL=http://localhost:8742/openai/v1
export ANTHROPIC_BASE_URL=http://localhost:8742/anthropic

echo 'export OPENAI_BASE_URL=http://localhost:8742/openai/v1' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL=http://localhost:8742/anthropic' >> ~/.bashrc
source ~/.bashrc

Every request is scanned for prompt injection. Every response is scanned for data leaks. Every dollar is tracked — whether via native plugin (OpenClaw) or proxy (all other frameworks).

Supported providers (13): openai anthropic gemini ollama groq deepseek mistral xai together cohere cerebras moonshot minimax

Update

After updating, restart Aegis.

Documentation

• Installation Guide — Binary installers, pip, service setup
• Use Cases & Examples — LangChain, LangGraph, CrewAI, Hermes, n8n, FastAPI
• MCP Server Guide — Claude Desktop, Cursor integration
• API Reference — REST API endpoints
• Security Policy — Vulnerability disclosure

Contributing

git clone https://gitee.com/wan-xianghao/ai-aegis.git
cd aegis-ai-threat-monitor
pip install -e ".[dev]"
pytest tests/ -v

Contributing Guidelines · Code of Conduct

Cloud (optional, opt-in)

A separate cloud product handles MCP tool-permission policy sync across enrolled devices, per-org audit attribution, and per-device fleet slicing. It also adds AI Agent Governance — your agents' governance posture rolled into a single score across the fleet — plus EU AI Act orientation that maps your action-layer logging and tamper-evident tool-call audit to the relevant obligations; orientation only, not legal advice. Sign in for the fleet-wide view — the local install already gives you the single-device snapshot. Strictly additive — the local install above works standalone without it.

License

Apache License 2.0 — see LICENSE.

The starter SIEM dashboard templates under docs/siem/ (Splunk XML, Sentinel workbook, Datadog + Grafana JSON) are MIT-licensed — see docs/siem/LICENSE and docs/siem/NOTICE for trademark disclaimers.

Aegis is a trademark of Aegis. See NOTICE.