# AEGIS — System Requirements Specification - **Document ID:** ARCH-02 - **Phase:** A — Problem Definition - **Status:** Draft for review - **Version:** 0.1 - **Date:** 2026-07-10 - **Owner:** Chief Security Architect - **Depends on:** ARCH-01 (Vision), CLAUDE.md --- ## 1. Purpose This document specifies the functional and non-functional requirements for AEGIS v0. It bounds *what the system must do*, *for whom*, *under what constraints*, and *at what quality*. Requirements are the acceptance contract for downstream architecture and implementation. ## 2. Requirement Notation - **MUST / MUST NOT** — binding for v0. - **SHALL** — binding by v1. - **SHOULD** — strongly preferred; deviations require documented rationale. - **MAY** — permitted; not required. Each requirement is tagged **F-** (functional), **NF-** (non-functional), or **C-** (constraint), and numbered. ## 3. Actors ### 3.1 Human Actors | ID | Actor | v0 Relevance | Notes | |---|---|---|---| | A-01 | **SOC Analyst** | Primary | Reviews AI recommendations, opens/closes cases, reads timeline. | | A-02 | **Security Engineer / Detection Engineer** | Primary | Authors and tunes Sigma rules, configures ingestion, reviews audit. | | A-03 | **Tenant Administrator** | Primary | Manages users, roles, integrations, tenant configuration. | | A-04 | **Compliance / Audit Officer** | Primary | Reviews audit trail, exports evidence for regulators. | | A-05 | **Individual / Prosumer** | Secondary | Solo operator on a single-node deployment. | | A-06 | **MSSP Operator** | Deferred (Phase 3) | Multi-tenant control plane not in v0. | | A-07 | **AEGIS Platform Operator** | Primary | Runs the AEGIS deployment (may be same person as A-02 for self-hosted). | | A-08 | **AEGIS Support Engineer** | Primary | External to tenant; needs privileged but audited break-glass access. | | A-09 | **External Auditor / Regulator** | Primary | Read-only access to audit exports; independent verification. | ### 3.2 Non-Human Actors | ID | Actor | Notes | |---|---|---| | A-10 | **Log Source** | External systems pushing telemetry (syslog, cloud audit stream, HTTP/JSON push, forwarder). | | A-11 | **AI Provider** | External or local model runtime. Untrusted from AEGIS's perspective. | | A-12 | **Threat-Intel Feed** | Deferred (Phase 2), but ingestion contract must anticipate. | | A-13 | **Identity Provider** | External OIDC / SAML / SCIM. | | A-14 | **Plugin** | Third-party extension. Untrusted by default. | | A-15 | **Backup / Archive Target** | S3-compatible object store, tape, cold storage. | ## 4. Functional Requirements ### 4.1 Log Collection (Capability 1) - **F-1.1 (MUST)** Ingest from syslog (RFC 3164 and RFC 5424) over UDP, TCP, and TLS. - **F-1.2 (MUST)** Ingest via authenticated HTTPS push endpoint accepting NDJSON. - **F-1.3 (MUST)** Ingest from a documented pull-based cloud audit log connector for **at least one** cloud provider by v0-GA. Choice deferred to ARCH-07, sequencing in ARCH-18. - **F-1.4 (MUST)** Ingest from a documented file-tail collector (e.g., Fluent Bit / Vector as reference forwarder) that can ship from Windows Event Log, Linux syslog, and macOS `unified log` — the *forwarder* is out-of-tree; AEGIS provides the receiving contract. - **F-1.5 (MUST)** Every accepted event MUST be persisted to the ingest bus (Kafka/Redpanda) before acknowledgment to the sender. - **F-1.6 (MUST)** Every accepted event MUST carry a source identity, receipt timestamp, tenant ID, and per-event integrity hash. - **F-1.7 (MUST NOT)** Silently drop events. Any drop MUST be logged, counted, and surfaced. - **F-1.8 (SHOULD)** Support backpressure signaling to the source when downstream is degraded. ### 4.2 Event Normalization (Capability 2) - **F-2.1 (MUST)** Map raw events to a canonical event schema. Working baseline: **OCSF v1.x** (final choice in ARCH-07). - **F-2.2 (MUST)** Preserve the original raw event, verbatim, alongside the normalized form. **Normalization is additive, never destructive.** - **F-2.3 (MUST)** Every normalized event MUST include: `tenant_id`, `event_id`, `source_id`, `receipt_time`, `event_time`, `class`, `category`, `severity`, `raw_ref`, `normalization_version`, `integrity_hash`. - **F-2.4 (MUST)** Unmapped fields go to a `raw_unmapped` structured field, not discarded. - **F-2.5 (MUST)** Every schema mapping change bumps `normalization_version`; historical events remain queryable against their original schema. ### 4.3 Security Event Correlation (Capability 3) - **F-3.1 (MUST)** Support **Sigma** as the primary rule format for v0. - **F-3.2 (MUST)** Support tenant-scoped rule sets; rules from one tenant MUST NOT affect another. - **F-3.3 (MUST)** Every rule match produces a **Finding** with: rule reference, matched event IDs, evidence hashes, confidence, severity, time window, tenant, and a stable finding ID. - **F-3.4 (MUST)** Findings feed into **Cases** — cases group related findings, hold state (open/investigating/resolved), and own an Incident Timeline. - **F-3.5 (MUST)** Correlation SHALL be deterministic and explainable: given the same events and rules, output is identical and every decision is traceable. - **F-3.6 (SHOULD)** Provide an extension contract for statistical detectors (baselines, anomaly, sequence) invoked as pluggable operators. - **F-3.7 (MUST)** Rule authoring MUST include a test harness: any rule shipped MUST have at least one positive and one negative fixture. ### 4.4 AI Security Recommendations (Capability 4) - **F-4.1 (MUST)** Every recommendation MUST cite the specific finding(s) and event(s) it is based on, by ID and integrity hash. - **F-4.2 (MUST)** Every recommendation MUST route through the three-tier AI router (L1 deterministic → L2 local → L3 hosted frontier), with tier selection driven by the Policy Engine at the boundary. - **F-4.3 (MUST)** Every AI request MUST carry: Policy Validation result, Data Classification, Evidence References, Prompt Redaction manifest, Audit Metadata (CLAUDE.md § Sensitive-Operation Contract). - **F-4.4 (MUST)** L3 (hosted frontier) MUST be off by default. Enablement is per-tenant, per-classification, and MUST log an explicit consent event. - **F-4.5 (MUST)** Recommendations SHALL NOT execute actions in v0. They are human-reviewed suggestions only. (Automated response = Phase 3.) - **F-4.6 (MUST)** Every recommendation persists its input context hash so it can be reproduced and re-audited. - **F-4.7 (MUST)** The system MUST detect and refuse to process prompt-injection attempts embedded in ingested events. Mitigation strategy defined in ARCH-09. - **F-4.8 (SHOULD)** Low-confidence recommendations SHOULD be labeled as such and MUST NOT be presented as high-confidence. ### 4.5 Incident Timeline (Capability 5) - **F-5.1 (MUST)** For each case, produce a chronological timeline of related events, findings, and analyst actions. - **F-5.2 (MUST)** Every timeline entry links to its source event(s), finding(s), and evidence hash(es). - **F-5.3 (MUST)** Analyst annotations are additive — never overwrite prior state; edits are versioned. - **F-5.4 (MUST)** Timelines are exportable as signed, self-contained evidence bundles (schema in ARCH-13). - **F-5.5 (SHOULD)** Timelines are shareable read-only via signed URL with expiration and revocation. ### 4.6 Immutable Audit Trail (Capability 6) - **F-6.1 (MUST)** Every sensitive operation (per CLAUDE.md contract) MUST produce a **Layer A** append-only, hash-chained audit event. - **F-6.2 (MUST)** Layer A MUST NOT be blocked by Layer B failure. Layer A degrades only if the entire storage substrate is unavailable, in which case the platform fails closed on the operation being audited. - **F-6.3 (MUST)** **Layer B** produces asynchronous, cryptographically signed batches to durable archival storage. - **F-6.4 (MUST)** Both layers MUST be independently verifiable by third-party tooling using published schemas and public keys. - **F-6.5 (MUST)** Audit records MUST NOT contain secrets or PII beyond what is strictly necessary for the audit purpose; a redaction policy applies. - **F-6.6 (MUST)** Every audit event includes: `event_id`, `tenant_id`, `actor_id` (human/service/agent), `action`, `resource_ref`, `boundary_crossed`, `policy_decision`, `classification`, `trace_id`, `previous_hash`, `event_hash`, `timestamp`, `signer_key_id`. - **F-6.7 (MUST)** Audit tamper-evidence: any break in the hash chain MUST alert immediately and MUST be irreversibly recorded. ### 4.7 Cross-Cutting Functional Requirements - **F-X.1 (MUST)** Multi-tenant isolation at the data, config, key, and query layer. Cross-tenant data access requires explicit break-glass (F-X.7). - **F-X.2 (MUST)** Identity via OIDC (v0). SAML and SCIM by v1. - **F-X.3 (MUST)** RBAC with a minimum role set: Owner, Admin, Security Engineer, Analyst, Read-Only, Auditor. ABAC extension in v1. - **F-X.4 (MUST)** MFA enforcement is configurable per tenant; default is required for Owner, Admin, and Security Engineer. - **F-X.5 (MUST)** All human sessions are auditable and revocable. - **F-X.6 (MUST)** Every API call carries a trace ID propagated end-to-end. - **F-X.7 (MUST)** **Break-glass**: elevated access requires an explicit reason, a time-boxed grant, and produces a high-severity audit event. - **F-X.8 (MUST)** All configuration changes are versioned with rollback. ## 5. Non-Functional Requirements ### 5.1 Availability, RTO, RPO - **NF-1.1 (MUST)** Availability target for v0 self-hosted single-node: 99.5% during business hours (customer-defined). Multi-node deployment target 99.9% by v1. - **NF-1.2 (MUST)** **RTO** — 4 hours for a full restore of a single tenant's data on the same substrate. - **NF-1.3 (MUST)** **RPO** — 15 minutes for control-plane data; 5 minutes for audit-chain; 1 hour for event-plane raw data. All target values will be revised by ARCH-15. - **NF-1.4 (MUST)** Fail-secure: on partial degradation, ingestion pauses gracefully; on unrecoverable audit failure, the platform fails closed on the operation being audited. ### 5.2 Latency (indicative budgets, single-tenant, single-node) | Path | p50 | p95 | p99 | |---|---|---|---| | Ingest ACK | 50 ms | 200 ms | 500 ms | | Normalization → indexed | 500 ms | 2 s | 5 s | | Rule correlation match → finding | 500 ms | 2 s | 5 s | | Finding → AI recommendation (L1) | 100 ms | 500 ms | 1 s | | Finding → AI recommendation (L2, local model) | 3 s | 10 s | 20 s | | Finding → AI recommendation (L3, hosted) | 5 s | 15 s | 30 s | | UI: case load | 200 ms | 1 s | 2 s | | UI: timeline render (≤1k entries) | 500 ms | 2 s | 4 s | All numbers are targets for v0-GA; revised per ARCH-16 sizing. ### 5.3 Scale - **NF-3.1 (MUST)** Sustained ingest **10M events/day** per tenant on a reference single-node deployment. - **NF-3.2 (SHALL)** Sustained ingest **100M events/day** per tenant on a reference multi-node deployment by v1. - **NF-3.3 (MUST)** Event retention: **90 days hot** (event plane) + **1 year warm archival** by v0-GA. Configurable per tenant / per classification. - **NF-3.4 (MUST)** Audit retention: **7 years by default**, configurable up to legal hold. - **NF-3.5 (MUST)** Concurrent analyst sessions per tenant: **≥ 25** for v0 single-node. ### 5.4 Security (NF-4) Requirements below restate constitutional posture as verifiable NFRs. Detailed control design in ARCH-06, ARCH-10, ARCH-11. - **NF-4.1 (MUST)** All data at rest MUST be encrypted with per-tenant data-encryption keys wrapped by a KMS/HSM-backed key hierarchy. - **NF-4.2 (MUST)** All service-to-service traffic MUST use mTLS. - **NF-4.3 (MUST)** All external endpoints MUST use TLS 1.3 with a hardened cipher profile. - **NF-4.4 (MUST)** Secrets MUST NOT appear in logs, error messages, telemetry, or AI prompts. - **NF-4.5 (MUST)** All privileged operations MUST pass the Security Pipeline (CLAUDE.md). - **NF-4.6 (MUST)** Every sensitive operation MUST be Authorized, Logged, Auditable, Traceable, Recoverable. - **NF-4.7 (MUST)** The system MUST detect and block prompt-injection attempts in AI paths (ARCH-09). - **NF-4.8 (MUST)** No offensive capability, ever (CLAUDE.md § Defensive-Only). ### 5.5 Privacy (NF-5) - **NF-5.1 (MUST)** Data minimization: collect only what serves a documented defensive purpose. - **NF-5.2 (MUST)** PII redaction pipeline in the normalization stage; per-tenant redaction policy. - **NF-5.3 (MUST)** Tenant data residency selectable at deployment time (self-hosted) or at tenant provisioning (hosted, future). - **NF-5.4 (MUST)** Right-to-erasure supported for tenant-scoped personal data, subject to legal-hold overrides. - **NF-5.5 (MUST)** AEGIS itself MUST minimize telemetry back to us; every outbound telemetry channel MUST be opt-in and documented. ### 5.6 Compliance Targets - **NF-6.1 (SHALL by v1)** SOC 2 Type II. - **NF-6.2 (SHALL by v1)** ISO 27001 controls mapped. - **NF-6.3 (SHOULD by v1)** HIPAA readiness (BAA-supportable, not certification). - **NF-6.4 (SHOULD by v1.x)** FedRAMP Moderate readiness (not certification in v1). - **NF-6.5 (SHOULD)** GDPR compliance for EU tenants. - **NF-6.6 (MUST for v0)** SLSA build-provenance level 3 minimum for AEGIS artifacts. ### 5.7 Observability - **NF-7.1 (MUST)** All services emit structured logs, metrics (Prometheus/OpenMetrics), and traces (OpenTelemetry). - **NF-7.2 (MUST)** AEGIS's own audit trail is separated from operational logs; they MUST NOT share storage or key material. - **NF-7.3 (MUST)** Health, readiness, and liveness endpoints for every service. ### 5.8 Deployment Matrix - **NF-8.1 (MUST)** Runs on Linux (x86_64, arm64). - **NF-8.2 (MUST)** Runs in Docker (single-node) and Kubernetes (multi-node). - **NF-8.3 (SHALL)** Runs on Windows Server (control-plane services) by v1. - **NF-8.4 (SHOULD)** Runs on macOS for developer workstations only. - **NF-8.5 (MUST)** Runs on VPS (single-node) and private cloud (self-hosted K8s). - **NF-8.6 (MUST)** Runs on AWS, Azure, GCP in customer-owned accounts (self-hosted). AEGIS-managed hosted mode is v1+. - **NF-8.7 (MUST)** **Air-gapped deployment** is a supported topology: no outbound network required at runtime; updates delivered as signed bundles. - **NF-8.8 (MUST)** All deployment topologies MUST pass the "cloud-off integration test" — full v0 functional test with no external network egress. ### 5.9 Maintainability - **NF-9.1 (MUST)** Every subsystem is independently replaceable (CLAUDE.md § Additional Principle 2). - **NF-9.2 (MUST)** No vendor lock-in on data plane, control plane, message bus, identity, or AI provider. - **NF-9.3 (MUST)** Every architectural document is versioned and cross-referenced. - **NF-9.4 (MUST)** SBOM published per release; all third-party components tracked. ### 5.10 Usability / Accessibility - **NF-10.1 (SHOULD)** UI MUST meet WCAG 2.1 AA for critical flows in v0-GA. - **NF-10.2 (SHOULD)** UI supports English at v0; localization scaffold present. ## 6. Constraints - **C-1.** Defensive-only. Any offensive capability is disqualifying regardless of business case. - **C-2.** Architecture First, Implementation Second, Optimization Last. - **C-3.** Provider-independent AI. No frontier-provider hard dependency. - **C-4.** Self-hostable and air-gappable — always. Hosted mode is *additional*, never *replacing*. - **C-5.** TypeScript / Node.js as the primary implementation language (from decisions memo). - **C-6.** Next.js (App Router) as the primary UI; Tauri desktop deferred to v0.2 as a thin viewer. - **C-7.** PostgreSQL + Prisma (control plane) and ClickHouse (event plane) — two-plane split. - **C-8.** Kafka / Redpanda (event bus) and NATS (control/RPC/realtime). - **C-9.** Data classification: Public / Internal / Confidential / Restricted / Highly Restricted. - **C-10.** No feature bypasses the Security Pipeline. ## 7. Out of Scope for v0 Explicitly out of v0 to keep the release trustworthy: - Endpoint agent (kernel-mode, EDR-class). - Automated response actions (SOAR-style playbooks executing changes). - Multi-tenant hosted control plane (MSSP). - Cloud posture management (CSPM). - Asset inventory and CMDB. - Risk scoring across assets. - Threat-intel correlation with commercial feeds. - Central dashboard beyond the case/timeline view. - Vulnerability management. - Mobile UI. Each is sequenced in ARCH-18 with entry criteria. ## 8. Assumptions - **AS-1.** Customer supplies at least one log source at deployment; AEGIS is not responsible for source-side agent development in v0. - **AS-2.** Customers with air-gap can accept L2-only recommendation quality. - **AS-3.** A single-node Kubernetes deployment on commodity hardware (16 vCPU, 64 GB RAM, NVMe) can meet NF-3.1 ingest scale (10M events/day). Validated in ARCH-16. - **AS-4.** OCSF v1.x is stable enough to base normalization on. Contingency: adapter layer allows alternate schema. - **AS-5.** Enterprise customers accept OIDC as the sole IdP protocol for v0. ## 9. Decisions ### D-02-1. OCSF as canonical event schema baseline - **Advantages.** Open, vendor-neutral, industry-backed (Splunk, IBM, AWS, Cloudflare), broad taxonomy, growing tooling. - **Disadvantages.** Still maturing; some categories underspecified; risk of vendor drift. - **Security Impact.** *Positive* — standard schema improves detection portability and reduces normalization bugs (a class of silent-drop risk). - **Operational Impact.** Requires ongoing schema-version tracking. - **Scalability.** Neutral. - **Maintainability.** *Positive* — reduces bespoke mapping work. - **Future Expansion.** Interoperable with other OCSF adopters. - **Risk Assessment.** *Low-medium.* Schema churn is manageable via `normalization_version`. - **Alternatives.** - *Elastic Common Schema (ECS).* Mature but Elastic-adjacent; less industry-broad. Rejected as primary. - *Custom schema.* Maximum control, worst interoperability, highest maintenance. Rejected. - **Reason.** Provider-independence principle favors open, multi-vendor standards. Escape hatch: alternate schema adapter. ### D-02-2. Air-gap as a first-class deployment topology (not a checkbox) - **Advantages.** Serves government/defense/critical-infra/regulated segments; forces architectural discipline (no runtime external calls); increases trust. - **Disadvantages.** Constrains AI quality to L1+L2; increases release engineering complexity (signed offline bundles). - **Security Impact.** *Strongly positive.* Removes an entire class of egress risks. - **Operational Impact.** Non-trivial — update path is more complex. - **Scalability.** Neutral. - **Maintainability.** Forces clean provider-independence. - **Future Expansion.** Enables sovereign / classified variants later. - **Risk Assessment.** *Medium.* Complexity; mitigated by testing cadence. - **Alternatives.** - *Air-gap as "supported" but not tested per release.* History shows this decays. Rejected. - *Air-gap as post-v1 add-on.* Retrofit is harder and less credible. Rejected. - **Reason.** Trust posture and market segment justify the discipline cost. ### D-02-3. Human-in-the-loop for all v0 recommendations - **Advantages.** Eliminates a whole class of AI-caused incidents; aligns with regulatory direction; simpler safety story. - **Disadvantages.** Slower response time; some prospective customers want automation. - **Security Impact.** *Strongly positive.* No AI action can independently modify a customer's environment in v0. - **Operational Impact.** Analysts see more work; but they see it *with evidence*, not blind. - **Scalability.** Neutral. - **Maintainability.** Higher — simpler failure modes. - **Future Expansion.** Automated response opens as a Phase 3 capability with governance (ARCH-14 / ARCH-18). - **Risk Assessment.** *Very low* for v0. - **Alternatives.** - *Limited auto-response for "safe" actions.* "Safe" is context-dependent and hostile inputs can flip that assumption. Rejected for v0. - **Reason.** No AI system in 2026 is trustworthy enough to hold live production-modifying authority in a security-critical context without gates. ### D-02-4. OIDC-only IdP protocol for v0 - **Advantages.** Modern, JSON/JWT, widely supported, simpler than SAML. - **Disadvantages.** Excludes enterprises that only speak SAML. - **Security Impact.** *Neutral.* Both protocols are secure when configured well. - **Operational Impact.** Simpler support surface at launch. - **Scalability.** Neutral. - **Maintainability.** *Positive* — one protocol to secure. - **Future Expansion.** SAML + SCIM in v1. - **Risk Assessment.** *Medium.* Market gap for SAML-only enterprises. - **Alternatives.** - *OIDC + SAML at v0.* Doubles auth surface and testing. Rejected for v0. - **Reason.** Ship narrow and correct in v0; add SAML with proper testing in v1. ## 10. Verification Plan Each requirement must map to a verification method by ARCH-12 (Secure Coding Standard) and ARCH-16 (Deployment Architecture). Methods: **T** = automated test, **R** = review, **A** = audit, **D** = demonstration. Traceability matrix will be maintained in `docs/traceability.md` starting Phase B. ## 11. Open Questions - Q-02-1. Exact cloud-provider connector to prioritize for F-1.3 (AWS CloudTrail vs Azure Activity Log vs GCP Audit Logs). Resolved in ARCH-18. - Q-02-2. Baseline compliance certification for v1 (SOC 2 Type II vs ISO 27001 first). Depends on customer segment. - Q-02-3. Reference hardware sizing for NF-3.1 target. Resolved in ARCH-16. - Q-02-4. RTO/RPO refinement per data class. Resolved in ARCH-15. ## 12. Change Log - **0.1 (2026-07-10)** — Initial draft for Phase A review.