diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go index aa445f71a..9b3a0cd2c 100644 --- a/pkg/cmd/attestation/attestation.go +++ b/pkg/cmd/attestation/attestation.go @@ -7,26 +7,16 @@ import ( "github.com/cli/cli/v2/pkg/cmd/attestation/verify" "github.com/cli/cli/v2/pkg/cmdutil" - "github.com/MakeNowJust/heredoc" "github.com/spf13/cobra" ) func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command { root := &cobra.Command{ Use: "attestation [subcommand]", - Short: "Work with attestations", + Short: "Work with artifact attestations", Aliases: []string{"at"}, Hidden: true, - Long: heredoc.Docf(` - Work with attestations that represent trusted metadata about artifacts and images. - - The %[1]sattestation%[1]s command and all subcommands support the following account types: - * Free tier - * Pro tier - * Team tier - * GHEC - * GHEC EMU - `, "`"), + Long: "Download and verify artifact attestations.", } root.AddCommand(download.NewDownloadCmd(f, nil)) diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index bf9b12894..2f40970fc 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -19,42 +19,42 @@ import ( func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command { opts := &Options{} downloadCmd := &cobra.Command{ - Use: "download [ | oci://]", + Use: "download [ | oci://] [--owner | --repo]", Args: cobra.ExactArgs(1), Short: "Download an artifact's Sigstore bundle(s) for offline use", Long: heredoc.Docf(` - Download an artifact's Sigstore bundle(s) for offline use. - + Download an artifact's attestations, aka Sigstore bundle(s), for offline use. + The command requires either: - * a relative path to a local artifact, or - * a container image URI (e.g. %[1]soci://%[1]s) + * a file path to an artifact, or + * a container image URI (e.g. %[1]soci://%[1]s) - Note that if you provide an OCI URI for the artifact you must already - be authenticated with a container registry. + (Note that if you provide an OCI URL, you must already be authenticated with + its container registry.) - In addition, the command also requires either: - * the %[1]s--owner%[1]s flag (e.g. github), or - * the %[1]s--repo%[1]s flag (e.g. github/example). + In addition, the command requires either: + * the %[1]s--owner%[1]s flag (e.g. --owner github), or + * the %[1]s--repo%[1]s flag (e.g. --repo github/example). - The value of the %[1]s--owner%[1]s flag must match the name of the GitHub - organization that the artifact is associated with. + The %[1]s--owner%[1]s flag value must match the name of the GitHub organization + that the artifact is associated with. - The value of the %[1]s--repo%[1]s flag must match the name of the GitHub - repository that the artifact is associated with. + The %[1]s--repo%[1]s flag value must match the name of the GitHub repository + that the artifact is associated with. - The corresponding Sigstore bundle(s) will be written to a file in the + Any associated Sigstore bundle(s) will be written to a file in the current directory named after the artifact's digest. For example, if the - artifact's digest is "sha256:1234", the file will be named "sha256:1234.jsonl". + digest is "sha256:1234", the file will be named "sha256:1234.jsonl". `, "`"), Example: heredoc.Doc(` # Download Sigstore bundle(s) for a local artifact associated with a GitHub organization - $ gh attestation download -o + $ gh attestation download example.bin -o github # Download Sigstore bundle(s) for a local artifact associated with a GitHub repository - $ gh attestation download -R + $ gh attestation download example.bin -R github/example # Download Sigstore bundle(s) for an OCI image associated with a GitHub organization - $ gh attestation download oci:// -o + $ gh attestation download oci://example.com/foo/bar:latest -o github `), // PreRunE is used to validate flags before the command is run // If an error is returned, its message will be printed to the terminal diff --git a/pkg/cmd/attestation/tufrootverify/tufrootverify.go b/pkg/cmd/attestation/tufrootverify/tufrootverify.go index 3c62a77ab..05971da54 100644 --- a/pkg/cmd/attestation/tufrootverify/tufrootverify.go +++ b/pkg/cmd/attestation/tufrootverify/tufrootverify.go @@ -17,9 +17,10 @@ func NewTUFRootVerifyCmd(f *cmdutil.Factory, runF func() error) *cobra.Command { var mirror string var root string var cmd = cobra.Command{ - Use: "tuf-root-verify --mirror --root ", - Args: cobra.ExactArgs(0), - Short: "Verify the TUF repository from a provided TUF root", + Use: "tuf-root-verify --mirror --root ", + Args: cobra.ExactArgs(0), + Short: "Verify the TUF repository from a provided TUF root", + Hidden: true, Long: heredoc.Docf(` Verify a TUF repository with a local TUF root. diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index e39c8e7f1..d9cc3e882 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -22,48 +22,49 @@ var ErrNoMatchingSLSAPredicate = fmt.Errorf("the attestation does not have the e func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command { opts := &Options{} verifyCmd := &cobra.Command{ - Use: "verify ", + Use: "verify [ | oci://] [--owner | --repo]", Args: cobra.ExactArgs(1), - Short: "Cryptographically verify an artifact", + Short: "Verify an artifact's integrity using attestations", Long: heredoc.Docf(` - Cryptographically verify the authenticity of an artifact using the - associated trusted metadata. + Verify the integrity and provenance of an artifact using its associated + cryptographically signed attestations. - The command accepts either: - * a relative path to a local artifact - * a container image URI (e.g. oci://) + The command requires either: + * a file path to an artifact, or + * a container image URI (e.g. %[1]soci://%[1]s) - Note that you must already be authenticated with a container registry - if you provide an OCI image URI as the artifact. + (Note that if you provide an OCI URL, you must already be authenticated with + its container registry.) - The command also requires you provide either the %[1]s--owner%[1]s - or %[1]s--repo%[1]s flag. - The value of the %[1]s--owner%[1]s flag should be the name of the GitHub organization + In addition, the command requires either: + * the %[1]s--owner%[1]s flag (e.g. --owner github), or + * the %[1]s--repo%[1]s flag (e.g. --repo github/example). + + The %[1]s--owner%[1]s flag value must match the name of the GitHub organization that the artifact is associated with. - The value of the %[1]s--repo%[1]s flag should be the name of the GitHub repository that - the artifact is associated with. - By default, the command will verify the artifact against trusted metadata stored remotely. - If you would like to verify the artifact against local metadata, - you can provide a path to the local trusted metadata bundle file with the - %[1]s--bundle%[1]s flag. + The %[1]s--repo%[1]s flag value must match the name of the GitHub repository + that the artifact is associated with. - By default, the command will use the SHA-256 hash algorithm to create the artifact digest - used for verification. - You can specify the SHA-512 algorithm instead using the %[1]s--digest-alg%[1]s flag. + By default, the verify command will attempt to fetch attestations associated + with the provided artifact from the GitHub API. If you would prefer to verify + the artifact using attestations stored on disk (i.e. from the download command), + provide a path to the %[1]s--bundle%[1]s flag. - If the %[1]s--json-result%[1]s flag is provided, the command will print the verification - results as JSON. + To see the full results that are generated upon successful verification, i.e. + for use with a policy engine, provide the %[1]s--json-result%[1]s flag. + + For more policy verification options, see the other available flags. `, "`"), Example: heredoc.Doc(` - # Verify a local artifact with the repository name - $ gh attestation verify --repo + # Verify a local artifact associated with a repository + $ gh attestation verify example.bin --repo github/example - # Verify a local artifact with the organization name - $ gh attestation verify --owner - - # Verify an OCI image using a local trusted metadata bundle - $ gh attestation verify oci:// --owner --bundle + # Verify a local artifact associated with an organization + $ gh attestation verify example.bin --owner github + + # Verify an OCI image using locally stored attestations + $ gh attestation verify oci:// --owner github --bundle sha256:foo.jsonl `), // PreRunE is used to validate flags before the command is run // If an error is returned, its message will be printed to the terminal