AEGIS
📖 Live documentation
🌐 Live: https://gesh75.github.io/aegis/ — an animated single-page guide: architecture diagrams, data flow, tech stack, and quickstart.
🗂️ Part of the gesh75 documentation hub — all my network & AI engineering project docs in one place.
Air-gapped Evidence-Grade Inspection System — preflight network changes against a
digital twin (containerlab live tier / simulator community tier), entirely inside your perimeter. Air-gapped by default:
no cloud backend and no non-loopback model URL unless an operator sets AEGIS_AIRGAP=0.
The open-source evidence and governance layer for network change, including changes
proposed by AI agents.
AEGIS runs a change → twin → validate → evidence loop inside your perimeter, on a
self-hosted LLM. The twin is a real containerlab topology in the live tier; the open
community tier runs a deterministic simulator. Air-gap is the default: the LLM
layer refuses cloud backends and non-loopback model URLs unless an operator explicitly sets
AEGIS_AIRGAP=0.
It emits a bundle an auditor can verify offline with a public key: an Ed25519 seal over
the evidence, the proposing model's identity and the autonomy bound. Promotion is gated by
separation of duties and single-use approvals. A hash-chained ledger records:
- every preflight decision, including guard rejections;
- every approval mint and mint denial;
- every promotion and promotion denial.
Commercial platforms (Forward, IP Fabric, NetBrain) go deeper on network modelling.
Forward Enterprise documents on-prem deployment, and NetPilot says it offers an air-gapped
option (an unverified vendor claim). AEGIS complements them; it does not replace them. See
docs/STRATEGY_2026-10.md §3.
Demo
▶ Watch the 3-minute feature tour (narrated) — every stage
on the live PreFlight UI: intent → digital twin → grounded config → PCI/SOC 2/NIST → sealed evidence →
offline Ed25519 verify → the BLOCKED guardrail → config-import → live mode.
Shorter cuts: 64-second overview (silent, captioned) ·
narrated overview · real-product demo
How it works
intent | paste-config ─▶ guard ─▶ generate (LLM) ─▶ batfish ─▶ spawn twin ─▶ apply+converge
─▶ diff ─▶ compliance ─▶ risk tier ─▶ rollback ─▶ verdict ─▶ evidence bundle
Only generate touches an LLM — and the config-import path skips even that. Every step
after the proposal is deterministic verification (the "guarded agentic" pattern). That is
what makes the evidence auditable: the LLM proposes, the pipeline verifies, a human
authorizes, and the sealed bundle proves nothing left the perimeter.
Why it's different
Vendor facts are as published on 2026-10-23. "?" means not found in the vendor's public
material, which is not proof of absence. Sources are in docs/STRATEGY_2026-10.md §3.8.
| Forward Enterprise + Predict | NetPilot | AEGIS |
|---|
| Twin | mathematical model (Predict GA 2026-09-29) | real NOS containers | containerlab emulation (live tier) / simulator (community) |
| Hosting | Enterprise: on-prem or SaaS (documented); Predict on-prem parity: ? | cloud; on-prem / air-gapped via sales (vendor claim; its pricing page conflicts) | on-prem / air-gapped by default, open source |
| LLM | Forward AI (hosting model: ?) | local LLM on-prem (vendor claim) | self-hosted, loopback-enforced by default (AEGIS_AIRGAP=0 opts out) |
| Reachability / ACL analysis | yes | in-lab | yes, via in-perimeter Batfish intents (reachability, ACL, SRX/PAN-OS zone policy and NAT; before/after differential, docs/INTENTS.md) |
| ITSM / source of truth | ServiceNow, NetBox | ? | ServiceNow CHG attach + hold, NetBox roles + sealed inventory rev, post-change verify (docs/INTEGRATIONS.md; contract-tested, not yet live) |
| Evidence an auditor verifies offline | ? | ? | Ed25519-sealed bundle + aegis.verify |
| Approval: SoD + single-use, bound to config | ? | ? | yes, plus hash-chained ledger |
| Output | reports / API | pre/post diff | sealed, 11-framework evidence + PDF / CAB / AEGIS-shaped OSCAL AR (not schema-validated) |
🏛️ Architecture
Everything runs inside an air-gapped perimeter: the operator submits a change, a
self-hosted Qwen3 LLM proposes config, a throwaway containerlab twin verifies it, and an
auditor consumes the sealed PDF — no actor or line ever reaches outside the wall.
flowchart LR
OP([Operator - change author]):::actor
APP([Approver - grants token]):::actor
AUD([Auditor - examiner]):::actor
subgraph PERIM["Air-gapped perimeter - egress none"]
direction LR
AEGIS{{"AEGIS - preflight and evidence engine"}}:::core
QWEN[/"Self-hosted Qwen3 - only AI dependency"/]:::ai
TWIN[("containerlab twin - multi-vendor routers")]:::twin
DCN["DCN_Network_Tool 5757 - batfish, nornir, pyats"]:::svc
end
PROD[("Production devices - approval-gated push")]:::prod
OP -->|"intent or config"| AEGIS
APP -->|approval token| AEGIS
AEGIS -->|generate_config| QWEN
AEGIS -->|"spawn, apply, converge"| TWIN
AEGIS -.->|live tier| DCN
AEGIS -->|sealed PDF bundle| AUD
AEGIS -.->|gated dry-run connector| PROD
classDef actor fill:#475569,stroke:#94a3b8,color:#fff
classDef core fill:#0d9488,stroke:#5eead4,color:#fff
classDef ai fill:#7c3aed,stroke:#a78bfa,color:#fff
classDef twin fill:#059669,stroke:#34d399,color:#fff
classDef svc fill:#0ea5e9,stroke:#38bdf8,color:#fff
classDef prod fill:#c0392b,stroke:#fb7185,color:#fff
class PERIM core
📐 Full architecture — system context, container/component map, primary sequence, data
flow, the Backend Protocol class map, and the verdict/promotion-gate decision tree — lives in
docs/ARCHITECTURE.md.
Run the demo (community / sim tier — fully offline)
docker compose up # then open http://localhost:8088/preflight
# or, without Docker:
pip install -r requirements.txt
python -m aegis.serve # from the directory ABOVE aegis/
Type a change (or paste a config), Run PreFlight, watch the verdict + evidence
bundle, and download the examiner-ready PDF. The PDF is a rendering of a self-consistent
bundle — before handing it to an examiner, verify the detached Ed25519 receipt
(POST /api/seal/verify) against the pinned key. See docs/EVIDENCE.md.
Live mode (real Qwen3 + containerlab twin) ships in the integrated air-gapped product —
see docs/GO_LIVE.md.
Air-gapped install (zero egress)
docker compose build && docker save aegis:local -o aegis-local.tar # online, once
# carry aegis-local.tar across the air gap on signed media, then:
docker load -i aegis-local.tar
docker compose -f docker-compose.yml -f docker-compose.airgap.yml up # network_mode: none
Test — 15 CI suites + SAST/SCA + container smoke, 0 violations
pip install -r requirements.txt
python -m aegis.tests.stress_test 25000 # pipeline invariants (8 invariants, adversarial)
python -m aegis.tests.contract_test # HttpBackend parsers vs real :5757 shapes
python -m aegis.tests.pdf_test # evidence PDF validity
python -m aegis.tests.promote_test 6000 # Phase 2 approval-gate safety (G1–G5 + HMAC)
python -m aegis.tests.tokens_test # HMAC approval tokens (T1 #9)
python -m aegis.tests.oscal_test # OSCAL AR + CAB export (integrity-gated)
python -m aegis.tests.compliance_test # 11-framework self-tests + schema-valid bundle
python -m aegis.tests.hardening_test # seal-at-gate, SoD, replay, ledger, prod mode, offline verify
# also in CI: seal_test, authority_test, ceiling_test, llm_egress_test, wedge_test
Offline auditor check (no server, public key only):
python -m aegis.verify --bundle run.json --pubkey pubkey.json # integrity + Ed25519 seal
python -m aegis.verify --ledger /var/lib/aegis/ledger.jsonl # hash-chain audit log
Production deployment (fail-closed mode, SSO-less approver identities, ledger, keys):
see SECURITY.md.
| Suite | Scale | In CI |
|---|
| pipeline invariants | 25,000 runs | yes |
| HttpBackend contract | real API shapes (incl. IPv6 BGP + fail-closed generation) | yes |
| evidence PDF | 1,500 bundles | yes |
| promotion gate | 6,000 bundles | yes |
| Flask test-client | 10 tests | yes |
| twin safety + mgmt isolation | 8,000 ops | yes |
| HMAC approval tokens | 17 property checks | yes |
| OSCAL AR + CAB export | integrity-gated JSON | yes |
| compliance frameworks | per-module SELF_TEST (incl. Junos set + {} form) | yes |
| seal / authority / ceiling / LLM egress / wedge | property suites | yes |
| hardening (G0 seal, SoD, replay, ledger + rejections, SIEM anchor, peer-AS policy, CSP, air-gap default, prod mode, CLI) | 73 checks | yes |
| intent engine (spec, differential, fidelity gate, fail-closed) | 51 checks, fixture oracle | yes |
live Batfish intents (real batfish/allinone) | Cisco ACL regression fixture | yes (batfish job) |
| Bandit SAST · pip-audit · container smoke | gate on HIGH / any CVE / non-root | yes |
See docs/DEVELOPER.md. Strategy, competitor analysis and roadmap:
docs/STRATEGY_2026-10.md.
Layout
core/orchestrator/ deterministic pipeline · guards · rollback
core/backends/ pluggable: simulator (CI) | http (live :5757)
core/llm/ single LLM egress · air-gap loopback check · model identity
core/risk/ authority ceiling (AUTO / HITL / HOTL / BLOCK)
core/seal/ detached CROSS-3 receipt (model + ceiling + bundle hash)
core/promote/ approval gate G0–G5 + SoD · HMAC tokens (single-use) · approver registry · connectors
core/runtime.py community vs production (fail-closed) mode
evidence/ bundler · sha256 integrity · OSCAL AR · CAB · 11-framework crosswalk · PDF
evidence/ledger.py append-only hash-chained audit ledger
evidence/secrets.py vendor-aware secret detection + redaction · evidence/junos.py {}→set
core/intents/ Batfish intent checks: reachability / ACL / BGP / refs, before→after
verify.py offline auditor CLI (integrity + seal + ledger)
ui/ self-contained PreFlight dashboard
serve.py standalone community server (sim tier)
docs/ ARCHITECTURE.md · COMPLIANCE.md · DEVELOPER.md · EVIDENCE.md · GO_LIVE.md
Project history & roadmap
Every phase — research → positioning → scaffold → live adapters → twin endpoints → UI →
evidence PDF → config-import → mgmt isolation → packaging → Phase 2 promotion gate — is
logged in docs/PHASES.md. Changelog: CHANGELOG.md.
Developer pitfalls (air-gap URLs, IPv6 BGP parser, DISA peer binding, seal key):
docs/DEVELOPER.md.
Auditor verify runbook (sha256 vs Ed25519): docs/EVIDENCE.md.
License
Apache-2.0 (see LICENSE). The community core is open; live production-push
connectors, RBAC, and hosted multi-tenant compute are the commercial tier.
