- Notifications
You must be signed in to change notification settings - Fork0
A Sigstore client in Python
License
step-security-bot/sigstore-python
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
sigstore is a Python tool for generating and verifying Sigstore signatures.You can use it to sign and verify Python package distributions, or anythingelse!
- Support for signing Python package distributions using an OpenID Connect identity
- Support for publishing signatures to aRekor instance
- Support for verifying signatures on Python package distributions
sigstore requires Python 3.7 or newer, and can be installed directly viapip:
python -m pip install sigstoreOptionally, to installsigstore and all its dependencies withhash-checking mode enabled, run the following:
python -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txtThis installs the requirements file locatedhere, which is kept up-to-date.
sigstore-python hasan official GitHub Action!
You can install it from theGitHub Marketplace, oradd it to your CI manually:
jobs:sigstore-python:steps: -uses:sigstore/gh-action-sigstore-python@v0.2.0with:inputs:foo.txt
See theaction documentationfor more details and usage examples.
You can runsigstore as a standalone program, or viapython -m:
sigstore --helppython -m sigstore --help
Top-level:
usage: sigstore [-h] [-V] [-v] [--staging] [--rekor-url URL] [--rekor-root-pubkey FILE] {sign,verify,get-identity-token} ...a tool for signing and verifying Python package distributionspositional arguments: {sign,verify,get-identity-token}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)Sigstore instance options: --staging Use sigstore's staging instances, instead of the default production instances (default: False) --rekor-url URL The Rekor instance to use (conflicts with --staging) (default: https://rekor.sigstore.dev) --rekor-root-pubkey FILE A PEM-encoded root public key for Rekor itself (conflicts with --staging) (default: None)usage: sigstore sign [-h] [--identity-token TOKEN] [--oidc-client-id ID] [--oidc-client-secret SECRET] [--oidc-disable-ambient-providers] [--oidc-issuer URL] [--no-default-files] [--signature FILE] [--certificate FILE] [--rekor-bundle FILE] [--overwrite] [--staging] [--rekor-url URL] [--rekor-root-pubkey FILE] [--fulcio-url URL] [--ctfe FILE] FILE [FILE ...]positional arguments: FILE The file to signoptional arguments: -h, --help show this help message and exitOpenID Connect options: --identity-token TOKEN the OIDC identity token to use (default: None) --oidc-client-id ID The custom OpenID Connect client ID to use during OAuth2 (default: sigstore) --oidc-client-secret SECRET The custom OpenID Connect client secret to use during OAuth2 (default: None) --oidc-disable-ambient-providers Disable ambient OpenID Connect credential detection (e.g. on GitHub Actions) (default: False) --oidc-issuer URL The OpenID Connect issuer to use (conflicts with --staging) (default: https://oauth2.sigstore.dev/auth)Output options: --no-default-files Don't emit the default output files ({input}.sig, {input}.crt, {input}.rekor) (default: False) --signature FILE, --output-signature FILE Write a single signature to the given file; does not work with multiple input files (default: None) --certificate FILE, --output-certificate FILE Write a single certificate to the given file; does not work with multiple input files (default: None) --rekor-bundle FILE, --output-rekor-bundle FILE Write a single offline Rekor bundle to the given file; does not work with multiple input files (default: None) --overwrite Overwrite preexisting signature and certificate outputs, if present (default: False)Sigstore instance options: --staging Use sigstore's staging instances, instead of the default production instances. This option will be deprecated in favor of the global `--staging` option in a future release. (default: False) --rekor-url URL The Rekor instance to use (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-url` option in a future release. (default: None) --rekor-root-pubkey FILE A PEM-encoded root public key for Rekor itself (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-root- pubkey` option in a future release. (default: None) --fulcio-url URL The Fulcio instance to use (conflicts with --staging) (default: https://fulcio.sigstore.dev) --ctfe FILE A PEM-encoded public key for the CT log (conflicts with --staging) (default: None)This is the most common verification done withsigstore, and thereforethe one you probably want: you can use it to verify that a signature wasproduced by a particular identity (likehamilcar@example.com), as attestedto by a particular OIDC provider (likehttps://github.com/login/oauth).
usage: sigstore verify identity [-h] [--certificate FILE] [--signature FILE] [--rekor-bundle FILE] --cert-identity IDENTITY [--require-rekor-offline] --cert-oidc-issuer URL [--staging] [--rekor-url URL] [--rekor-root-pubkey FILE] [--certificate-chain FILE] FILE [FILE ...]optional arguments: -h, --help show this help message and exitVerification inputs: --certificate FILE, --cert FILE The PEM-encoded certificate to verify against; not used with multiple inputs (default: None) --signature FILE The signature to verify against; not used with multiple inputs (default: None) --rekor-bundle FILE The offline Rekor bundle to verify with; not used with multiple inputs (default: None) FILE The file to verifyVerification options: --cert-identity IDENTITY The identity to check for in the certificate's Subject Alternative Name (default: None) --require-rekor-offline Require offline Rekor verification with a bundle; implied by --rekor-bundle (default: False) --cert-oidc-issuer URL The OIDC issuer URL to check for in the certificate's OIDC issuer extension (default: None)Sigstore instance options: --staging Use sigstore's staging instances, instead of the default production instances. This option will be deprecated in favor of the global `--staging` option in a future release. (default: False) --rekor-url URL The Rekor instance to use (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-url` option in a future release. (default: None) --rekor-root-pubkey FILE A PEM-encoded root public key for Rekor itself (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-root- pubkey` option in a future release. (default: None) --certificate-chain FILE Path to a list of CA certificates in PEM format which will be needed when building the certificate chain for the Fulcio signing certificate (default: None)For backwards compatibility,sigstore verify [args ...] is equivalent tosigstore verify identity [args ...], but the latter form isstronglypreferred.
If your signatures are coming from GitHub Actions (e.g., a workflowthat uses itsambient credentials),then you can use thesigstore verify github subcommand to verifyclaims more precisely thansigstore verify identity allows:
usage: sigstore verify github [-h] [--certificate FILE] [--signature FILE] [--rekor-bundle FILE] --cert-identity IDENTITY [--require-rekor-offline] [--trigger EVENT] [--sha SHA] [--name NAME] [--repository REPO] [--ref REF] [--staging] [--rekor-url URL] [--rekor-root-pubkey FILE] [--certificate-chain FILE] FILE [FILE ...]optional arguments: -h, --help show this help message and exitVerification inputs: --certificate FILE, --cert FILE The PEM-encoded certificate to verify against; not used with multiple inputs (default: None) --signature FILE The signature to verify against; not used with multiple inputs (default: None) --rekor-bundle FILE The offline Rekor bundle to verify with; not used with multiple inputs (default: None) FILE The file to verifyVerification options: --cert-identity IDENTITY The identity to check for in the certificate's Subject Alternative Name (default: None) --require-rekor-offline Require offline Rekor verification with a bundle; implied by --rekor-bundle (default: False) --trigger EVENT The GitHub Actions event name that triggered the workflow (default: None) --sha SHA The `git` commit SHA that the workflow run was invoked with (default: None) --name NAME The name of the workflow that was triggered (default: None) --repository REPO The repository slug that the workflow was triggered under (default: None) --ref REF The `git` ref that the workflow was invoked with (default: None)Sigstore instance options: --staging Use sigstore's staging instances, instead of the default production instances. This option will be deprecated in favor of the global `--staging` option in a future release. (default: False) --rekor-url URL The Rekor instance to use (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-url` option in a future release. (default: None) --rekor-root-pubkey FILE A PEM-encoded root public key for Rekor itself (conflicts with --staging). This option will be deprecated in favor of the global `--rekor-root- pubkey` option in a future release. (default: None) --certificate-chain FILE Path to a list of CA certificates in PEM format which will be needed when building the certificate chain for the Fulcio signing certificate (default: None)sigstore supports a wide variety of workflows and usages. Some common ones areprovided below.
For environments that support OpenID Connect, nativelysigstore supports ambient credentialdetection. This includes many popular CI platforms and cloud providers.
| Service | Status | Notes |
|---|---|---|
| GitHub Actions | Supported | Requires theid-token permission; seethe docs andthis example |
| Google Compute Engine (GCE) | Supported | Automatic |
| Google Cloud Build (GCB) | Supported | Requires settingGOOGLE_SERVICE_ACCOUNT_NAME to an appropriately configured service account name; seethe docs andthis example |
| GitLab CI | Planned | See#31 |
| CircleCI | Planned | See#31 |
Sign a single file (foo.txt) using an ambient OpenID Connect credential,saving the signature and certificate tofoo.txt.sig andfoo.txt.crt:
$python -m sigstore sign foo.txtsigstore can use an OAuth2 + OpenID flow to establish an email identity,allowing you to request signing certificates that attest to control overthat email.
Sign a single file (foo.txt) using the OAuth2 flow, saving thesignature and certificate tofoo.txt.sig andfoo.txt.crt:
$python -m sigstore sign foo.txtBy default,sigstore attempts to doambient credential detection, which may preemptthe OAuth2 flow. To force the OAuth2 flow, you can explicitly disable ambient detection:
$python -m sigstore sign --oidc-disable-ambient-providers foo.txtIf you can't use an ambient credential or the OAuth2 flow, you can pass a pre-createdidentity token directly intosigstore sign:
$python -m sigstore sign --identity-token YOUR-LONG-JWT-HERE foo.txtNote that passing a custom identity token does not circumvent Fulcio's requirements,namely the Fulcio's supported identity providers and the claims expected within the token.
By default,sigstore verify will attempt to find a<filename>.sig and<filename>.crt in thesame directory as the file being verified:
#looksfor foo.txt.sig and foo.txt.crt$python -m sigstore verify identity foo.txt \ --cert-identity 'hamilcar@example.com' \ --cert-oidc-issuer 'https://github.com/login/oauth'
Multiple files can be verified at once:
#looksfor {foo,bar}.txt.{sig,crt}$python -m sigstore verify identity foo.txt bar.txt \ --cert-identity 'hamilcar@example.com' \ --cert-oidc-issuer 'https://github.com/login/oauth'
If your signature and certificate are at different paths, you can specify themexplicitly (but only for one file at a time):
$python -m sigstore verify identity foo.txt \ --certificate some/other/path/foo.crt \ --signature some/other/path/foo.sig \ --cert-identity 'hamilcar@example.com' \ --cert-oidc-issuer 'https://github.com/login/oauth'
sigstore is licensed under the Apache 2.0 License.
Seethe contributing docs for details.
Everyone interacting with this project is expected to follow thesigstore Code of Conduct.
Should you discover any security issues, please refer to sigstore'ssecurityprocess.
This project emits a SLSA provenance on its release! This enables you to verify the integrityof the downloaded artifacts and ensured that the binary's code really comes from this source code.
To do so, please follow the instructionshere.
sigstore-python is developed as part of thesigstore project.
We also use aslack channel!Clickhere for the invite link.
About
A Sigstore client in Python
Resources
License
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Languages
- Python98.5%
- Makefile1.3%
- Standard ML0.2%