Architecture Of Konflux

55. SLSA Source Provenance Verification

Date: 2025-10-09

# Status

Accepted

# Context

Konflux’s trust model is organized entirely around SLSA build provenance. Build provenance attestations, generated by Tekton Chains and stored alongside container images in OCI registries, form the foundation of our verification and release policies in Enterprise Contract/Conforma. This approach follows the SLSA principle of storing attestations close to the artifacts they describe.

The SLSA specification includes multiple tracks for establishing trust at different stages of the software supply chain. While Konflux uses the Build Track to establish trust through build provenance, the Source Track provides increasing levels of trust in source code by verifying source control system practices. The source track addresses threats like unauthorized source modifications, bypassed code reviews, and compromised version control systems. Just as build provenance attestations are stored alongside the artifacts they describe (container images in OCI registries), the SLSA community has created a tool to store source verification summary attestations (VSAs) as git notes in source repositories, keeping attestations close to the source commits they verify.

However, Konflux’s build-provenance-centered architecture prompts a question: How should we verify and incorporate source provenance into our existing trust model?

Some different approaches are possible:

  1. Direct reference: Include source provenance attestations directly in build provenance
  2. Parallel verification: Verify source provenance independently alongside build provenance
  3. Chained attestations: Create build provenance attestations about source provenance attestations

The challenge is that the source track’s storage model (git notes in repositories) differs significantly from our build artifact storage model (OCI registries), making it non-obvious how to integrate source provenance verification into our existing Conforma policies and attestation chains.

# References

# Decision

We will verify SLSA source provenance through a chained attestation approach that leverages the movable test pattern from ADR 48.

# Verification Workflow

  1. Source VSA generation (external to Konflux):

    • Source repository maintainers configure automation (GitHub Actions, GitLab CI/CD pipelines, etc.) to generate source VSAs
    • These VSAs are stored as git notes in the source repository, contemporaneously with commits
    • VSAs attest to source control practices (e.g., two-person review, branch protection, audit logs)

  2. Source provenance verification task (in Konflux pipeline):

    • A Konflux pipeline task reads the source VSA from git notes for the cloned commit
    • The task accepts a public key parameter (provided via IntegrationTestScenario configuration) and verifies the source VSA signature against that key
    • The task verifies the VSA contents (format, subject matching the commit, etc.)
    • The task pushes the source VSA to the OCI registry as a separate artifact (manifest) using the OCI referrers API (via oras attach), with the container image as the subject of the OCI reference (the git commit remains the subject within the VSA payload itself)
    • The task exposes the pullspec of the OCI representation of the VSA (digest reference) in its task results using *_ARTIFACT_OUTPUTS format

  3. Build provenance chain (via Tekton Chains):

    • Tekton Chains observes the task results containing the source VSA artifact reference
    • Chains generates and signs a SLSA build provenance attestation about the source provenance attestation
    • This creates an attestation chain: Build Provenance → Source VSA → Source Commit

  4. Verification in Conforma:

    • Conforma policies can verify source provenance by checking for the presence of the attestation chain (using the referrers-based attestation storage)
    • Conforma trusts Tekton Chains’ signatures (existing trust root)
    • Conforma verifies trust in the source verification task itself using the Trusted Tasks mechanisms described in ADR 53
    • Conforma reads the public key from the provenance attestation of the verification task (which includes the task parameters) and verifies it matches the expected signer identity for the source repository
    • Through the chain, Conforma gains transitive trust in the source VSA’s signature verification (performed by the task) without needing to re-verify the signature itself
    • This bootstraps trust in source provenance through our existing build-provenance infrastructure

# Rationale

This approach provides several advantages:

# Integration Points

# Consequences

# Positive

# Negative

# Implementation Requirements

  1. New Tekton task: Implement verify-source source provenance verification task that:

    • Accepts a public key parameter (configured via IntegrationTestScenario)
    • Fetches git notes from cloned repositories
    • Verifies source VSA signatures against the provided public key
    • Verifies source VSA contents (format, subject, etc.)
    • Pushes VSAs to OCI registry
    • Exposes pullspec in *_ARTIFACT_OUTPUTS results format

  2. Conforma policy updates: Update Enterprise Contract policies to:

    • Detect source provenance attestation chains
    • Verify build provenance attestations about source VSAs
    • Read the public key from test attestation task parameters and verify it matches expected signer identities for source repositories
    • Determine if source verification levels meet release requirements

  3. Documentation for source repository owners:

    • How to generate source VSAs (GitHub Actions, GitLab CI templates)
    • How to store VSAs as git notes
    • What source verification levels mean

  4. ITS Provisioning: Konflux deployments that want to adopt source provenance verification across their instance can update their onboarding mechanisms to provision a source verification ITS automatically

# Future Considerations