12 KiB
12 KiB
Stella Ops Reference Architecture Card (Dec 2025)
One-Pager for product managers, architects, and auditors. Full specification:
docs/ARCHITECTURE_OVERVIEW.md
Topology & Trust Boundaries
┌─────────────────────────────────────────────────────────────────────────────┐
│ TRUST BOUNDARY 1 │
│ ┌─────────────────┐ │
│ │ EDGE LAYER │ StellaRouter (Gateway) / UI │
│ │ │ OAuth2/OIDC Authentication │
│ └────────┬────────┘ │
│ │ Signed credentials/attestations required │
├───────────┼─────────────────────────────────────────────────────────────────┤
│ ▼ TRUST BOUNDARY 2 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CONTROL PLANE │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │Scheduler │ │ Policy │ │Authority │ │ Attestor │ │ │
│ │ │ │ │ Engine │ │ │ │ │ │ │
│ │ │ Routes │ │ Signed │ │ Keys & │ │ DSSE + │ │ │
│ │ │ work │ │ verdicts │ │ identity │ │ Rekor │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ Timeline / Notify │ │ │
│ │ │ Immutable audit + notifications │ │ │
│ │ └──────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ Only blessed evidence/identities influence decisions │
├───────────┼─────────────────────────────────────────────────────────────────┤
│ ▼ TRUST BOUNDARY 3 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ EVIDENCE PLANE │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Sbomer │ │Excititor │ │Concelier │ │Reachabil-│ │ │
│ │ │ │ │ │ │ │ │ity/Sigs │ │ │
│ │ │CDX 1.7 / │ │ VEX │ │Advisory │ │ Is vuln │ │ │
│ │ │SPDX 3.0.1│ │ claims │ │ feeds │ │reachable?│ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ Tamper-evident, separately signed; opinions in Policy only │
├───────────┼─────────────────────────────────────────────────────────────────┤
│ ▼ TRUST BOUNDARY 4 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ DATA PLANE │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ Workers / Scanners │ │ │
│ │ │ Pull tasks → compute → emit artifacts + attestations │ │ │
│ │ │ Isolated per tenant; outputs tied to inputs cryptographically│ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Artifact Association (OCI Referrers)
Image Digest (Subject)
│
├──► SBOM (CycloneDX 1.7 / SPDX 3.0.1)
│ └──► DSSE Attestation
│ └──► Rekor Log Entry
│
├──► VEX Claims
│ └──► DSSE Attestation
│
├──► Reachability Subgraph
│ └──► DSSE Attestation
│
└──► Policy Verdict
└──► DSSE Attestation
└──► Rekor Log Entry
- Every artifact is a subject in the registry
- SBOMs, VEX, verdicts attached as OCI referrers
- Multiple versioned, signed facts per image without altering the image
Data Flows
Evidence Flow
Workers ──► SBOM (CDX 1.7) ──► DSSE Sign ──► OCI Referrer ──► Registry
├─► VEX Claims ──► DSSE Sign ──► OCI Referrer ──►
├─► Reachability ──► DSSE Sign ──► OCI Referrer ──►
└─► All wrapped as in-toto attestations
Verdict Flow
Policy Engine ──► Ingests SBOM/VEX/Reachability/Signals
──► Applies rules (deterministic IR)
──► Emits signed verdict
──► Verdict attached via OCI referrer
──► Replayable: same inputs → same output
Audit Flow
Timeline ──► Captures all events (immutable)
──► Links to attestation digests
──► Enables replay and forensics
Tenant Isolation
| Layer | Mechanism |
|---|---|
| Database | PostgreSQL RLS (Row-Level Security) |
| Application | AsyncLocal tenant context |
| Storage | Tenant-scoped paths |
| Crypto | Per-tenant keys & trust roots |
| Network | Tenant header propagation |
Minimal Day-1 Policy
rules:
# Block reachable HIGH/CRITICAL unless VEX says not_affected
- match: { severity: [CRITICAL, HIGH], reachability: reachable }
unless: { vexStatus: not_affected }
action: block
# Fail on >5% unknowns
- match: { unknownsRatio: { gt: 0.05 } }
action: block
# Require signed SBOM + verdict for production
- match: { environment: production }
require: { signedSbom: true, signedVerdict: true }
SBOM Format Support
| Format | Generation | Parsing | Notes |
|---|---|---|---|
| CycloneDX 1.7 | Yes | Yes | Primary format |
| CycloneDX 1.6 | - | Yes | Backward compat |
| SPDX 3.0.1 | Yes | Yes | Alternative format |
| SPDX 2.x | - | Yes | Import only |
Key Capabilities
| Capability | Status | Notes |
|---|---|---|
| Deterministic SBOMs | Complete | Same input → same output |
| Signed Verdicts | Complete | DSSE + in-toto |
| Replayable Verdicts | Complete | Content-addressed proofs |
| OCI Referrers | Complete | Subject digest model |
| Rekor Transparency | Complete | v2 tile-backed |
| Tenant Isolation | Complete | RLS + crypto separation |
| Air-Gap Operation | Complete | Offline bundles |
| CycloneDX 1.7 | Planned | Sprint 3600.0002 |
| SPDX 3.0.1 Generation | Planned | Sprint 3600.0003 |
| Gateway WebService | Planned | Sprint 3600.0001 |
| Proof Chain UI | Planned | Sprint 4200.0001 |
Quick Glossary
| Term | Definition |
|---|---|
| SBOM | Software Bill of Materials (what's inside) |
| VEX | Vulnerability Exploitability eXchange (is CVE relevant?) |
| Reachability | Graph proof that vulnerable code is (not) callable |
| DSSE | Dead Simple Signing Envelope |
| in-toto | Supply chain attestation framework |
| OCI Referrers | Registry mechanism to link artifacts to image digest |
| OpTok | Short-lived operation token from Authority |
| DPoP | Demonstrating Proof of Possession (RFC 9449) |
Implementation Sprints
| Sprint | Title | Priority |
|---|---|---|
| 3600.0001.0001 | Gateway WebService | HIGH |
| 3600.0002.0001 | CycloneDX 1.7 Upgrade | HIGH |
| 3600.0003.0001 | SPDX 3.0.1 Generation | MEDIUM |
| 4200.0001.0001 | Proof Chain Verification UI | HIGH |
| 5200.0001.0001 | Starter Policy Template | HIGH |
Audit Checklist
- All SBOMs have DSSE signatures
- All verdicts have DSSE signatures
- Rekor log entries exist for production artifacts
- Tenant isolation verified (RLS + crypto)
- Replay tokens verify (same inputs → same verdict)
- Air-gap bundles include all evidence
- OCI referrers discoverable for all images
Source: Reference Architecture Advisory (Dec 2025) Last Updated: 2025-12-21