# AEGIS-AI — Technical Dossier

> Public engineering documentation for the AEGIS-AI autonomous Security Operations Center.
> Claims are falsifiable; each carries its reproduction path.

---

## 1. What it is

AEGIS-AI is a self-operating SOC in Rust: **six LLM-driven agents** that detect, investigate, hunt, deceive, and contain threats end-to-end, governed by a **9-layer fail-closed safety substrate** that lets them act on a live network **without a human in the per-action loop** — and without going off the rails.

The design rule, applied recursively: **agents propose; the substrate decides.**

Built to fight **AI-driven attackers**: the SOC treats its own LLM input as hostile (indirect prompt-injection defense, OWASP LLM01) and binds every autonomous action to a tamper-evident, cryptographically-chained audit trail.

## 2. Measured engineering profile

One workspace, 24 crates, memory-safe Rust throughout:

| crate | LOC | tests | | crate | LOC | tests |
|---|---|---|---|---|---|---|
| **soc-safety** | **3,397** | **40** | | agent-respond | 2,625 | 54 |
| soc-improve | 2,824 | 35 | | agent-orchestrator | 1,906 | 35 |
| soc-llm | 1,948 | 30 | | soc-tools | 1,898 | 35 |
| agent-triage | 1,883 | 37 | | agent-hunt | 1,810 | 30 |
| soc-intel | 1,705 | 42 | | agent-investigate | 1,394 | 23 |
| agent-deception | 1,260 | 34 | | soc-detect | 1,024 | 17 |
| soc-agent | 913 | 16 | | soc-common | 990 | 21 |
| soc-dashboard-ui | 894 | 4 | | event-producer | 745 | 19 |
| soc-memory | 729 | 7 | | soc-anomaly | 614 | 14 |
| soc-config | 660 | 8 | | soc-siem | 494 | 10 |
| soc-bus | 472 | 6 | | soc-metrics | 444 | 5 |
| soc-identity | 359 | 9 | | soc-dfir | 296 | 4 |

**~30.8k LOC · ~490 tests** · edition 2024 · Rust 1.85 · Apache-2.0

Reading the shape: the **largest crate is the safety substrate, and it is well-tested** — investment ordered by consequence, not by feature count. `soc-dfir` is intentionally thin: it is the seam in front of **SLEUTH** (see §8). Coverage roadmap: dashboard UI tests are the next expansion area.

## 3. Architecture

```mermaid
flowchart TB
    T[syslog · Wazuh · network · OT-IoT · CTI] --> B[raw-events bus]
    B --> TR["TRIAGE (L1) — classify sev 1–10 · prompt-injection defense"]
    TR --> IV[INVESTIGATE L2]
    TR --> HU[HUNT L2 proactive]
    TR --> DE[DECEPTION honeypots]
    TR --> RE[RESPOND L3]
    RE --> AG["L5 ActionGuard — 9-layer substrate<br/>breaker → trust-tier → dry-run → board<br/>(3 reviewers · quorum + veto · fail-closed)<br/>→ range check → hash-chained audit"]
    AG --> NFT["actuation — reversible, time-boxed"]
    OR[ORCHESTRATOR — cases + tasking] -.-> TR & IV & HU & DE & RE
```

**Deployment shape:** hybrid. Latency-tolerant triage runs containerized; the actuation-path agents run as systemd-native binaries for fast cold-start and direct host-level enforcement access.
**LLM:** NVIDIA NIM primary → OpenRouter backup, with client-side token-bucket throttle and backoff-retry so the reasoning path stays online under provider rate-limiting.

## 4. The 9-layer ActionGuard substrate

Agents *propose*; the substrate *decides*. Every autonomous action passes:

| # | Layer | Guarantee |
|---|---|---|
| 1 | **Trust tier** | Autonomy is earned; failures demote (ratchet) |
| 2 | **Board review** | 3 independent LLM reviewers — Threat Analyst, Blast-Radius Officer, Business-Continuity Officer — quorum + veto, **fail-closed** |
| 3 | **Decision segregation** | Board is independent of the proposing agent's LLM |
| 4 | **Cost ceiling** | Per-call + daily USD caps; trips to rules when exceeded |
| 5 | **Dry-run gate** | Render the side effect without executing |
| 6 | **Tamper-evident audit** | Keyed-BLAKE3 hash chain; every decision bound to `git · model · config` provenance |
| 7 | **Circuit breaker** | Kill switch degrades the whole SOC to rules-only |
| 8 | **Isolated sandbox** | Staged promotion gate; no live actuation |
| 9 | **Range protection** | Internal/management ranges refused; containment reversible & time-boxed |

## 5. The rule-net override

For a critical event with an actionable external source, if the LLM hedges, the agent escalates to a **rule-based containment proposal** — the safety board decides, not the LLM's caution.

This is visible in the benchmark: 2 of the 8 contained threats (data exfiltration, port scan) were caught by the rule-net override **when the LLM hedged**. Detection recall holds even when the model is degraded or rate-limited — robustness is in the architecture, not in model quality.

## 6. Measured benchmark — 16 MITRE-mapped events

| Metric | Result |
|---|---|
| Detection recall (threats contained) | **100%** (8/8) |
| Precision (containments correct) | **100%** (8/8) |
| False-positive rate (benign blocked) | **0%** (0/8) |
| Mean decision latency | **11.8s** (under live rate-limits) |

Events: ssh/rdp brute force (T1110), c2 beacon (T1071), data exfiltration (T1048), port scan (T1046), web exploit (T1190), malware c2 callback (T1059), crypto mining (T1496) — plus 8 benign look-alikes (normal SSH, sudo, cron, VPN login, package update, single typo, health check, internal file access) that must pass untouched.

## 7. Self-improvement loop

The SOC gets better over time **without escaping the substrate that governs it**:

```
OBSERVE → HYPOTHESIZE → VALIDATE → GATE → PROMOTE → MEASURE → (ROLLBACK)
 audit      typed         L8 sandbox  board  apply +   delta       auto-revert
 outcomes   reversible    + benchmark        ledger                on regression
```

- Improvements are **typed, reversible candidates** (threshold nudges, whitelist entries, detection rules, prompt refinements) with mechanical apply/revert.
- Hard rails: a candidate may **never touch the safety substrate**; it must pass the L8 sandbox + non-regression gate before the Improvement Board (quorum + veto, fail-closed) convenes; promotions are rate-capped and kill-switchable; a post-promotion regression **auto-rolls-back**.
- Every cycle is recorded in a tamper-evident improvement ledger.

## 8. The SLEUTH seam

`soc-dfir` defines an `EvidenceBroker` interface in front of **[SLEUTH](https://wilbtc.github.io/sleuth/demo/)**, the autonomous DFIR app. The broker is the only thing allowed to touch the isolated capture store; every forensic finding it returns carries a **BLAKE3 `Citation`** back to the exact evidence bytes, and `verify_citation` recomputes that hash against the broker's live store — a spoofed or stale finding is **rejected, not trusted**. Verified forensic evidence joins the same hash-chained audit trail as every other SOC action.

## 9. Failure-mode register

| Failure class | The surprise | Structural answer | Residual exposure |
|---|---|---|---|
| **Prompt injection via evidence** | Adversary crafts log lines / PCAP content that hijack the analyzing LLM | Injection fence on ingest; LLM treated as hostile input; detect + escalate | Documented at OWASP-LLM01 level; fence coverage is benchmarked |
| **LLM provider collapse** | Provider outage or hard rate-limiting mid-incident | Token-bucket + backoff-retry; NIM → OpenRouter failover; **rule-net override** contains criticals without the LLM | Latency rises; correctness held by rule-net |
| **LLM hedging on a critical** | Model refuses/waffles on a real attack | Rule-net override → deterministic containment proposal | Recall floor = rule-net's coverage |
| **Audit tampering** | Attacker (or agent) edits history | Keyed-BLAKE3 chain; `verify` walks the chain, exits non-zero on tamper | Assumes key material integrity (OpenBao AppRole + rotation) |
| **Cost runaway** | Agent loops on expensive calls | Per-call + daily USD ceilings; trips to rules when exceeded | Rules-mode is lower-judgment by design |
| **Adversary studies the SOC** | Attacker targets the defender's own automation | Decision segregation (board ≠ proposer), dry-run gate, honeypots as disinformation, deception surfaces | Adversary knowledge of substrate internals is assumed in board review |
| **The SOC harms the network** | Containment blocks something critical | Range protection (internal/management refused), reversible time-boxed actions, dry-run first, 0% FP on the benchmark's benign set | Real-network blast radius is governed by range policy, not model judgment |
| **Improvement turns malignant** | A "better" prompt degrades safety | Candidates can never touch the substrate; L8 sandbox + non-regression gate; board quorum; auto-rollback | Covered by hard rails (unit-tested) |

What the system structurally *refuses to do*: irreversible actions; actuation without a hash-chained decision record; internal/management range containment; promotion of an unvalidated improvement; operation after a breaker trip beyond rules mode. Robustness here is subtractive: each layer exists to make a class of failure *impossible*, not unlikely.

## 10. Falsifiable claims

| Claim | How to reproduce |
|---|---|
| 100% recall / 0% FP on 16 mapped events | Benchmark harness (16 labeled events through the real `agent-respond` path) |
| Rule-net override works under LLM hedging | 2 of 8 benchmark threats contained by override; run with a degraded/rate-limited model |
| Audit chain is tamper-evident | `soc-l5 verify` — full chain walk, non-zero exit on tamper |
| Containment is reversible | Every `block_ip` / `isolate_host` carries a time-box; expiry auto-reverts |
| Self-improvement cannot weaken safety | Candidate→substrate touch is rejected by design; unit-tested rails |

---

<div align="center">

<b>AEGIS-AI</b> — agents detect. The substrate decides.<br>
[Live dashboard](https://wilbtc.github.io/darkcloud-soc/) · [Dark Cloud Corp](https://wilbtc.github.io/darkcloudcorp/) · SDVOSB

</div>