docker

Generation of SLSA3+ provenance for artifacts created in a Docker container

This document explains how to generate SLSA provenance for artifacts created by running a command inside a user-supplied container.

The container-based workflow uses a GitHub Actions reusable workflow to build the artifacts and generate the SLSA provenance. We'll call this workflow the "container-based workflow" from now on.

This workflow differs from the generic container workflow which attests to a container image, not artifacts that are built from a process within a Docker image. This also differs from the generic artifact workflow as it performs the build as well as generates the provenance. This workflow uses a distinct build type that provides the full details on the build process.

NOTE: This workflow is currently in beta testing.

• Benefits of Provenance
• Generating Provenance
  • Getting Started
  • Referencing the SLSA builder
  • Private Repositories
  • Registry Authentication
  • Supported Triggers
  • Configuration File
  • Workflow Inputs
  • Workflow Example
  • Workflow Outputs
  • Provenance Format
  • Provenance Example
• Command line tool
  • The dry-run subcommand
  • The build subcommand
  • The verify command
• Users
• Known Issues
  • Compatibility with actions/download-artifact

Benefits of Provenance

Using this workflow to build artifacts will generate a non-forgeable attestation to specified artifacts using the identity of the GitHub workflow. This can be used to create a positive attestation to artifacts built inside a container image coming from your repository.

In addition, the provenance contains detailed information about the build process: the base image, the command that was run to generate the artifact, the produced artifacts, and the environment where the execution was preformed.

That means that once your users verify the artifacts they have downloaded they can be sure that the artifacts was created by your repository's workflow and hasn't been tampered with. The details in the provenance allow users to create policy on or verify properties of the build and even provide enough information to reproduce the artifact.

Generating Provenance

The container-based workflow uses a Github Actions reusable workflow to generate the provenance.

Getting Started

Referencing the SLSA builder

At present, the generator MUST be referenced by a tag of the form @vX.Y.Z, because the build will fail if you reference it via a shorter tag like @vX.Y or @vX or if you reference it by a hash.

For more information about this design decision and how to configure renovatebot, see the main repository README.md.

Private Repositories

Private repositories are supported with some caveats. Currently all builds generate and post a new entry in the public Rekor API server instance at https://rekor.sigstore.dev/. This entry includes the repository name. This will cause the private repository name to leak and be discoverable via the public Rekor API server.

If this is ok with you, you can set the rekor-log-public flag in order to opt in to publishing to the public Rekor instance from a private repository.

with:
  rekor-log-public: true

If you do not set this flag then private repositories will generate an error in order to prevent leaking repository name information.

Support for private transparency log instances that would not leak repository name information is tracked on issue #372.

Registry Authentication

This workflow support authentication against a Docker registry for private base images through an input registry-username and registry-password secret. Authentication is not required for public base images. See Workflow Inputs for more.

Authentication to GCR using GCP workflow identity federation is also supported using gcp-workload-identity-provider and gcp-service-account.

Supported Triggers

The following GitHub trigger events are fully supported and tested:

• schedule
• Manual run via workflow_dispatch
• push (including new tags)
• release

In practice, most triggers should work. For events that do not have access to the id-token: write permission, like pull_request, the workflow will run the container-based build and produce an unsigned DSSE attestation for the purposes of testing.

If you have an issue with any other triggers please submit a new issue.

Configuration File

The user must supply a configuration file location in their source repository that contains the details of the build.

# (Required) Docker run command.
command = ["cp", "internal/builders/docker/testdata/config.toml", "config.toml"]

# Path to the file generated by the command above.
artifact_path = "**.toml"

The output artifact path supports wildcard characters. All matching files will be measured and recorded as attestation subjects. The subject names will be the basenames of the matching files.

Workflow Inputs

The container-based workflow accepts the following inputs:

Inputs:

Secrets:

Workflow Example

Create a new workflow, e.g., .github/workflows/slsa-build.yml.

name: SLSA container-based releaser
on:
  workflow_dispatch:
  push:
    tags:
      - "*"

permissions: read-all

jobs:
  # Trusted builder.
  build:
    permissions:
      id-token: write # To sign the provenance.
      contents: write # To upload assets to release.
      actions: read # To read the workflow path.
    needs: args
    uses: slsa-framework/slsa-github-generator/.github/workflows/builder_container-based_slsa3.yml@v1.9.0
    with:
      builder-image: "bash"
      builder-digest: "sha256:9e2ba52487d945504d250de186cb4fe2e3ba023ed2921dd6ac8b97ed43e76af9"
      config-path: ".github/configs-docker/config.toml"

Workflow Outputs

The container-based workflow produces the following outputs:

Provenance Format

The buildDefinition contains the following fields:

The CLI tool described in externalParameters.resolvedDependencies contains the uri of the source that was used to build the artifact (from this GitHub repository). The digest referes to the cryptographic digest of the built binary. Using this information, a verifier may download the source artifact from the GitHub releases inferred by the URI and verify its digest.

Provenance Example

The following is an example of the generated provenance. Provenance is generated as an in-toto statement with a SLSA predicate.

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [
    {
      "name": "example.js",
      "digest": {
        "sha256": "5d672b0dbb696a3289632bf241cc4bb08dbb32c3e9559ea7e9f96b0490209891"
      }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1.0",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://slsa.dev/container-based-build/v0.1?draft",
      "externalParameters": {
        "source": {
          "uri": "git+https://github.com/slsa-framework/example-package@refs/heads/main",
          "digest": {
            "sha1": "ca220e54c07b6fcdd758184a12c132ee3ae531f1"
          }
        },
        "builderImage": {
          "uri": "bash@sha256:9e2ba52487d945504d250de186cb4fe2e3ba023ed2921dd6ac8b97ed43e76af9",
          "digest": {
            "sha256": "9e2ba52487d945504d250de186cb4fe2e3ba023ed2921dd6ac8b97ed43e76af9"
          }
        },
        "configPath": ".github/configs-docker/config.toml",
        "buildConfig": {
          "ArtifactPath": "bin/**",
          "Command": ["npm", "run", "all"]
        }
      },
      "resolvedDependencies": [
        {
          "uri": "git+https://github.com/asraa/slsa-on-github-test@refs/heads/main",
          "digest": {
            "sha1": "c35e20e93ad5465899c12ce71cd6253d6e28fb15"
          }
        },
        {
          "uri": "git+https://github.com/asraa/slsa-github-generator@refs/tags/v1.6.0",
          "digest": {
            "sha256": "6ea80f1d7ca237eb390b2ce10a383cee229be8d084cee2af9bd1f55f87e28541"
          }
        }
      ],
      "internalParameters": {
        "GITHUB_ACTOR_ID": "5194569",
        "GITHUB_EVENT_NAME": "workflow_dispatch",
        "GITHUB_REF": "refs/heads/main",
        "GITHUB_REF_TYPE": "branch",
        "GITHUB_REPOSITORY": "asraa/slsa-on-github-test",
        "GITHUB_REPOSITORY_ID": "501395242",
        "GITHUB_REPOSITORY_OWNER_ID": "5194569",
        "GITHUB_RUN_ATTEMPT": "1",
        "GITHUB_RUN_ID": 5125704193,
        "GITHUB_RUN_NUMBER": 6,
        "GITHUB_SHA": "c35e20e93ad5465899c12ce71cd6253d6e28fb15",
        "GITHUB_TRIGGERING_ACTOR_ID": "5194569",
        "GITHUB_WORKFLOW": ".github/workflows/go-builder.yml",
        "GITHUB_WORKFLOW_REF": "asraa/slsa-on-github-test/.github/workflows/go-builder.yml@refs/heads/main",
        "GITHUB_WORKFLOW_SHA": "c35e20e93ad5465899c12ce71cd6253d6e28fb15",
        "GITHUB_BASE_REF": "",
        "GITHUB_EVENT_PAYLOAD": {},
      }
    },
    "runDetails": {
      "builder": {
        "id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_container-based_slsa3.yml@refs/tags/v1.5.0"
      },
      "metadata": {
        "invocationId": "https://github.com/slsa-framework/example-package/actions/runs/4310284899/attempts/1"
      }
    }
  }
}

See hello-transparent-release for a more detailed description of how to use this workflow.

Command line tool

This folder contains a command line tool for building artifacts using a Docker image.

It is meant to be used as part of a GitHub Actions reusable workflow for generating SLSA provenances. However, users can also run the command locally to test their builds. When a build is intended to be reproducible, consumers may also use the verify sub-command to reproduce the build from the SLSA provenance.

The command line tool provides three sub-commands, namely dry-run, build, and verify.

The dry-run subcommand

The dry-run subcommand can be used to validate the inputs. If the inputs are valid, then the tool creates a BuildDefinition and stores that as a JSON document in the output path that must be provided as one of the flags to the command. The following is an example, which assumes you are running the code in internal/builders/docker:

go run *.go  dry-run \
  --build-config-path internal/builders/docker/testdata/config.toml \
  --builder-image bash@sha256:9e2ba52487d945504d250de186cb4fe2e3ba023ed2921dd6ac8b97ed43e76af9 \
  --git-commit-digest sha1:cf5804b5c6f1a4b2a0b03401a487dfdfbe3a5f00 \
  --source-repo git+https://github.com/slsa-framework/slsa-github-generator \
  --build-definition-path bd.json \
  --force-checkout

The output of this is a JSON document stored in bd.json.

The build subcommand

The build subcommand takes more or less the same inputs as the dry-run subcommand, but actually builds the artifacts. To successfully run this command, you need to have rootless Docker installed.

The following is an example:

go run *.go build \
  --build-config-path internal/builders/docker/testdata/config.toml \
  --builder-image bash@sha256:9e2ba52487d945504d250de186cb4fe2e3ba023ed2921dd6ac8b97ed43e76af9 \
  --git-commit-digest sha1:cf5804b5c6f1a4b2a0b03401a487dfdfbe3a5f00 \
  --source-repo git+https://github.com/slsa-framework/slsa-github-generator \
  --subjects-path subjects.json \
  --output-folder /tmp/build-outputs \
  --force-checkout

If the build is successful, this command will generate subjects.json containing a JSON-encoded list of generated artifacts and their SHA256 digests. It also writes all artifacts to the output-folder.

The verify command

The verify subcommand takes the path to a SLSAv1.0 provenance and verifies it, by rebuilding the artifacts using the build definition in the provenance, and checking that the resulting artifacts have the same names and subjects as the ones in the provenance subject.

Here is an example:

go run *.go verify --provenance-path testdata/slsa1-provenance.json

Users

The following project currently use the container-based workflow:

• Oak; See the workflow file

We welcome any success stories. Please create a PR to add your project to the list, if you are using the container-based workflow.

Known Issues

Compatibility with actions/download-artifact

To download provenance (e.g., if you don't use upload-assets) you have to use actions/download-artifact@v3. The workflow uses actions/upload-artifact@3 which is not compatible with actions/download-artifact@v4.