Merge remote-tracking branch 'origin/main' into andrew/bundled-trust-root

Author: tnytown

.github/workflows/release.yml

@@ -121,7 +121,7 @@ jobs:
         uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2
 
       - name: publish
-        uses: pypa/gh-action-pypi-publish@c7f29f7adef1a245bd91520e94867e5c6eedddcc
+        uses: pypa/gh-action-pypi-publish@22b4d1f12511f2696162c08546dafbaa903448a2
         with:
           user: __token__
           password: ${{ secrets.PYPI_TOKEN }}

CHANGELOG.md

@@ -19,6 +19,8 @@ All versions prior to 0.9.0 are untracked.
 
 * Replaced ambient credential detection logic with the `id` package
   ([#535](https://github.com/sigstore/sigstore-python/pull/535))
+* Revamped error diagnostics reporting. All errors with diagnostics now implement
+  `sigstore.errors.Error`.
 
 ### Fixed
 

install/requirements.txt

@@ -371,9 +371,9 @@ typing-extensions==4.5.0 \
     --hash=sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb \
     --hash=sha256:fb33085c39dd998ac16d1431ebc293a8b3eedd00fd4a32de0ff79002c19511b4
     # via pydantic
-urllib3==1.26.14 \
-    --hash=sha256:076907bf8fd355cde77728471316625a4d2f7e713c125f51953bb5b3eecf4f72 \
-    --hash=sha256:75edcdc2f7d85b137124a6c3c9fc3933cdeaa12ecb9a6a959f22797a0feca7e1
+urllib3==1.26.15 \
+    --hash=sha256:8a388717b9476f934a21484e8c8e61875ab60644d29b9b39e11e4b9dc1c6b305 \
+    --hash=sha256:aa751d169e23c7479ce47a0cb0da579e3ede798f994f5816a74e4f4500dcea42
     # via requests
 zipp==3.15.0 \
     --hash=sha256:112929ad649da941c23de50f356a2b5570c954b65150642bccdd66bf194d224b \

pyproject.toml

@@ -64,7 +64,7 @@ lint = [
   "mypy ~= 1.1",
   # NOTE(ww): ruff is under active development, so we pin conservatively here
   # and let Dependabot periodically perform this update.
-  "ruff < 0.0.255",
+  "ruff < 0.0.256",
   "types-requests",
   # Needed for protocol typing in 3.7; remove when our minimum Python is 3.8.
   "typing-extensions; python_version < '3.8'",

sigstore/_cli.py

@@ -24,11 +24,9 @@
 from typing import Optional, TextIO, Union, cast
 
 from cryptography.x509 import load_pem_x509_certificates
-from id import GitHubOidcPermissionCredentialError, detect_credential
 from sigstore_protobuf_specs.dev.sigstore.bundle.v1 import Bundle
 
 from sigstore import __version__
-from sigstore._errors import Error
 from sigstore._internal.ctfe import CTKeyring
 from sigstore._internal.fulcio.client import DEFAULT_FULCIO_URL, FulcioClient
 from sigstore._internal.keyring import Keyring
@@ -40,21 +38,23 @@
 )
 from sigstore._internal.tuf import TrustUpdater
 from sigstore._utils import PEMCert
+from sigstore.errors import Error
 from sigstore.oidc import (
     DEFAULT_OAUTH_ISSUER_URL,
     STAGING_OAUTH_ISSUER_URL,
     Issuer,
+    detect_credential,
 )
 from sigstore.sign import Signer
 from sigstore.transparency import LogEntry
 from sigstore.verify import (
     CertificateVerificationFailure,
     LogEntryMissing,
-    VerificationFailure,
     VerificationMaterials,
     Verifier,
     policy,
 )
+from sigstore.verify.models import VerificationFailure
 
 logging.basicConfig()
 logger = logging.getLogger(__name__)
@@ -844,6 +844,60 @@ def _collect_verification_state(
     return (verifier, all_materials)
 
 
+class VerificationError(Error):
+    """Raised when the verifier returns a `VerificationFailure` result."""
+
+    def __init__(self, result: VerificationFailure):
+        self.message = f"Verification failed: {result.reason}"
+        self.result = result
+
+    def diagnostics(self) -> str:
+        message = f"Failure reason: {self.result.reason}\n"
+
+        if isinstance(self.result, CertificateVerificationFailure):
+            message += dedent(
+                f"""
+                The given certificate could not be verified against the
+                root of trust.
+
+                This may be a result of connecting to the wrong Fulcio instance
+                (for example, staging instead of production, or vice versa).
+
+                Additional context:
+
+                {self.result.exception}
+                """
+            )
+        elif isinstance(self.result, LogEntryMissing):
+            message += dedent(
+                f"""
+                These signing artifacts could not be matched to a entry
+                in the configured transparency log.
+
+                This may be a result of connecting to the wrong Rekor instance
+                (for example, staging instead of production, or vice versa).
+
+                Additional context:
+
+                Signature: {self.result.signature}
+
+                Artifact hash: {self.result.artifact_hash}
+                """
+            )
+        else:
+            message += dedent(
+                f"""
+                A verification error occurred.
+
+                Additional context:
+
+                {self.result}
+                """
+            )
+
+        return message
+
+
 def _verify_identity(args: argparse.Namespace) -> None:
     verifier, files_with_materials = _collect_verification_state(args)
 
@@ -861,64 +915,8 @@ def _verify_identity(args: argparse.Namespace) -> None:
         if result:
             print(f"OK: {file}")
         else:
-            result = cast(VerificationFailure, result)
             print(f"FAIL: {file}")
-            print(f"Failure reason: {result.reason}", file=sys.stderr)
-
-            if isinstance(result, CertificateVerificationFailure):
-                # If certificate verification failed, it's either because of
-                # a chain issue or some outdated state in sigstore itself.
-                # These might already be resolved in a newer version, so
-                # we suggest that users try to upgrade and retry before
-                # anything else.
-                print(
-                    dedent(
-                        f"""
-                        The given certificate could not be verified against the
-                        root of trust.
-
-                        This may be a result of connecting to the wrong Fulcio instance
-                        (for example, staging instead of production, or vice versa).
-
-                        Additional context:
-
-                        {result.exception}
-                        """
-                    ),
-                    file=sys.stderr,
-                )
-            elif isinstance(result, LogEntryMissing):
-                # If Rekor lookup failed, it's because the certificate either
-                # wasn't logged after creation or because the user requested the
-                # wrong Rekor instance (e.g., staging instead of production).
-                # The latter is significantly more likely, so we add
-                # some additional context to the output indicating it.
-                #
-                # NOTE: Even though the latter is more likely, it's still extremely
-                # unlikely that we'd hit this -- we should always fail with
-                # `CertificateVerificationFailure` instead, as the cert store should
-                # fail to validate due to a mismatch between the leaf and the trusted
-                # root + intermediates.
-                print(
-                    dedent(
-                        f"""
-                        These signing artifacts could not be matched to a entry
-                        in the configured transparency log.
-
-                        This may be a result of connecting to the wrong Rekor instance
-                        (for example, staging instead of production, or vice versa).
-
-                        Additional context:
-
-                        Signature: {result.signature}
-
-                        Artifact hash: {result.artifact_hash}
-                        """
-                    ),
-                    file=sys.stderr,
-                )
-
-            sys.exit(1)
+            raise VerificationError(cast(VerificationFailure, result))
 
 
 def _verify_github(args: argparse.Namespace) -> None:
@@ -952,106 +950,14 @@ def _verify_github(args: argparse.Namespace) -> None:
         if result:
             print(f"OK: {file}")
         else:
-            result = cast(VerificationFailure, result)
             print(f"FAIL: {file}")
-            print(f"Failure reason: {result.reason}", file=sys.stderr)
-
-            if isinstance(result, CertificateVerificationFailure):
-                # If certificate verification failed, it's either because of
-                # a chain issue or some outdated state in sigstore itself.
-                # These might already be resolved in a newer version, so
-                # we suggest that users try to upgrade and retry before
-                # anything else.
-                print(
-                    dedent(
-                        f"""
-                        The given certificate could not be verified against the
-                        root of trust.
-
-                        This may be a result of connecting to the wrong Fulcio instance
-                        (for example, staging instead of production, or vice versa).
-
-                        Additional context:
-
-                        {result.exception}
-                        """
-                    ),
-                    file=sys.stderr,
-                )
-            elif isinstance(result, LogEntryMissing):
-                # If Rekor lookup failed, it's because the certificate either
-                # wasn't logged after creation or because the user requested the
-                # wrong Rekor instance (e.g., staging instead of production).
-                # The latter is significantly more likely, so we add
-                # some additional context to the output indicating it.
-                #
-                # NOTE: Even though the latter is more likely, it's still extremely
-                # unlikely that we'd hit this -- we should always fail with
-                # `CertificateVerificationFailure` instead, as the cert store should
-                # fail to validate due to a mismatch between the leaf and the trusted
-                # root + intermediates.
-                print(
-                    dedent(
-                        f"""
-                        These signing artifacts could not be matched to a entry
-                        in the configured transparency log.
-
-                        This may be a result of connecting to the wrong Rekor instance
-                        (for example, staging instead of production, or vice versa).
-
-                        Additional context:
-
-                        Signature: {result.signature}
-
-                        Artifact hash: {result.artifact_hash}
-                        """
-                    ),
-                    file=sys.stderr,
-                )
-
-            sys.exit(1)
+            raise VerificationError(cast(VerificationFailure, result))
 
 
 def _get_identity_token(args: argparse.Namespace) -> Optional[str]:
     token = None
     if not args.oidc_disable_ambient_providers:
-        try:
-            token = detect_credential(DEFAULT_AUDIENCE)
-        except GitHubOidcPermissionCredentialError as exception:
-            # Provide some common reasons for why we hit permission errors in
-            # GitHub Actions.
-            print(
-                dedent(
-                    f"""
-                    Insufficient permissions for GitHub Actions workflow.
-
-                    The most common reason for this is incorrect
-                    configuration of the top-level `permissions` setting of the
-                    workflow YAML file. It should be configured like so:
-
-                        permissions:
-                          id-token: write
-
-                    Relevant documentation here:
-
-                        https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#adding-permissions-settings
-
-                    Another possible reason is that the workflow run has been
-                    triggered by a PR from a forked repository. PRs from forked
-                    repositories typically cannot be granted write access.
-
-                    Relevant documentation here:
-
-                        https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
-
-                    Additional context:
-
-                    {exception}
-                    """
-                ),
-                file=sys.stderr,
-            )
-            sys.exit(1)
+        token = detect_credential(DEFAULT_AUDIENCE)
 
     if not token:
         if args.staging:

sigstore/_internal/sct.py

@@ -34,6 +34,7 @@
 from sigstore._internal.ctfe import CTKeyring
 from sigstore._internal.keyring import KeyringError, KeyringLookupError
 from sigstore._utils import DERCert, KeyID, key_id
+from sigstore.errors import Error
 
 logger = logging.getLogger(__name__)
 
@@ -134,12 +135,35 @@ def _get_issuer_cert(chain: List[Certificate]) -> Certificate:
     return issuer
 
 
-class InvalidSCTError(Exception):
+class InvalidSCTError(Error):
     """
     Raised during SCT verification if an SCT is invalid in some way.
     """
 
-    pass
+    def diagnostics(self) -> str:
+        """Returns diagnostics for the error."""
+        # We specialize this error case, since it usually indicates one of
+        # two conditions: either the current sigstore client is out-of-date,
+        # or that the SCT is well-formed but invalid for the current configuration
+        # (indicating that the user has asked for the wrong instance).
+        if isinstance(self.__cause__, KeyringLookupError):
+            return dedent(
+                f"""
+                Invalid key ID in SCT: not found in current keyring.
+
+                This may be a result of an outdated `sigstore` installation.
+
+                Consider upgrading with:
+
+                    python -m pip install --upgrade sigstore
+
+                Additional context:
+
+                {self.__cause__}
+                """
+            )
+
+        return str(self)
 
 
 def verify_sct(
@@ -190,28 +214,8 @@ def verify_sct(
             key_id=KeyID(sct.log_id), signature=sct.signature, data=digitally_signed
         )
     except KeyringLookupError as exc:
-        # We specialize this error case, since it usually indicates one of
-        # two conditions: either the current sigstore client is out-of-date,
-        # or that the SCT is well-formed but invalid for the current configuration
-        # (indicating that the user has asked for the wrong instance).
-        #
-        # TODO(ww): Longer term, this should be specialized elsewhere.
         raise InvalidSCTError(
-            dedent(
-                f"""
-                Invalid key ID in SCT: not found in current keyring.
-
-                This may be a result of an outdated `sigstore` installation.
-
-                Consider upgrading with:
-
-                    python -m pip install --upgrade sigstore
-
-                Additional context:
-
-                {exc}
-                """
-            ),
-        )
+            "Invalid key ID in SCT: not found in current keyring"
+        ) from exc
     except KeyringError as exc:
         raise InvalidSCTError from exc

sigstore/_internal/tuf.py

@@ -37,8 +37,8 @@
 from tuf.api import exceptions as TUFExceptions
 from tuf.ngclient import RequestsFetcher, Updater
 
-from sigstore._errors import MetadataError, TUFError
 from sigstore._utils import read_embedded
+from sigstore.errors import MetadataError, TUFError
 
 logger = logging.getLogger(__name__)