master
53503cb407
- Created a new document for the Stella Ops Reference Architecture outlining the system's topology, trust boundaries, artifact association, and interfaces. - Developed a comprehensive Testing Strategy document detailing the importance of offline readiness, interoperability, determinism, and operational guardrails. - Introduced a README for the Testing Strategy, summarizing processing details and key concepts implemented. - Added guidance for AI agents and developers in the tests directory, including directory structure, test categories, key patterns, and rules for test development.
224 lines
12 KiB
Markdown
224 lines
12 KiB
Markdown
# Stella Ops Reference Architecture Card (Dec 2025)
|
|
|
|
> **One-Pager** for product managers, architects, and auditors.
|
|
> Full specification: `docs/07_HIGH_LEVEL_ARCHITECTURE.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
|
|
|
|
```yaml
|
|
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
|