stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7600caea632e9e44571bc1661003948a5e1d22fb
git.stella-ops.org/docs/modules/attestor
History
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
2025-10-30 00:09:39 +02:00
..
AGENTS.md
feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
2025-10-30 00:09:39 +02:00
architecture.md
feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
2025-10-30 00:09:39 +02:00
implementation_plan.md
feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
2025-10-30 00:09:39 +02:00
README.md
feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
2025-10-30 00:09:39 +02:00
TASKS.md
feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
2025-10-30 00:09:39 +02:00

README.md

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.

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.