# Trustabl Action
一个运行 [trustabl](https://github.com/trustabl/trustabl) 的 GitHub Action —— 它是
用于 agent 仓库（Claude Agent SDK, OpenAI
Agents SDK, Google ADK, LangChain, CrewAI, Pydantic AI, Vercel AI, AutoGen, MCP
服务器，以及 Claude 子 agent 和技能）的
静态可靠性/安全性分析器 —— 并在你工作的环境中展示结果：
- **内联 PR 注释 + Security 标签页。** 结果会被上传到 GitHub
Code Scanning，因此它们会显示在 PR diff 的已更改行以及仓库的
Security 标签页中。
- **置顶 PR 评论**，包含就绪度评分、严重程度细分，以及
修复空间阶梯 —— 每次运行都会原地更新。
- **状态检查门禁。**（可选）根据风险评分或严重程度阈值使作业失败，
从而将其作为必要检查。
- **就绪度面板**，显示在运行日志和 Step Summary 中。
- **可选的依赖项 CVE 扫描**（`vuln-scan: true`）—— 将你声明的
依赖项与固定的 OSV 快照进行匹配，并将已知的 CVE 作为结果报告，
因此它们会出现在每个界面（评分、门禁、注释、Security 标签页）中。
它会下载官方的 `trustabl` 发布二进制文件（根据发布版
`checksums.txt` 进行 sha256 校验），将其放入工具缓存中，扫描你的检出内容，
并报告结果。
## 快速开始
```
name: Trustabl
on: [push, pull_request]
permissions:
contents: read
security-events: write # SARIF → Security tab + inline PR alerts
pull-requests: write # sticky PR comment
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: trustabl/trustabl-action@v0
```
在零配置的情况下，该 action 会扫描检出内容，将结果发布到 Security
标签页，并且（在 PR 中）作为置顶评论 + 内联注释，将
`trustabl.json` + `trustabl.sarif` 作为 artifact 附加，并且仅当
`trustabl` 本身标记出中危或更高危的发现时才会使作业失败。
## 带注释的示例
```
name: Trustabl
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
permissions:
contents: read
security-events: write
pull-requests: write
jobs:
scan:
runs-on: ubuntu-latest # also works on macos-* / windows-*
steps:
- uses: actions/checkout@v4 # REQUIRED first — the action scans your checkout
- uses: trustabl/trustabl-action@v0
with: # every input is optional
# detectors: openai_sdk # limit SDKs: claude_sdk,openai_sdk,google_adk,openshell
# version: latest # trustabl release to run; pin e.g. v0.5.0 for reproducible CI
# vuln-scan: true # also scan dependencies for known CVEs (OSV)
# severity-threshold: high # fail if any finding >= level (none|low|medium|high|critical)
# risk-score-threshold: 70 # fail if risk (100 - readiness) >= N (0 disables)
# comment-on-pr: true # sticky PR summary comment
# annotations: true # inline annotations
# upload-sarif: true # Security tab upload
# upload-artifact: true # attach trustabl.json + trustabl.sarif
```
## 固定版本 + 门禁
```
- uses: trustabl/trustabl-action@v0.3.1
with:
version: v0.5.0
detectors: claude_sdk,openai_sdk
severity-threshold: high # fail on any high or critical finding
risk-score-threshold: 70 # fail if risk (100 - readiness) >= 70
artifact-retention-days: "30"
```
## 丰富信息与自动丰富信息
当设置为 `enrich: true` 时，扫描完成后，该 action 会使用你的
LLM API 密钥调用 `trustabl enrich`，为每个发现生成 AI 解释和代码修复。
当设置为 `auto-enrich: true` 时，高置信度的修复会直接应用到源
文件中。当设置为 `create-fix-pr: true` 时，补丁将被提交到一个新分支上，
并开启一个 pull request 以供人工审查。
```
permissions:
contents: write # push fix branch
pull-requests: write # open fix PR
security-events: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: trustabl/trustabl-action@v0
with:
enrich: true
llm-key: ${{ secrets.ANTHROPIC_API_KEY }}
auto-enrich: true
create-fix-pr: true
```
Enrich 是尽力而为的 —— 如果失败，扫描结果和门禁决策不会
受到影响，只会发出警告而不是导致作业失败。
**仅限 PR 的自动丰富信息。** 如果要在每次推送时生成解释，但仅在
pull request 中应用修复并开启修复 PR：
```
- uses: trustabl/trustabl-action@v0
with:
enrich: true
llm-key: ${{ secrets.ANTHROPIC_API_KEY }}
auto-enrich: ${{ github.event_name == 'pull_request' }}
create-fix-pr: ${{ github.event_name == 'pull_request' }}
```
## 输入项
| 名称 | 默认值 | 描述 |
|---|---|---|
| `target` | `.` | 要扫描的路径或 GitHub URL。 |
| `version` | `latest` | trustabl 发布标签（例如 `v0.5.0`）或 `latest`。 |
| `detectors` | _(全部)_ | 逗号分隔的 SDK 子集：`claude_sdk`, `openai_sdk`, `google_adk`, `openshell`, `mcp`, `langchain`, `crewai`, `pydantic_ai`, `vercel_ai`, `autogen`。 |
| `strict` | `false` | 传递 `--strict`（有任何发现即失败）。 |
| `vuln-scan` | `false` | 将依赖项与固定的 OSV 快照进行匹配；将已知 CVE 作为发现报告。 |
| `rules-ref` | _(默认)_ | 固定一个 `trustabl-rules` git 引用。 |
| `rules-repo` | _(默认)_ | 覆盖 `trustabl-rules` 源仓库。 |
| `upload-sarif` | `true` | 将 SARIF 上传到 Code Scanning。需要 `security-events: write`。 |
| `sarif-file` | `trustabl.sarif` | SARIF 输出路径。 |
| `json-file` | `trustabl.json` | JSON `ScanResult` 输出路径。 |
| `upload-artifact` | `true` | 将 JSON + SARIF 作为工作流 artifact 附加。 |
| `artifact-name` | `trustabl-scan-results` | Artifact 名称。 |
| `artifact-retention-days` | _(仓库默认值)_ | Artifact 保留天数 (1-90)。 |
| `comment-on-pr` | `true` | 置顶 PR 摘要评论。需要 `pull-requests: write`。 |
| `annotations` | `true` | 为发现生成内联注释。 |
| `max-annotations` | `10` | 最大内联注释数（按最严重的优先）。 |
| `risk-score-threshold` | `0` | 当 `风险 >= N` 时失败（0 表示禁用）。 |
| `severity-threshold` | `none` | 当任何发现 `>= 严重程度`（`none`/`low`/`medium`/`high`/`critical`）时失败。 |
| `branch` | _(自动)_ | 报告分支标签；从检出中自动检测。 |
| `github-token` | `${{ github.token }}` | 用于发布查找、SARIF 上传和 PR 评论的 token。 |
| `enrich` | `false` | 对发现运行 AI 丰富信息（解释 + 修复）。需要 `llm-key`。 |
| `llm-provider` | `anthropic` | 用于丰富信息的 LLM 提供商（例如 `anthropic`）。 |
| `llm-key` | _(无)_ | LLM 提供商的 API 密钥 (BYOK)。当 `enrich` 为 true 时是必需的。 |
| `auto-enrich` | `false` | 将 AI 生成的修复应用到源文件。需要 `enrich: true`。 |
| `create-fix-pr` | `false` | 开启一个包含已应用修复的 PR。需要 `auto-enrich: true`。需要 `contents: write` + `pull-requests: write`。 |
| `enrich-model` | _(二进制默认值)_ | 用于丰富信息的 Claude 模型（例如 `claude-sonnet-4-6`）。默认为 `claude-haiku-4-5`。 |
| `enrich-rules` | _(全部)_ | 逗号分隔的要丰富信息的规则 ID（例如 `ADK-201,ADK-105`）。空 = 所有发现。 |
| `fix-pr-base` | _(当前分支)_ | 修复 PR 的基础分支。 |
## 输出项
| 名称 | 描述 |
|---|---|
| `exit-code` | trustabl 原生退出代码 (0 / 1 / 2)。 |
| `readiness-score` | 整数百分比 [0, 100]，越高越好。 |
| `risk-score` | `100 - 就绪度评分`。 |
| `max-severity` | 发现中的最高严重程度，或 `none`。 |
| `findings-count` | 总发现数。 |
| `sarif-uploaded` | Code Scanning 是否接受了 SARIF (`true`/`false`)。 |
| `sarif-file` | 生成的 SARIF 文件的路径。 |
| `json-file` | 生成的 JSON 文件的路径。 |
| `artifact-name` | 用于上传的 artifact 名称。 |
| `enrich-json-file` | `enriched.json` 的路径（当 `enrich` 为 true 时）。 |
| `fix-pr-url` | 开启的修复 PR 的 URL（当 `create-fix-pr` 为 true 时）。 |
## 工作原理
- **经过验证的安装。** Runner OS/arch 对应的发布资产将被下载，
并在运行前根据发布的 `checksums.txt` 检查其 sha256，然后放入工具缓存，
以便重新运行时跳过下载。
- **单次扫描。** 当安装的引擎支持 `--json-out`/`--sarif-out` 时，
一次分析过程就会生成这两个 artifact。较旧的引擎会自动回退到两次扫描
（并且修复空间阶梯会被隐藏，因为它需要引擎的
`projected_scores`）。使用 `version: latest` 以获取快速路径。
- **依赖项 CVE 扫描（可选）。** 当设置 `vuln-scan: true` 时，声明的依赖项
将与固定的 OSV 快照进行匹配；每个已知的 CVE 都会成为一项发现（因此它
会被计入评分、门禁、注释和 Security 标签页），并在每个报告中增加一行
依赖项扫描情况 / 已知漏洞说明。OSV
数据库会在首次使用时获取一次，然后进行缓存。
- **可靠的门禁。** 失败或空的扫描会使作业报错，而不是报告一个
干净的评分。门禁决策基于退出代码/阈值，并显示在
Step Summary 和 PR 评论中。
## 下载扫描结果
运行结束后，打开运行页面并找到 **`trustabl-scan-results`** artifact：
- `trustabl.json` — 完整的机器可读 `ScanResult`。
- `trustabl.sarif` — SARIF 2.1.0。
```
- uses: actions/download-artifact@v4
with:
name: trustabl-scan-results
```
## 版本控制
- 固定发布版本：`uses: trustabl/trustabl-action@v0.3.1`。
- 或者跟踪版本线：`uses: trustabl/trustabl-action@v0`（移动的主版本标签）。
## 注意事项
- 运行在 `ubuntu-*`、`macos-*` 和 `windows-*` runner 上（x64/arm64；Windows 仅支持
amd64，与 trustabl 发布矩阵相匹配）。
- `actions/checkout` 必须首先运行 —— 该 action 会扫描你的检出内容。
- 上传到 Security 标签页需要 `security-events: write`；
置顶评论需要 `pull-requests: write`。如果缺少这两者，它们会优雅降级。
## 开发说明
这是一个使用
[`ncc`](https://github.com/vercel/ncc) 打包到 `dist/` 的 node24 TypeScript action。
```
npm ci
npm run typecheck # tsc --noEmit
npm test # jest unit tests
npm run build # bundle to dist/index.js (commit the result)
npm run all # all of the above
```
`dist/` 被提交是因为 node24 action 会直接从
使用者检出的发布标签中运行 `dist/index.js`。**Build check** 工作流会使
`dist/` 过期的 PR 失败，因此在修改
`src/` 后，请务必运行 `npm run build` 并提交。