_cli: add sigstore verify identity (#379)

* _cli: add `sigstore verify identity`

This adds `sigstore verify identity`, which is aliased
(through some `argparse` hackery) back to `sigstore verify`.

This allows us to remain compatible with the existing CLI,
while also giving us the flexibility we need to extend verification
(e.g. `sigstore verify github`).

Signed-off-by: William Woodruff <[email protected]>

* _cli: help text for `sigstore verify identity`

Signed-off-by: William Woodruff <[email protected]>

* _cli, Makefile, README: fix `--help` generation

Signed-off-by: William Woodruff <[email protected]>

* README: typo

Signed-off-by: William Woodruff <[email protected]>

* ci: run check-readme against min Python version

Signed-off-by: William Woodruff <[email protected]>

* Makefile: fix `check-readme` target

Signed-off-by: William Woodruff <[email protected]>

* README: render `--help` with min Python version

Signed-off-by: William Woodruff <[email protected]>

* _cli: fix `sigstore verify` behavior

Signed-off-by: William Woodruff <[email protected]>

* _cli: hackety hack

Signed-off-by: William Woodruff <[email protected]>

* _cli: hackety hack

Signed-off-by: William Woodruff <[email protected]>

* README: update docs, examples

Signed-off-by: William Woodruff <[email protected]>

* _cli: add warning to bare `sigstore verify`

Signed-off-by: William Woodruff <[email protected]>

Signed-off-by: William Woodruff <[email protected]>
Signed-off-by: William Woodruff <[email protected]>

Author: woodruffw

.github/workflows/ci.yml

@@ -57,22 +57,31 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@755da8c3cf115ac066823e79a1e1788f8940201b # v3.2.0
+
+      # NOTE: We intentionally lint against our minimum supported Python.
       - uses: actions/setup-python@5ccb29d8773c3f3f653e1705f474dfaa8a06a912
         with:
           python-version: "3.7"
+
       - name: deps
         run: make dev SIGSTORE_EXTRA=lint
+
       - name: lint
         run: make lint
 
   check-readme:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@755da8c3cf115ac066823e79a1e1788f8940201b # v3.2.0
+
+      # NOTE: We intentional check `--help` rendering against our minimum Python,
+      # since it changes slightly between Python versions.
       - uses: actions/setup-python@5ccb29d8773c3f3f653e1705f474dfaa8a06a912
         with:
-          python-version: "3.x"
+          python-version: "3.7"
+
       - name: deps
         run: make dev
+
       - name: check-readme
         run: make check-readme

Makefile

@@ -117,14 +117,14 @@ check-readme:
 	    $(MAKE) -s run ARGS="sign --help" \
 	  )
 
-	# sigstore verify --help
+	# sigstore verify identity --help
 	@diff \
 	  <( \
-	    awk '/@begin-sigstore-verify-help@/{f=1;next} /@end-sigstore-verify-help@/{f=0} f' \
+	    awk '/@begin-sigstore-verify-identity-help@/{f=1;next} /@end-sigstore-verify-identity-help@/{f=0} f' \
 	      < README.md | sed '1d;$$d' \
 	  ) \
 	  <( \
-	    $(MAKE) -s run ARGS="verify --help" \
+	    $(MAKE) -s run ARGS="verify identity --help" \
 	  )
 
 

README.md

@@ -78,15 +78,16 @@ a tool for signing and verifying Python package distributions
 positional arguments:
   {sign,verify,get-identity-token}
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
   -V, --version         show program's version number and exit
   -v, --verbose         run with additional debug logging; supply multiple
                         times to increase verbosity (default: 0)
 ```
 <!-- @end-sigstore-help@ -->
 
-Signing:
+
+### Signing
 
 <!-- @begin-sigstore-sign-help@ -->
 ```
@@ -102,7 +103,7 @@ usage: sigstore sign [-h] [--identity-token TOKEN] [--oidc-client-id ID]
 positional arguments:
   FILE                  The file to sign
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
 
 OpenID Connect options:
@@ -150,22 +151,30 @@ Sigstore instance options:
 ```
 <!-- @end-sigstore-sign-help@ -->
 
-Verifying:
+### Verifying
+
+#### Identities
 
-<!-- @begin-sigstore-verify-help@ -->
+This is the most common verification done with `sigstore`, and therefore
+the one you probably want: you can use it to verify that a signature was
+produced by a particular identity (like `[email protected]`), as attested
+to by a particular OIDC provider (like `https://github.com/login/oauth`).
+
+<!-- @begin-sigstore-verify-identity-help@ -->
 ```
-usage: sigstore verify [-h] [--certificate FILE] [--signature FILE]
-                       [--rekor-bundle FILE] [--certificate-chain FILE]
-                       [--cert-email EMAIL] --cert-identity IDENTITY
-                       --cert-oidc-issuer URL [--require-rekor-offline]
-                       [--staging] [--rekor-url URL]
-                       [--rekor-root-pubkey FILE]
-                       FILE [FILE ...]
+usage: sigstore verify identity [-h] [--certificate FILE] [--signature FILE]
+                                [--rekor-bundle FILE]
+                                [--certificate-chain FILE]
+                                [--cert-email EMAIL] --cert-identity IDENTITY
+                                --cert-oidc-issuer URL
+                                [--require-rekor-offline] [--staging]
+                                [--rekor-url URL] [--rekor-root-pubkey FILE]
+                                FILE [FILE ...]
 
 positional arguments:
   FILE                  The file to verify
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
 
 Verification inputs:
@@ -203,7 +212,11 @@ Sigstore instance options:
                         A PEM-encoded root public key for Rekor itself
                         (conflicts with --staging) (default: None)
 ```
-<!-- @end-sigstore-verify-help@ -->
+<!-- @end-sigstore-verify-identity-help@ -->
+
+For backwards compatibility, `sigstore verify [args ...]` is equivalent to
+`sigstore verify identity [args ...]`, but the latter form is **strongly**
+preferred.
 
 ## Example uses
 
@@ -270,51 +283,31 @@ same directory as the file being verified:
 
 ```console
 # looks for foo.txt.sig and foo.txt.crt
-$ python -m sigstore verify foo.txt
+$ python -m sigstore verify identity foo.txt \
+    --cert-identity '[email protected]' \
+    --cert-oidc-issuer 'https://github.com/login/oauth'
 ```
 
 Multiple files can be verified at once:
 
 ```console
 # looks for {foo,bar}.txt.{sig,crt}
-$ python -m sigstore verify foo.txt bar.txt
+$ python -m sigstore verify identity foo.txt bar.txt \
+    --cert-identity '[email protected]' \
+    --cert-oidc-issuer 'https://github.com/login/oauth'
 ```
 
 If your signature and certificate are at different paths, you can specify them
 explicitly (but only for one file at a time):
 
 ```console
-$ python -m sigstore verify \
+$ python -m sigstore verify identity foo.txt \
     --certificate some/other/path/foo.crt \
     --signature some/other/path/foo.sig \
-    foo.txt
-```
-
-### Extended verification against OpenID Connect claims
-
-By default, `sigstore verify` only checks the validity of the certificate,
-the correctness of the signature, and the consistency of both with the
-certificate transparency log.
-
-To assert further details about the signature (such as *who* or *what* signed for the artifact),
-you can test against the OpenID Connect claims embedded within it.
-
-For example, to accept the signature and certificate only if they correspond to a particular
-email identity:
-
-```console
-$ python -m sigstore verify --cert-email [email protected] foo.txt
-```
-
-Or to accept only if the OpenID Connect issuer is the expected one:
-
-```console
-$ python -m sigstore verify --cert-oidc-issuer https://github.com/login/oauth foo.txt
+    --cert-identity '[email protected]' \
+    --cert-oidc-issuer 'https://github.com/login/oauth'
 ```
 
-These options can be combined, and further extended validation options (e.g., for
-signing results from GitHub Actions) are under development.
-
 ## Licensing
 
 `sigstore` is licensed under the Apache 2.0 License.

sigstore/_cli.py

@@ -82,6 +82,42 @@ def _boolify_env(envvar: str) -> bool:
         raise ValueError(f"can't coerce '{val}' to a boolean")
 
 
+def _set_default_verify_subparser(parser: argparse.ArgumentParser, name: str) -> None:
+    """
+    An argparse patch for configuring a default subparser for `sigstore verify`.
+
+    Adapted from <https://stackoverflow.com/a/26379693>
+    """
+    subparser_found = False
+    for arg in sys.argv[1:]:
+        if arg in ["-h", "--help"]:  # global help if no subparser
+            break
+    else:
+        for x in parser._subparsers._actions:  # type: ignore[union-attr]
+            if not isinstance(x, argparse._SubParsersAction):
+                continue
+            for sp_name in x._name_parser_map.keys():
+                if sp_name in sys.argv[1:]:
+                    subparser_found = True
+        if not subparser_found:
+            try:
+                # If `sigstore verify identity` wasn't passed explicitly, we need
+                # to insert the `identity` subcommand into the correct position
+                # within `sys.argv`. To do that, we get the index of the `verify`
+                # subcommand, and insert it directly after it.
+                verify_idx = sys.argv.index("verify")
+                sys.argv.insert(verify_idx + 1, name)
+                logger.warning(
+                    "`sigstore verify` without a subcommand will be treated as "
+                    "`sigstore verify identity`, but this behavior will be deprecated "
+                    "in a future release"
+                )
+            except ValueError:
+                # This happens when we invoke `sigstore sign`, since there's no
+                # `verify` subcommand to insert under. We do nothing in this case.
+                pass
+
+
 def _add_shared_instance_options(group: argparse._ArgumentGroup) -> None:
     group.add_argument(
         "--staging",
@@ -243,10 +279,18 @@ def _parser() -> argparse.ArgumentParser:
 
     # `sigstore verify`
     verify = subcommands.add_parser(
-        "verify", formatter_class=argparse.ArgumentDefaultsHelpFormatter
+        "verify",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
+    verify_subcommand = verify.add_subparsers(dest="verify_subcommand")
 
-    input_options = verify.add_argument_group("Verification inputs")
+    # `sigstore verify identity`
+    verify_identity = verify_subcommand.add_parser(
+        "identity",
+        help="verify against a known identity and identity provider",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    input_options = verify_identity.add_argument_group("Verification inputs")
     input_options.add_argument(
         "--certificate",
         "--cert",
@@ -270,7 +314,9 @@ def _parser() -> argparse.ArgumentParser:
         help="The offline Rekor bundle to verify with; not used with multiple inputs",
     )
 
-    verification_options = verify.add_argument_group("Extended verification options")
+    verification_options = verify_identity.add_argument_group(
+        "Extended verification options"
+    )
     verification_options.add_argument(
         "--certificate-chain",
         metavar="FILE",
@@ -309,17 +355,21 @@ def _parser() -> argparse.ArgumentParser:
         help="Require offline Rekor verification with a bundle; implied by --rekor-bundle",
     )
 
-    instance_options = verify.add_argument_group("Sigstore instance options")
+    instance_options = verify_identity.add_argument_group("Sigstore instance options")
     _add_shared_instance_options(instance_options)
 
-    verify.add_argument(
+    verify_identity.add_argument(
         "files",
         metavar="FILE",
         type=Path,
         nargs="+",
         help="The file to verify",
     )
 
+    # `sigstore verify` defaults to `sigstore verify identity`, for backwards
+    # compatibility.
+    _set_default_verify_subparser(verify, "identity")
+
     # `sigstore get-identity-token`
     get_identity_token = subcommands.add_parser("get-identity-token")
     _add_shared_oidc_options(get_identity_token)