Feature: Provenance and Attestation

Relevant source files

The following files were used as context for generating this wiki page:

• services/provenance/attestation.py
• cli/fixops_provenance.py
• backend/api/provenance/router.py
• .github/workflows/provenance.yml
• simulations/demo_pack/provenance.slsa.json
• readme_updated.md

The Provenance and Attestation feature is a core component of the Aldeci platform, designed to guarantee build traceability and supply-chain integrity. It implements the SLSA v1 framework to generate and verify attestations for all release artifacts. This ensures that every artifact can be tied back to its source and build process, providing verifiable evidence for security audits and downstream consumption.

This system provides functionality through a core Python service, a command-line interface (CLI) for local and CI/CD usage, and a REST API for external access. The entire process is integrated into the release workflow to automatically generate, sign, and attach attestations to release assets. This functionality is critical for achieving higher levels of supply-chain security and is a key part of the Evidence Bundles & CI Agent feature.

Sources: readme_updated.md:79, readme_updated.md:389, readme_updated.md:449

Architecture Overview

The provenance system is composed of several key components that work together to create and verify attestations. The core logic resides in the services/provenance/attestation.py module, which is utilized by both the cli/fixops-provenance CLI tool and the backend/api/provenance API endpoint. The GitHub Actions workflow (provenance.yml) orchestrates the process during releases.

The following diagram illustrates the high-level data flow for generating an attestation.

This diagram shows that a build artifact is passed to the fixops-provenance attest command, which uses the core attestation service to hash the artifact, collect metadata, and generate a signed SLSA v1 attestation JSON file.

Sources: readme_updated.md:399-406, readme_updated.md:449-452

Core Service: Attestation Logic

The central logic for creating and managing attestations is located in services/provenance/attestation.py. This module defines the data structures for SLSA v1 statements and provides the functions to build and verify them.

Sources: services/provenance/attestation.py

Data Models

The service uses Pydantic models to represent the in-toto attestation statement, ensuring type safety and serialization to the correct JSON format. The main models are Statement, Predicate, Builder, Material, and Subject.

The relationship between these models is shown in the class diagram below.

This diagram illustrates how a Statement contains Subjects and a Predicate, which in turn contains details about the Builder, build process, and Materials used.

Sources: services/provenance/attestation.py (inferred from general structure and SLSA standard)

Key Functions

• build_statement_from_env(artifact_path: Path) -> Statement: This function is the primary entry point for creating an attestation. It gathers build metadata from environment variables (typically in a CI environment), computes the SHA-256 hash of the specified artifact, and assembles the Statement object.
• verify_statement(attestation: Statement, artifact_path: Path) -> bool: This function verifies an existing attestation against a local artifact. It re-computes the artifact's hash and compares it with the hash stored in the subject field of the attestation. It returns True if they match, confirming the artifact's integrity.

Sources: services/provenance/attestation.py:40-220

Command-Line Interface (CLI)

The fixops-provenance CLI provides a user-friendly way to interact with the attestation service from the command line, making it ideal for integration into build scripts and CI/CD pipelines.

Sources: cli/fixops_provenance.py, readme_updated.md:395

Commands and Arguments

The CLI is organized into two main subcommands: attest and verify.

Command	Description	Arguments
attest	Generates a SLSA v1 attestation for a given artifact.	--artifact <path> (required), --out <path> (optional output file)
verify	Verifies an artifact against its attestation.	--artifact <path> (required), --attestation <path> (required)

Sources: readme_updated.md:461-462, cli/fixops_provenance.py

Example Usage

Here is how you would generate and then verify an attestation for an artifact:

# Generate an attestation for the artifact
$ fixops-provenance attest --artifact dist/fixops.tar.gz --out artifacts/attestations/fixops.json

# Verify the artifact against the generated attestation
$ fixops-provenance verify --artifact dist/fixops.tar.gz --attestation artifacts/attestations/fixops.json

Sources: readme_updated.md:461-462

The following sequence diagram shows the flow when a developer runs the attest command.

REST API

The platform exposes a REST API endpoint to retrieve provenance information for a given artifact. This is useful for external systems, auditors, or UIs that need to fetch attestation data without direct access to the file system.

Sources: backend/api/provenance/router.py, readme_updated.md:464

Endpoint Details

Method	Path	Description	Response Body
GET	/provenance/{artifact}	Returns the stored SLSA attestation for the requested artifact.	Statement JSON object

Sources: backend/api/provenance/router.py:1-120, readme_updated.md:929

CI/CD Integration

Provenance generation is fully integrated into the project's release process via the .github/workflows/provenance.yml workflow. This workflow automatically runs on pushes to tags, generating attestations for release artifacts and uploading them as release assets.

Sources: .github/workflows/provenance.yml, readme_updated.md:396

The workflow performs the following steps:

1. Checks out the code.
2. Sets up Python and installs dependencies.
3. Runs the fixops-provenance attest command for each artifact that needs an attestation.
4. Uploads the generated attestation JSON files as release artifacts.

This process is visualized in the flowchart below.

Attestation Schema Example

The generated attestations conform to the in-toto attestation framework with a SLSA v1 predicate. Below is a condensed example of a generated attestation file.

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [
    {
      "name": "dist/fixops.tar.gz",
      "digest": {
        "sha256": "..."
      }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://github.com/actions/workflow/v1%22%2C
      "externalParameters": {
        "workflow": {
          "ref": "refs/tags/v0.1.0",
          "repository": "fixops/fixops",
          "path": ".github/workflows/release.yml"
        }
      },
      "internalParameters": {
        "github": {
          "event_name": "push"
        }
      }
    },
    "runDetails": {
      "builder": {
        "id": "https://github.com/actions/runner%22
      },
      "metadata": {
        "invocationId": "..."
      }
    }
  }
}

This JSON structure provides a verifiable link between the subject artifact (dist/fixops.tar.gz), its cryptographic hash, and the context of its creation (the GitHub Actions builder and workflow).

Sources: simulations/demo_pack/provenance.slsa.json