sigstore/sigstore-python
GitHub: sigstore/sigstore-python
Sigstore 的 Python 客户端，提供基于 OIDC 身份的无密钥签名和验证能力，帮助保障软件制品的供应链安全。
Stars: 313 | Forks: 76
# sigstore-python
[](https://github.com/sigstore/sigstore-python/actions/workflows/ci.yml)
[](https://pypi.org/project/sigstore)
[](https://securityscorecards.dev/viewer/?uri=github.com/sigstore/sigstore-python)
[](https://slsa.dev/)
[](https://sigstore.github.io/sigstore-python)
`sigstore` 是一个用于生成和验证 Sigstore 签名的 Python 工具。
你可以使用它来签名和验证 Python 包分发版，或者其他任何东西！
## 目录
* [功能特性](#features)
* [安装](#installation)
* [用法](#usage)
* [签名](#signing)
* [验证](#verifying)
* [通用身份](#generic-identities)
* [来自 GitHub Actions 的签名](#signatures-from-github-actions)
* [高级用法](#advanced-usage)
* [故障排除](#troubleshooting)
* [文档](#documentation)
* [许可协议](#licensing)
* [社区](#community)
* [贡献](#contributing)
* [行为准则](#code-of-conduct)
* [安全](#security)
* [SLSA 来源证明](#slsa-provenance)
## 功能特性
* 支持使用 [Sigstore](https://www.sigstore.dev/) 进行无密钥签名生成和验证
* 支持使用 ["环境" OpenID Connect 身份](https://github.com/sigstore/sigstore-python#signing-with-ambient-credentials)进行签名
* 提供一个全面的 [CLI](https://github.com/sigstore/sigstore-python#usage) 和相应的
[可导入 Python API](https://sigstore.github.io/sigstore-python)
## 安装
`sigstore` 需要 Python 3.10 或更新版本，可以直接通过 `pip` 安装：
```
python -m pip install sigstore
```
有关更多安装选项，请参阅文档中的[安装](https://sigstore.github.io/sigstore-python/installation)页面。
## 用法
关于 Python API 的使用，请参阅我们的 [API](https://sigstore.github.io/sigstore-python/api/)。
你可以将 `sigstore` 作为独立程序运行：
```
sigstore --help
```
顶层命令：
```
usage: sigstore [-h] [-v] [-V]
[--staging | --instance URL | --trust-config FILE]
COMMAND ...
a tool for signing and verifying Python package distributions
positional arguments:
COMMAND the operation to perform
attest sign one or more inputs using DSSE
sign sign one or more inputs
verify verify one or more inputs
get-identity-token
retrieve and return a Sigstore-compatible OpenID
Connect token
trust-instance Initialize trust for a Sigstore instance
plumbing developer-only plumbing operations
options:
-h, --help show this help message and exit
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
-V, --version show program's version number and exit
--staging Use sigstore's staging instance, instead of the default
production instance. Mutually exclusive with other
instance configuration arguments. (default: False)
--instance URL Use a given Sigstore instance URL, instead of the
default production instance. Mutually exclusive with
other instance configuration arguments. (default: None)
--trust-config FILE Use given client trust configuration instead of using
the default production instance. Mutually exclusive
with other instance configuration arguments. (default:
None)
```
### 签名
```
usage: sigstore sign [-h] [-v] [--rekor-version VERSION]
[--identity-token TOKEN] [--oidc-client-id ID]
[--oidc-client-secret SECRET]
[--oidc-disable-ambient-providers] [--oidc-issuer URL]
[--oauth-force-oob] [--no-default-files]
[--signature FILE] [--certificate FILE] [--bundle FILE]
[--output-directory DIR] [--overwrite]
FILE [FILE ...]
positional arguments:
FILE The file to sign
options:
-h, --help show this help message and exit
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
--rekor-version VERSION
Force the rekor transparency log version. Valid values
are [1, 2]. By default the highest available version
is used
OpenID 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 (default: None)
--oauth-force-oob Force an out-of-band OAuth flow and do not
automatically start the default web browser (default:
False)
Output options:
--no-default-files Don't emit the default output files
({input}.sigstore.json) (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)
--bundle FILE Write a single Sigstore bundle to the given file; does
not work with multiple input files (default: None)
--output-directory DIR
Write default outputs to the given directory
(conflicts with --signature, --certificate, --bundle)
(default: None)
--overwrite Overwrite preexisting signature and certificate
outputs, if present (default: False)
```
### 使用 DSSE envelopes 签名
```
usage: sigstore attest [-h] [-v] [--rekor-version VERSION] --predicate FILE
--predicate-type TYPE [--identity-token TOKEN]
[--oidc-client-id ID] [--oidc-client-secret SECRET]
[--oidc-disable-ambient-providers] [--oidc-issuer URL]
[--oauth-force-oob] [--bundle FILE] [--overwrite]
FILE [FILE ...]
positional arguments:
FILE The file to sign
options:
-h, --help show this help message and exit
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
--rekor-version VERSION
Force the rekor transparency log version. Valid values
are [1, 2]. By default the highest available version
is used
DSSE options:
--predicate FILE Path to the predicate file (default: None)
--predicate-type TYPE
Specify a predicate type
(https://slsa.dev/provenance/v0.2,
https://slsa.dev/provenance/v1) (default: None)
OpenID 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 (default: None)
--oauth-force-oob Force an out-of-band OAuth flow and do not
automatically start the default web browser (default:
False)
Output options:
--bundle FILE Write a single Sigstore bundle to the given file; does
not work with multiple input files (default: None)
--overwrite Overwrite preexisting bundle outputs, if present
(default: False)
```
### 验证
#### 身份
```
usage: sigstore verify identity [-h] [-v] [--certificate FILE]
[--signature FILE] [--bundle FILE] [--offline]
--cert-identity IDENTITY --cert-oidc-issuer
URL
FILE_OR_DIGEST [FILE_OR_DIGEST ...]
options:
-h, --help show this help message and exit
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
Verification 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)
--bundle FILE The Sigstore bundle to verify with; not used with
multiple inputs (default: None)
FILE_OR_DIGEST The file path or the digest to verify. The digest
should start with the 'sha256:' prefix.
Verification options:
--offline Perform offline verification; requires a Sigstore
bundle (default: False)
--cert-identity IDENTITY
The identity to check for in the certificate's Subject
Alternative Name (default: None)
--cert-oidc-issuer URL
The OIDC issuer URL to check for in the certificate's
OIDC issuer extension (default: None)
```
#### 来自 GitHub Actions 的签名
```
usage: sigstore verify github [-h] [-v] [--certificate FILE]
[--signature FILE] [--bundle FILE] [--offline]
[--cert-identity IDENTITY] [--trigger EVENT]
[--sha SHA] [--name NAME] [--repository REPO]
[--ref REF]
FILE_OR_DIGEST [FILE_OR_DIGEST ...]
options:
-h, --help show this help message and exit
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
Verification 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)
--bundle FILE The Sigstore bundle to verify with; not used with
multiple inputs (default: None)
FILE_OR_DIGEST The file path or the digest to verify. The digest
should start with the 'sha256:' prefix.
Verification options:
--offline Perform offline verification; requires a Sigstore
bundle (default: False)
--cert-identity IDENTITY
The identity to check for in the certificate's Subject
Alternative Name (default: None)
--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-python 项目为最新版本提供支持，并为最新的 3.6.x 版本提供尽力的关键错误修复。
### 常见问题
1. "_bundle contains a transparency log entry that is incompatible with
this version of sigstore-python_"（以及 "_not enough sources of
verified time_"）意味着需要升级才能验证此签名
bundle：包含 Rekor v2 transparency log 条目的签名 bundle 只能
通过 sigstore-python 4 及更高版本进行验证
2. 在没有网络连接的情况下验证会导致 HTTP 错误：默认情况下
sigstore-python 在每次启动时都会检查受信密钥材料的更新。
可以使用 `--offline` 暂时避免这种情况，但请阅读
[文档](https://sigstore.github.io/sigstore-python/advanced/offline/)
了解注意事项
3. 签名导致 HTTP 错误：使用 sigstore-python 签名依赖于多个
Sigstore 服务。如果任何
这些服务失败，重试可能是一个有用的解决方法，但我们感谢您针对特定失败提交问题
### 我的问题不在这里
请[提交 issue](https://github.com/sigstore/sigstore-python/issues/new?template=bug.md)或在 [slack 频道](#community)中提问。
## 文档
`sigstore` 文档可在 [https://sigstore.github.io/sigstore-python](https://sigstore.github.io/sigstore-python) 获取
## 许可协议
`sigstore` 根据 Apache 2.0 许可证授权。
## 行为准则
所有参与本项目的人员均应遵守
[sigstore 行为准则](https://github.com/sigstore/.github/blob/main/CODE_OF_CONDUCT.md)。
## 安全
如果您发现任何安全问题，请参阅 sigstore 的[安全
流程](https://github.com/sigstore/.github/blob/main/SECURITY.md)。
标签：CVE, DevSecOps, DNS 反向解析, OpenID Connect, PyPI安全, Python, Sigstore, SLSA, 上游代理, 代码签名, 数字签名, 无后门, 无密钥签名, 签名验证, 软件完整性, 逆向工具