starhaven-io/pinprick-action
GitHub: starhaven-io/pinprick-action
用于在 GitHub Actions 工作流中运行 pinprick 引擎，审计 Actions 供应链安全并检测版本锁定绕过问题的 action 封装。
Stars: 0 | Forks: 0
# pinprick-action
从 GitHub Actions 运行 [pinprick](https://github.com/starhaven-io/pinprick)。
pinprick 通过发现绕过版本锁定的运行时获取模式、检查 action 引用，并通过可解释的开放式评分标准报告结果，从而审计 GitHub Actions 的供应链安全。
## 快速开始
### 配合 GitHub Advanced Security 使用
这是默认模式。该 action 会生成 SARIF 并将检测结果上传到 GitHub code scanning，以便它们显示在仓库的 Security 标签页中。
在此模式下，除非设置了 `fail-on-findings: true`，否则当 pinprick 报告检测结果时，该 action 不会使工作流失败。如果您希望 code scanning 警报阻止合并，请使用 GitHub rulesets。
请在受信任的事件（例如 `push` 或 `workflow_dispatch`）上运行 SARIF 上传。来自 fork 的拉取请求会收到只读 token，因此 SARIF 上传可能会在那里失败；请使用控制台模式来获取拉取请求反馈。
```
name: GitHub Actions supply chain audit
on:
push:
branches:
- main
workflow_dispatch:
permissions: {}
jobs:
pinprick:
runs-on: ubuntu-24.04
permissions:
security-events: write
contents: read # needed for checkout and private/internal repositories
actions: read # needed for private/internal repositories
steps:
- name: Checkout repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
persist-credentials: false
- name: Run pinprick
uses: starhaven-io/pinprick-action@b711e85aacbd9cf73e0285b16b0f3d0b35b3ae60 # v0.2.0
```
### 不使用 GitHub Advanced Security
设置 `advanced-security: false` 以将结果打印到工作流日志中，而不是上传 SARIF。此模式适用于来自 fork 的拉取请求。
```
name: GitHub Actions supply chain audit
on:
push:
branches:
- main
pull_request:
branches:
- "**"
permissions: {}
jobs:
pinprick:
runs-on: ubuntu-24.04
permissions:
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
persist-credentials: false
- name: Run pinprick
uses: starhaven-io/pinprick-action@b711e85aacbd9cf73e0285b16b0f3d0b35b3ae60 # v0.2.0
with:
advanced-security: false
```
每个示例都通过尾部注释中的发布标签将 pinprick-action 锁定为完整的 commit SHA，而不是可变标签。这正是 pinprick 本身所检查的锁定方式；当您采用较新的版本时，请更新该 SHA。
### 检测到结果时失败
```
- name: Run pinprick
uses: starhaven-io/pinprick-action@b711e85aacbd9cf73e0285b16b0f3d0b35b3ae60 # v0.2.0
with:
fail-on-findings: true
```
## 输入
| 输入 | 默认值 | 描述 |
| --- | --- | --- |
| `version` | `0.18.0` | 要安装的 pinprick 版本，默认锁定以确保运行确定性。使用 `latest` 获取最新版本，或使用精确版本如 `v0.18.0`。 |
| `path` | `.` | 要扫描的仓库路径。 |
| `advanced-security` | `true` | 生成 SARIF 并将其上传到 GitHub code scanning。 |
| `fail-on-findings` | `false` | 当 pinprick 报告检测结果时使工作流失败。内部错误始终会导致失败。 |
pinprick 目前支持通过 `.pinprick.toml` 进行严重性过滤，而不是通过审计 CLI 标志，因此该 action 不提供 `min-severity` 输入。
## 输出
| 输出 | 描述 |
| --- | --- |
| `sarif-file` | 当 `advanced-security: true` 时，SARIF 结果的文件路径。 |
## 权限
使用 `permissions: {}` 启动工作流，并仅在运行 pinprick 的作业上授予权限。
| 权限 | 适用场景 |
| --- | --- |
| `security-events: write` | `advanced-security: true` 将 SARIF 上传到 code scanning 时。 |
| `contents: read` | 克隆仓库时，以及私有/内部仓库使用 Advanced Security 时。 |
| `actions: read` | 私有/内部仓库使用 Advanced Security 时。 |
该 action 会将工作流的 `GITHUB_TOKEN` 传递给 pinprick，以便在作业权限允许的情况下，它可以获取并审计外部 action 源码。如果没有 token，pinprick 仍会扫描本地工作流的 `run:` 代码块和本地 action。
## 退出行为
pinprick 使用以下退出代码：
| 代码 | 含义 | Action 行为 |
| --- | --- | --- |
| `0` | 干净（无问题） | 成功。 |
| `1` | 存在检测结果 | 默认成功；仅在设置了 `fail-on-findings: true` 时失败。 |
| `2+` | 错误 | 失败。 |
在 Advanced Security 模式下，SARIF 上传发生在可选的 `fail-on-findings` 失败之前，因此检测结果仍然可以在 code scanning 中查看。
## 版本控制
此 action 的每个版本都通过默认的 `version` 锁定了特定的 pinprick 版本，因此锁定到特定 action ref 的工作流在每次运行时都会安装相同的 pinprick 构建版本。要升级到较新的 pinprick，请将该 action 升级到以其为默认目标的发布版本，或者自行设置 `version`（如果您接受非确定性安装，也可以包括 `latest`）。
## 许可证
此 action 包装器采用 MIT 许可证授权。请参阅 [LICENSE](LICENSE)。
由此 action 下载并运行的 pinprick 引擎是一个独立的项目，仅采用 [GNU Affero General Public License v3.0](https://github.com/starhaven-io/pinprick/blob/main/LICENSE) 授权。
使用此包装器不会重新授权 pinprick，也不会更改 pinprick 的许可条款。
## 鸣谢
此 action 的复合结构受到了
[zizmor-action](https://github.com/zizmorcore/zizmor-action) 的启发 (MIT, © William Woodruff)。
标签：Cutter, DevSecOps, GitHub Actions, Python安全, SARIF, 上游代理, 云安全监控, 自动笔记, 静态分析