git.stella-ops.org/docs/provenance/inline-dsse.md

# Inline DSSE Provenance

> **Status:** Draft – aligns with the November 2025 advisory “store DSSE attestation refs inline on every SBOM/VEX event node.”  
> **Owners:** Authority Guild · Feedser Guild · Platform Guild · Docs Guild.

This document defines how Stella Ops records provenance for SBOM, VEX, scan, and derived events: every event node in the Mongo event graph includes DSSE + Rekor references and verification metadata so audits and replay become first-class queries.

---

## 1. Event patch (Mongo schema)

```jsonc
{
  "_id": "evt_...",
  "kind": "SBOM|VEX|SCAN|INGEST|DERIVED",
  "subject": {
    "purl": "pkg:nuget/example@1.2.3",
    "digest": { "sha256": "..." },
    "version": "1.2.3"
  },
  "provenance": {
    "dsse": {
      "envelopeDigest": "sha256:...",
      "payloadType": "application/vnd.in-toto+json",
      "key": {
        "keyId": "cosign:SHA256-PKIX:ABC...",
        "issuer": "fulcio",
        "algo": "ECDSA"
      },
      "rekor": {
        "logIndex": 1234567,
        "uuid": "b3f0...",
        "integratedTime": 1731081600,
        "mirrorSeq": 987654   // optional
      },
      "chain": [
        { "type": "build", "id": "att:build#...", "digest": "sha256:..." },
        { "type": "sbom",  "id": "att:sbom#...",  "digest": "sha256:..." }
      ]
    }
  },
  "trust": {
    "verified": true,
    "verifier": "Authority@stella",
    "witnesses": 1,
    "policyScore": 0.92
  },
  "ts": "2025-11-11T12:00:00Z"
}
```

### Key fields

| Field | Description |
|-------|-------------|
| `provenance.dsse.envelopeDigest` | SHA-256 of the DSSE envelope (not payload). |
| `provenance.dsse.payloadType` | Usually `application/vnd.in-toto+json`. |
| `provenance.dsse.key` | Key fingerprint / issuer / algorithm. |
| `provenance.dsse.rekor` | Rekor transparency log metadata (index, UUID, integrated time). |
| `provenance.dsse.chain` | Optional chain of dependent attestations (build → sbom → scan). |
| `trust.*` | Result of local verification (DSSE signature, Rekor proof, policy). |

---

## 2. Write path (ingest flow)

1. **Obtain provenance metadata** for each attested artifact (build, SBOM, VEX, scan). The CI script (`scripts/publish_attestation_with_provenance.sh`) captures `envelopeDigest`, Rekor `logIndex`/`uuid`, and key info.
2. **Authority/Feedser** verify the DSSE + Rekor proof (local cosign/rekor libs or the Signer service) and set `trust.verified = true`, `trust.verifier = "Authority@stella"`, `trust.witnesses = 1`.
3. **Attach** the provenance block before appending the event to Mongo, using `StellaOps.Provenance.Mongo` helpers.
4. **Backfill** historical events by resolving known subjects → attestation digests and running an update script.

Reference helper: `src/__Libraries/StellaOps.Provenance.Mongo/ProvenanceMongoExtensions.cs`.

---

## 3. CI/CD snippet

See `scripts/publish_attestation_with_provenance.sh`:

```bash
rekor-cli upload --rekor_server "$REKOR_URL" \
  --artifact "$ATTEST_PATH" --type dsse --format json > rekor-upload.json
LOG_INDEX=$(jq '.LogIndex' rekor-upload.json)
UUID=$(jq -r '.UUID' rekor-upload.json)
ENVELOPE_SHA256=$(sha256sum "$ATTEST_PATH" | awk '{print $1}')
cat > provenance-meta.json <<EOF
{
  "subject": { "imageRef": "$IMAGE_REF", "digest": { "sha256": "$IMAGE_DIGEST" } },
  "dsse": {
    "envelopeDigest": "sha256:$ENVELOPE_SHA256",
    "payloadType": "application/vnd.in-toto+json",
    "key": { "keyId": "$KEY_ID", "issuer": "$KEY_ISSUER", "algo": "$KEY_ALGO" },
    "rekor": { "logIndex": $LOG_INDEX, "uuid": "$UUID", "integratedTime": $(jq '.IntegratedTime' rekor-upload.json) }
  }
}
EOF
```

Feedser ingests this JSON and maps it to `DsseProvenance` + `TrustInfo`.

---

## 4. Mongo indexes

Create indexes to keep provenance queries fast (`mongosh`):

```javascript
db.events.createIndex(
  { "subject.digest.sha256": 1, "kind": 1, "provenance.dsse.rekor.logIndex": 1 },
  { name: "events_by_subject_kind_provenance" }
);

db.events.createIndex(
  { "kind": 1, "trust.verified": 1, "provenance.dsse.rekor.logIndex": 1 },
  { name: "events_unproven_by_kind" }
);

db.events.createIndex(
  { "provenance.dsse.rekor.logIndex": 1 },
  { name: "events_by_rekor_logindex" }
);
```

Corresponding C# helper: `MongoIndexes.EnsureEventIndexesAsync`.

---

## 5. Query recipes

* **All proven VEX for an image digest:**

```javascript
db.events.find({
  kind: "VEX",
  "subject.digest.sha256": "<digest>",
  "provenance.dsse.rekor.logIndex": { $exists: true },
  "trust.verified": true
})
```

* **Compliance gap (unverified data used for decisions):**

```javascript
db.events.aggregate([
  { $match: { kind: { $in: ["VEX","SBOM","SCAN"] } } },
  { $match: {
      $or: [
        { "trust.verified": { $ne: true } },
        { "provenance.dsse.rekor.logIndex": { $exists: false } }
      ]
    }
  },
  { $group: { _id: "$kind", count: { $sum: 1 } } }
])
```

* **Replay slice:** filter for events where `provenance.dsse.chain` covers build → sbom → scan and export referenced attestation digests.

---

## 6. Policy gates

Examples:

```yaml
rules:
  - id: GATE-PROVEN-VEX
    when:
      all:
        - kind: "VEX"
        - trust.verified: true
        - key.keyId in VendorAllowlist
        - rekor.integratedTime <= releaseFreeze
    then:
      decision: ALLOW

  - id: BLOCK-UNPROVEN
    when:
      any:
        - trust.verified != true
        - provenance.dsse.rekor.logIndex missing
    then:
      decision: FAIL
      reason: "Unproven evidence influences decision; require Rekor-backed attestation."
```

---

## 7. UI nudges

* **Provenance chip** on findings/events: `Verified • Rekor#1234567 • KeyID:cosign:...` (click → inclusion proof & DSSE preview).
* Facet filter: `Provenance = Verified / Missing / Key-Policy-Mismatch`.

---

## 8. Implementation tasks

| Task ID | Scope |
|---------|-------|
| `PROV-INLINE-401-028` | Extend Authority/Feedser write-paths to attach `provenance.dsse` + `trust` blocks using `StellaOps.Provenance.Mongo`. |
| `PROV-BACKFILL-401-029` | Backfill historical events with DSSE/Rekor refs based on existing attestation digests. |
| `PROV-INDEX-401-030` | Create Mongo indexes and expose helper queries for audits. |

Keep this document updated when new attestation types or mirror/witness policies land.