git.stella-ops.org/docs/modules/attestor

StellaOps Attestor

Attestor converts signed DSSE evidence from the Signer into transparency-log proofs and verifiable reports for every downstream surface (Policy Engine, Export Center, CLI, Console, Scheduler). It is the trust backbone that proves SBOM, scan, VEX, and policy artefacts were signed, witnessed, and preserved without tampering.

Why it exists

• Evidence first: organisations need portable, verifiable attestations that prove build provenance, SBOM availability, policy verdicts, and VEX statements.
• Policy enforcement: verification policies ensure only approved issuers, key types, witnesses, and freshness windows are accepted.
• Sovereign/offline-ready: Attestor archives envelopes, signatures, and proofs so air-gapped deployments can replay verification without contacting external services.

Roles & surfaces

• Subjects: immutable digests for container images, SBOMs, reports, and policy bundles.
• Issuers: builders, scanners, policy engines, or operators signing DSSE envelopes using keyless (Fulcio), KMS/HSM, or FIDO2 keys.
• Consumers: CLI/SDK, Console, Export Center, Scanner, Policy Engine, and Notify retrieving verification bundles or triggering policy checks.
• Scopes: Authority issues attestor.write, attestor.verify, attestor.read, and administrative scopes for issuer/key management; every call is bound with mTLS + DPoP.

Supported payloads

• StellaOps.BuildProvenance@1, StellaOps.SBOMAttestation@1
• StellaOps.ScanResults@1, StellaOps.VEXAttestation@1
• StellaOps.PolicyEvaluation@1, StellaOps.RiskProfileEvidence@1 All predicates capture subjects, issuer metadata, policy context, materials, optional witnesses, and versioned schemas. Unsupported predicates return 422 predicate_unsupported.

Trust & envelope model

• DSSE envelopes are canonicalised, hashed, and stored alongside the Rekor UUID, index, and proof.
• Signature modes span keyless (Fulcio), keyful (KMS/HSM), and hardware-backed (FIDO2). Multiple signatures are supported per envelope.
• Proofs include Merkle inclusion path, checkpoint metadata, optional witness endorsements, and cached verification verdicts.
• CAS/object storage retains envelopes + provenance for later replay; Rekor backends may be primary plus mirrors.

Security hardening

• attestor.write, attestor.verify, and attestor.read scopes are enforced per endpoint; verify/list flows accept read/verify scopes while submissions remain write-only.
• JSON content-type is mandatory; malformed content returns 415 unsupported_media_type.
• DSSE payloads are capped at 2 MiB (configurable), certificate chains at six entries, and each envelope may carry up to six signatures to contain parsing abuse.
• All verification/list APIs share the token-bucket rate limiter (quotas.perCaller) in addition to the existing submission limiter.

UI, CLI, and SDK workflows

• Console: Evidence browser, verification reports, chain-of-custody graph, issuer/key management, attestation workbench, and bulk verification flows.
• CLI / SDK: stella attest sign|verify|list|fetch|key commands plus language SDKs to integrate build pipelines and offline verification scripts.
• Policy Studio: Verification policies author required predicate types, issuers, witness requirements, and freshness windows; simulations show enforcement impact.

Storage, offline & air-gap posture

• MongoDB stores entry metadata, dedupe keys, and audit events; object storage optionally archives DSSE bundles.
• Export Center packages attestation bundles (stella export attestation-bundle) for Offline Kit delivery.
• Transparency logs can be mirrored; offline mode records gaps and provides compensating controls.

Observability & performance

• Metrics: attestor_submission_total, attestor_verify_seconds, attestor_cache_hit_ratio, attestor_rekor_latency_seconds.
• Logs capture tenant, issuer, subject digests, Rekor UUID, proof status, and policy verdict.
• Performance target: ≥1 000 envelopes/minute per worker with cached verification, batched operations, and concurrency controls.

Key integrations

• Signer (DSSE source), Authority (scopes & tenancy), Export Center (attestation bundles), Policy Engine (verification policies), Scanner/Excititor (subject evidence), Notify (key rotation & verification alerts), Observability stack (dashboards/alerts).

Backlog references

• DOCS-ATTEST-73-001 … DOCS-ATTEST-75-002 (Attestor console, key management, air-gap bundles) in ../../TASKS.md.
• EXPORT-ATTEST-75-002 (Export Center attestation packaging) in ../export-center/TASKS.md.

Epic alignment

• Epic 19 – Attestor Console: console experience, verification APIs, issuer/key governance, transparency integration, and offline bundles.
• Epic 10 – Export Center: provenance alignment so exports carry signed manifests and attestation bundles.

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.