Skip to content

Commit

Permalink
doc: add links to GH builders (slsa-framework#268)
Browse files Browse the repository at this point in the history
* Update README.md

Signed-off-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>

* Update README.md

Signed-off-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>

Signed-off-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>
  • Loading branch information
laurentsimon authored Sep 26, 2022
1 parent b5da86b commit ad0648c
Showing 1 changed file with 7 additions and 7 deletions.
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Usage:

Flags:
--build-workflow-input map[] [optional] a workflow input provided by a user at trigger time in the format 'key=value'. (Only for 'workflow_dispatch' events). (default map[])
--builder-id string EXPERIMENTAL: the unique builder ID who created the provenance
--builder-id string the unique builder ID who created the provenance
-h, --help help for verify-artifact
--print-provenance print the verified provenance to stdout
--provenance-path string path to a provenance file
Expand All @@ -88,15 +88,15 @@ Flags:

### Option details

The following options are supported for [SLSA GitHub builders and generators](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance):
The following options are available:

| Option | Description | Support
| --- | ----------- | --------
| `source-uri` | Expects a source, for e.g. `github.com/org/repo`. | All builders
| `source-branch` | Expects a `branch` like `main` or `dev`. Not supported for all GitHub Workflow triggers. | GitHub builders only
| `source-tag` | Expects a `tag` like `v0.0.1`. Verifies exact tag used to create the binary. Supported for new [tag](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.tag.main.config-ldflags-assets-tag.slsa3.yml#L5) and [release](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.release.main.config-ldflags-assets-tag.slsa3.yml) triggers. | GitHub builders only
| `source-versioned-tag` | Like `tag`, but verifies using semantic versioning. | GitHub builders only
| `build-workflow-input` | Expects key-value pairs like `key=value` to match against [inputs](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputs) for GitHub Actions `workflow_dispatch` triggers. | GitHub builders only
| `source-branch` | Expects a `branch` like `main` or `dev`. Not supported for all GitHub Workflow triggers. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
| `source-tag` | Expects a `tag` like `v0.0.1`. Verifies exact tag used to create the binary. Supported for new [tag](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.tag.main.config-ldflags-assets-tag.slsa3.yml#L5) and [release](https://github.com/slsa-framework/example-package/blob/main/.github/workflows/e2e.go.release.main.config-ldflags-assets-tag.slsa3.yml) triggers. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
| `source-versioned-tag` | Like `tag`, but verifies using semantic versioning. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)
| `build-workflow-input` | Expects key-value pairs like `key=value` to match against [inputs](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputs) for GitHub Actions `workflow_dispatch` triggers. | [GitHub builders](https://github.com/slsa-framework/slsa-github-generator#generation-of-provenance)

## Verification for GitHub builders

Expand Down Expand Up @@ -167,4 +167,4 @@ For a more in-depth technical dive, read the [SPECIFICATIONS.md](https://github.
### TOCTOU attacks
As explained on [Wikipedia](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use), a "time-of-check to time-of-use (TOCTOU) is a class of software bugs caused by a race condition involving the checking of the state of a part of a system and the use of the results of that check".

In the context of provenance verification, imagine you verify a container refered to via a _mutable_ image `image:tag`. The verification succeeds and verifies the corresponding hash is `sha256:abcdef...`. After verification, you pull and run the image using `docker run image:tag`. An attacker could have altered the image between the verification step and the run step. To mitigate this attack, we ask users to always pass an _immutable_ reference to the artifact they verify.
In the context of provenance verification, imagine you verify a container refered to via a _mutable_ image `image:tag`. The verification succeeds and verifies the corresponding hash is `sha256:abcdef...`. After verification, you pull and run the image using `docker run image:tag`. An attacker could have altered the image between the verification step and the run step. To mitigate this attack, we ask users to always pass an _immutable_ reference to the artifact they verify.

0 comments on commit ad0648c

Please sign in to comment.