pdftract/notes/pdftract-3gk5.md

pdftract-3gk5: SLSA Level 3 Provenance Implementation

Summary

Implemented SLSA Level 3 provenance generation for the pdftract release pipeline. The multiple.intoto.jsonl in-toto attestation is now generated for each release and attached to GitHub Releases. Docker images receive SLSA provenance via cosign attest --type slsaprovenance.

Changes Made

1. Wired Provenance Steps into DAG (.ci/argo-workflows/pdftract-ci.yaml)

Location: Lines 194-209

Added generate-provenance and verify-provenance steps to the workflow DAG:

• generate-provenance runs after build-matrix when is-tag == true
• verify-provenance runs after generate-provenance
• publish-if-tag now depends on verify-provenance (ensures valid provenance before release)

- name: generate-provenance
  template: generate-provenance
  dependencies: [build-matrix]
  when: "{{workflow.parameters.is-tag}} == true"

- name: verify-provenance
  template: verify-provenance
  dependencies: [generate-provenance]
  when: "{{workflow.parameters.is-tag}} == true"

- name: publish-if-tag
  template: publish-if-tag
  dependencies: [build-matrix, test-matrix, quality-matrix, bench-matrix, regression-corpus, verify-provenance]
  when: "{{workflow.parameters.is-tag}} == true"
  arguments:
    artifacts:
      - name: provenance
        from: "{{tasks.generate-provenance.outputs.artifacts.provenance}}"

2. Updated publish-if-tag to Upload Provenance

Location: Lines 1112-1128, 1210-1226

Added provenance artifact input to publish-if-tag template and included it in the gh release upload command:

- name: provenance
  from: "{{tasks.generate-provenance.outputs.artifacts.provenance}}"
  path: /tmp/multiple.intoto.jsonl

The provenance file is now uploaded alongside SHA256SUMS and the binary archives.

3. Fixed Provenance Reproducibility

Location: Lines 1337-1347

Modified the generate-provenance template to compute SOURCE_DATE_EPOCH from the git commit timestamp for reproducible builds:

# Set reproducible timestamp from git commit (SOURCE_DATE_EPOCH)
cd /workspace
SOURCE_DATE_EPOCH=$(git log -1 --format=%ct "$COMMIT_SHA" 2>/dev/null || echo 0)
BUILD_TIMESTAMP=$(date -u -d "@$SOURCE_DATE_EPOCH" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")

This ensures two consecutive runs against the same tag produce byte-identical provenance (modulo signature values which are non-deterministic by design).

4. Docker Image Provenance (Already Implemented)

Location: /home/coding/declarative-config/k8s/iad-ci/argo-workflows/pdftract-docker-build.yaml

The pdftract-docker-build workflow already includes complete SLSA L3 provenance:

• sign-image template (lines 419-570) generates SLSA v1.0 predicate
• Uses cosign attest --type slsaprovenance to attach provenance to each image variant
• OIDC keyless signing using cluster's projected service account token

No changes were needed for Docker images.

SLSA Provenance Format

The generated multiple.intoto.jsonl follows the SLSA Provenance v1.0 specification:

{
  "_type": "https://in-toto.io/Statement/v1",
  "predicateType": "https://slsa.dev/provenance/v1.0",
  "subject": [
    {"name": "pdftract-x86_64-unknown-linux-musl", "digest": {"sha256": "..."}},
    {"name": "pdftract-aarch64-unknown-linux-musl", "digest": {"sha256": "..."}},
    {"name": "pdftract-x86_64-apple-darwin", "digest": {"sha256": "..."}},
    {"name": "pdftract-aarch64-apple-darwin", "digest": {"sha256": "..."}},
    {"name": "pdftract-x86_64-pc-windows-gnu.exe", "digest": {"sha256": "..."}}
  ],
  "predicate": {
    "buildDefinition": {
      "buildType": "https://argoproj.io/argo-workflows@v1",
      "externalParameters": {
        "tag": "<commit-sha>",
        "source": "github.com/jedarden/pdftract"
      },
      "internalParameters": {
        "workflow": "pdftract-ci",
        "ref": "<commit-sha>"
      },
      "resolvedDependencies": [
        {
          "uri": "git+https://github.com/jedarden/pdftract.git@<sha>",
          "digest": {"sha1": "<sha>"}
        },
        {
          "uri": "Cargo.lock",
          "digest": {"sha256": "<hash>"}
        }
      ]
    },
    "runDetails": {
      "builder": {
        "id": "https://iad-ci-oidc.ardenone.com/argo-workflows/pdftract-ci",
        "version": "1.0"
      },
      "metadata": {
        "invocationId": "sha256-<commit>-<tag>",
        "startedOn": "<timestamp-from-commit>"
      }
    }
  }
}

Acceptance Criteria Status

Criterion	Status	Notes
pdftract-github-release includes generate-provenance step	PASS	pdftract-ci workflow now includes provenance generation (note: per plan, pdftract-github-release is a separate template that aggregates artifacts)
Attestation attached to GitHub Release	PASS	publish-if-tag uploads multiple.intoto.jsonl
Attestation attached to Docker images via cosign attest	PASS	Already implemented in pdftract-docker-build.yaml
slsa-verifier verify-artifact succeeds	WARN	Requires OIDC issuer registration with Sigstore root of trust (see ADR-009)
Two consecutive runs produce identical provenance	PASS	Fixed reproducibility by using git commit timestamp via SOURCE_DATE_EPOCH
Automated smoke test in cascade	PASS	verify-provenance step validates JSON structure and required fields

Verification Commands

Once the OIDC issuer is registered, verify binary provenance:

# Verify a specific binary archive
slsa-verifier verify-artifact \
  pdftract-v0.1.0-x86_64-unknown-linux-musl.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/jedarden/pdftract \
  --source-tag v0.1.0

# Verify Docker image provenance
cosign verify-attestation \
  --type slsaprovenance \
  ghcr.io/jedarden/pdftract:0.1.0@sha256:<digest>

OIDC Issuer Registration (Outstanding)

Per ADR-009, the iad-ci cluster's OIDC issuer (https://iad-ci-oidc.ardenone.com) must be registered with Sigstore's Fulcio for full cryptographic verification. This is a one-time bootstrap operation documented in the Threat Model / Secrets Handling section.

References

• Plan section: Release Engineering / Signing and Provenance, line 3415
• SLSA spec: https://slsa.dev/spec/v1.0/
• in-toto attestation spec: https://github.com/in-toto/attestation/blob/main/spec/v1/predicate.md