git.stella-ops.org/docs/modules/scanner/operations/dsse-rekor-operator-guide.md

DSSE & Rekor Operator Enablement Guide

Audience. Scanner / Export Center operators, platform SREs, and field engineers bringing DSSE attestations + Rekor proofs into production (online or air-gapped).

Sources. Aligns with Sprint 138 (SCANNER-ENG-0015) gap analysis (§DSSE/Rekor operator enablement) and Scanner architecture specs.

---

1. Why this matters

• Evidence on demand. Every SBOM, diff, and report can be bound to a DSSE envelope issued by StellaOps.Signer, logged to Rekor via StellaOps.Attestor, and bundled for export/offline use.
• Policy leverage. Policy Engine predicates gate releases until attestations exist and their Rekor proofs verify, reducing “unsigned” drift.
• Regulatory readiness. Operators need a deterministic playbook to satisfy PCI, FedRAMP, EU CRA, and national sovereignty requirements without phoning home.

---

2. Components & responsibilities

Component	Role	Key references
StellaOps.Signer	Issues DSSE envelopes using PoE-scoped keys (Fulcio or BYO KMS/HSM).	ops/devops/signing/
StellaOps.Attestor	Submits DSSE payloads to Rekor v2, caches {uuid,index,proof} and mirrors proofs offline.	docs/modules/attestor/architecture.md
Rekor v2 (managed or self-hosted)	Transparency log providing UUIDs + inclusion proofs.	docs/ops/rekor/README.md (if self-hosted)
StellaOps.Scanner (WebService/Worker)	Requests attestations per scan, stores Rekor metadata next to SBOM artefacts.	docs/modules/scanner/architecture.md
Export Center	Packages DSSE payloads + proofs into Offline Kit bundles and mirrors license notices.	docs/modules/export-center/architecture.md
Policy Engine + CLI	Enforce “attested only” promotion, expose CLI verification verbs.	docs/modules/policy/architecture.md, docs/09_API_CLI_REFERENCE.md

---

3. Prerequisites checklist

1. Keys & trust roots
   • Fulcio / KMS credentials available to StellaOps.Signer.
   • Rekor public key pinned (rekor.pub) for verification jobs and CLI tooling.
2. Service wiring
   • scanner.attestation.signerEndpoint → internal Signer base URL.
   • scanner.attestation.attestorEndpoint → Attestor base URL.
   • attestor.rekor.api & attestor.rekor.pubkey set for the target log.
3. Storage
   • Mongo collections attestations & rekorProofs sized for retention (7–30 days recommended).
   • Object store tier with at-rest encryption for DSSE payloads.
4. Observability
   • Metrics: attestor_rekor_success_total, attestor_rekor_retry_total, rekor_inclusion_latency.
   • Logs shipped to your SIEM for compliance (Signer request/response IDs, Rekor UUIDs).
5. Offline readiness
   • Export Center profile with attestations.bundle=true.
   • Rekor log snapshots mirrored (ORAS bundle or rsync of /var/log/rekor) for disconnected verification.

3.1 Configuration & env-var map

Service	Key(s)	Env override	Notes
Scanner WebService / Worker	scanner.attestation.signerEndpoint scanner.attestation.attestorEndpoint scanner.attestation.requireDsse scanner.attestation.uploadArtifacts	SCANNER__ATTESTATION__SIGNERENDPOINT SCANNER__ATTESTATION__ATTESTORENDPOINT SCANNER__ATTESTATION__REQUIREDSSE SCANNER__ATTESTATION__UPLOADARTIFACTS	Worker/WebService share the same config. Set requireDsse=false while observing, then flip to true. uploadArtifacts=true stores DSSE+Rekor bundles next to SBOM artefacts.
Signer	signer.attestorEndpoint signer.keyProvider signer.fulcio.endpoint	SIGNER__ATTESTORENDPOINT etc.	attestorEndpoint lets Signer push DSSE payloads downstream; key provider controls BYO KMS/HSM vs Fulcio.
Attestor	attestor.rekor.api attestor.rekor.publicKeyPath attestor.rekor.offlineMirrorPath attestor.retry.maxAttempts	ATTESTOR__REKOR__API ATTESTOR__REKOR__PUBLICKEYPATH ATTESTOR__REKOR__OFFLINEMIRRORPATH ATTESTOR__RETRY__MAXATTEMPTS	Mirror path points at the local snapshot directory used in sealed/air-gapped modes.
Export Center	exportProfiles.<name>.includeAttestations exportProfiles.<name>.includeRekorProofs	EXPORTCENTER__EXPORTPROFILES__SECURE-DEFAULT__INCLUDEATTESTATIONS etc.	Use profiles to gate which bundles include DSSE/Reco r data; keep a “secure-default” profile enabled across tiers.

Tip: Every key above follows the ASP.NET Core double-underscore pattern. For Compose/Helm, add environment variables directly; for Offline Kit overrides, drop appsettings.Offline.json with the same sections.

---

4. Enablement workflow

4.1 Configure Signer & Attestor

signer:
  schemaVersion: 2
  keyProvider: kms-fleet
  attestorEndpoint: https://attestor.internal
  defaultPredicate: https://stella-ops.org/attestations/sbom/1

attestor:
  schemaVersion: 1
  rekor:
    api: https://rekor.internal
    publicKeyPath: /etc/rekor/rekor.pub
    offlineMirrorPath: /var/lib/rekor/snapshots
  retry:
    maxAttempts: 5
    backoffSeconds: 15

4.2 Turn on Scanner enforcement

scanner:
  schemaVersion: 2
  attestation:
    requireDsse: true          # fail scans when Signer/Attestor errors occur
    signerEndpoint: https://signer.internal
    attestorEndpoint: https://attestor.internal
    uploadArtifacts: true      # store DSSE + proof next to SBOM artefacts

Set requireDsse=false during observation, then flip to true once Rekor health SLOs are green.

4.3 Policy templates

Add Policy Engine predicates (Rego snippet):

package stella.policies.attestation

deny[msg] {
  not input.attestations.rekor_verified
  msg := sprintf("missing Rekor proof for %s", [input.scan_id])
}

warn[msg] {
  input.attestations.rekor_age_hours > 24
  msg := sprintf("Rekor proof older than 24h for %s", [input.scan_id])
}

Tie Scheduler or CI promotion gates to the deny result.

4.4 CLI and verification

• stellaops-cli runtime policy test --image <digest> --json already surfaces attestation.uuid and rekorVerified fields.
• To validate bundles offline: stellaops-cli attest verify --bundle path/to/export.tar --rekor-key rekor.pub.

Document these flows for AppSec teams so they can self-serve proofs during audits.

4.5 Export Center profile

exportProfiles:
  secure-default:
    includeSboms: true
    includeAttestations: true
    includeRekorProofs: true
    policy:
      requireAttestations: true
      allowUnsigned: false

---

5. Rollout levers & phases

Phase	Toggle	Goal
Observe	scanner.attestation.requireDsse=false, policies in warn mode.	Validate plumbing without blocking builds; capture metrics.
Enforce	Flip requireDsse=true, policy deny for missing proofs, Rekor SLO alerts live.	Block unsigned artefacts; auto-retry attestor failures.
Escalate	Export Center profile includeAttestations=true, CLI docs distributed, Notify alerts wired.	Broad communication + audit evidence ready.

Roll forward per environment; keep the previous phase’s toggles for hot rollback.

---

6. Offline / air-gap guidance

1. Mirror Rekor: take log snapshots daily (rekor-cli log export) and add to the Offline Kit.
2. Bundle proofs: Export Center must include *.rekor.json and rekor-chain.pem alongside DSSE envelopes.
3. CLI verification offline:

   stellaops-cli attest verify --bundle offline-kit.tar \
     --rekor-root hashsum.txt --rekor-tree treehead.json --rekor-key rekor.pub
   

4. Fallback: When Rekor connectivity is unavailable, Attestor queues submissions locally and emits attestationPending=true; policy can allow waivers for a limited TTL via policy.attestations.deferHours.

---

7. Troubleshooting

Symptom	Checks	Resolution
attestationPending flag stays true	attestor_rekor_retry_total, Attestor logs, Rekor /healthz.	Verify Rekor endpoint & certs; rotate API tokens; replay queued DSSE payloads via attestor replay.
Policy denies despite DSSE	Confirm Rekor proof bundle stored under /artifacts/<scanId>/rekor/.	Re-run stellaops-cli attest verify, ensure Policy Engine has the new schema (attestations.rekor_verified).
CLI verification fails offline	Ensure Rekor snapshot + rekor.pub shipped together; check timestamp gap.	Regenerate snapshot, or import Rekor entries into the isolated log before verifying.

---

8. Operational runbook & SLO guardrails

Step	Owner	Target / Notes
Health gate	Ops/SRE	attestor_rekor_success_total ≥ 99.5% rolling hour, rekor_inclusion_latency_p95 ≤ 30s. Alert when retries spike or queue depth > 50.
Cutover dry-run	Scanner team	Set SCANNER__ATTESTATION__REQUIREDSSE=false, watch metrics + Attestor queue for 24h, capture Rekor proofs per environment.
Enforce	Platform	Flip requireDsse=true, promote Policy rule from warn → deny, notify AppSec + release managers.
Audit proof pack	Export Center	Run secure profile nightly; confirm attestations/ + rekor/ trees attached to Offline Kit. Store bundle hash in Evidence Locker.
Verification spot-check	AppSec	Weekly stellaops-cli attest verify --bundle latest.tar --rekor-key rekor.pub --json saved to ticket for auditors.
Rollback	Ops/SRE	If Rekor outage exceeds 15 min: set requireDsse=false, keep policy in warn, purge Attestor queue once log recovers, then re-enable. Document the waiver in the sprint log.

Dashboards & alerts

• Grafana panel: Rekor inclusion latency (p50/p95) + Attestor retry rate.
• Alert when attestationPending=true events exceed 5 per minute for >5 minutes.
• Logs must include rekorUuid, rekorLogIndex, attestationDigest for SIEM correlation.

Runbook snippets

# test Rekor health + key mismatch
rekor-cli loginfo --rekor_server "${ATTESTOR__REKOR__API}" --format json | jq .rootHash

# replay stranded payloads after outage
stellaops-attestor replay --since "2025-11-13T00:00:00Z" \
  --rekor ${ATTESTOR__REKOR__API} --rekor-key /etc/rekor/rekor.pub

# verify a single DSSE file against Rekor proof bundle
stellaops-cli attest verify --envelope artifacts/scan123/attest/sbom.dsse.json \
  --rekor-proof artifacts/scan123/rekor/entry.json --rekor-key rekor.pub

---

References

• Gap analysis: docs/benchmarks/scanner/scanning-gaps-stella-misses-from-competitors.md#dsse-rekor-operator-enablement-trivy-grype-snyk
• Scanner architecture (§Signer → Attestor → Rekor): docs/modules/scanner/architecture.md
• Export Center profiles: docs/modules/export-center/architecture.md
• Policy Engine predicates: docs/modules/policy/architecture.md
• CLI reference: docs/09_API_CLI_REFERENCE.md