cert-fabric — Architecture

cert-fabric — Architecture

Components

┌──────────────────────────────────────────────────────────────────────────┐
│                       cert-fabric service (port 48030)                   │
│                                                                          │
│  ┌──────────────────┐   ┌──────────────────────────────────────────────┐ │
│  │ FastAPI surface  │   │              Orchestrator                    │ │
│  │ (api/server.py)  ├──>│  Stage 0: manifest intake (manifest.py)      │ │
│  │  POST /run       │   │  Stage 1: static gates (stages/static_gates) │ │
│  │  GET /verdict    │   │  Stage 2: provenance (stages/provenance)     │ │
│  │  GET /metrics    │   │  Stage 3: test exec + R-8 (stages/test_exec) │ │
│  │  /healthz /readyz│   │  Stage 4: vuln scan (stages/vuln_scan)       │ │
│  └──────────────────┘   │  Stage 5: verdict (stages/verdict)           │ │
│           ▲             │  Stage 5.5: redaction (evidence/redaction)   │ │
│           │             │  Stage 6: sealing (stages/evidence_sealing)  │ │
│  ┌──────────────────┐   │  Stage 7: ledger (ledger/factory)            │ │
│  │ CLI              │   │  Stage 8: teardown verify (runners/isolation)│ │
│  │ (cli/main.py)    │──>│                                              │ │
│  │  --local mode    │   └──────────────────────────────────────────────┘ │
│  │                  │              │                  │                  │
│  └──────────────────┘              │                  │                  │
│                                    ▼                  ▼                  │
│                          ┌─────────────────┐  ┌─────────────────┐        │
│                          │ Ledger (sqlite  │  │ Evidence bundle │        │
│                          │  or postgres)   │  │  storage (S3/   │        │
│                          │  cert_runs +    │  │  local fs)      │        │
│                          │  cert_birth_    │  │                 │        │
│                          │  events outbox  │  │  per-run dirs   │        │
│                          └─────────────────┘  └─────────────────┘        │
└──────────────────────────────────────────────────────────────────────────┘
        │                          │                            │
        │ POST verify              │ Read PR context            │ Submit pytest
        ▼                          ▼                            ▼
   ┌──────────┐               ┌──────────┐                ┌──────────────┐
   │ Sigstore │               │ GitHub   │                │ Quality-     │
   │ Fulcio/  │               │ App API  │                │ Fabric       │
   │ Rekor    │               │          │                │ (optional)   │
   │ (cosign) │               │          │                │              │
   └──────────┘               └──────────┘                └──────────────┘

API surface

Module map

src/cert_fabric/
├── __init__.py                # version, predicate_type, port, log init
├── logging_config.py          # structlog + secret-redaction processor
├── manifest.py                # cert.manifest.yaml v1 schema (pydantic)
├── api/
│   └── server.py              # FastAPI app — production surface
├── cli/
│   └── main.py                # Typer CLI — local mode + ops commands
├── stages/
│   ├── static_gates.py        # Stage 1 — R-1..R-7 static integrity
│   ├── provenance.py          # Stage 2 — cosign verify-attestation
│   ├── test_executor.py       # Stage 3 — pytest + R-8 typed DB
│   ├── vuln_scan.py           # Stage 4 — Trivy / Grype
│   ├── verdict.py             # Stage 5 — 10-clause + maturity score
│   ├── evidence_sealing.py    # Stage 6 — Cosign-attested proof manifest
│   └── contract_compat.py     # N-1 backward compat check
├── runners/
│   ├── orchestrator.py        # wire all stages together
│   ├── self_test.py           # Stage 8 — adversarial matrix
│   └── isolation.py           # scorched-earth env + Docker hygiene
├── ledger/
│   ├── factory.py             # sqlite:// or postgresql:// dispatch
│   ├── sqlite_ledger.py       # dev/local backend
│   └── postgres_ledger.py     # production backend w/ pool + WAL
├── evidence/
│   └── redaction.py           # pre-seal secret-shape scanner
└── parity/
    ├── __init__.py
    └── assertions.py          # shared Bucket D/E behavioral parity suite

Key invariants (from v8.1 spec)

1. Verification ≠ Provenance — CertaaS attests testing (Tier-2 signature, cert-fabric/v2 predicate); CI builder attests creation (Tier-1 signature, SLSA provenance predicate).
2. Test before Sign — Stage 6 sealing + deploy-authoritative signing occur ONLY after Stages 3-4 PASS. Failed tests = no signature = no deploy.
3. Hard gates override score — A 95/100 score with one FAIL clause still produces verdict FAIL.
4. Server-derived PR context — caller hints are advisory; CertaaS rederives base/head/files/actor/labels from GitHub API.
5. R-8 typed — postgres | none | other; no silent passes on non-Postgres services.
6. BirthEvent internal-only until TLA-11 — outbox row written on PASS; NATS publisher worker deferred.
7. Secret leak = BLOCK — pre-seal redaction scanner forces verdict BLOCK on any non-mock secret-shaped string in the bundle.
8. Scorched-earth env — subprocesses see only the whitelist; operator's shell vars (OPENAI_API_KEY, AWS_*, etc.) never leak through.
9. Idempotent ledger writes — re-submitting the same run_id updates without duplicating.
10. Self-test on every release — 7-mode adversarial fixtures run weekly + on deploy; runner is suspect until all 7 are green.

Decision trail

The architecture is the result of 6 rounds of independent review:

Full traceability at delivery/MODULARITY-CERT-FRAMEWORK-V1-ARCHITECTURE-REVIEW-2026-05-22.md (../../delivery/MODULARITY-CERT-FRAMEWORK-V1-ARCHITECTURE-REVIEW-2026-05-22.md) §A1-§A8.

Scaling considerations (deferred to v0.3)