Aegis-Chaos: Autonomous Self-Healing SRE Control Plane

Built on the Google Antigravity SDK

📖 Read the Architectural Walkthrough on Blogger: From “Vibe Coding” to Closed-Loop SRE

---

What It Does

Aegis-Chaos is a production-grade, zero-trust autonomous SRE control plane. It detects service anomalies, gates every destructive mutation behind a declarative security fabric, and drives remediation in isolated Git worktrees—without human intervention unless an approval checkpoint is required.

Key Features

• Decoupled Declarative Safety Policies — L1 deny, L2 escrow approval, L6 wildcard allow for diagnostics.
• Parallel Subagent Orchestration — Spawns focused remediation agents in isolated Git worktrees to keep context windows small and token usage low.
• Non-Blocking Checkpoint State Machine — Math-based token budget (C_turn, C_cumulative) with a hard kill-switch to prevent runaway loops.
• At-Most-Once Execution — Firestore delete-first checkpoint semantics guarantee exactly-once resumption even under Cloud Tasks retries.
• End-to-End Visual Verification — Headless Chrome actuation captures design-token screenshots and .webm recordings for every remediation cycle.
• Secure Webhook Ingestion — HMAC-SHA256 signature validation + ±60s replay guard before any task is enqueued.

---

Architecture

flowchart TD
    A[Anomaly Detected] --> B["Webhook HMAC + Timestamp Guard"]
    B --> C["Cloud Tasks Enqueue run-{session_id}"]
    D1["Worker: Firestore delete-first checkpoint"]
    D2["Restore isolated Git worktree"]
    D3["Resume Antigravity agent conversation"]
    C --> D1
    D1 --> D2
    D2 --> D3
    D3 --> G{Policy Layer}
    G -->|L1 deny| H[Block]
    G -->|L2 ask_user| I["CheckpointRequested → Firestore"]
    G -->|L6 allow| J[Execute diagnostic]
    I --> K[Out-of-band approval]
    K -->|approved| D3
    K -->|denied| H
    J --> L["Token Ledger: C_turn, C_cumulative"]
    L -->|budget breached| M["Kill-switch → scale down"]
    L -->|in-budget| D3
    D3 --> N["Browser actuation: verify UI + record WebM"]
    N --> O["Report evidence + leave branch for review"]

Loading

---

Quick Start

# 1. Clone
git clone https://github.com/rabimba/aegis.git
cd aegis

# 2. Virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -e .

# 3. Configure Antigravity CLI
mkdir -p ~/.gemini/antigravity-cli
cp .agents/skills/chaos-heal/scripts/render_title.sh ~/.gemini/antigravity-cli/
cp .agents/skills/chaos-heal/scripts/render_status.sh ~/.gemini/antigravity-cli/
# Edit ~/.gemini/antigravity-cli/settings.json and mcp_config.json per walkthrough.md

# 4. Launch services
uvicorn src.aegis_chaos.webhook_ingest:app --host 0.0.0.0 --port 8000
python tests/mock_services/app.py

# 5. Run tests
pytest -q

# 6. Run visual verification
python .agents/skills/chaos-heal/scripts/verify_ui.py

---

Project Structure

aegis/
├── src/aegis_chaos/
│   ├── policies.py            # Declarative security fabric + CheckpointRequested
│   ├── orchestrator.py        # Token ledger, kill-switch, background ingress monitor
│   ├── webhook_ingest.py      # FastAPI HMAC + replay-guarded ingestion gateway
│   └── worker.py              # Firestore delete-first checkpoint resumption
├── tests/
│   ├── conftest.py            # SDK stubs for offline test execution
│   ├── test_pipeline.py       # 8-case self-healing harness
│   └── mock_services/
│       └── app.py             # Flask latency dashboard (port 8080)
├── .agents/skills/chaos-heal/
│   ├── SKILL.md               # Agent playbook: plan → isolate → validate
│   └── scripts/
│       ├── render_title.sh
│       ├── render_status.sh
│       └── verify_ui.py       # Playwright /browser actuation + WebM recording
├── artifacts/                 # Screenshots + video evidence (gitignored binaries)
├── pyproject.toml
├── walkthrough.md             # Deep-dive for judges / GDE Sprint panel
└── README.md

---

Security Highlights

Threat Vector	Mitigation
Tampered webhook payload	HMAC-SHA256 with hmac.compare_digest
Replay attack	Millisecond timestamp ±60s drift window
Runaway agent loop	Token budget kill-switch (C_cumulative > Θ_budget)
Destructive shell command	L1 explicit deny + L2 escrow checkpoint
Partial failure / retry	Firestore delete() before side effects
Context pollution	Git worktree isolation + scoped subagent contexts

---

Demo Script

See walkthrough.md for the complete judging panel walkthrough, including architecture deep-dives, math derivations, and CLI setup commands.

---

Project Aegis-Chaos — Google Developer Expert Sprint