MihailMihaylov97/catchai-action
GitHub: MihailMihaylov97/catchai-action
一个 GitHub Action 封装，在每次推送或 PR 时自动运行 catchai 七层安全扫描并将结果呈现于 Code Scanning 和 PR 评论中。
Stars: 0 | Forks: 0
# catchai 安全扫描 — GitHub Action
在每次推送或拉取请求时运行 [catchai](https://github.com/MihailMihaylov97/catchai) 多层漏洞扫描器。扫描结果将显示在仓库的**安全**选项卡中（通过 SARIF 上传至 GitHub Code Scanning），并作为摘要评论显示在每个 PR 上。
| 层级 | 覆盖范围 |
|------:|----------------|
| L1 | 依赖项 CVE (Trivy + Grype + OSV.dev)、供应链风险 |
| L2 | 静态分析 — SAST 模式，感知框架的来源 |
| L3 | 硬编码机密（熵 + 正则表达式 + 上下文） |
| L4 | 配置 / IaC — Dockerfile、Terraform、k8s、CI/CD |
| L5 | 过程间污点分析（调用图 + 数据流） |
| L6 | 业务逻辑 / 授权模型（入口点覆盖率） |
| L7 | LLM 语义审查 — 文件模式（按文件）或流模式（按攻击面，具有跨流链检测功能） |
## 快速开始
创建 `.github/workflows/security.yml`：
```
name: security
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
security-events: write # for SARIF upload to Code Scanning
pull-requests: write # for the PR summary comment
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: MihailMihaylov97/catchai-action@v1
```
大功告成。推送工作流，打开一个 PR。此 Action 将：
1. 安装 catchai（单次 curl）。
2. 运行确定性扫描（L1-L6，无 LLM 调用）。
3. 将 SARIF 上传至“安全”选项卡。
4. 在 PR 上发布摘要评论。
5. 如果存在任何高危或严重发现，则使工作流步骤失败。
## 启用第 7 层（LLM 语义审查）
L7 能够捕获 L1-L6 无法发现的多步漏洞利用和跨函数推理缺陷——代价是产生 LLM API 费用。
```
- uses: MihailMihaylov97/catchai-action@v1
with:
semantic: 'true'
semantic-mode: 'flows' # 'flows' or 'files'
semantic-top-n: '20'
semantic-chain-review: 'true' # cross-flow exploit chain detection
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```
`anthropic-api-key` 必须设置为仓库或组织机密。该 Action 从 `${{ secrets.ANTHROPIC_API_KEY }}` 读取它，并通过 `ANTHROPIC_API_KEY` 环境变量传递给 `catchai`。该密钥绝不会被记录到日志中。
每次扫描的 LLM 成本取决于仓库大小和 `semantic-top-n`。典型范围为：在中等规模的仓库上每次扫描 $0.20-$2。如果需要硬性上限，可以通过内置的 `prompts.yaml` 中的 `cost_budget_tokens` 旋钮进行限制。
## 所有输入
| 输入 | 默认值 | 作用 |
|---|---|---|
| `path` | `.` | 要扫描的目录 |
| `semantic` | `false` | 启用第 7 层 LLM 审查 |
| `semantic-mode` | `files` | `files`（按文件深度审查）或 `flows`（按入口点） |
| `semantic-top-n` | `20` | LLM 阶段审查的最大文件/流数量 |
| `semantic-chain-review` | `false` | 跨流漏洞链检测（仅限 flows 模式） |
| `semantic-verbose` | `false` | 为每次 LLM 调用打印一行进度 |
| `anthropic-api-key` | — | 当 `semantic=true` 时为必填项。通过机密传递。 |
| `upload-sarif` | `true` | 将扫描结果上传至 GitHub Code Scanning |
| `fail-on-severity` | `high` | 导致步骤失败的严重性阈值 (`critical|high|medium|low|info|none`) |
| `comment-on-pr` | `true` | 在 PR 对话中发布/更新摘要评论 |
## 所有输出
该 Action 将扫描总计数据作为步骤输出公开，以便下游作业可以对它们做出反应：
| 输出 | 示例 |
|---|---|
| `total-findings` | `42` |
| `critical-findings` | `3` |
| `high-findings` | `7` |
| `sarif-path` | `/.../reports/repo/scan_2026-05-03.sarif` |
| `json-path` | `/.../reports/repo/scan_2026-05-03.json` |
```
- id: scan
uses: MihailMihaylov97/catchai-action@v1
- name: React to high-severity findings
if: ${{ steps.scan.outputs.high-findings != '0' }}
run: |
echo "Posting incident to PagerDuty..."
```
## 权限参考
| 权限 | 原因 |
|---|---|
| `contents: read` | 标准检出。始终需要。 |
| `security-events: write` | 将 SARIF 上传至 Code Scanning。可使用 `upload-sarif: false` 跳过。 |
| `pull-requests: write` | 发布/更新 PR 摘要评论。可使用 `comment-on-pr: false` 跳过。 |
## 私有仓库上的 Code Scanning
将 SARIF 上传到**私有**仓库的 GitHub Code Scanning 需要 GitHub Advanced Security。如果您的组织没有 GHAS，请设置 `upload-sarif: false` —— 扫描仍将运行，报告将作为工作流构件（`catchai-report`）上传，并且 PR 评论将显示发现计数。
## 工作原理（底层机制）
此 Action 是一个轻量级的复合包装器。它会：
1. 通过 curl 请求 `https://raw.githubusercontent.com/MihailMihaylov97/catchai-dist/main/install.sh` 来安装 catchai 二进制文件，该脚本会下载适合当前平台的预构建 wheel。
2. 使用从输入派生的参数运行 `catchai scan ...`。
3. 解析规范的扫描 JSON 输出以获取严重性计数。
4. 将 SARIF 上传至 GitHub Code Scanning。
5. 使用标记行发布/更新 PR 摘要评论，以便推送到 PR 分支时会更新现有评论，而不是堆叠新评论。
该 Action 源码（此 `action.yml`）采用宽松许可证授权（参见 [`LICENSE`](LICENSE)）。catchai 二进制文件本身受其自身条款管辖 —— 参见 [`LICENSE_NOTE.md`](LICENSE_NOTE.md)。
## 版本控制
固定到主要版本（`@v1`）可获取带有稳定 Action 接口的自动次要/补丁更新。如果您希望获得哈希等效的可复现性，请固定到特定标签（`@v1.0.0`）。
## 问题
Action 管道错误（工作流 YAML、SARIF 上传、PR 评论格式）请提交至本仓库的 [issues](https://github.com/MihailMihaylov97/catchai-action/issues)。
扫描结果质量问题（遗漏发现、误报、错误的严重性）请提交至上游的 [catchai 仓库](https://github.com/MihailMihaylov97/catchai/issues)。
标签：Chrome Headless, CI/CD安全, CISA项目, Claude, CVE检测, DevSecOps, GitHub Action, GitHub代码扫描, Kubernetes安全, Llama, SARIF, StruQ, Terraform安全, Web截图, 上游代理, 代码安全, 代码审查, 依赖漏洞, 基础设施即代码扫描, 容器安全, 文档安全, 权限模型检测, 漏洞枚举, 结构化查询, 自动化安全, 逆向工具, 静态应用安全测试