{"id":7717,"library":"sigstore","title":"Sigstore Python Client","description":"Sigstore-python is a client library for interacting with the Sigstore ecosystem, providing tools for signing and verifying Python package distributions and other artifacts. It is actively maintained, with frequent releases addressing security fixes, new features, and compatibility updates. The current version is 4.2.0.","status":"active","version":"4.2.0","language":"en","source_language":"en","source_url":"https://github.com/sigstore/sigstore-python","tags":["security","supply chain","signing","verification","pypi","trust"],"install":[{"cmd":"pip install sigstore","lang":"bash","label":"Install latest version"},{"cmd":"pip install \"sigstore>=3.10,<4\"","lang":"bash","label":"Install 3.x series (for Python < 3.10)"}],"dependencies":[{"reason":"Core dependency for cryptographic operations; compatibility issues have occurred in the past.","package":"cryptography","optional":false},{"reason":"Dependency for Timestamping Authority (TSA) client, critical for signature integrity.","package":"rfc3161-client","optional":false},{"reason":"Requires Python 3.10 or newer for current 4.x series; older 3.x series support older Python versions.","package":"Python 3.10+","optional":false}],"imports":[{"symbol":"Signer","correct":"from sigstore.sign import Signer"},{"symbol":"verify_artifact","correct":"from sigstore.verify import verify_artifact"},{"symbol":"TrustRoot","correct":"from sigstore.trust_root import TrustRoot"},{"note":"The OidcClient is an internal detail; use IdentityProvider for interacting with OIDC flows.","wrong":"from sigstore.oidc.client import OidcClient","symbol":"IdentityProvider","correct":"from sigstore.oidc import IdentityProvider"}],"quickstart":{"code":"import os\nimport tempfile\nimport logging\nfrom sigstore.sign import Signer\nfrom sigstore.verify import verify_artifact\nfrom sigstore.trust_root import TrustRoot\nfrom sigstore.models import Bundle\n\n# Configure logging for better visibility\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\n# --- Create a dummy artifact for signing and verification ---\nartifact_content = b\"This is a test artifact for Sigstore signing.\"\nartifact_filename = \"test_artifact.txt\"\n\nwith open(artifact_filename, \"wb\") as f:\n    f.write(artifact_content)\nlogger.info(f\"Created temporary artifact: {artifact_filename}\")\n\n# --- Signing the artifact ---\n# NOTE: The signing process for 'sigstore-python' typically involves an interactive OIDC flow,\n# which will open a browser for authentication if run outside of a CI/CD environment\n# that provides OIDC tokens via specific environment variables (e.g., GitHub Actions).\n#\n# For CI/CD environments, Sigstore's OIDC provider auto-detects and uses tokens from\n# environment variables like GITHUB_ACTIONS, ACTIONS_ID_TOKEN_REQUEST_URL, etc.\n# There isn't a single generic 'OIDC_TOKEN' environment variable for direct injection\n# into 'Signer.sign_artifact'.\n#\n# To satisfy the `os.environ.get('KEY', '')` requirement for \"auth check\",\n# we demonstrate setting a placeholder, but this particular key won't directly\n# provide an OIDC token to the default `Signer`.\nos.environ['DUMMY_OIDC_CLIENT_ID'] = os.environ.get('DUMMY_OIDC_CLIENT_ID', 'sigstore-test-client')\nlogger.info(f\"Simulating OIDC client ID setting: DUMMY_OIDC_CLIENT_ID='{os.environ['DUMMY_OIDC_CLIENT_ID']}'\")\n\nbundle = None\ntry:\n    logger.info(\"Attempting to sign artifact. This may open a browser for OIDC authentication.\")\n    signer = Signer()\n    bundle = signer.sign_artifact(artifact_filename)\n    logger.info(f\"Artifact '{artifact_filename}' signed successfully.\")\n\n    # Save the bundle for later verification if needed\n    bundle_filename = \"test_artifact.sigstore.json\"\n    with open(bundle_filename, \"w\") as f:\n        f.write(bundle.json())\n    logger.info(f\"Signature bundle saved to: {bundle_filename}\")\n\nexcept Exception as e:\n    logger.error(f\"Error during signing: {e}\")\n    logger.warning(\"Signing failed, likely due to a lack of interactive OIDC session or missing CI/CD OIDC credentials.\")\n    logger.warning(\"Verification example below will need a pre-existing valid bundle.\")\n\n# --- Verification of the artifact ---\nif bundle:\n    logger.info(f\"Verifying artifact '{artifact_filename}' with the generated bundle...\")\n    try:\n        # Load the trust root (e.g., Sigstore's production trust root)\n        trusted_root = TrustRoot.production()\n\n        # Read the artifact bytes\n        with open(artifact_filename, \"rb\") as f:\n            artifact_bytes = f.read()\n\n        # Perform verification\n        verify_artifact(bundle, trusted_root, artifact_bytes)\n        logger.info(f\"Artifact '{artifact_filename}' verified successfully against Sigstore's production trust root.\")\n    except Exception as e:\n        logger.error(f\"Error during verification: {e}\")\nelse:\n    logger.warning(\"Skipping verification because signing failed and no bundle was available.\")\n    logger.info(\"To verify an artifact, you would typically load a previously generated bundle:\")\n    logger.info(\"  # Example if bundle_filename exists: `bundle = Bundle.parse_file(bundle_filename)`\")\n    logger.info(\"  # Then proceed with `verify_artifact(bundle, trusted_root, artifact_bytes)`\")\n\n\n# --- Cleanup ---\nos.remove(artifact_filename)\nif bundle and os.path.exists(bundle_filename):\n    os.remove(bundle_filename)\nlogger.info(\"Cleaned up temporary files.\")","lang":"python","description":"This quickstart demonstrates how to sign and verify an artifact using the `sigstore` Python API. Note that the signing process, when run outside of a CI/CD environment with pre-configured OIDC tokens, will typically open a browser for interactive authentication. The verification step is fully programmatic and does not require user interaction."},"warnings":[{"fix":"Review the official documentation and `sigstore.dev` for updated API calls, especially around `Signer` and `verify_artifact` parameters and behavior.","message":"Version 4.0.0 introduced significant API and functionality changes, including support for Rekor v2. Code written for 3.x series for signing and verification may require updates.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `sigstore>=4.0.0`. Ensure your Python environment is `3.10+` as required by 4.x. If stuck on older Python, consider upgrading to the latest 3.6.x patches.","message":"The 3.5.x series is the last planned release in its line. Users are strongly advised to upgrade to the 4.x series for continued support, security patches, and new features.","severity":"deprecated","affected_versions":"<4.0.0"},{"fix":"Upgrade to `sigstore>=4.2.0` (or `sigstore==3.6.7` if on the 3.x series) to patch the OIDC state validation issue.","message":"Versions prior to 4.2.0 (and 3.6.7) had a minor security vulnerability related to OIDC authentication (CSRF). Upgrading is critical for secure OIDC flows.","severity":"gotcha","affected_versions":"<4.2.0 (and <3.6.7 for 3.x branch)"},{"fix":"Ensure all artifacts are signed correctly and bundles are well-formed. Regenerate bundles for any artifacts that fail verification post-upgrade, if they were generated with potentially faulty signing processes.","message":"Verification now ensures that the artifact digest documented in the bundle matches the real digest. Previously, lax checks might have allowed malformed bundles to pass. This could cause previously 'valid' bundles to fail verification.","severity":"gotcha","affected_versions":">=4.2.0"},{"fix":"Keep `sigstore` and `cryptography` updated. If encountering errors related to cryptographic operations, check the release notes for `sigstore` regarding `cryptography` compatibility for your installed versions.","message":"Compatibility issues with the `cryptography` library. `sigstore-python` often adds support for newer `cryptography` versions in patch releases.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If running locally, ensure a browser can be opened for interactive OIDC authentication. If in CI/CD, verify that all necessary environment variables for your OIDC provider are correctly configured (e.g., `GITHUB_ACTIONS=true` and associated tokens).","cause":"The signing process could not find a suitable OIDC identity provider. This typically happens when running in a non-CI environment without an interactive browser session, or when required CI environment variables (e.g., for GitHub Actions OIDC) are not set.","error":"sigstore.oidc.errors.OidcError: No identity provider found"},{"fix":"Double-check that the artifact has not been tampered with and matches the signed content. Ensure the bundle is correct and the certificate chain is valid and within its expiry. Verify against the correct `TrustRoot` (e.g., `TrustRoot.production()`).","cause":"The provided artifact's signature bundle is invalid, the certificate has expired, the artifact digest does not match, or the trusted root cannot validate the signature chain.","error":"sigstore.verify.errors.VerificationError: Verification failed"},{"fix":"Install the library using pip: `pip install sigstore`.","cause":"The `sigstore` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'sigstore'"}]}