From 152607e0e8373c7570705b2f3a3636c99707bd76 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Sun, 23 Jun 2024 21:53:09 -0400 Subject: [PATCH 1/8] Removed beta note from `gh at verify`, clarified reusable workflows use case. --- pkg/cmd/attestation/verify/verify.go | 43 +++++++++++++++++++--------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 526194d93..8a640bf1c 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -25,18 +25,22 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), Short: "Verify an artifact's integrity using attestations", Long: heredoc.Docf(` - ### NOTE: This feature is currently in beta, and subject to change. - Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations. - The command requires either: + In order to verify an attestation, you must validate the identity of the Actions + workflow that produced the attestation (a.k.a. the signer workflow). Given this + identity, the verification process checks the signatures in the attestations, + and confirms that the attestation refers to provided artifact. + + To specify the artifact, the command requires: * a file path to an artifact, or * a container image URI (e.g. %[1]soci://%[1]s) * (note that if you provide an OCI URL, you must already be authenticated with its container registry) - In addition, the command requires either: + To fetch the attestation, and validate the identity of the signer, the command + requires either: * the %[1]s--repo%[1]s flag (e.g. --repo github/example). * the %[1]s--owner%[1]s flag (e.g. --owner github), or @@ -54,27 +58,38 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command To see the full results that are generated upon successful verification, i.e. for use with a policy engine, provide the %[1]s--format=json%[1]s flag. - The attestation's certificate's Subject Alternative Name (SAN) identifies the entity - responsible for creating the attestation, which most of the time will be a GitHub - Actions workflow file located inside your repository. By default, this command uses + The signer workflow's identity is validated against the attestation's + certificate's Subject Alternative Name (SAN). Often, the signer workflow is the + same workflow that originated the run and generated the attestation, and will + be located inside your repository. For this reason, by default this command uses either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN. - However, if you generate attestations with a reusable workflow then the SAN will - identify the reusable workflow – which may or may not be located inside your %[1]s--repo%[1]s - or %[1]s--owner%[1]s. In these situations, you can use the %[1]s--cert-identity%[1]s or - %[1]s--cert-identity-regex%[1]s flags to specify the reusable workflow's URI. + However, sometimes the originating workflow is not be the same workflow that + performed the signing. If your attestation was generated via a reusable + workflow, then that reusable workflow is the signer whose identity needs to be + validated. In this situation, the signer workflow may or may not be located + inside your %[1]s--repo%[1]s or %[1]s--owner%[1]s. + + When using reusable workflows, use the %[1]s--signer-repo%[1]s, %[1]s--signer-workflow%[1]s, + or %[1]s--cert-identity%[1]s flags to validate the signer workflow's identity. For more policy verification options, see the other available flags. `, "`"), Example: heredoc.Doc(` - # Verify a local artifact linked with a repository + # Verify an artifact linked with a repository $ gh attestation verify example.bin --repo github/example - # Verify a local artifact linked with an organization + # Verify an artifact linked with an organization $ gh attestation verify example.bin --owner github - # Verify an OCI image using locally stored attestations + # Verify an artifact and output the full verification result + $ gh attestation verify example.bin --owner github --format json + + # Verify an OCI image using attestations stored on disk $ gh attestation verify oci:// --owner github --bundle sha256:foo.jsonl + + # Verify an artifact signed with a reusable workflow + $ gh attestation verify example.bin --owner github --signer-repo actions/example `), // PreRunE is used to validate flags before the command is run // If an error is returned, its message will be printed to the terminal From 40abc9a7856a5732eee366b587258bb9a5523254 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Sun, 23 Jun 2024 21:54:01 -0400 Subject: [PATCH 2/8] Removed beta note from `gh at download`. --- pkg/cmd/attestation/download/download.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index 3af3b6200..b73513341 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -23,8 +23,6 @@ func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Comman Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), Short: "Download an artifact's attestations for offline use", Long: heredoc.Docf(` - ### NOTE: This feature is currently in beta, and subject to change. - Download attestations associated with an artifact for offline use. The command requires either: From 8318e7a1dea01008cc13d8c3ee21c2f7ed4b3de2 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Mon, 24 Jun 2024 09:32:32 -0400 Subject: [PATCH 3/8] Actually, let's keep `download` in beta for now. --- pkg/cmd/attestation/download/download.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index b73513341..b6459b1fd 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -23,6 +23,8 @@ func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Comman Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), Short: "Download an artifact's attestations for offline use", Long: heredoc.Docf(` + ### NOTE: This feature is currently in beta, and subject to change. + Download attestations associated with an artifact for offline use. The command requires either: From 846b6ec20b13b9419daa1d5e3c8fdbc7e820fd81 Mon Sep 17 00:00:00 2001 From: William Martin Date: Mon, 24 Jun 2024 15:41:22 +0200 Subject: [PATCH 4/8] Fix whitespacing --- pkg/cmd/attestation/download/download.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index b6459b1fd..3af3b6200 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -23,7 +23,7 @@ func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Comman Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), Short: "Download an artifact's attestations for offline use", Long: heredoc.Docf(` - ### NOTE: This feature is currently in beta, and subject to change. + ### NOTE: This feature is currently in beta, and subject to change. Download attestations associated with an artifact for offline use. From d7c56bfb13f99b1df9d3a6f867cae60091171c44 Mon Sep 17 00:00:00 2001 From: William Martin Date: Mon, 24 Jun 2024 15:46:00 +0200 Subject: [PATCH 5/8] Remove beta note from attestation top level command --- pkg/cmd/attestation/attestation.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go index 423de1807..121ae3db0 100644 --- a/pkg/cmd/attestation/attestation.go +++ b/pkg/cmd/attestation/attestation.go @@ -17,8 +17,6 @@ func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command { Short: "Work with artifact attestations", Aliases: []string{"at"}, Long: heredoc.Doc(` - ### NOTE: This feature is currently in beta, and subject to change. - Download and verify artifact attestations. `), } From 06607d3e95b6862d7e79eb4da77ac3aa23961767 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Mon, 24 Jun 2024 10:05:58 -0400 Subject: [PATCH 6/8] s/originated/caller/ workflow --- pkg/cmd/attestation/verify/verify.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 8a640bf1c..4db18e0b1 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -60,11 +60,11 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command The signer workflow's identity is validated against the attestation's certificate's Subject Alternative Name (SAN). Often, the signer workflow is the - same workflow that originated the run and generated the attestation, and will - be located inside your repository. For this reason, by default this command uses + same workflow that started the run and generated the attestation, and will be + located inside your repository. For this reason, by default this command uses either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN. - However, sometimes the originating workflow is not be the same workflow that + However, sometimes the caller workflow is not be the same workflow that performed the signing. If your attestation was generated via a reusable workflow, then that reusable workflow is the signer whose identity needs to be validated. In this situation, the signer workflow may or may not be located From c25dacc33e6a443be1fa74943818a9acae14a96f Mon Sep 17 00:00:00 2001 From: Phill MV Date: Mon, 24 Jun 2024 13:32:51 -0400 Subject: [PATCH 7/8] Update pkg/cmd/attestation/verify/verify.go Co-authored-by: Andy Feller --- pkg/cmd/attestation/verify/verify.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 4db18e0b1..9ddf2f97f 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -64,7 +64,7 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command located inside your repository. For this reason, by default this command uses either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN. - However, sometimes the caller workflow is not be the same workflow that + However, sometimes the caller workflow is not the same workflow that performed the signing. If your attestation was generated via a reusable workflow, then that reusable workflow is the signer whose identity needs to be validated. In this situation, the signer workflow may or may not be located From c9f9fac7dc36b5cab36cd0788b1da42423b0972d Mon Sep 17 00:00:00 2001 From: Phill MV Date: Mon, 24 Jun 2024 13:33:10 -0400 Subject: [PATCH 8/8] Update pkg/cmd/attestation/verify/verify.go Co-authored-by: Andy Feller --- pkg/cmd/attestation/verify/verify.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 9ddf2f97f..60196583a 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -58,8 +58,8 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command To see the full results that are generated upon successful verification, i.e. for use with a policy engine, provide the %[1]s--format=json%[1]s flag. - The signer workflow's identity is validated against the attestation's - certificate's Subject Alternative Name (SAN). Often, the signer workflow is the + The signer workflow's identity is validated against the Subject Alternative Name (SAN) + within the attestation certificate. Often, the signer workflow is the same workflow that started the run and generated the attestation, and will be located inside your repository. For this reason, by default this command uses either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN.