Halfblood-Prince/trustcheck-action
GitHub: Halfblood-Prince/trustcheck-action
在 CI 中自动运行 TrustCheck，评估 PyPI 包的供应链信任信号并阻断高风险依赖。
Stars: 1 | Forks: 0
# TrustCheck GitHub Action
[](https://pypi.org/project/trustcheck/)
[](https://pypi.org/project/trustcheck/)
[](LICENSE)
在 GitHub Actions 中运行 [TrustCheck](https://github.com/Halfblood-Prince/trustcheck)，以在安装、推广或批准 PyPI 包之前评估其信任状况。
此操作是对核心 `trustcheck` CLI 的轻量级封装。它会安装 CLI 并在工作流中运行 `trustcheck inspect`，以便在 CI 期间展示来源、发布者、仓库、漏洞以及与策略相关的信号。
## 为何使用 TrustCheck
传统的依赖检查通常只回答“此包是否已知存在漏洞？”
TrustCheck 帮助回答更早期的问题，例如：
- 此发布版本是否具有已验证的来源？
- 已证明的发布者详细信息是否指向预期的仓库和工作流？
- 声明的仓库 URL 是否与已证明的证据一致？
- 是否存在应阻止采用的漏洞记录或更高风险的信任信号？
核心 CLI 将 PyPI 元数据、来源可用性、加密证明验证、已信任发布者身份提示、仓库匹配、发布版本漂移信号以及漏洞记录整合到单个报告中。
## 此操作的作用
当前，此操作：
1. 从 PyPI 安装 `trustcheck`
2. 运行 `trustcheck inspect `
3. 如果 CLI 以非零状态退出，则使工作流步骤失败
这使得在 GitHub Actions 中引入 TrustCheck 成为一种简便方式，同时将繁重的工作保留在核心项目中。
## 快速开始
```
name: TrustCheck Scan
on:
pull_request:
workflow_dispatch:
jobs:
trustcheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Inspect package with TrustCheck
uses: Halfblood-Prince/trustcheck-action@v1
with:
package: requests
```
## 输入
| 名称 | 必需 | 描述 |
| --- | --- | --- |
| `package` | 是 | 要检查的 PyPI 包名 |
## 示例用例
在拉取请求期间审查包：
```
name: Dependency Trust Check
on:
pull_request:
jobs:
trustcheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Inspect requests
uses: Halfblood-Prince/trustcheck-action@v1
with:
package: requests
```
按需运行检查：
```
name: Manual TrustCheck
on:
workflow_dispatch:
jobs:
trustcheck:
runs-on: ubuntu-latest
steps:
- name: Inspect sampleproject
uses: Halfblood-Prince/trustcheck-action@v1
with:
package: sampleproject
```
## 核心 CLI 可评估的内容
根据核心 TrustCheck 文档，`trustcheck inspect` 可以评估：
- 来自 PyPI 的项目与发布元数据
- 声明的仓库 URL
- 发布工件的来源信封
- 针对工件摘要的证明验证
- 已信任发布者身份详情，例如仓库和工作流
- 预期的仓库匹配
- 发布者仓库与工作流之间的漂移
- 选定版本的漏洞记录
- 供操作人员和自动化使用的文本或 JSON 输出
核心项目中的推荐等级包括 `verified`、`metadata-only`、`review-required` 和 `high-risk`。
## 关于此操作的重要说明
当前的 GitHub Action 故意保持最小化。它仅公开 `package` 输入并运行默认的 `trustcheck inspect` 命令。
如果需要核心项目中记录的更高级 TrustCheck 行为，例如：
- `--version`
- `--expected-repo`
- `--strict`
- `--policy` 或 `--policy-file`
- `--format json`
- `--verbose`
- `--config-file`
- `--cache-dir` 或 `--offline`
请直接在工作流中使用核心 CLI，或扩展此操作以将这些标志作为额外输入暴露出来。
## 建议的高级工作流
如果希望立即实施更严格的策略，请直接安装并运行 CLI：
```
name: Verify Dependency Trust
on:
pull_request:
workflow_dispatch:
jobs:
trustcheck:
runs-on: ubuntu-latest
steps:
- uses: actions/setup-python@v6
with:
python-version: "3.12"
- name: Install TrustCheck
run: python -m pip install --upgrade pip trustcheck
- name: Inspect pinned release with strict policy
run: |
trustcheck inspect sampleproject \
--version 4.0.0 \
--expected-repo https://github.com/pypa/sampleproject \
--strict
```
## 退出行为
根据核心 CLI 文档：
- `0` 表示成功
- `1` 表示上游 PyPI 或网络故障
- `2` 表示命令用法错误
- `3` 表示无效响应或内部处理失败
- `4` 表示策略失败
在 CI 中，策略失败非常有用：这意味着 TrustCheck 已正确运行并有意根据所选策略阻止了该包。
## 文档
- 核心项目：https://github.com/Halfblood-Prince/trustcheck
- 文档：https://halfblood-prince.github.io/trustcheck/
- PyPI 包：https://pypi.org/project/trustcheck/
## 许可证
本仓库在“TrustCheck Action Personal Use License”下以来源可用方式授权。
在 GitHub Action Use Exception 包含于 [LICENSE](LICENSE) 的条件下，允许在流程中使用官方的 `Halfblood-Prince/trustcheck-action` GitHub Action。
该例外适用于在流程中使用官方操作。它不授予广泛复制、修改、重新分发、再许可或在此上下文之外重新发布本仓库源代码的权利。
标签：CI, GitHub Action, PyPI, TrustCheck, 代码审核, 信任信号, 发布者验证, 发布证明, 可信发布, 安全扫描, 工作流, 开源框架, 持续集成, 时序注入, 结构化查询, 自动化安全, 软件供应链, 软件供应链完整性, 逆向工具