https://github.com/philips-labs/slsa-provenance-action
Github Action implementation of SLSA Provenance Generation
https://github.com/philips-labs/slsa-provenance-action
github-action github-actions hacktoberfest in-toto provenance security security-tools slsa software-supply-chain
Last synced: about 1 month ago
JSON representation
Github Action implementation of SLSA Provenance Generation
- Host: GitHub
- URL: https://github.com/philips-labs/slsa-provenance-action
- Owner: philips-labs
- License: mit
- Created: 2021-09-13T12:54:02.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-23T05:03:18.000Z (5 months ago)
- Last Synced: 2025-01-02T16:36:38.537Z (4 months ago)
- Topics: github-action, github-actions, hacktoberfest, in-toto, provenance, security, security-tools, slsa, software-supply-chain
- Language: Go
- Homepage:
- Size: 861 KB
- Stars: 47
- Watchers: 6
- Forks: 18
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
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](https://slsa.dev/). 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](https://github.com/slsa-framework/github-actions-demo) built by SLSA.
## Background
[SLSA](https://github.com/slsa-framework/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](https://github.com/in-toto/attestation/blob/main/spec/README.md)
metadata format.
### Built With
- [SLSA Framework](https://github.com/slsa-framework/slsa/)
- [Golang](https://golang.org/)
- [GitHub Actions](https://github.com/features/actions)
## 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](https://code.visualstudio.com/)
### Local Installation
1. Clone the repo.
```sh
git clone [email protected]:philips-labs/slsa-provenance-action.git
```
1. Build the binary.
```sh
make build
```
1. Execute the binary.
```sh
./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.](https://hub.docker.com/r/philipssoftware/slsa-provenance/tags)
Run the Docker image by doing:
```sh
docker run philipssoftware/slsa-provenance:v0.7.2
```
**GitHub Container Registry**
See all available images [here.](https://github.com/philips-labs/slsa-provenance-action/pkgs/container/slsa-provenance)
Run the Docker image by doing:
```sh
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.
## 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](.github/workflows/ci.yaml) for a full example using GitHub releases.
> :warning: **NOTE:** this job depends on a release job that publishes the release assets to a GitHub Release.
```yaml
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/[email protected]
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](.github/workflows/example-publish.yaml) for a full example using GitHub artifacts.
```yaml
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/[email protected]
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` | |
## 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](/CONTRIBUTING.md) for all the guidelines.
## License
Distributed under the MIT License. See [LICENSE](/LICENSE.md) for more information.
## Contact
*Powered by Philips SWAT Eindhoven*
- [Brend Smits](https://github.com/Brend-Smits) - [email protected]
- [Marco Franssen](https://github.com/marcofranssen)
- [Jeroen Knoops](https://github.com/JeroenKnoops)
- [Annie Jovitha](https://github.com/AnnieJovitha)
## Acknowledgments
This project is inspired by:
- [SLSA Framework](https://slsa.dev/)
- [SLSA GitHub Action Example](https://github.com/slsa-framework/github-actions-demo)
[contributors-shield]: https://img.shields.io/github/contributors/philips-labs/slsa-provenance-action.svg?style=for-the-badge
[contributors-url]: https://github.com/philips-labs/slsa-provenance-action/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/philips-labs/slsa-provenance-action.svg?style=for-the-badge
[forks-url]: https://github.com/philips-labs/slsa-provenance-action/network/members
[stars-shield]: https://img.shields.io/github/stars/philips-labs/slsa-provenance-action.svg?style=for-the-badge
[stars-url]: https://github.com/philips-labs/slsa-provenance-action/stargazers
[issues-shield]: https://img.shields.io/github/issues/philips-labs/slsa-provenance-action.svg?style=for-the-badge
[issues-url]: https://github.com/philips-labs/slsa-provenance-action/issues
[license-shield]: https://img.shields.io/github/license/philips-labs/slsa-provenance-action.svg?style=for-the-badge
[license-url]: https://github.com/philips-labs/slsa-provenance-action/blob/main/LICENSE.md
[slsa-provenance]: https://slsa.dev/provenance/v0.2