# AEGIS — Security Kernel Architecture

- **Document ID:** ARCH-06
- **Phase:** B.1 — Structural Foundations
- **Status:** Draft for review (post independent architecture review)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect
- **Depends on:** ARCH-01 through ARCH-05, CLAUDE.md
- **Consumed by:** ARCH-07 through ARCH-16

---

## 1. Purpose

Specify the Security Kernel: the smallest, most-trusted, most-scrutinized component in AEGIS. The Kernel exists so that every other engine can be simpler and every boundary crossing can be enforced consistently. The design bias is *reduction*: fewer responsibilities, fewer dependencies, fewer lines of code, fewer failure modes.

## 2. What the Kernel Is (and Is Not)

### 2.1 In scope for the Kernel

The Kernel **is**:

1. **The capability broker.** Mints, verifies, delegates, and revokes capability tokens (ARCH-08).
2. **The policy enforcement point (PEP) for cross-engine calls.** Consults the Policy Engine and enforces its decisions at the boundary.
3. **The audit gateway for Layer-A.** Every mediated operation writes a hash-chained audit record via the Kernel's local integrity ring.
4. **The identity verifier.** Enforces mTLS + message-signature verification (ARCH-09) at every crossing.
5. **The boundary quota governor.** Enforces per-caller rate, concurrency, and payload-size budgets on privileged operations.
6. **The break-glass gate.** All break-glass requests flow through the Kernel; consent capture, time-boxing, and audit are non-bypassable.
7. **The trust root of the Kernel-signed intermediate CA** that issues engine identities on attestation.

### 2.2 Explicitly out of scope for the Kernel

The Kernel **is not**:

- **The Policy Engine.** The Kernel *consults* Policy; it does not *evaluate* rules. Policy Engine can be replaced without touching the Kernel.
- **The AI Engine, Detection Engine, Storage Engine, or any other business-logic engine.** No reasoning, correlation, or persistence.
- **A workflow engine.** No long-running orchestration.
- **A data plane.** No high-volume data motion passes through the Kernel per record. It is on the control path only.
- **Extensible.** No plugins. No user-supplied code. No dynamic module loading.
- **Multi-tenant-monolithic.** Sharded per-tenant partition; horizontally scalable.

**Rule of thumb:** if a proposed feature can live outside the Kernel without weakening enforcement, it MUST live outside the Kernel.

## 3. Design Principles

1. **Minimality.** Target ≤ 20k lines of trust-critical code in the Kernel core (excluding vendored crypto libraries). Every kLoC in the Kernel is scrutinized; every kLoC outside is merely reviewed.
2. **Determinism.** Same inputs produce the same policy/capability decision; no wall-clock or random-based branching in decision code.
3. **Statelessness where possible.** Verification is stateless; state is limited to the capability directory, revocation list, and local audit ring.
4. **No dynamic code.** No `eval`. No dynamic plugin load. No JIT rule authoring inside the Kernel.
5. **Fail-secure by default.** Any verification failure fails closed on the mediated operation.
6. **Independently verifiable.** Every audit record and every issued capability token is verifiable outside the Kernel using published public keys.
7. **Small blast radius.** Kernel compromise is catastrophic; therefore the Kernel is written, reviewed, tested, and deployed with disproportionate care.
8. **Language-level safety.** TypeScript strict mode + runtime input validation + property tests. High-risk crypto in vendored, audited libraries (libsodium bindings, node built-in `crypto` with post-quantum extensions when available).
9. **Reproducible builds.** Kernel binaries hash-pinned per release, signed by Z0.

## 4. Kernel Responsibilities in Detail

### 4.1 Capability Brokering
- Verify capability requests are legitimate (caller identity, caller's own capabilities include the delegation right, tenant scope match).
- Mint short-lived, scoped, revocable capability tokens (details in ARCH-08).
- Maintain the capability directory (issued tokens, delegation graph, revocation state).
- Broadcast revocations on NATS control bus.
- Verify capability tokens presented at boundary crossings.

### 4.2 Policy Enforcement
- Compose the request context: caller identity, tenant, capability, classification, resource, operation, boundary label, trace ID.
- Ask the Policy Engine for a decision.
- Enforce the decision (allow / deny / require-consent / require-4-eyes / require-break-glass).
- Cache decisions per (caller, capability, resource-class, classification) tuple for the capability TTL only.

### 4.3 Audit Gateway (Layer A)
- Compose a Layer-A audit event for every mediated operation (per F-6.6 event schema).
- Append to the Kernel-instance-local integrity ring (per D-05-3).
- Publish the record to the Audit Engine over NATS for asynchronous durability replication.
- Sign the record with the Kernel's audit-signing key (rotated per policy; anchored under Z0).

### 4.4 Identity Verification
- Enforce mTLS on every inbound and outbound Kernel connection.
- Verify message signatures on control-plane messages (defense in depth beyond mTLS).
- Refuse callers whose certificate is not attested-and-active in the Identity Engine snapshot the Kernel keeps.
- Rotate own identity per policy.

### 4.5 Quota Governance
- Per-caller identity, per-capability class, per-tenant:
  - RPS budget
  - Concurrency budget
  - Payload-size budget
- Enforced at the Kernel edge; exceedance returns a structured `QuotaExceeded` response and produces an audit event.

### 4.6 Break-Glass Gate
- Break-glass requests require: requester identity, reason, target scope, requested capabilities, requested duration, approver(s).
- Kernel verifies approver identities and multi-party requirement, records consent, mints time-boxed elevated capabilities, and produces a high-severity audit event.
- Automatic expiry; no manual re-issuance path that skips the same gate.

### 4.7 Intermediate CA
- The Kernel operates the intermediate CA that signs engine workload certificates on attestation.
- Root CA lives in Z0 (offline HSM); Kernel's intermediate is issued by the root under a documented ceremony.
- CA signing is a distinct Kernel subprocess with its own audit stream and its own signing key handling.

## 5. Interface Contract

### 5.1 Transport
- **gRPC over mTLS** for engine ↔ Kernel synchronous calls. Protobuf-defined API. Versioned.
- **NATS (mTLS + subject-scoped ACLs)** for capability revocation broadcast, Kernel liveness heartbeat, engine attestation events.

### 5.2 Core Kernel API (illustrative sketch — final in Phase B.2)

| Method | Purpose | Notes |
|---|---|---|
| `IssueCapability(request)` | Mint a capability | Requester must hold the same capability + delegate-right |
| `VerifyCapability(token, context)` | Fast-path verify with quota + policy | Called on boundary crossing |
| `RevokeCapability(token_id, reason)` | Revoke | Broadcast on NATS |
| `Mediate(op_request)` | Full boundary-crossing evaluation | BC-1..BC-10 |
| `AttestEngine(evidence)` | First-boot attestation | Issues workload cert on success |
| `RequestBreakGlass(request)` | Initiate break-glass | Kicks off approval workflow |
| `ApproveBreakGlass(request_id, approver_sig)` | Contribute an approval | Multi-party |
| `GetAuditReceipt(op_id)` | Return signed Layer-A record | Independent verification |
| `Health` / `Ready` / `Live` | Liveness | Never allow-lists anything |

Every method:
- Requires caller mTLS + message signature verification.
- Includes trace ID for correlation.
- Produces a Layer-A audit event on success and on refusal.
- Returns signed responses so callers can verify Kernel identity end-to-end.

### 5.3 Versioning and Compatibility
- Semantic versioning; wire compatibility guaranteed within a minor.
- Cross-version behavior: newer Kernel MAY accept older engine requests; older Kernel MUST refuse newer requests it cannot fully validate (fail-secure).

## 6. Deployment Topology

### 6.1 Modes

| Mode | Kernel topology | Notes |
|---|---|---|
| **Single-node** (VPS, developer) | Primary + warm standby in-process (supervisor restarts on primary failure) | RTO target ≤ 1s |
| **Kubernetes self-hosted** | Kernel StatefulSet with N ≥ 2 replicas; leader for capability directory writes; all replicas verify | Verification is horizontally scalable |
| **Air-gapped** | Same as K8s or single-node; **L3 permanently disabled at Kernel policy** | Update path is offline-signed bundles |
| **Hosted (v1+)** | Per-region Kernel cluster; per-tenant partitioning by consistent hashing | Cross-tenant queries require batch-capability (F-13) |

### 6.2 State
- **Capability directory** — Postgres (control plane) with in-memory Kernel cache, refreshed on write and on NATS broadcast.
- **Revocation list** — Kept small; broadcast on change; delta gossip after reconnect.
- **Local integrity ring** — Per-Kernel-instance, on fast local storage (NVMe recommended), size-bounded, replicated to Audit Engine.
- **Kernel identity keys** — In HSM / cloud KMS or software-emulated HSM depending on deployment (ARCH-11).

### 6.3 High Availability
- Active-active verification (any Kernel replica can verify).
- Active-passive for capability directory writes (leader elected).
- Split-brain guard: writes require a lease from the leader; passive replicas serve reads only until the lease heals.

### 6.4 Failure Modes and Recovery (Recovery-First Design)

| Failure | Detection | Recovery |
|---|---|---|
| Kernel process crash | Supervisor + heartbeat gap on NATS | Restart; warm standby takes over; local ring replayed on reboot |
| Kernel instance total loss | Cluster loses a replica | Replacement instance re-attests to Root of Trust; catches up capability directory from Postgres and revocation list from control bus |
| Kernel cluster loses quorum (multi-node) | Leader election fails | Verification continues (read-only); writes (new capability issuance) pause; alert; escalation runbook |
| Signing key compromise suspected | Detection Engine alert (anomaly), independent verification failure, external report | Immediate revocation of Kernel's intermediate at Z0; issue new Kernel identity; force re-attestation of engines; documented ceremony |
| Local integrity ring corruption | Chain-verification failure on read | Isolate instance; forensic capture; rebuild from Audit Engine replicated copy; gap recorded |
| Audit replication lag | Ring water-mark exceeded | Alert; drain instance if archival is far behind; fail-secure on new operations for that instance |

Every failure produces an alert routed to Recovery Engine, which owns the runbook (ARCH-16).

## 7. Bootstrap and Trust Establishment

### 7.1 Root of Trust (Z0)
- Root CA private key is generated in an offline HSM at a witnessed ceremony (multi-party, video-recorded, chain-of-custody documented).
- Root public key is published to all AEGIS deployments and to the AEGIS transparency log (roadmap).
- Root private key is used only to issue Kernel-signing certificates. It never signs engine certificates directly.

### 7.2 Kernel Identity
- Kernel bootstrap identity is issued by Z0 (rooted at HSM), valid for a bounded period (target: 90 days), rotated by ceremony.
- Kernel operates its own intermediate CA that signs engine workload certificates.
- Kernel identity revocation is signed by Z0 and broadcast; engines refuse an unrevoked-then-revoked Kernel.

### 7.3 Engine Attestation
- On first boot, an engine presents attestation evidence to the Kernel:
  - For Kubernetes: signed ServiceAccount token + workload identity provider signature (SPIFFE-style, ARCH-09).
  - For VPS: TPM-quote when available; otherwise, out-of-band shared enrollment token exchanged once during deployment.
  - **Future Readiness:** hardware-attested TEE identity; adopted when the deployment supports it, without redesign.
- Kernel verifies evidence and issues a workload certificate (short-lived — hours to a day).
- Renewal is automatic and requires only that the engine's continued identity is still trusted (no expired workload identity, no revocation, still in the fleet).

### 7.4 First-Boot Chicken-and-Egg
- The Kernel needs its identity signed by Z0 before it can serve engines. Cold-start solution: the Kernel image ships with its identity certificate already issued by Z0 in the release ceremony. First-run stores it. Rotation happens on subsequent ceremonies.
- Air-gapped deployments receive Z0-signed Kernel identity as part of the release bundle; verified against the offline-published Z0 public key.

## 8. Independent Architecture Review

### 8.1 SPOFs

| Finding | Response |
|---|---|
| **F-A.** *Kernel is a SPOF for capability issuance during Kernel outage.* | Multi-replica Kernel; capability caching in engines (D-05-2); most operations use cached tokens; only issuance (rare) requires a live Kernel. |
| **F-B.** *The Kernel's intermediate CA is a SPOF; its compromise revokes trust in every engine.* | Documented CA-compromise runbook: Z0 revokes the intermediate, issues a new one; engines re-attest; scheduled rehearsal at least yearly. |
| **F-C.** *Z0 root key is the ultimate SPOF.* | Threshold cryptography for Z0 (m-of-n signing) is on the Future Readiness roadmap (ARCH-11); v0 uses standard HSM with documented multi-party access controls. |
| **F-D.** *NATS control bus outage breaks revocation broadcast.* | Bounded cache TTLs (D-05-2) mean revocations become effective within a few minutes; degraded-mode engines shorten their TTLs further; complete NATS outage triggers a documented degraded-mode that halts new-privilege issuance. |

### 8.2 Privilege Escalation

| Finding | Response |
|---|---|
| **F-E.** *A compromised engine attempts to obtain capabilities it does not hold.* | Kernel refuses issuance unless caller holds the capability + delegation right. Delegation is tracked in the directory and audited. |
| **F-F.** *A compromised engine calls `Mediate` with forged tenant context.* | Tenant context is bound to the caller's workload identity, not the request payload. Kernel refuses when they mismatch. |
| **F-G.** *A malicious insider with Kernel admin access alters the capability directory.* | Every directory write produces a Layer-A audit event, verifiable outside the Kernel; anomaly detection watches for out-of-band writes; the underlying database has an append-only shadow log (ARCH-11) — divergence from the directory alerts. |
| **F-H.** *Break-glass path abused for silent elevation.* | Multi-party approval required; every step audited at Layer A + Layer B; break-glass audit events are high-severity by default and monitored. |

### 8.3 Bottlenecks and Scalability

| Finding | Response |
|---|---|
| **F-I.** *Every engine call becomes a Kernel round-trip.* | Not true; only issuance and full mediation are Kernel round-trips. Verification of cached tokens is engine-local; per-message data-plane authorization is broker-ACL-driven. Kernel throughput target for v0-GA: ≥ 5k mediations/sec/replica on reference hardware. |
| **F-J.** *Kernel writes to Postgres for every capability issuance.* | Batched with local ring; Postgres writes are asynchronous with respect to Kernel response; strong-consistency is guaranteed by leader-write + read-your-writes cache. |
| **F-K.** *Local ring on NVMe becomes the Kernel bottleneck under high issuance load.* | Sized in ARCH-16; issuance rate is far lower than verification rate; ring rotation and archival move it out of the hot path. |

### 8.4 Trust Boundary Violations

| Finding | Response |
|---|---|
| **F-L.** *Kernel silently downgrades classification to permit an L3 call.* | Kernel does not modify classifications; it consults Policy and either allows or denies. Downgrade requires an explicit policy rule and produces an audit event. |
| **F-M.** *Kernel accepts a policy update that removes an audit requirement.* | Policy Engine changes are themselves Kernel-mediated operations; auditing an audit-removing change is enforced by the Policy Engine's own invariants (some rules cannot be turned off; ARCH-13). |

### 8.5 AI-Specific Risks

| Finding | Response |
|---|---|
| **F-N.** *AI Engine tries to invoke another engine directly, bypassing the Safety Layer.* | AI Engine has no direct engine calls; every action goes through Kernel; AI Safety Layer sits before Kernel-mediated calls (ARCH-14). |
| **F-O.** *AI Engine's capability is set too broad ("Read-Logs" tenant-wide).* | Capability scoping is per-case, per-time-window, and further limited by the Safety Layer's per-request budget; monitored anomaly-detection watches for AI capability drift. |

### 8.6 Supply Chain

| Finding | Response |
|---|---|
| **F-P.** *A compromised gRPC library injects into Kernel.* | Kernel uses hash-pinned dependencies with SLSA-3+ builds; SBOM per release; kernel-critical dependencies get extra scrutiny in review; message signatures beyond mTLS defend against library-level tampering. |
| **F-Q.** *An open-weights model is loaded by AI Engine with a hidden backdoor and calls out via a plugin capability.* | Plugins hold their own capabilities; models do not; models cannot mint capabilities; if the model directs the AI Engine to call something out of scope, the Kernel denies. |

### 8.7 Operational Risks

| Finding | Response |
|---|---|
| **F-R.** *Kernel upgrade during a live incident.* | Kernel supports rolling upgrade behind stable API; blue-green possible; version compatibility contract in §5.3. |
| **F-S.** *Operator misconfigures a policy that inadvertently locks the platform out.* | Policy changes are versioned and rollbackable; a "safety policy" invariant set cannot be removed even by operators; Recovery runbook exists. |
| **F-T.** *Kernel's own telemetry leaks tenant identifiers to external observability.* | Kernel telemetry is scrubbed at the boundary; opt-in per deployment; disabled in air-gap. |

### 8.8 Hidden Assumptions Surfaced

| Assumption | Handling |
|---|---|
| We can keep the Kernel core under 20k LoC. | Enforced by a build-time check and code-review discipline; if we can't, we cut features from the Kernel. |
| Policy Engine responses are always fast. | Kernel has a timeout on Policy consultation; timeout = deny; observability alerts when timeouts spike. |
| Cluster clock skew is bounded. | Time-based expiry uses monotonic clocks with an external NTP anchor; audit records carry both wall-clock and monotonic markers; skew > threshold triggers alert. |
| Kubernetes attestation is trustworthy. | It is not, alone. We combine SPIFFE/K8s attestation with the Identity Engine's fleet directory and Kernel-side heuristics; anomalies alert. |

## 9. Decisions

### D-06-1. Kernel is a distinct process with its own identity, not a library

- **Advantages.** Independent lifecycle, upgrade, audit, and blast-radius; separate deployment topology; enforceable minimality; clean interface.
- **Disadvantages.** RPC hop cost on the control path.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Small* — cached tokens absorb the cost; issuance is a control-path operation.
- **Operational Complexity.** *Higher* — another service to run; mitigated by HA topology and self-contained deployment.
- **Maintainability.** *Positive* — clear ownership.
- **Scalability.** *Positive* — horizontally scalable.
- **Alternative Designs.** *(a) Kernel-as-library in every engine.* Duplicates critical code, drift-prone. Rejected. *(b) Kernel-as-sidecar per engine.* Better than library but multiplies attack surface. Rejected as primary; can co-exist for boundary-only tasks. *(c) Kernel-as-service-mesh policy engine (Istio + OPA).* Insufficient for capability model. Rejected as primary.
- **Reason for Final Selection.** Distinct-service is the cleanest embodiment of the microkernel principle and yields the smallest verifiable trust core.

### D-06-2. Kernel bounds itself to ≤ 20k trust-critical LoC

- **Advantages.** Auditable; formal analysis feasible for parts; forces feature discipline.
- **Disadvantages.** Some conveniences pushed outside the Kernel.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** Neutral.
- **Operational Complexity.** Neutral.
- **Maintainability.** *Strongly positive* — a small core is a joy to maintain.
- **Scalability.** Neutral.
- **Alternative Designs.** *No LoC target.* History shows growth; rejected.
- **Reason.** Trust core credibility is proportional to review depth; review depth is proportional to code size inverse.

### D-06-3. Local integrity ring + async replication for Layer-A

- **Advantages.** Non-blocking Layer-A; strong tamper-evidence; sub-ms writes.
- **Disadvantages.** Bounded tail loss on instance loss before replication.
- **Security Impact.** *Positive net.*
- **Performance Impact.** *Positive.*
- **Operational Complexity.** Moderate — local storage requirements documented.
- **Maintainability.** Moderate.
- **Scalability.** *Positive.*
- **Alternative Designs.** *Synchronous to Audit Engine.* Blocks Kernel on Audit health; rejected. *No local ring.* No integrity while Audit is unreachable; rejected.
- **Reason.** Best availability/integrity tradeoff.

### D-06-4. Kubernetes + SPIFFE-style attestation as the v0 baseline; TEE/HRoT as Future Readiness

- **Advantages.** Broad support today; clear upgrade path.
- **Disadvantages.** K8s attestation is not itself sufficient; requires combination with Identity Engine.
- **Security Impact.** *Positive.*
- **Performance Impact.** Neutral.
- **Operational Complexity.** Moderate.
- **Maintainability.** Good — well-known patterns.
- **Scalability.** Good.
- **Alternative Designs.** *TEE-only.* Excludes non-TEE hardware; rejected as v0 baseline. *Static enrollment tokens only.* Weaker; used only as fallback for non-K8s VPS.
- **Reason.** Best coverage in 2026 without foreclosing future hardware trust primitives.

## 10. Open Questions

- Q-06-1. Language choice for the Kernel core — TypeScript (matches stack, high productivity) vs. Rust (better memory safety guarantees for trust-critical code). Recommendation: **TypeScript for now**, with a Rust module option reserved for the capability directory and signing hot path if profiling shows need. Resolved in ARCH-12.
- Q-06-2. Threshold cryptography for Z0 root (m-of-n signing) — v1 or later. Resolved in ARCH-11.
- Q-06-3. Formal analysis scope — property-based tests only, or lightweight model checking (TLA+ or Alloy) for the capability directory. Resolved in ARCH-12.
- Q-06-4. Kernel telemetry format and retention. Resolved in ARCH-13.

## 11. Change Log

- **0.1 (2026-07-10)** — Initial draft after independent architecture review.