| 21 | ) |
| 22 | |
| 23 | func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command { |
| 24 | opts := &Options{} |
| 25 | verifyCmd := &cobra.Command{ |
| 26 | Use: "verify [<file-path> | oci://<image-uri>] [--owner | --repo]", |
| 27 | Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), |
| 28 | Short: "Verify an artifact's integrity using attestations", |
| 29 | Long: heredoc.Docf(` |
| 30 | Verify the integrity and provenance of an artifact using its associated |
| 31 | cryptographically signed attestations. |
| 32 | |
| 33 | ## Understanding Verification |
| 34 | |
| 35 | An attestation is a claim (i.e. a provenance statement) made by an actor |
| 36 | (i.e. a GitHub Actions workflow) regarding a subject (i.e. an artifact). |
| 37 | |
| 38 | In order to verify an attestation, you must provide an artifact and validate: |
| 39 | * the identity of the actor that produced the attestation |
| 40 | * the expected attestation predicate type (the nature of the claim) |
| 41 | |
| 42 | By default, this command enforces the %[1]s%[2]s%[1]s |
| 43 | predicate type. To verify other attestation predicate types use the |
| 44 | %[1]s--predicate-type%[1]s flag. |
| 45 | |
| 46 | The "actor identity" consists of: |
| 47 | * the repository or the repository owner the artifact is linked with |
| 48 | * the Actions workflow that produced the attestation (a.k.a the |
| 49 | signer workflow) |
| 50 | |
| 51 | This identity is then validated against the attestation's certificate's |
| 52 | SourceRepository, SourceRepositoryOwner, and SubjectAlternativeName |
| 53 | (SAN) fields, among others. |
| 54 | |
| 55 | It is up to you to decide how precisely you want to enforce this identity. |
| 56 | |
| 57 | At a minimum, this command requires either: |
| 58 | * the %[1]s--owner%[1]s flag (e.g. --owner github), or |
| 59 | * the %[1]s--repo%[1]s flag (e.g. --repo github/example) |
| 60 | |
| 61 | The more precisely you specify the identity, the more control you will |
| 62 | have over the security guarantees offered by the verification process. |
| 63 | |
| 64 | Ideally, the path of the signer workflow is also validated using the |
| 65 | %[1]s--signer-workflow%[1]s or %[1]s--cert-identity%[1]s flags. |
| 66 | |
| 67 | Please note: if your attestation was generated via a reusable workflow then |
| 68 | that reusable workflow is the signer whose identity needs to be validated. |
| 69 | In this situation, you must use either the %[1]s--signer-workflow%[1]s or |
| 70 | the %[1]s--signer-repo%[1]s flag. |
| 71 | |
| 72 | For more options, see the other available flags. |
| 73 | |
| 74 | ## Loading Artifacts And Attestations |
| 75 | |
| 76 | To specify the artifact, this command requires: |
| 77 | * a file path to an artifact, or |
| 78 | * a container image URI (e.g. %[1]soci://<image-uri>%[1]s) |
| 79 | * (note that if you provide an OCI URL, you must already be authenticated with |
| 80 | its container registry) |