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

Keys & trust roots
- Fulcio / KMS credentials available to StellaOps.Signer.
- Rekor public key pinned (rekor.pub) for verification jobs and CLI tooling.
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.
Storage
- Mongo collections attestations & rekorProofs sized for retention (7–30 days recommended).
- Object store tier with at-rest encryption for DSSE payloads.
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).
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

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

CLI verification offline:

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

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