git.stella-ops.org/docs/doctor/articles/security/evidence-integrity.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.security.evidence.integrity	stellaops.doctor.security	fail	security evidence integrity dsse rekor offline

Evidence Integrity

What It Checks

Validates DSSE signatures, Rekor inclusion proofs, and evidence hash consistency for files in the evidence locker. The check only runs when EvidenceLocker:LocalPath or Evidence:BasePath is configured and the directory exists.

The check scans up to 100 evidence files (.json and .dsse) and performs structural verification on three evidence formats:

DSSE Envelopes

• Payload must be valid base64.
• At least one signature must exist.
• Each signature must have keyid and sig fields, with sig being valid base64.
• If payloadDigest is present, verifies SHA-256 digest matches the payload bytes.

Evidence Bundles

• Manifest must have a version field.
• If rekorReceipt is present, validates the Rekor receipt structure.

Rekor Receipts

• Must have non-empty uuid.
• Must have numeric logIndex.
• Must have inclusionProof with a non-empty hashes array.

Content Digest

• Must have algorithm prefix (sha256: or sha512:).

Files that don't match any known format are skipped. Files that fail to parse as JSON are marked invalid.

Why It Matters

Evidence integrity is the foundation of Stella Ops' auditability guarantee. Every release decision, scan result, and policy evaluation is recorded as signed evidence. If evidence files are tampered with, the entire audit trail becomes untrustworthy. Broken DSSE signatures mean attestations may have been modified after signing. Missing or invalid Rekor inclusion proofs mean the transparency log cannot verify the evidence was recorded.

Common Causes

• Evidence files may have been tampered with or corrupted
• DSSE signatures are invalid (payload was modified after signing)
• Evidence digests do not match content (partial writes, disk corruption)
• Rekor inclusion proofs are invalid or missing required fields
• Evidence locker directory does not exist or has not been initialized

How to Fix

Docker Compose

Verify the evidence locker path is configured and accessible:

environment:
  EvidenceLocker__LocalPath: "/data/evidence"

volumes:
  - stellaops-evidence:/data/evidence

Investigate invalid files:

# List evidence files
docker compose exec platform ls -la /data/evidence/

# Check a specific file
docker compose exec platform cat /data/evidence/<file>.json | jq

Re-generate affected evidence:

# Re-scan and re-sign evidence bundles
docker compose exec platform stella evidence regenerate --path /data/evidence/<file>

Bare Metal / systemd

# Create the evidence directory if missing
mkdir -p /var/lib/stellaops/evidence
chown stellaops:stellaops /var/lib/stellaops/evidence

# Verify file integrity
sha256sum /var/lib/stellaops/evidence/*.json

# Check Rekor entries
rekor-cli get --uuid <uuid-from-evidence>

Kubernetes / Helm

Ensure evidence is stored on a persistent volume:

evidenceLocker:
  localPath: "/data/evidence"
  persistentVolume:
    enabled: true
    size: "10Gi"
    storageClass: "standard"

Verify inside the pod:

kubectl exec -it <pod> -- ls -la /data/evidence/
kubectl exec -it <pod> -- stella doctor run --check check.security.evidence.integrity

Verification

stella doctor run --check check.security.evidence.integrity

Related Checks

• check.security.encryption — validates encryption keys used for evidence signing
• check.core.crypto.available — SHA-256 must be available for digest verification
• check.core.env.diskspace — insufficient disk space can cause incomplete evidence writes