philips-labs / slsa-provenance-action

Github Action implementation of SLSA Provenance Generation

SLSA Provenance GitHub Action

Github Action to generate [SLSA provenance][slsa-provenance]
Report Bug · Request Feature

About This Project

This GitHub action implements the level 1 requirements of the SLSA framework. By using this GitHub Action it is possible to easily generate the provenance file for different artifact types. Different artifact types include, but not limited to:

• Files
• Push event (Docker Hub, trigger different workflow, etc)

While there are no integrity guarantees on the produced provenance at L1, publishing artifact provenance in a common format opens up opportunities for automated analysis and auditing. Additionally, moving build definitions into source control and onto well-supported, secure build systems represents a marked improvement from the ecosystem's current state.

This is not an official GitHub Action set up and maintained by the SLSA team. This GitHub Action is built for research purposes by Philips Research. It is heavily inspired by the original Provenance Action example built by SLSA.

(back to top)

Background

SLSA is a framework intended to codify and promote secure software supply-chain practices. SLSA helps trace software artifacts (e.g. binaries) back to the build and source control systems that produced them using in-toto's Attestation metadata format.

Built With

• SLSA Framework
• Golang
• GitHub Actions

(back to top)

Getting Started

Get started quickly by reading the information below.

Prerequisites

Ensure you have the following installed:

• Golang
• Docker

Recommendations

The following IDE is recommended when working on this codebase:

• VSCode

Local Installation

1. Clone the repo.

   git clone [e-mail]:philips-labs/slsa-provenance-action.git

2. Build the binary.

   make build

3. Execute the binary.

   ./bin/slsa-provenance help

Docker Image

Our Docker images are available at both GitHub Container Registry (ghcr) and Docker Hub.

Docker Hub See all available images here. Run the Docker image by doing:

docker run philipssoftware/slsa-provenance:v0.7.2

GitHub Container Registry See all available images here. Run the Docker image by doing:

docker run ghcr.io/philips-labs/slsa-provenance:v0.7.2

The Docker image includes the working binary that can be executed by using the slsa-provenance command.

(back to top)

Usage

The easiest way to use this action is to add the following into your workflow file. Additional configuration might be necessary to fit your usecase.

GitHub Releases

Add the following part in your workflow file:

See ci workflow for a full example using GitHub releases.

⚠️ NOTE: this job depends on a release job that publishes the release assets to a GitHub Release.

provenance:
  name: provenance
  needs: [release]
  runs-on: ubuntu-20.04
  permissions:
    # required to update the release.
    contents: write

  steps:
    - name: Generate provenance for Release
      uses: philips-labs/slsa-provenance-action@v0.7.2
      with:
        command: generate
        subcommand: github-release
        arguments: --artifact-path release-assets --output-path 'provenance.json' --tag-name ${{ github.ref_name }}
      env:
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

GitHub artifacts

Add the following part in your workflow file:

See example workflow for a full example using GitHub artifacts.

generate-provenance:
  name: Generate build provenance
  runs-on: ubuntu-latest
  steps:
    - name: Download build artifact
      uses: actions/download-artifact@v2
      with:
        path: artifact/

    - name: Download extra materials for provenance
      uses: actions/download-artifact@v2
      with:
        name: extra-materials
        path: extra-materials/

    - name: Generate provenance
      uses: philips-labs/slsa-provenance-action@v0.7.2
      with:
        command: generate
        subcommand: files
        arguments: --artifact-path artifact/ --extra-materials extra-materials/file1.json,extra-materials/some-more.json

    - name: Upload provenance
      uses: actions/upload-artifact@v2
      with:
        path: provenance.json

Description

An action to generate SLSA build provenance for an artifact

Inputs

parameter	description	required	default
command	The slsa-provenance command to run	false	generate
subcommand	The subcommand to use when generating provenance	false	files
github_context	internal (do not set): the "github" context object in json	true	${{ toJSON(github) }}
runner_context	internal (do not set): the "runner" context object in json	true	${{ toJSON(runner) }}
arguments	the arguments for the given command and subcommand	true

(back to top)

Contributing

If you have a suggestion that would make this project better, please fork the repository and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please refer to the Contributing Guidelines for all the guidelines.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Powered by Philips SWAT Eindhoven

• Brend Smits - [e-mail]
• Marco Franssen
• Jeroen Knoops
• Annie Jovitha

(back to top)

Acknowledgments

This project is inspired by:

• SLSA Framework
• SLSA GitHub Action Example

(back to top)