aegis-atv

Aegis ATV — Agent Telemetry Vector

Every Claude Code tool call gets a cryptographic audit line. SHA3-chained, Ed25519-signed, on local disk only. Tamper-evident with one CLI command. Plus a 16-step ATV-2080-v1 firewall that BLOCKs / requires approval / ALLOWs before the tool runs. 0 cloud calls by default, ~5-minute install.

Three release tracks

Aegis ATV ships in three release tracks. Pick the one that matches your environment:

Detailed track docs (Korean): docs/releases/ — 1-page decision matrix + per-track manual.

The npm package is published live as @happyikas/openclaw-plugin-aegis@0.3.0; installs via the default latest dist-tag (no @preview tag needed).

Three named features (work across all tracks)

Aegis is packaged around three named features built on the same firewall + audit chain:

v0.5+ uses operator-vocabulary canonical names (live / coach / guard / memory / doctor / autonomy / knowledge). Older command names (dashboard / burnin / rule / case-memory / advisor-calibration / fleet-monitor) keep working as aliases — see aegis --help for the full index.

Closed loop: raw events → wiki → wiki-grounded advisor (v0.5.18)

Raw ContextMemory (audit chain, append-only)
  ↓ aegis knowledge build
Knowledge wiki (~/.aegis/knowledge/*.json — one article per entity)
  ↓ knowledge_context_for_advisor(aid)  [mtime-cached, hot-path safe]
Markdown block embedded in the sLLM advisor prompt
  ↓ Haiku / sLLM advisor
Wiki-grounded ActionAdvice + TripleAxisAdvice on the firewall hot path

Enable via export AEGIS_ADVISOR_USE_KNOWLEDGE=1. Default off — strictly additive. Run aegis knowledge measure <aid> first to confirm the wiki is rich enough (infobox facts ≥ ~20, cross-refs ≥ 2) before flipping the flag globally. End-to-end demo: uv run python demo/wiki_grounded_advisor.py.

User manuals (Korean is the canonical version): docs/USER_GUIDE.ko.md (비전문가용 통합 가이드) · docs/manuals/ (기능별 깊은 reference)

Why this exists

Claude Code's built-in --allowedTools / --dangerously-skip-permissions are binary toggles with no audit trail. Aegis adds three things they don't:

1. Cryptographic audit chain — every decision is appended to ~/.aegis/audit.jsonl with an Ed25519 signature and SHA3-256 prev/this hash. aegis verify-audit walks the chain in one command — detects edits, deletes, re-orderings.
2. Per-call structured risk scoring — 31 detection rules + 6 incident playbooks running over a 30-subfield ATV-2080-v1 vector representation, with sLLM judge for grey-zone calls (Solo Free: dummy/local; opt-in: Anthropic Haiku).
3. Cost / loop / instruction-drift gates — catches runaway agents, redundant retry loops, and tampered CLAUDE.md / .mcp.json baseline before the tool runs, not after the bill.

For regulated industries (finance, healthcare, government) where AI coding assistants are blocked by audit requirements, the cryptographic decision log turns "we have logs of what the AI did" into "we have signed proof that the AI did exactly this and nothing more."

Side-by-side: Aegis vs Claude Code's built-in flags

The built-in flags solve "is this tool allowed to run?" Aegis solves "what did the agent actually do, can we prove it later, and how do we catch the bad cases the allowlist missed?"

Both are useful — Aegis is layered on top, not a replacement. The two work together: keep --allowedTools for coarse permissions, add Aegis for the cryptographic audit + structured per-call scoring + cost / drift / loop gates that the binary flags can't express.

Verify integrity (the differentiating feature)

Two layers, both runnable any time without network:

# 1) Hash chain — default, no key required.
#    Detects any post-write mutation of ~/.aegis/audit.jsonl.
uv run aegis verify-audit
#   ✓ verify-audit (local chain) — 5,583 records intact
#   signing pubkey: not configured

# 2) Optional Ed25519 signing — opt-in, one-shot setup.
#    Without the private key, the chain cannot be re-computed forward
#    from a tampered point.  Recommended for any audit log you intend
#    to share, archive, or use as compliance evidence.
uv run aegis audit-key init      # generate ~/.aegis/keys/audit.ed25519{,.pub}
uv run aegis verify-audit
#   ✓ verify-audit (local chain) — 6 records intact
#   signing pubkey: loaded — signed records were also Ed25519-verified

# 3) Share the public fingerprint so others can verify without your machine:
uv run aegis audit-key show
#   fingerprint: f2a17931406e4f56
#   pub:         ~/.aegis/keys/audit.ed25519.pub

Real-session output is checked in under docs/launch/dogfooding/ — captured against an actual 5,583-record ~/.aegis/audit.jsonl, not synthetic.

What you get in 5 minutes

Pick whichever fits your setup — all three end at the same place:

# Option A: source clone (full dev environment)
git clone https://github.com/happyikas/Aegis-ATV.git && cd Aegis-ATV
uv sync                              # ~30s
uv run aegis install --mode local    # patches ~/.claude/settings.json

# Option B: one-liner installer (no manual clone)
curl -LsSf https://raw.githubusercontent.com/happyikas/Aegis-ATV/main/scripts/install.sh | bash

# Option C: Homebrew tap (macOS / Linuxbrew)
brew tap happyikas/aegis https://github.com/happyikas/Aegis-ATV.git
brew install happyikas/aegis/aegis
aegis install --mode local

# Then restart Claude Code. Done.

Now every tool call Claude Code makes goes through Aegis first. Try a destructive command in your next session — it gets BLOCKed cryptographically with a signed audit line:

⛔ BLOCK  Bash  trace=ebf0c92d  (165 ms)
   reason: dangerous pattern: <step310 regex>
   advise: [HIGH] security-reviewer — Block until reviewer ACKs

→ 5-minute walkthrough: docs/PERSONAL_QUICKSTART.md.

What gets caught (highlights)

• Filesystem destructive — recursive purge against system paths (/var, /home, /).
• VCS destructive — force-push to main/master/prod/release, force-delete protected branches.
• Cloud destructive — Kubernetes delete, Terraform destroy, Helm uninstall, AWS IAM/EC2/S3 mutation, GCP/Azure resource removal.
• SQL destructive — drop-table on production, unbounded delete (no WHERE).
• Sandbox escape — privileged Docker, capability adds, nsenter, chroot, mount --bind.
• Prompt injection — "ignore previous instructions", [INST] system, MCP-injection patterns.
• Sensitive paths — cloud credentials (~/.aws/credentials), SSH private keys, system password files, .env.
• Loop / runaway cost — same call 3× → REQUIRE_APPROVAL.
• Instruction drift — CLAUDE.md / .mcp.json / plugin manifest tampering.

→ Full catalog: policies/rag_corpus/rules.jsonl (31 rules + 6 incident playbooks).

Solo Free contract — no data leaves your laptop

→ The default install makes 0 outbound network requests. Verify yourself with tcpdump / Little Snitch while Claude Code runs.

After it's installed

uv run aegis report                # 5-line risk summary of recent activity
uv run aegis verify-audit          # cryptographic chain check (detects any tampering)
uv run aegis forensic last         # postmortem timeline of the most-recent session
uv run aegis advise                # live cost / performance / security advice (--profile pro/cloud)
uv run aegis policy diff --since 7d  # what rules / playbooks / baselines changed
uv run aegis pull-model --recommend  # upgrade path to Phi-3.5-mini / Haiku
uv run python -m demo.macmini all  # 100-case self-validation

Modes

uv run aegis install --mode local      # Solo Free in-process hook (no service)
uv run aegis install --mode sidecar    # multi-tenant FastAPI + Postgres + Redis (Enterprise)

Local-mode intelligence tiers (--profile)

# free   (default): dummy embedding + dummy judge, advisor OFF, 0 cloud, 0 model files
uv run aegis install --mode local --profile free

# pro    : bge-local embedding + hybrid (M13+local-phi) judge + advisor ON; 0 cloud,
#          ~700 MB GGUF auto-downloaded on install
uv run aegis install --mode local --profile pro

# cloud  : pro stack + Anthropic Haiku judge for grey-zone calls;
#          requires ANTHROPIC_API_KEY in shell profile
uv run aegis install --mode local --profile cloud

Explicit --judge / --embedding override the profile baseline — useful for pinning a specific tier (e.g., --profile pro --judge dummy keeps the pro embedding + advisor but uses keyword-only judge).

• Safe Auto-Run — known-safe ops (Read/Grep/Glob, ls, pytest, ruff, git status) skip the sLLM judge — <5 ms median.
• 12 / 12 known incident classes block + cloud destructive patterns (kubectl delete / terraform destroy / aws iam / unbounded DELETE) caught at step311.
• Loop & Redundant Call Saver — same call 3× → REQUIRE_APPROVAL; read-only repeats deduped and surfaced in aegis report.
• Poisoned Instruction Detector — CLAUDE.md / AGENTS.md / .mcp.json / plugin & skill manifest hashes baselined; any drift BLOCKs every subsequent PreToolUse until reviewed.
• Local-mode signed audit chain — SHA3-256 prev_hash / this_hash per line; aegis verify-audit catches mutations and re-orderings.

📖 v2.2 사용자 매뉴얼 (한국어) — 설치, CLI 레퍼런스, 시나리오, 트러블슈팅 14개 섹션. 🧪 Mac mini 90-case 검증 매뉴얼 (한국어) — python -m demo.macmini 으로 8 advisor / 11 verb 결정적 검증. 🗺️ ATV-2080-v1 구조 다이어그램 — 30 subfields × 2,080 float32 + 16-step firewall pipeline. 소스: docs/diagrams/draw_atv_2080_v1.py. 🎯 10분 라이브 데모: docs/RUNBOOK.md. 📋 변경 내역: CHANGELOG.md.

---

What's in the box

The hardware band (200-D, indices 1880..2079) is intentionally zero-filled in T2 per patent ¶[0042] — that's the T3 work.

Endpoints

---

Quick start

# 1. Install deps (downloads Python 3.11+ if missing)
uv sync

# 2. Run the test suite (326 tests)
uv run pytest -q

# 3. Lint + typecheck
uv run ruff check . && uv run mypy src

# 4. Boot the service
uv run uvicorn aegis.main:app --reload --port 8000

# 5. In a second shell — run the full demo
uv run python -m demo.agent_demo

The demo runs the original 5-call scenario (ALLOW/BLOCK/APPROVAL mix) followed by three extension scenarios that exercise every M8–M16 endpoint:

=== M14: AID circuit breaker (aid=breaker-demo-…, role=read-only-role) ===
  violation 1/3 -> BLOCK: ... write_file; violations=1/3
  violation 2/3 -> BLOCK: ... write_file; violations=2/3
  violation 3/3 -> BLOCK: ... write_file; violations=3/3
  post-quarantine read_file -> BLOCK: AID … is quarantined — admin release required
  /admin/aid lists 1 quarantined AID(s).
  /admin/aid/release ok -> status=normal
  post-release read_file -> ALLOW: all firewall steps passed

=== M16: Hierarchical Agent Memory (aid=ham-demo-…) ===
  memory  -> object_id=…  seq=1
  memory  -> object_id=…  seq=2
  memory  -> object_id=…  seq=3
  recall(tags=['report']) -> 2 items
  context -> bundle of 3 items
  ground  -> bound=2 missing=1 claim_hash=630b056b3d6defc2…
  forget  -> ok=True
  summarize -> live=2 tag_hist={'calendar': 1, 'report': 1, 'customer': 1}

=== M15: Forensic replay (/forensic/replay) ===
  decrypted     = 10
  tampered      = 0
  aids touched  = 2
  chains valid  = 2/2

Set AEGIS_DEMO_SKIP_EXTRAS=1 to run only the original 5-call scenario.

One-shot helper

./demo/run_scenario.sh

Brings the service up via docker compose if available, otherwise via uv run uvicorn, waits for /healthz, then runs the demo.

Docker

docker compose up --build

The compose file provisions persistent volumes for the audit DB, ATMU intent log, encrypted journal, HAM store, and signing keys (distinct keys for telemetry vs. cost attestation per Claim 34). Verified end-to-end with OrbStack on macOS.

Use as a Claude Code firewall

tools/aegis_hook.py is a PreToolUse hook that fires before every tool call inside Claude Code, asks the running Aegis service for a verdict, and short-circuits the tool with stderr if blocked. See tools/README.md for install + tool mapping.

Compose with an LLM gateway (OpenRouter)

If you route LLM calls through OpenRouter, Aegis composes naturally — they sit at different layers:

• OpenRouter: 300+ models × 60+ providers behind one API. Decides which model handles this prompt.
• Aegis: 16-step firewall + cryptographic audit chain on every tool call. Decides is this resulting action safe?

The aegis.integrations.openrouter Python helper stamps the served-provider name (from OpenRouter's provider_responses[]) into Aegis's provider field — so aegis report --by-provider cross-groups by actual provider (openrouter:anthropic-claude-sonnet-4 vs openrouter:openai-gpt-4o), and the provider-drift advisor can flag "this provider's BLOCK rate diverges 3× from the cross-provider median" — a check that's only meaningful when multiple providers serve the same prompt.

See docs/integrations/openrouter.md for the 3-layer stack figure, code snippets, and honest scope.

---

Documentation

Roadmap

ROADMAP.md tracks what's in flight, what's next, and what's recently shipped — mirrored from the GitHub issues + PRs surface so a public reader has a stable URL to watch.

Getting started

Recording / launch kit

Pricing & business model

Release & distribution

Security

Enterprise sales / design partner

---

Configuration

Copy .env.example to .env and fill in API keys when ready.

The defaults are deliberately offline-friendly:

Storage paths (auto-created on first run):

If you set the provider to openai / haiku but the corresponding key is missing, the code automatically falls back to the dummy implementation so nothing breaks.

---

Web dashboard

Open http://localhost:8000 for the live single-page dashboard. It surfaces every M8–M16 panel:

• Craft a tool call — preset buttons + sliders for prompt_injection, pii_exposure, the 16-slot cost metrics, and a free-form JSON args field
• Action Firewall pipeline — animated row-by-row trace through steps 310 / 315 / 320 / 330 / 335 / 340 / 350 / 360 / 370
• Verdict — decision badge, reason, ATV id, Ed25519 signature
• ATV-2080-v1 bands — color-coded strip with deterministic intensity per band derived from atv_id
• Audit chain — per-AID Merkle chain with prev_hash → this_hash visualization and live chain_valid flag
• Burn-in baseline — per-layer phase + samples + TPR/FPR/precision
• Burn-in attestation — L1–L5 code/config/key hashes + browser-side Ed25519 signature verification
• AID circuit breaker (M14) — live quarantine list, admin release form
• Forensic replay (M15) — decrypted / tampered / aids-seen tiles + per-AID chain head listing
• Hierarchical Agent Memory (M16) — three-column store / recall / summarize+ground+forget interface; checkboxes auto-fill ground refs

/theater shows the ATV vector itself with a band-by-band breakdown.

---

Tests

uv run pytest --cov=aegis

• 326 tests across unit + integration + e2e
• mypy --strict over 61 source files
• ruff clean
• Concurrency: 100-record SQLite audit chain, 200-line JSONL, 100-intent ATMU WAL, and per-AID circuit-breaker counters all pass under thread contention
• No network in tests: respx mocks api.anthropic.com; OpenAI is unused under dummy provider

Per-milestone test files:

tests/unit/
├── test_step310_args.py … test_step370_exec.py        firewall
├── test_step315_aid_auth.py · test_circuit_breaker.py   M14
├── test_atmu_state_machine.py · test_intent_log.py     M10
├── test_burnin_*.py                                     M11
├── test_cost_*.py                                       M12
├── test_judge_haiku.py (attribution head)               M13
├── test_encrypted_journal.py · test_replay.py          M15
└── test_ham.py                                          M16

tests/integration/
├── test_evaluate_e2e.py · test_audit_chain_e2e.py      M1
├── test_tool_outcome_e2e.py                             M10
├── test_burnin_e2e.py                                   M11
├── test_cost_attestation_e2e.py                         M12
├── test_admin_aid_e2e.py                                M14
├── test_replay_e2e.py                                   M15
└── test_ham_e2e.py                                      M16

---

Where to look

src/aegis/
├── schema.py                ATV slice constants + 30-subfield Pydantic models
├── config.py                pydantic-settings (.env loader)
├── main.py                  FastAPI factory + `app`
├── atv/
│   ├── embeddings.py        EmbeddingProvider abstraction
│   └── builder.py           build_atv() — 19 SW encoders + HW zero-fill
├── firewall/
│   ├── core.py              FirewallContext + run_firewall orchestrator
│   ├── circuit_breaker.py   M14 — per-AID violation counter + quarantine
│   ├── step310_args.py      pattern blocklist + injection threshold
│   ├── step315_aid_auth.py  M14 — AID-region authorization
│   ├── step320_blast.py     tool blast-radius lookup
│   ├── step330_human.py     high-blast → REQUIRE_APPROVAL
│   ├── step335_cost.py      M8 — forecast-gating with 16-slot metrics
│   ├── step340_policy.py    policy match + sLLM judge fallback
│   ├── step350_approval.py  M9 — approval dispatch (channels)
│   ├── step360_audit.py     M9 — sign + append + cost_attestation_hint
│   └── step370_exec.py      M9 — exec annotation (PROCEED/SUPPRESS/DEFER)
├── atmu/                    M10 — Agent Telemetry Management Unit
│   ├── state_machine.py     7-state machine + legal transitions
│   ├── intent_log.py        SQLite-backed Write-Ahead Intent Log
│   ├── checkpoint.py        blast≥7 checkpoint manifests
│   └── compensating.py      DEFAULT_COMPENSATION_STRATEGIES
├── burnin/                  M11 — 5-layer × 4-phase
│   ├── phases.py            Phase StrEnum + PhaseMetrics + can_graduate
│   └── controller.py        BurnInController (observe / record_label / try_graduate)
├── cost/                    M12 — Cost Attestation Ledger
│   ├── model_flops.py       FLOPS_PER_TOKEN per model
│   ├── divergence.py        token-to-FLOPs / memory-cost / dollar-cost metrics
│   ├── escalation.py        Claim 27 — independent of sLLM verdict
│   └── ledger.py            separate Ed25519 key + per-aid Merkle chain
├── judge/
│   ├── base.py              Judge ABC + JudgeVerdict (with `subfield_attribution`)
│   ├── haiku.py             M13 — Claude Haiku 4.5 + attribution head
│   └── dummy.py             offline stub
├── sign/
│   ├── ed25519.py           keypair management + sign/verify
│   └── merkle.py            chain hashing + verify_chain
├── audit/
│   ├── sqlite_store.py      indexed records + chain head (transactional)
│   ├── jsonl_store.py       append-only raw record dump
│   ├── encrypted_journal.py M15 — AES-256-GCM with AAD-bound header
│   └── replay.py            M15 — ReplayReport + per-AID chain rebuild
├── ham/                     M16 — Hierarchical Agent Memory L3+L4
│   └── store.py             encrypted SQLite + L1 OrderedDict cache
├── attest/
│   ├── code_attestation.py  L3/L4/L5 hashes signed at startup
│   └── burn_in.py           BurnInMeasurement assembly
└── api/
    ├── evaluate.py          POST /evaluate
    ├── approve.py           POST /approve
    ├── audit_query.py       GET  /audit/{aid}
    ├── attestation.py       GET  /attestation
    ├── tool_outcome.py      POST /tool-outcome (M10)
    ├── burnin_status.py     M11 endpoints
    ├── cost_attestation.py  M12 endpoints
    ├── admin_aid.py         M14 endpoints
    ├── replay.py            M15 endpoint
    ├── ham.py               M16 endpoints
    └── source.py            dashboard source-peek

policies/
├── default.json             deny + allow rules (PLAN 6.9)
└── aid_region.json          M14 — per-AID role policy

demo/
├── agent_demo.py            5-call scenario + M14/M15/M16 extensions
├── tools.py                 Anthropic tool catalog
└── run_scenario.sh          bring service up + run demo

tools/
├── aegis_hook.py            Claude Code PreToolUse hook
├── aegis_safety.py          PRE-LLM safety classifier (regex / OpenAI / Haiku)
└── test_hook.sh             10-case smoke test

---

T3 — patent-future work

The T3 (hardware) tier is fully specified — see PLAN_v3.md for the 10-milestone breakdown (M17–M26) and docs/T3_BOUNDARY.md for the T2 → T3 substitution boundary.

Quick summary of what T3 adds:

The external contract doesn't move. T2 clients talk to T3 servers without code changes — schema, endpoints, and JSON shapes stay identical. The only visible difference is that some response fields stop being zero.

T3 hardware claims (CSD, FPGA, TEE) have schema placeholders already in place — tier_profile, cost_attestation_profile, the 200-D HW band, the hw_cost_attestation subfield range 2044..2059, the linkage_consistency_features 2060..2079. T3 fills these placeholders without breaking the external contract.