alex-jung/pipeguard-cli

# PipeGuard GitHub Actions 工作流的 Pre-commit 安全扫描器。在您推送代码之前，捕获供应链风险、未固定 (unpinned) 的 actions、已知 CVE 以及秘密信息泄露。 ## PipeGuard 与替代方案对比 | 功能 | PipeGuard | actionlint | StepSecurity | act | |---------|:---------:|:----------:|:------------:|:---:| | SHA 固定检查 | ✅ | ❌ | ✅ | ❌ | | CVE 数据库 (离线) | ✅ | ❌ | ✅ (在线) | ❌ | | 权限分析 | ✅ | ⚠️ 仅语法 | ✅ | ❌ | | 秘密信息泄露检测 | ✅ | ❌ | ✅ (运行时) | ❅ | | 供应链审计 | ✅ | ❌ | ✅ | ❅ | | 语法 / 类型检查 | ✅ 通过 actionlint | ✅ | ❅ | ❅ | | 本地运行工作流 | ❅ | ❅ | ❅ | ✅ | | 运行时加固 | ❅ | ❅ | ✅ | ❅ | | Pre-commit 钩子 | ✅ | ✅ | ❅ | ❅ | | SARIF 输出 | ✅ | ✅ | ❅ | ❅ | | 无需 API 密钥 | ✅ | ✅ | ❅ | ✅ | | 完全离线 | ✅ | ✅ | ❅ | ⚠️ 需要镜像 | | 开源 | ✅ | ✅ | ✅ | ✅ | | 免费 | ✅ 核心功能 | ✅ | ⚠️ 免费增值 | ✅ | PipeGuard 填补了编写与执行之间的空白：在您推送代码之前，无需任何外部服务即可进行静态安全分析和离线检查。 ## 安装说明 **前置条件：** Python 3.11+ ``` pip install pipeguard-cli ``` **安装 actionlint**（语法检查必需，其他检查可选）： ``` # Linux curl -fsSL https://github.com/rhysd/actionlint/releases/latest/download/actionlint_linux_amd64.tar.gz \ | tar xz actionlint && sudo mv actionlint /usr/local/bin/ # macOS brew install actionlint # Ubuntu/Debian (snap) sudo snap install actionlint ``` ## 使用说明 ``` pipeguard scan [PATH] ``` `PATH` 可以是单个工作流文件或目录。如果省略，则默认为 `.github/workflows`。 ### 示例 ``` # 扫描整个 .github/workflows 目录（默认） pipeguard scan # 扫描特定目录 pipeguard scan .github/workflows/ # 扫描单个文件 pipeguard scan .github/workflows/ci.yml # JSON 输出（用于脚本 / CI pipelines） pipeguard scan --format json # SARIF 输出（用于 IDE integration, GitHub Code Scanning） pipeguard scan --format sarif # 使用自定义配置文件 pipeguard scan --config path/to/.pipeguard.yml # 仅运行特定的 scanner(s) — 始终在本地运行 pipeguard scan --scanner sha-pinning pipeguard scan --scanner sha-pinning --scanner cve ``` 扫描目录时，pipeguard 会打印每个文件的标题并在最后输出汇总信息： ``` .github/workflows/ci.yml ✓ No issues found .github/workflows/deploy.yml ✗ error sha-pinning line 12 Action 'actions/checkout' is pinned to 'v3' instead of a full commit SHA. ✗ error cve-cve-2025-30066 line 15 Action 'tj-actions/changed-files@v35' is affected by CVE-2025-30066: ... ⚠ warning supply-chain line 15 Untrusted action 'tj-actions/changed-files' — verify publisher and pin to a SHA. ✗ error permissions-missing line 1 No top-level 'permissions:' key found. · info action-inventory line 12 Action 'actions/checkout' used with ref(s): 'v3' (1 occurrence(s)). 5 issue(s) found (3 error(s), 1 warning(s)) Scanned 2 file(s) — 3 error(s), 1 warning(s), 1 info(s) total. ``` ### 退出代码 | 代码 | 含义 | |------|---------| | `0` | 没有错误或警告 | | `1` | 发现一个或多个错误或警告 | | `2` | 无效或过期的 Pro 许可证密钥 | Info 级别的发现（action 清单）不会影响退出代码。 ### 选项 | 标志 | 描述 | |------|-------------| | `--format terminal\|json\|sarif` | 输出格式（默认：`terminal`） | | `--fix` | 通过 Pro API 应用自动修复（需要许可证密钥） | | `--config PATH` | `.pipeguard.yml` 配置文件的路径 | | `--verbose` / `-v` | 显示每个扫描器的进度和 Pro API 响应 | | `--scanner NAME` | 仅运行此扫描器。可重复使用。遵循配置文件设置（例如 `trusted_publishers`、`min_cvss`）但会覆盖 `skip`。绕过 Pro API —— 始终在本地运行。有效名称：`sha-pinning`、`supply-chain`、`cve`、`permissions`、`secrets-flow`、`pull-request-target`、`actionlint`、`action-inventory` | ## 安全检查 ### 错误与警告 | 规则 | 严重程度 | 描述 | |------|----------|-------------| | `sha-pinning` | error | Action 固定到标签或分支，而不是完整的 commit SHA —— 供应链风险（参见 [CVE-2025-30066](https://www.cve.org/CVERecord?id=CVE-2025-30066)） | | `sha-pinning-reusable` | error | 可复用工作流使用标签或分支引用调用，而不是完整的 commit SHA —— 与未固定 actions 的供应链风险相同 | | `cve-` | error | Action 与本地数据库中的已知 CVE 匹配（离线，无需 API） | | `supply-chain` | warning | 来自未验证发布者的第三方 action —— 可通过 `.pipeguard.yml` 按发布者或 action 取消警告 | | `secrets-leak` | error | Secret 值在 `run:` 步骤中被回显或记录到日志 | | `secrets-leak-debug` | error / warning | `run:` 步骤中包含 `set -x` 或 `set -o xtrace` —— shell 调试模式会打印每个展开的命令；当 env 作用域中存在 secrets 时报错，否则报警告 | | `permissions-missing` | error | 没有 `permissions:` 块 —— GitHub 默认授予大多数作用域的写入权限 | | `permissions-write-all` | error | 在顶层或每个 job 中使用了 `permissions: write-all` | | `permissions-excessive` | warning | 敏感作用域（如 `secrets`、`workflows`）被设置为 `write` | | `permissions-id-token-unused` | warning | 设置了 `id-token: write` 但不存在使用 OIDC 的 action —— 允许不必要地生成云凭证 | | `permissions-invalid` | error | 未知的权限级别（不是 `read`、`write` 或 `none`） | | `pull-request-target` | warning | `pull_request_target` 触发器使用基础仓库的写入权限和 secret 访问权限运行 —— 即使是来自 Fork 的 PR 也是如此 | | `pull-request-target-pwn` | error | `pull_request_target` 结合了对 PR head ref 的检出 —— 允许不受信任的 Fork 代码使用 secrets 运行（Pwn Request） | | `actionlint` | error | 语法和类型错误（需要 actionlint） | ### 信息 | 规则 | 严重程度 | 描述 | |------|----------|-------------| | `action-inventory` | info | 使用的所有第三方 action 的清单，包括 ref 和出现次数 | ## CVE 数据库 PipeGuard 内置了离线 CVE 数据库 —— 无需 API 密钥，扫描期间也无需网络请求。该数据库每天通过 NVD 更新，并随每周的新版本发布。 | CVE | Action | 描述 | |-----|--------|-------------| | [CVE-2025-30066](https://www.cve.org/CVERecord?id=CVE-2025-30066) | `tj-actions/changed-files` | tj-actions/changed-files 在一次供应链攻击中被攻破。所有基于标签的引用都可能受到影响 —— 请固定到已知良好的 SHA。 | | [CVE-2025-30154](https://www.cve.org/CVERecord?id=CVE-2025-30154) | `reviewdog/action-setup` | reviewdog/action-setup 在与 tj-actions/changed-files 相同的供应链攻击活动中被攻破。请固定到经过审查的 SHA。 | | [CVE-2023-49291](https://www.cve.org/CVERecord?id=CVE-2023-49291) | `tj-actions/branch-names` | tj-actions/branch-names 在 run 步骤中不正确地引用了 github.event.pull_request.head.ref 和 github.head_ref，允许精心构造的分支名执行任意代码并窃取 secrets 或滥用 GITHUB_TOKEN 权限。 | SHA 固定的引用不会被标记 —— 这是始终固定到 commit SHA 的另一个原因。 要获取最新的 CVE，请升级到最新版本： ``` pip install --upgrade pipeguard-cli ``` ## 配置 PipeGuard 会在当前目录及其父目录中查找 `.pipeguard.yml`（或 `.pipeguard.yaml`、`pipeguard.yml`、`pipeguard.yaml`）。 所有扫描器设置都位于 `scanners:` 键下。每个扫描器都可以独立配置： ``` # .pipeguard.yml scanners: # Disable a scanner entirely supply-chain: skip: false # default; set to true to disable trusted_publishers: - my-org # suppresses warnings for my-org/* - some-vendor trusted_actions: - other-org/specific-action # exact match, without @ref # Lower the CVE severity threshold (default: 9.0) cve: min_cvss: 7.0 # Skip a scanner entirely actionlint: skip: true ``` **扫描器名称：** `sha-pinning`、`supply-chain`、`cve`、`permissions`、`secrets-flow`、`pull-request-target`、`actionlint`、`action-inventory`。 - `trusted_publishers` 作为前缀匹配 —— 来自 `my-org/*` 的每个 action 都被视为受信任的。 - `trusted_actions` 需要与 action 名称（不带 `@ref`）完全匹配。 - 发布者名称中结尾的 `/` 是可选的；PipeGuard 会自动将其规范化。 - 未在配置文件中列出的扫描器将以其默认设置运行。 内置白名单（GitHub、AWS、Azure、Google、Docker、HashiCorp 等）始终处于激活状态，无法被移除。 ## CI 集成 将 pipeguard 添加为 pre-push 检查或 CI 步骤： ``` # .github/workflows/pipeguard.yml - name: Scan workflows run: | pip install pipeguard-cli pipeguard scan .github/workflows/ ``` 或者作为 pre-commit 钩子（`.pre-commit-config.yaml`）： ``` repos: - repo: local hooks: - id: pipeguard name: PipeGuard workflow scan entry: pipeguard scan language: python additional_dependencies: [pipeguard-cli] files: \.github/workflows/.*\.ya?ml$ ``` ## 输出格式 **Terminal**（默认）—— 具有规则、位置和修复建议的可读表格。 **JSON** —— 机器可读，每个发现对应一个对象： ``` [ { "id": "a1b2c3d4e5f6", "rule": "cve-cve-2025-30066", "severity": "error", "message": "Action 'tj-actions/changed-files@v35' is affected by CVE-2025-30066: ...", "file": ".github/workflows/ci.yml", "line": 12, "col": 0, "fix_suggestion": "Immediately pin 'tj-actions/changed-files' to a verified safe SHA.", "patch": null, "score": null, "detail": null } ] ``` 每个发现都有一个稳定的 `id`（`sha256(rule:line:message)[:12]`）—— 在一次扫描会话内有效。在调用 Pro API 进行自动修复时，请使用它来引用特定的发现。 **SARIF** —— 与 GitHub 代码扫描兼容。 ## PipeGuard Pro PipeGuard Pro 通过云 API 扩展了免费的 CLI，提供了更深入的分析和自动修复功能。 ### 激活许可证密钥 ``` pipeguard auth ``` 密钥存储在 `~/.pipeguard/credentials` 中，并在每次执行 `pipeguard scan` 时自动读取。您也可以通过环境变量进行设置： ``` export PIPEGUARD_LICENSE_KEY= ``` ### Pro 模式的工作原理 当存在许可证密钥时，**所有的扫描将由 Pro API 处理** —— 免费的本地扫描器将被完全跳过。Pro API 运行相同的免费检查以及额外的深度分析扫描器，并返回带有可选 `patch` 和 `score` 字段的发现。 如果 Pro API 无法访问或返回错误，PipeGuard 将自动回退到免费的本地扫描器。 ### 自动修复 ``` pipeguard scan --fix ``` 将带有可用补丁的发现发送回 Pro API（`POST /v1/fix`）。修补后的工作流将被写回磁盘。最后会打印已应用和已跳过的计数。 ## 许可证 Apache 2.0 —— 详见 [LICENSE](LICENSE)。

标签：Action 加固, CI/CD 安全, CLI 工具, CVE 检测, DevSecOps, GitHub Actions, Pre-commit, Python, SARIF, SHA-pinning, StruQ, 上游代理, 代码安全, 哈希固化, 指令注入, 敏感信息泄漏, 数据投毒防御, 无后门, 漏洞枚举, 离线安全检测, 秘密检测, 自动化安全扫描, 自动笔记, 软件开发工具包, 逆向工具, 错误基检测, 静态代码分析