Halfblood-Prince/trustcheck

# trustcheck [](https://awesome.re) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/source-build.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/codeql.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/bandit.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/semgrep.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/fuzz.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/binary-security.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/binary-security.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://pypi.org/project/trustcheck/) [](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/ci.yml) [](https://pepy.tech/projects/trustcheck) [](https://github.com/marketplace/actions/trustcheck-package-scanner) [](https://snapcraft.io/trustcheck) `trustcheck` 是一个 Python package 和 CLI，用于在安装、推广或批准 PyPI 版本之前评估其信任状态。 它将 PyPI 元数据、漏洞记录、来源（provenance）可用性、加密证明验证、受信任发布者（Trusted Publisher）身份提示以及代码库匹配结合到一个对运维人员友好的报告中。 未发布来源（provenance）的 package 会被视为需要人工审查，而不是自动将其标记为高风险发现；同时，无效的来源、部分覆盖、代码库不匹配以及已知漏洞仍然是较强的负面信号。 ## 检查内容 对于选定的 package 版本，`trustcheck` 可以： - 从 PyPI 获取项目和发布元数据 - 根据构件摘要验证已发布的来源（provenance） - 解析 SLSA v1 构建定义、构建器、源材料、提交、 工作流以及已解析的构建依赖项 - 检测可变工作流引用、未固定的构建操作以及 源到构件的不一致性 - 呈现受信任发布者（Trusted Publisher）的代码库和工作流身份提示 - 在整个发布历史中，对比签名者、代码库、工作流、构建器、构建类型和源提交 证据 - 将预期的代码库输入与声明及已证明的信号进行对比 - 标记发布者漂移、缺失验证以及已知漏洞 - 扫描 requirements 文件、项目 TOML、`pylock.toml`、`Pipfile.lock`、 pip-tools 输出以及 `uv.lock`、`poetry.lock` 或 `pdm.lock` - 使用 pip 安装报告解析完整的依赖集，包括 约束、嵌套 requirements、extras、依赖组、可编辑 requirements 以及 VCS 引用 - 审计活动的 Python 环境或任意的 `site-packages` 目录 - 使用可选的 keyring 凭据，针对 PEP 503/691 私有索引进行解析 - 阻断跨公共和私有索引的依赖混淆（dependency-confusion）冲突 - 在信任下载的字节之前，保留并验证 lockfile 构件哈希 - 规划、预演（dry-run）、应用或发布最小且经过验证的安全依赖 升级集，而不会静默扩大声明的约束 - 批处理 OSV 查询，限制并发目标工作，并按 已验证的 SHA-256 内容摘要存储响应 - 使用离线建议快照，恢复中断的扫描，并 加载明确启用的建议、索引、构件、策略或渲染器插件 - （可选）在不导入或执行 package 代码的情况下检查 wheel 和 sdist 内容 - 对抢注（typosquatting）、依赖混淆、package 历史、源代码以及 原生二进制启发式指标进行评分，但不做出恶意软件裁决 - 输出 text、JSON、SARIF 2.1.0、CycloneDX 1.6 JSON/XML、SPDX 2.3 JSON、 OpenVEX 0.2.0 或 Markdown 每次推送还会构建独立的 Windows 和 Linux 可执行文件。Windows 构件会使用 Microsoft Defender 的 `MpCmdRun.exe` 进行扫描；Linux 构件会使用 ClamAV 进行扫描。干净的二进制文件、校验和和扫描报告 将作为工作流构件由 [Binary Security](https://github.com/Halfblood-Prince/trustcheck/actions/workflows/binary-security.yml) 保留。 ## 最新基准测试 在 Python `3.14.6` 环境下使用 `pip-audit 2.10.0` 生成于 `2026-06-21T08:43:40.047949+00:00`。语料库 `2026.06` 涵盖了 112 个可比较的 package 条目。 | 工具 | Cold p50 | Warm p50 | Warm p95 | 峰值 RSS | Requests p50 | 召回率 | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | trustcheck scan --fast | 17.08 s | 15.70 s | 15.70 s | 88.3 MiB | unknown | 1 | | pip-audit | 38.71 s | 39.96 s | 39.96 s | 74.4 MiB | unknown | 1 | 别名感知一致性：在 `109` 个被比较的 package 和 `227` 个匹配的建议中为 `0.759197`。 解析器精确匹配：`True`（trustcheck `22`，pip-audit `22`）。 ## 安装说明 从 PyPI 安装： ``` pip install trustcheck ``` 当私有索引凭据存储在进程内的 keyring 后端时，安装可选的 Python keyring 提供程序： ``` pip install "trustcheck[keyring]" ``` 项目默认配置可以存放在 `.trustcheck.toml` 中，或 `pyproject.toml` 的 `[tool.trustcheck]` 下。CLI 标志会覆盖环境变量，而环境变量会覆盖 项目配置。请参阅[配置指南](https://halfblood-prince.github.io/trustcheck/cli/configuration/)。 或者安装 Snap Store package： ``` sudo snap install trustcheck ``` Snap 命令为 `trustcheck`。如果安装后 shell 立即报告 `command not found`，请启动一个新的登录会话，或将 Snap 的 命令目录添加到当前 shell 中： ``` export PATH="/snap/bin:$PATH" trustcheck --version ``` 你始终可以通过以下方式绕过 shell PATH 查找： ``` snap run trustcheck inspect requests ``` PyPI 安装要求： - Python `>=3.11` - 可访问 PyPI 的网络 机器可读报告目前使用 JSON schema `1.11.0`。Package 和报告 schema 版本是相互独立的，因此仅包含文档的 package 发布不会 强制更改契约。 ## Pre-commit 与 monorepos Trustcheck 为已更改的依赖文件发布了第一方 hook： ``` repos: - repo: https://github.com/Halfblood-Prince/trustcheck rev: v1 hooks: - id: trustcheck ``` 该 hook 运行 `--fast --no-deps --with-osv`，保留 lockfile 构件哈希， 对文件名进行去重，并合并每个已更改依赖文件中的失败结果。 对于 monorepos，`trustcheck-workspace . --format sarif` 会发现受支持的文件， 聚合相对于代码库的结果，并接受 `--baseline` 以及用于各项目策略的 `--policy-overrides`。 ## TrustCheck Package Scanner 使用 TrustCheck Package Scanner 操作在合并前扫描已提交的依赖文件： ``` steps: - uses: actions/checkout@v7 - uses: Halfblood-Prince/trustcheck@v1 with: target: requirements.txt policy: strict ``` 该操作会安装并运行 `trustcheck`，将 `trustcheck-report.json` 作为 工作流构件上传，并在策略评估失败时使用 CLI 的退出代码使 作业失败。`target` 还接受 PyPI package 名称、`pyproject.toml`、 `pylock.toml`、`Pipfile.lock`、`uv.lock`、`poetry.lock` 或 `pdm.lock`。 每个稳定版本都会发布一个不可变的完整版本标签，并更新上面 使用的兼容的主要操作标签。 为 GitHub 代码扫描生成 SARIF，而无需重复审计： ``` - uses: Halfblood-Prince/trustcheck@v1 id: trustcheck with: target: requirements.txt format: sarif - uses: github/codeql-action/upload-sarif@v4 if: always() with: sarif_file: ${{ steps.trustcheck.outputs.report-path }} ``` 请参阅 [CI 集成指南](https://halfblood-prince.github.io/trustcheck/guides/ci-integration/) 以了解自定义策略、OSV、依赖遍历、输出和报告命名。 ## 快速开始 检查最新发布版本： ``` trustcheck inspect requests ``` 检查特定版本： ``` trustcheck inspect sampleproject --version 4.0.0 ``` 仅显示发布版本的已知漏洞： ``` trustcheck scan sampleproject --version 4.0.0 --fast ``` 扫描配置文件使分析深度更加明确。`--fast`（默认值）仅执行 依赖解析和漏洞建议查找。`--standard` 会添加来源（provenance）验证， 而 `--full` 会添加静态归档、原生二进制文件、发布历史以及 恶意 package 启发式检查。构件范围默认为请求目标的最佳兼容 wheel，并以 sdist 作为后备。 ``` trustcheck scan -f requirements.txt --standard trustcheck scan sampleproject --version 4.0.0 --full --workers 8 trustcheck scan sampleproject --full --artifact-scope all --strict ``` 使用 `--artifact-scope sdist` 进行源码审查，或使用 `--artifact-scope all` 进行 严格的整体发布审查。 使用 OSV 和 GitHub Advisory Database 数据丰富漏洞情报： ``` trustcheck scan jinja2 --version 2.10.0 --with-osv ``` 合并 OSV、Ecosyste.ms、私有 OSV 兼容服务、CISA KEV 和 FIRST EPSS 情报： ``` trustcheck scan jinja2 \ --version 2.10.0 \ --with-osv \ --with-ecosystems \ --osv-url https://advisories.example.com \ --with-kev \ --with-epss ``` 仅对严重、已知被利用或可修复的漏洞进行拦截： ``` trustcheck scan -f pylock.toml --fail-on-vulnerability kev ``` 要求经过验证的发布者必须属于已批准的组织： ``` trustcheck inspect sampleproject \ --version 4.0.0 \ --trusted-publisher-organization github:pypa ``` 自定义策略文件可以暂时抑制特定的建议，但每次 抑制都必须指明负责人、理由以及 ISO 过期日期。 检查一个 package 及其直接依赖： ``` trustcheck inspect sampleproject --version 4.0.0 --with-deps ``` 检查完整的传递依赖树： ``` trustcheck inspect sampleproject --version 4.0.0 --with-transitive-deps ``` 检查 requirements 格式文件中列出的每个 package： ``` trustcheck inspect -f requirements.txt ``` 解析使用 `pip install --dry-run --report`，并包含由 pip 选择的传递 package： ``` trustcheck scan -f requirements.txt \ --constraint constraints.txt \ --python-version 3.12 \ --platform manylinux_2_28_x86_64 \ --implementation cp \ --abi cp312 ``` 即使在 dry-run 模式下，Pip 也可能会调用构建后端元数据 hook。Trustcheck 可以隔离该解析器调用： ``` trustcheck scan -f requirements.txt --sandbox auto ``` `--sandbox auto` 是默认设置。它优先在 Linux 上使用 Bubblewrap，然后是 Docker 或 Podman，并在没有可用 runtime 时回退到严格的仅限 wheel 的解析。完整的模式集为： - `warn`：明确保留主机 pip 行为，并发出执行风险警告 - `off`：保留 pip 行为，但不发出警告 - `container`：在只读的 Docker/Podman 容器中以非特权进程方式运行 pip， 丢弃相关能力，并仅挂载暂存的解析器输入 - `bubblewrap`：在低权限的 Linux 命名空间中运行 pip，配合只读的 暂存输入树、只读的系统路径以及清空的环境 - `strict`：拒绝可编辑、VCS、本地非 wheel、直接非 wheel 和源 归档输入，忽略用户 pip 配置，并要求每个解析的 package 都使用 wheel； 禁止创建子进程，因此意外的传递源 hook 和 VCS 命令将直接失败 Container 和 Bubblewrap 模式会保留用于 package 索引解析的 网络访问权限。Requirements、嵌套包含、约束、依赖组 文件以及引用的本地依赖会被复制到临时输入树中； 项目工作区不会被挂载。当使用 `--sandbox-image` 提供 容器镜像时，必须通过完整的 SHA-256 摘要进行固定。跨目标 解析始终仅限 wheel。 检查 TOML 项目文件中声明的依赖： ``` trustcheck inspect -f pyproject.toml ``` 规划最小且兼容约束的安全升级集： ``` trustcheck scan -f requirements.txt \ --with-osv \ --plan-fixes \ --remediation-output reports/trustcheck-remediation.json ``` 在不更改工作树的情况下生成并验证准确的补丁： ``` trustcheck scan -f pyproject.toml --with-osv --fix --dry-run ``` 仅在重新解析和完整重新扫描后应用相同的事务： ``` trustcheck scan -f uv.lock --with-osv --fix ``` 被声明的范围排除在外的安全版本仍会被拦截，除非 传递了 `--allow-constraint-changes`。可编辑、本地路径、直接归档 和 VCS 依赖将被为需要人工修复。 选择项目的 extras 和依赖组： ``` trustcheck scan -f pyproject.toml --extra security --group test ``` 从受支持的 lockfile 中检查准确的直接和传递版本： ``` trustcheck inspect -f pylock.toml --with-transitive-deps trustcheck scan -f Pipfile.lock ``` 运行有界、可恢复的扫描并发布漏洞建议快照： ``` trustcheck scan -f requirements.txt \ --with-osv \ --workers 8 \ --resume-state .trustcheck/scan-state.json \ --write-advisory-snapshot .trustcheck/advisories.json \ --sign-advisory-snapshot ``` 签名快照包含源 URL、生成和过期时间，以及 规范建议记录的 SHA-256 摘要。读取快照需要受信任的 Sigstore 证书身份，并且默认情况下最多接受 7 天的快照； 使用 `--max-advisory-age HOURS` 调整该界限。 显式启用已安装的签名插件： ``` trustcheck scan -f requirements.txt --plugin policy:company-policy ``` 每个插件都必须被明确加入白名单。Trustcheck 会在使用生成的 资源受限 worker 之前，验证其签名的 `trustcheck-plugin.json` 名称、类型、入口点和 API 版本。可选的签名者指纹位于 插件配置的 `_trustcheck.trusted_signers` 下。每次调用都会在 `diagnostics.plugin_executions` 中报告其状态、持续时间和隔离状态。 哈希固定的 pip-tools 输出会被自动检测。每个保留的 lockfile 哈希都会以合并的 JSON 格式输出，并与下载的 构件进行核对。此完整性检查不需要 `--inspect-artifacts`。 从私有 PEP 503/691 索引解析并审计： ``` trustcheck scan -f requirements.txt \ --index-url https://username@packages.example.com/simple \ --keyring-provider subprocess ``` 添加公共回退受到刻意的保护： ``` trustcheck scan -f requirements.txt \ --index-url https://username@packages.example.com/simple \ --extra-index-url https://pypi.org/simple ``` 如果两个索引上都存在相同的规范化项目名称，扫描将停止 并报出依赖混淆错误。对于已通过独立审查的源冲突，可以使用 `--allow-dependency-confusion`；该发现 仍会保留在合并的 JSON 中。 审计当前活动环境： ``` trustcheck environment ``` 审计一个或多个显式的 `site-packages` 目录： ``` trustcheck environment --path .venv/lib/python3.12/site-packages ``` 静态检查 wheel 和 sdist 内容： ``` trustcheck inspect sampleproject --version 4.0.0 --inspect-artifacts --verbose ``` 构件检查会验证 wheel `RECORD` 哈希，列出控制台脚本， 使用 `ast` 解析 Python 源代码，检测可疑的能力组合， 并比较 wheel 和 sdist 元数据。PE、ELF 和 Mach-O 文件将接受检查， 以查找导入的库、嵌入式签名状态、熵以及嵌入式 payload 签名。它仅读取归档字节，绝不导入被 检查的 package。 对于行为证据，`--dynamic-analysis` 作为一种明确的可选选项提供。 它会在一次性的 Docker 容器中执行下载的构件，该容器没有 网络，使用非 root 用户，丢弃相关能力，并具有严格的 CPU、内存、进程 和实际时间限制。它永远不会被默认启用。 名称、索引、所有权、代码库和发布频率启发式检查会在 常规检查期间运行。使用可重复的 `--trusted-project` 添加组织特定的参考名称： ``` trustcheck inspect -f requirements.txt \ --trusted-project internal-sdk \ --trusted-project internal-auth ``` 每个恶意 package 的发现都会被明确标记为供审查的启发式指标， 而不是该 package 恶意的证据。 要求发布版本与预期的代码库相匹配： ``` trustcheck inspect sampleproject \ --version 4.0.0 \ --expected-repo https://github.com/pypa/sampleproject ``` 为其他工具输出 JSON： ``` trustcheck inspect sampleproject --version 4.0.0 --format json ``` 为 requirements 格式、TOML 或 lockfile 扫描输出合并的 JSON： ``` trustcheck scan -f requirements.txt --format json ``` 将 SARIF、SBOM、VEX 或 Markdown 输出直接写入文件： ``` trustcheck scan -f requirements.txt \ --format sarif \ --output-file reports/trustcheck.sarif trustcheck scan -f pylock.toml \ --format cyclonedx-json \ --output-file reports/trustcheck.cdx.json ``` 支持的行业标准格式包括 `sarif`、`cyclonedx-json`、`cyclonedx-xml`、 `spdx-json`、`openvex` 和 `markdown`。SBOM 导出会保留 package purl、 漏洞、来源覆盖范围、构件哈希、建议以及 策略违规。 仅以 JSON 格式输出漏洞记录： ``` trustcheck scan sampleproject --version 4.0.0 --format json ``` 当缺少完整验证时使 CI 失败： ``` trustcheck inspect sampleproject --version 4.0.0 --strict ``` 从 Python 中使用它： ``` from trustcheck import inspect_package report = inspect_package("sampleproject", version="4.0.0", include_dependencies=True) print(report.recommendation) ``` ## 文档 完整文档：https://halfblood-prince.github.io/trustcheck/ - 入门：[安装说明](https://halfblood-prince.github.io/trustcheck/getting-started/installation/) 和 [快速开始](https://halfblood-prince.github.io/trustcheck/getting-started/quickstart/) - CLI 用法：[CLI 概览](https://halfblood-prince.github.io/trustcheck/cli/)、[策略](https://halfblood-prince.github.io/trustcheck/cli/policies/) 和 [配置与离线模式](https://halfblood-prince.github.io/trustcheck/cli/configuration/) - 集成：[JSON 契约](https://halfblood-prince.github.io/trustcheck/reference/json-contract/)、[Python API](https://halfblood-prince.github.io/trustcheck/reference/python-api/) 和 [兼容性](https://halfblood-prince.github.io/trustcheck/reference/compatibility/) - 信任模型：[验证模型与代码库匹配](https://halfblood-prince.github.io/trustcheck/reference/trust-model/) - 自动化：[CI 集成](https://halfblood-prince.github.io/trustcheck/guides/ci-integration/) - 性能与可扩展性：[批处理、缓存、快照、恢复状态与插件](https://halfblood-prince.github.io/trustcheck/reference/performance-extensibility/) - 基准测试：[与 pip-audit 的可重复比较](https://halfblood-prince.github.io/trustcheck/reference/benchmarks/) - 项目详情：[更新日志](https://halfblood-prince.github.io/trustcheck/changelog/) 项目支持： - Bug 和功能请求：[GitHub Issues](https://github.com/Halfblood-Prince/trustcheck/issues) - 敏感安全报告：[GitHub 私有漏洞报告](https://github.com/Halfblood-Prince/trustcheck/security/advisories/new) - 安全策略：[SECURITY.md](https://github.com/Halfblood-Prince/trustcheck/security/policy) ## 许可证 [Trustcheck 个人使用许可证](LICENSE)

标签：PyPI, Python, 供应链安全, 依赖管理, 完整性校验, 无后门