STACKITGit/cli
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #2 from phillmv/gh-attestation-cmd

Browse source 
Tweak gh attestation doc strings
This commit is contained in:
Meredith Lancaster 2024-03-25 10:26:20 -06:00 • committed by GitHub
commit de63deab20
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 56 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

14
pkg/cmd/attestation/attestation.go
View file

@ -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))

38
pkg/cmd/attestation/download/download.go
View file

@ -19,42 +19,42 @@ import (
func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command {
opts := &Options{}
downloadCmd := &cobra.Command{
Use: "download [<file path> | oci://<OCI image URI>]",
Use: "download [<file-path> | oci://<image-uri>] [--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://<my-OCI-image-URI>%[1]s)
* a file path to an artifact, or
* a container image URI (e.g. %[1]soci://<image-uri>%[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 <my-artifact> -o <GitHub organization>
$ gh attestation download example.bin -o github
# Download Sigstore bundle(s) for a local artifact associated with a GitHub repository
$ gh attestation download <my-artifact> -R <GitHub repo>
$ 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://<my-OCI-image> -o <GitHub organization>
$ 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

7
pkg/cmd/attestation/tufrootverify/tufrootverify.go
View file

@ -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 <mirror-url> --root <root.json>",
Args: cobra.ExactArgs(0),
Short: "Verify the TUF repository from a provided TUF root",
Use: "tuf-root-verify --mirror <mirror-url> --root <root.json>",
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.

61
pkg/cmd/attestation/verify/verify.go
View file

@ -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 <artifact-path-or-url>",
Use: "verify [<file-path> | oci://<image-uri>] [--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://<my-OCI-image-URI>)
The command requires either:
* a file path to an artifact, or
* a container image URI (e.g. %[1]soci://<image-uri>%[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 <my-artifact> --repo <repo-name>
# 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 <my-artifact> --owner <owner>
# Verify an OCI image using a local trusted metadata bundle
$ gh attestation verify oci://<my-OCI-image> --owner <owner> --bundle <path-to-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://<image-uri> --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