From b69172f77ce65fefae407ba05d4d1927783c3676 Mon Sep 17 00:00:00 2001 From: Ian Lewis Date: Thu, 27 Oct 2022 19:39:28 +0900 Subject: [PATCH] Add documentation for private-repository input (#1165) * Add documentation for private-repository input Signed-off-by: Ian Lewis * Fix input table Signed-off-by: Ian Lewis * Add more extensive docs on private repositories Signed-off-by: Ian Lewis * Update private-repository input doc Signed-off-by: Ian Lewis * Add links Signed-off-by: Ian Lewis Signed-off-by: Ian Lewis --- internal/builders/container/README.md | 38 +++++++++++-- internal/builders/generic/README.md | 39 ++++++++++--- internal/builders/go/README.md | 82 +++++++++++++++++---------- 3 files changed, 117 insertions(+), 42 deletions(-) diff --git a/internal/builders/container/README.md b/internal/builders/container/README.md index 9411d1ddd6..a83dc66abf 100644 --- a/internal/builders/container/README.md +++ b/internal/builders/container/README.md @@ -19,6 +19,7 @@ project simply generates provenance as a separate step in an existing workflow. - [Generating Provenance](#generating-provenance) - [Getting Started](#getting-started) - [Referencing the SLSA generator](#referencing-the-slsa-generator) + - [Private Repositories](#private-repositories) - [Supported Triggers](#supported-triggers) - [Workflow Inputs](#workflow-inputs) - [Provenance Format](#provenance-format) @@ -149,6 +150,7 @@ jobs: secrets: registry-password: ${{ secrets.GITHUB_TOKEN }} ``` + ### Referencing the SLSA generator At present, the generator **MUST** be referenced @@ -156,6 +158,29 @@ by a tag of the form `@vX.Y.Z`, because the build will fail if you reference it For more information about this design decision and how to configure renovatebot,see the main repository [README.md](../../../README.md). +### Private Repositories + +Private repositories are supported with some caveats. Currently all builds +generate and post a new entry in the public +[Rekor](https://github.com/sigstore/rekor) API server instance at +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 `private-repository` flag in order to +opt in to publishing to the public Rekor instance from a private repository. + +```yaml +with: + private-repository: 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](https://github.com/slsa-framework/slsa-github-generator/issues/372). + ### Supported Triggers The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested: @@ -177,12 +202,13 @@ The [container workflow](https://github.com/slsa-framework/slsa-github-generator Inputs: -| Name | Required | Description | -| ------------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `image` | yes | The OCI image name. This must not include a tag or digest. | -| `digest` | yes | The OCI image digest. The image digest of the form ':' (e.g. 'sha256:abcdef...') | -| `registry-username` | yes | Username to log into the container registry. | -| `compile-generator` | false | Whether to build the generator from source. This increases build time by ~2m. | +| Name | Required | Default | Description | +| -------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `image` | yes | | The OCI image name. This must not include a tag or digest. | +| `digest` | yes | | The OCI image digest. The image digest of the form ':' (e.g. 'sha256:abcdef...') | +| `registry-username` | yes | | Username to log into the container registry. | +| `compile-generator` | false | false | Whether to build the generator from source. This increases build time by ~2m. | +| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). | Secrets: diff --git a/internal/builders/generic/README.md b/internal/builders/generic/README.md index f0529932a9..d21c7bd1e9 100644 --- a/internal/builders/generic/README.md +++ b/internal/builders/generic/README.md @@ -19,6 +19,7 @@ project simply generates provenance as a separate step in an existing workflow. - [Generating Provenance](#generating-provenance) - [Getting Started](#getting-started) - [Referencing the SLSA generator](#referencing-the-slsa-generator) + - [Private Repositories](#private-repositories) - [Supported Triggers](#supported-triggers) - [Workflow Inputs](#workflow-inputs) - [Workflow Outputs](#workflow-outputs) @@ -81,7 +82,7 @@ provenance: base64-subjects: "${{ needs.build.outputs.hashes }}" ``` -**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`. +**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`. More information [here](/README.md#referencing-slsa-builders-and-generators). Here's an example of what it might look like all together. @@ -170,6 +171,29 @@ by a tag of the form `@vX.Y.Z`, because the build will fail if you reference it For more information about this design decision and how to configure renovatebot,see the main repository [README.md](../../../README.md). +### Private Repositories + +Private repositories are supported with some caveats. Currently all builds +generate and post a new entry in the public +[Rekor](https://github.com/sigstore/rekor) API server instance at +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 `private-repository` flag in order to +opt in to publishing to the public Rekor instance from a private repository. + +```yaml +with: + private-repository: 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](https://github.com/slsa-framework/slsa-github-generator/issues/372). + ### Supported Triggers The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested: @@ -189,12 +213,13 @@ issue](https://github.com/slsa-framework/slsa-github-generator/issues/new/choose The [generic workflow](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_generic_slsa3.yml) accepts the following inputs: -| Name | Required | Default | Description | -| ------------------ | -------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base64-subjects` | yes | | Artifact(s) for which to generate provenance, formatted the same as the output of sha256sum (SHA256 NAME\n[...]) and base64 encoded. The encoded value should decode to, for example: `90f3f7d6c862883ab9d856563a81ea6466eb1123b55bff11198b4ed0030cac86 foo.zip` | -| `upload-assets` | no | false | If true provenance is uploaded to a GitHub release for new tags. | -| `provenance-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. | -| `attestation-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. DEPRECATED: use `provenance-name` instead. | +| Name | Required | Default | Description | +| -------------------- | -------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base64-subjects` | yes | | Artifact(s) for which to generate provenance, formatted the same as the output of sha256sum (SHA256 NAME\n[...]) and base64 encoded. The encoded value should decode to, for example: `90f3f7d6c862883ab9d856563a81ea6466eb1123b55bff11198b4ed0030cac86 foo.zip` | +| `upload-assets` | no | false | If true provenance is uploaded to a GitHub release for new tags. | +| `provenance-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. | +| `attestation-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. DEPRECATED: use `provenance-name` instead. | +| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). | ### Workflow Outputs diff --git a/internal/builders/go/README.md b/internal/builders/go/README.md index 3606083f71..b50165b273 100644 --- a/internal/builders/go/README.md +++ b/internal/builders/go/README.md @@ -4,16 +4,16 @@ This document explains how to use the builder for [Go](https://go.dev/) projects --- -[Generation of provenance](#generation) - -- [Referencing the SLSA builder](#referencing-the-slsa-builder) -- [Supported Triggers](#supported-triggers) -- [Configuration File](#configuration-file) -- [Migration from GoReleaser](#migration-from-GoReleaser) -- [Workflow Inputs](#workflow-inputs) -- [Workflow Example](#workflow-example) -- [Provenance Example](#provenance-example) -- [BuildConfig Format](#buildconfig-format) +- [Generation of provenance](#generation) + - [Referencing the SLSA builder](#referencing-the-slsa-builder) + - [Private Repositories](#private-repositories) + - [Supported Triggers](#supported-triggers) + - [Configuration File](#configuration-file) + - [Migration from GoReleaser](#migration-from-GoReleaser) + - [Workflow Inputs](#workflow-inputs) + - [Workflow Example](#workflow-example) + - [Provenance Example](#provenance-example) + - [BuildConfig Format](#buildconfig-format) --- @@ -29,6 +29,29 @@ by a tag of the form `@vX.Y.Z`, because the build will fail if you reference it For more information about this design decision and how to configure renovatebot,see the main repository [README.md](../../../README.md). +### Private Repositories + +Private repositories are supported with some caveats. Currently all builds +generate and post a new entry in the public +[Rekor](https://github.com/sigstore/rekor) API server instance at +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 `private-repository` flag in order to +opt in to publishing to the public Rekor instance from a private repository. + +```yaml +with: + private-repository: 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](https://github.com/slsa-framework/slsa-github-generator/issues/372). + ### Supported Triggers The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested: @@ -91,19 +114,19 @@ In the meantime, you can use both GoReleaser and this builder in the same reposi ```yaml builds: -... - goos: - - windows - - linux - - darwin - goarch: - - amd64 - - arm64 - - s390x - # This instructs GoReleaser to not build for linux amd64. - ignore: - - goos: linux - goarch: amd64 +--- +goos: + - windows + - linux + - darwin +goarch: + - amd64 + - arm64 + - s390x +# This instructs GoReleaser to not build for linux amd64. +ignore: + - goos: linux + goarch: amd64 ``` The configuration file accepts many of the common fields GoReleaser uses, as you can see in the [example](#configuration-file). The configuration file also supports two variables: `{{ .Os }}` and `{{ .Arch }}`. Other variables can be set manually as shown in the table below, in combination with the builder's `evaluated-envs`: @@ -125,12 +148,13 @@ If you think you need suppport for other variables, please [open an issue](https The builder workflow [slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/builder_go_slsa3.yml) accepts the following inputs: -| Name | Required | Description | Default | -| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `config-file` | no | `.github/workflows/slsa-goreleaser.yml` | The configuration file for the builder. A path within the calling repository. | -| `evaluated-envs` | no | empty value | A list of environment variables, seperated by `,`: `VAR1: value, VAR2: value`. This is typically used to pass dynamically-generated values, such as `ldflags`. Note that only environment variables with names starting with `CGO_` or `GO` are accepted. | -| `go-version` | yes | The go version for your project. This value is passed, unchanged, to the [actions/setup-go](https://github.com/actions/setup-go) action when setting up the environment | -| `upload-assets` | no | true on new tags | Whether to upload assets to a GitHub release or not. | +| Name | Required | Default | Description | +| -------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `config-file` | no | `.github/workflows/slsa-goreleaser.yml` | The configuration file for the builder. A path within the calling repository. | +| `evaluated-envs` | no | empty value | A list of environment variables, seperated by `,`: `VAR1: value, VAR2: value`. This is typically used to pass dynamically-generated values, such as `ldflags`. Note that only environment variables with names starting with `CGO_` or `GO` are accepted. | +| `go-version` | yes | | The go version for your project. This value is passed, unchanged, to the [actions/setup-go](https://github.com/actions/setup-go) action when setting up the environment | +| `upload-assets` | no | true on new tags | Whether to upload assets to a GitHub release or not. | +| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). | ### Workflow Example