# AEGIS — Plugin Isolation Architecture

- **Document ID:** ARCH-17
- **Phase:** B.3 — AI, Plugins, Recovery
- **Status:** Draft for review (post three-reviewer discipline)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect
- **Depends on:** ARCH-06, ARCH-07, ARCH-08, ARCH-09, ARCH-14
- **Consumed by:** ARCH-18

---

## 1. Purpose

Specify the Plugin Engine (E-12) and the isolation contract for third-party extensions. Every plugin is treated as potentially malicious; every plugin has an independent identity, permissions, storage, audit trail, lifecycle, and revocation. Implements Phase-B constraint #6 (Plugin Sandbox) and B.3 mandate #3 (Plugin Zero Trust).

v0 delivers the **interface, sandbox, and governance model**. Plugin runtime is v0.2+. The interface must be right in v0 because retrofitting isolation is much harder than designing it.

## 2. Simplicity Choice: WebAssembly + Wasm Component Model

**Chosen substrate: WebAssembly (WASI + Component Model).**

Rationale, in order of importance:
1. **Language-agnostic sandbox with mature tooling.** Publishers can write in Rust, Go, C++, TinyGo, AssemblyScript.
2. **Capability-based host bindings.** Wasm imports are precisely the surface AEGIS grants; nothing else is reachable. Aligns with our capability model.
3. **Deterministic execution.** Bounded memory, bounded CPU, no ambient authority.
4. **Portable.** Same plugin runs on every deployment topology.
5. **Small verifier + mature engines** (Wasmtime, Wasmer) — SBOM tractable; SLSA-3 attestations available.

Alternatives considered: OS-level containers (heavier, mutable, slower cold-start), language-level sandboxes per language (n-way maintenance burden), native shared libraries (unacceptable — arbitrary memory access). Wasm wins on simplicity, portability, and security.

## 3. Zero-Trust Independence Properties (Mandate #3)

### 3.1 Independent Identity
- Every plugin instance has its own SVID (workload identity, per-launch, short TTL).
- Publisher identity is separate: publisher signs the plugin binary; the binary's runtime SVID is issued by the Kernel on attestation of the launch context.

### 3.2 Independent Permissions
- Capability set is declared in the plugin manifest, granted at install (4-eyes + `Grant-Plugin-Capability`, per ARCH-08 §4.7), and enforced by the Kernel.
- Capabilities are attenuated: a plugin cannot delegate broader than granted, cannot escalate at runtime, cannot inherit from the host.
- Default: **no capabilities**. Every capability is explicit.

### 3.3 Independent Storage
- Each plugin gets a dedicated storage namespace with its own KEK-wrapped DEK.
- Storage access is Kernel-mediated via a capability (`Read/Write-PluginStore-<plugin_id>`).
- No shared storage between plugins; no direct DB access; no filesystem access outside the plugin's namespace.

### 3.4 Independent Audit Trail
- Every plugin has its own audit stream keyed by plugin instance.
- Layer-A entries carry `plugin_id + plugin_instance_id + publisher_id + version + manifest_hash`.
- Audit contents are tenant-scoped for tenants using the plugin.

### 3.5 Independent Lifecycle
- Install → Configure → Enable → Run → Disable → Uninstall.
- Each state transition is Kernel-mediated and audited.
- Upgrade is a distinct lifecycle event with re-attestation (new manifest = new capability grant workflow).

### 3.6 Independent Revocation
- Kill-switch: `Kill-Plugin` (one-shot, 60s TTL) revokes all plugin capabilities and terminates the sandbox immediately.
- Publisher revocation: revoking a publisher revokes every plugin signed by it (broadcast on control bus).
- Version blacklist: known-bad versions blocked from install/enable.

## 4. Plugin Manifest

A signed structure declared by the publisher:

```
PluginManifest {
  plugin_id                : PublisherScopedId
  version                  : semver
  publisher_id             : PublisherIdentity
  wasm_component_hash      : Sha256
  capabilities_requested   : [CapabilityRequest]     // named + resource scope
  host_bindings_requested  : [HostBinding]           // enumerated below
  network_egress_policy    : { allowed_destinations: [...], forbidden_by_default: true }
  storage_namespace        : { size_max, retention }
  concurrency_limits       : { max_instances, max_cpu_ms_per_call, max_memory_mb }
  data_classification_max  : ClassificationLevel      // what the plugin may see
  reproducibility          : { deterministic: bool, seed_required: bool }
  provenance               : { SLSA_provenance_ref, SBOM_ref }
  signature                : PublisherSig            // publisher signs the manifest
}
```

Install workflow verifies signature, checks publisher against publisher registry, presents requested capabilities to the operator for explicit approval (4-eyes for HR-classification-eligible plugins).

## 5. Host Bindings (the plugin's world model)

A plugin's world is exactly the imports it declares and gets granted. The full v0 binding set is:

| Binding | Purpose |
|---|---|
| `read_normalized_events(query)` | Query normalized events within capability scope |
| `read_findings(query)` | Query findings within capability scope |
| `emit_finding(structured)` | Publish a plugin-produced finding via the Detection Engine's plugin interface |
| `emit_recommendation(structured)` | Publish a proposed action to the Case Engine (still gated by pipeline) |
| `kv_read/write(namespace_key)` | Read/write the plugin's storage namespace |
| `log_event(structured)` | Emit to the plugin's audit stream |
| `now() / monotonic_now()` | Time (signed by Kernel) |
| `fetch_signed_config(config_id)` | Fetch signed configuration from Kernel-mediated config store |
| `sleep(ms)` | Bounded sleep |

There is *no* raw filesystem, no arbitrary network, no arbitrary process, no eval, no dynamic module load. The absence is the security. Any future binding is a governed extension.

**Network egress** is *always* Kernel-mediated: the plugin declares intended destinations in the manifest; Kernel enforces network policy at the sandbox network layer; egress not covered by declaration is refused fail-secure.

## 6. Communication Between Plugins

**No direct communication.** If plugin A wants to consume plugin B's output, it consumes B's *findings* or *recommendations* through the standard Kernel-mediated interfaces, with capability checks. This preserves audit and prevents a compromised plugin from silently altering another's execution.

## 7. Publisher Governance

- **Publisher Registry.** AEGIS maintains a governed list of trusted publishers.
- **Publisher Signing.** Each publisher has a signing key attested at publisher onboarding (ceremony).
- **Publisher Trust.** Adaptive Trust vector per publisher (§ARCH-11 §6): incident history, security posture, community reputation.
- **Publisher Revocation.** Two-party approval; cascades to all their plugins; kill-switches all running instances.
- **Community Plugins vs. AEGIS-Signed.** Community publishers exist; AEGIS-signed plugins are a higher-trust tier (canary-tested, SBOM-verified, extra review).

## 8. Sandbox Runtime Details

- **Engine.** Wasmtime (Rust-based, memory-safe, small footprint). Alternative: Wasmer.
- **Resource limits.** Per-instance CPU-ms, memory, syscall rate; bounded queue depth.
- **Isolation.** Each plugin instance runs in its own subprocess (defense in depth against runtime bugs); sandbox network in its own network namespace.
- **Determinism.** By default, Wasm is deterministic; non-determinism sources (time, randomness) are host-provided and audited.
- **Fault handling.** Trap → instance terminated; logged; auto-restart per policy; repeated traps → auto-disable with alert.

## 9. Safe Failure Modes (Mandate #7)

For the Plugin Engine (E-12):

| Mode | Trigger | Behavior |
|---|---|---|
| **Normal** | Plugin runtime healthy | Plugins run per manifest + capabilities |
| **Degraded** | Plugin exceeded resource limits | Instance killed; documented; back-off; next launch throttled |
| **Recovery** | Multiple plugins misbehaving | Enter Recovery: pause all optional plugins; keep only AEGIS-signed plugins; alert |
| **Maintenance** | Runtime engine update | Drain gracefully; new installs blocked; upgrade; verify with canary plugin |
| **Emergency** | Publisher revoked; malicious plugin confirmed; runtime engine integrity failure | Kill-switch every affected plugin; refuse new installs; alert; require operator ack |

## 10. Recovery-First Answers

1. *How does it fail?* Plugin trap; runtime engine bug; capability over-grant; publisher key compromise; network policy misconfig; resource exhaustion.
2. *Detection.* Plugin health metrics; audit anomaly detection; publisher revocation stream; per-plugin failure rate.
3. *Initiation.* Automatic kill on repeated trap; automatic Emergency on publisher revocation; runbook for runtime-engine incidents.
4. *Automated?* Yes for transient; ceremony for publisher-registry changes.
5. *Rollback?* Manifest versions retained; downgrade path documented; capability grants versioned.

## 11. Defensive Telemetry (Mandate #8)

Plugin telemetry is proportional:
- **Collected always:** invocation count, failure rate, capability use, resource consumption per instance.
- **Collected on anomaly:** trace-level detail for a specific instance.
- **Never collected:** plugin input/output content by default (tenant-controlled opt-in for debugging with explicit consent).

## 12. Independent Architecture Review (Reviewer 1)

### 12.1 Hidden Assumptions

| Assumption | Handling |
|---|---|
| Wasm engine (Wasmtime) is trustworthy. | Small, audited, memory-safe (Rust); SLSA-attested; SBOM-tracked; RIV monitors at runtime. |
| Publishers can be governed. | Onboarding + revocation + trust vector; community publishers held at lower trust ceiling. |
| Manifest schema captures all publisher intent. | Schema is versioned; unknown fields refused fail-secure; deprecation cycle. |

### 12.2 SPOFs

| Finding | Response |
|---|---|
| **F-1.** *Plugin Engine outage blocks legitimate plugin work.* | Plugins are enhancement, not critical path — Deterministic Core continues without them. |
| **F-2.** *Publisher Registry unreachable → new installs fail.* | Registry cached; new installs require live check for R/HR-eligible plugins; existing plugins keep running. |

### 12.3 Privilege Escalation

| Finding | Response |
|---|---|
| **F-3.** *Plugin escapes sandbox.* | Subprocess isolation + network-namespace + capability-mediated bindings; escape requires Wasm engine + kernel bug; RIV detects unexpected host binary hash; defense in depth. |
| **F-4.** *Plugin requests broader capabilities via a runtime API.* | No runtime API for privilege change; grants are install-time only. |
| **F-5.** *Plugin exfiltrates via network.* | Egress policy default-deny; Kernel-mediated; deviations refused + alerted. |

### 12.4 Trust-Boundary Violations

| Finding | Response |
|---|---|
| **F-6.** *Plugin reads cross-tenant data via a shared cache.* | Tenant scope encoded in every host binding call; caches are per-plugin-per-tenant. |
| **F-7.** *Plugin emits findings that impersonate AEGIS-Detection.* | Findings from plugins are marked `origin: plugin<id>`; UI shows attribution; policy can filter. |

### 12.5 Bottlenecks

| Finding | Response |
|---|---|
| **F-8.** *Plugin runtime hot-path is slow.* | Wasmtime is fast; typical call ~µs range; per-tenant fairness in queue. |
| **F-9.** *Publisher registry lookups on every launch.* | Cache with TTL; revocation broadcast pushes updates. |

### 12.6 Supply Chain

| Finding | Response |
|---|---|
| **F-10.** *Compromised publisher key.* | Publisher revocation cascades; kill-switch on all their plugins; ceremony for new publisher key. |
| **F-11.** *Malicious dependency in plugin binary.* | SBOM required in manifest; SCA scans; SLSA provenance; runtime hash-verified. |
| **F-12.** *Compromised Wasm engine dependency.* | Hash-pinned; SBOM; RIV; canary tenant on runtime engine updates. |

### 12.7 AI-Specific Risks

| Finding | Response |
|---|---|
| **F-13.** *Plugin uses AI Engine and hides prompt injection in its manifest text.* | Plugins do not embed AI prompts in manifests; if a plugin uses AI Engine, requests go through the same AI pipeline including Safety Layer. |
| **F-14.** *Plugin exfiltrates data by triggering L3 AI calls.* | Plugin lacks `Invoke-AI-L3` unless explicitly granted; classification-based routing at Kernel; audit records all AI-invocation attempts. |

### 12.8 Operational Risks

| Finding | Response |
|---|---|
| **F-15.** *Plugin compatibility across AEGIS versions.* | Host binding versions are semver; deprecation cycle; canary matrix per release. |
| **F-16.** *Plugin store performance under many plugins.* | Storage sizing per plugin manifest; per-tenant fair-share; drift alerts. |

## 13. Adversarial Architect Review (Reviewer 2)

| Attack path | Design response |
|---|---|
| **A-1.** Malicious plugin signed by legitimate publisher (compromised publisher CI). | Publisher trust decays on incidents; canary run-time evals; behavioral anomaly; kill-switch. |
| **A-2.** Timing side-channel between plugin instances on shared CPU. | Documented residual risk; mitigations: per-plugin cgroup CPU pinning where policy requires; Future Readiness path to confidential-compute with mitigations. |
| **A-3.** Plugin publishes findings that overwhelm Detection review. | Rate limits per plugin per tenant; anomaly detection on plugin finding volume; auto-throttle. |
| **A-4.** Insider grants a plugin over-broad capabilities. | Grant path is 4-eyes for privileged capabilities; audit event high severity; ceremony for HR-eligible grants. |
| **A-5.** Plugin manifest declares deceptive network egress list. | Egress policy enforced by network layer; deceptive declaration is caught by drift monitor on actual egress attempts. |
| **A-6.** Plugin acts as a covert channel between two tenants. | Plugin cannot access data outside its tenant scope; even a compromised plugin sees only its per-tenant instance data. Cross-tenant communication is architecturally impossible. |
| **A-7.** Compromised Wasm engine bypasses capabilities. | RIV monitors runtime binary hashes; kernel-side network policy + subprocess isolation as belt-and-braces; runtime-update ceremony for signed engines only. |
| **A-8.** Cloud compromise reads plugin memory. | Documented residual risk; TEE/confidential-compute Future Readiness. |

## 14. Operational Reliability Review (Reviewer 3)

| Concern | Response |
|---|---|
| **O-1. 15-year plugin ecosystem sustainability.** | Stable host binding contract; versioning; deprecation cycle; backward-compat for one major version. |
| **O-2. Publisher governance workload.** | Automated where safe; ceremony minimum for onboarding + revocation; trust vector reduces manual review. |
| **O-3. Debugging failing plugins.** | Structured logs per instance; audit stream per plugin; tenant-controlled tracing opt-in. |
| **O-4. Runtime engine upgrade safety.** | Canary tenant subset; kernel-mediated staged rollout; automatic rollback on failure-rate spike. |
| **O-5. Air-gap plugin delivery.** | Air-gap bundles include signed plugin catalog; installation runbook. |
| **O-6. Observability of plugin fleet.** | Per-plugin dashboards; trust-vector visibility; alarm on anomalies. |
| **O-7. Multi-tenant fairness.** | Per-tenant resource quotas; fairness scheduler; per-tenant metrics. |
| **O-8. Contract stability under new Wasm standards.** | AEGIS pins Wasm Component Model version; migration on major upgrades follows deprecation cycle. |

## 15. Attacker's First-Target Analysis and Redesign

**"If I were an experienced attacker, what part of this design would I target first?"**

**Publisher onboarding.** Reason: publishers become trust anchors; onboarding a rogue publisher (or convincing AEGIS staff to onboard one) legitimizes a persistent supply of malicious plugins with fewer downstream checks than an unknown publisher would face. Onboarding is a *human process* with the lowest structural constraints of any part of the plugin path.

**Redesign response.**

1. **Onboarding ceremony with independent verification.** Publisher onboarding requires: signed publisher key; verified identity (business + technical contacts); reference deployments; period of *observation* under community-tier trust before promotion; two AEGIS approvers + Auditor.
2. **Reputation-tiered trust.** Publishers exist at tiers (Community → Verified → AEGIS-Signed). Higher tiers require operational history and canary success. Even a legitimately onboarded publisher does not start at the highest tier.
3. **Continuous re-verification.** Publisher trust re-assessed on cadence; incidents decay trust; sustained good behavior recovers.
4. **Capability ceilings by tier.** Community-tier publishers cannot request HR-classification-eligible capabilities. AEGIS-Signed plugins have higher ceilings only after formal signing ceremonies.
5. **Public transparency log.** Publisher onboarding events published to a transparency log; community can watch for suspicious additions.
6. **Kill-switch drilled.** Publisher revocation runbook rehearsed quarterly; automated cascade tested with canary plugins.

**Second target after redesign.** Wasm engine dependency chain. Response: hash-pinned; SBOM; RIV monitors runtime binary; canary tenant on updates; automatic rollback on Safety-Layer-adjacent anomaly.

**Third target.** Network egress policy misconfiguration. Response: policy is signed configuration; changes ceremony-controlled; drift monitor on actual egress traffic surfaces attempts not in the declared policy.

No further high-impact silent-compromise vector identified at this abstraction.

## 16. Security Economics (Mandate #10)

- **Attacker cost raised.** Publisher trust must be built over time; short-cut attempts are ceremony-blocked. Compromising a *plugin* still yields only per-tenant per-instance access with per-plugin storage; no cross-tenant reach.
- **Attacker cost raised.** Wasm sandbox + subprocess isolation + network policy + capability model = four independent layers. Compromising the whole chain is expensive.
- **Defender cost reduced.** Kill-switch is a single Kernel operation. Publisher revocation cascades automatically. Manifest changes are structured and diffable.

## 17. Decisions

### D-17-1. WebAssembly + Wasm Component Model as sandbox substrate

- **Advantages.** Language-agnostic; capability-native; portable; mature engines; simplicity.
- **Disadvantages.** Some workloads (heavy math without SIMD, GPU) don't fit v0.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Positive net* — near-native for many workloads; startup fast.
- **Operational Complexity.** *Positive* — single sandbox stack vs. n-language.
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *Containers per plugin.* Heavier; slower; larger attack surface; rejected. *Language-level sandboxes.* n-way; rejected.
- **Reason.** Mandate #3, #24.

### D-17-2. Independent identity + storage + audit per plugin

- **Advantages.** Blast-radius per plugin; kill-switch simple; audit legible.
- **Disadvantages.** More SVIDs.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Neutral.*
- **Operational Complexity.** *Moderate.*
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *Shared identity.* Concentrates trust; rejected.
- **Reason.** Mandate #3.

### D-17-3. Publisher tiers with ceremony onboarding + capability ceilings

- **Advantages.** Addresses primary redesign target (§15); reputation-graduated.
- **Disadvantages.** More governance work.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** N/A.
- **Operational Complexity.** *Moderate.*
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *Flat trust.* Rejected. *No community publishers.* Rejected — ecosystem needs openness.
- **Reason.** Reputation-graduation is the honest model.

### D-17-4. No plugin-to-plugin direct communication

- **Advantages.** No covert channels; all inter-plugin flows visible in audit.
- **Disadvantages.** Some compositions require plumbing through platform contracts.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Small.*
- **Operational Complexity.** *Positive.*
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *Direct IPC.* Rejected.
- **Reason.** Mandate #3.

## 18. Open Questions

- Q-17-1. GPU-accelerated plugin support (for future AI-adjacent plugins). Roadmap.
- Q-17-2. Multi-tenant plugin data-sharing model (Phase 3). Roadmap.
- Q-17-3. Transparency-log integration for publisher events. Resolved in ARCH-14 + ARCH-18.

## 19. Change Log

- **0.1 (2026-07-10)** — Initial draft after three-reviewer discipline.