Security Guardrails

用于拉取请求的高信号、可复用 GitHub Actions 安全门禁。

OpenGrep SAST，仅限已验证的 TruffleHog 密钥，依赖审查，Trivy 漏洞与许可证审计，以及 CycloneDX SBOM 构件 — 经过调优以实现 低噪声且具可操作性的结果。

✓ PR 范围内的 SAST   ✓ 仅限已验证密钥   ✓ CRITICAL/HIGH CVE   ✓ Copyleft 许可证防护   ✓ CycloneDX SBOM 构件

## 概述 **Security Guardrails** 是一个[可复用的 GitHub Actions 工作流](https://docs.github.com/en/actions/using-workflows/reusing-workflows)， 运行在使用者仓库的拉取请求中。它专注于**变更的 文件和依赖项**，展示**高置信度的结果**，并 为下游工具上传机器可读的结果（JSON / CycloneDX）。 | 任务 | 工具 | 识别内容 | | ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | **OpenGrep – SAST** | [OpenGrep](https://opengrep.dev/) | PR diff 中的 ERROR 级别安全模式（`p/security-audit`, `p/owasp-top-ten`） | | **TruffleHog – 密钥** | [TruffleHog](https://github.com/trufflesecurity/trufflehog) | 仅限**已验证的**凭证（`--results=verified`），JSON 输出 | | **供应链** | Dependency Review + [Trivy](https://github.com/aquasecurity/trivy) | 新的易受攻击依赖、CRITICAL/HIGH CVE、禁用的 Copyleft 许可证、CycloneDX SBOM | ## 快速开始 在你的仓库中添加一个工作流（例如 `.github/workflows/security-guardrails.yaml`）： ``` name: 'Security Guardrails' on: pull_request jobs: security-guardrails: uses: garretpatten/security-guardrails/.github/workflows/security-guardrails.yaml@master with: opengrep_run: true trufflehog_run: true supply_chain_run: true secrets: inherit ``` 为了进行供应链控制，请**固定 commit SHA** 来代替 `@master`： ``` uses: garretpatten/security-guardrails/.github/workflows/security-guardrails.yaml@ ``` ## 工作流输入 | 输入 | 类型 | 默认值 | 描述 | | ------------------ | ------- | --------------- | ------------------------------------------------ | | `opengrep_run` | boolean | `true` | 对变更的文件运行 OpenGrep 静态分析 | | `trufflehog_run` | boolean | `true` | 对 PR diff 运行 TruffleHog 密钥扫描 | | `supply_chain_run` | boolean | `true` | Dependency Review，Trivy 漏洞/许可证扫描，SBOM | | `opengrep_version` | string | `v1.22.0` | 固定的 OpenGrep 发布标签 | | `trivy_severity` | string | `CRITICAL,HIGH` | Trivy 最小漏洞严重级别 | Dependabot PR 会被自动跳过。 ## 扫描器 ### OpenGrep (SAST) [OpenGrep](https://github.com/opengrep/opengrep) 是 Semgrep CE 的一个开源分支，具有兼容的规则和 SARIF/JSON 输出。该工作流： - 通过官方安装脚本安装**固定的发布版本** - 仅扫描**在 PR 中变更的文件** - 使用规则集 `p/security-audit` 和 `p/owasp-top-ten` - 仅在出现 **`ERROR` 严重级别**结果时失败，以减少噪声 - 将 `opengrep-results.json` 作为工作流构件上传 ### TruffleHog (密钥) - 扫描 PR diff（`base` → `HEAD`） - **`--results=verified`** — 仅限由提供商 API 确认处于活跃状态的密钥 - **`--json`** — 作为构件上传的结构化输出 - 遵循使用者仓库中的 **`.truffleignore`** ### 供应链 1. **GitHub Dependency Review** — 阻止引入带有 **高严重性**安全通告或**禁用许可证**（GPL、AGPL、SSPL、 BUSL 及相关标识）依赖的 PR。 2. **Trivy filesystem 扫描** — lockfile/manifest 中的 CRITICAL/HIGH CVE； **`ignore-unfixed: true`** 避免在遇到没有补丁的问题时失败。 3. **Trivy 许可证审计** — 通过完整的许可证文本匹配，标记 **HIGH 严重性（禁用的/copyleft）** 许可证。 4. **CycloneDX SBOM** — 每次 PR 上传 `sbom.cyclonedx.json`，用于审计和 合规流水线。 在你的仓库中添加一个 **`.trivyignore`** 以排除路径（参见本仓库的 示例）。 ## 迁移 ### 从 `security-checks` 重命名 该项目被重命名为 **Security Guardrails**（`security-guardrails`）。请更新 使用者工作流： ``` # 之前 uses: garretpatten/security-checks/.github/workflows/security-checks.yaml@master # 之后 uses: garretpatten/security-guardrails/.github/workflows/security-guardrails.yaml@master ``` ### 从 Semgrep **`semgrep_run`** 输入已被替换为 **`opengrep_run`**。OpenGrep 使用 相同的 registry 规则集，对于 Semgrep CE 扫描来说，是一次直接的引擎替换。 ``` # 之前 with: semgrep_run: true # 之后 with: opengrep_run: true supply_chain_run: true # disable if you only want SAST + secrets ``` ## 理念：高信号，低噪声 | 选择 | 理由 | | ------------------------------ | --------------------------------------------------------- | | 仅限 ERROR 的 OpenGrep | 警告通常反映代码风格或较低置信度的模式 | | 仅限已验证的 TruffleHog | 未验证的熵匹配会导致警报疲劳 | | CRITICAL/HIGH + ignore-unfixed | 专注于可利用、可修补的 CVE | | 禁用的许可证列表 | 在新依赖中揭示 copyleft / 商业风险许可证 | | PR 范围内的 SAST | 更快的反馈；与审查中的代码保持一致 | ## 维护者 [@garretpatten](https://github.com/garretpatten/) 请使用 [问题模板](./.github/ISSUE_TEMPLATE/) 反馈 Bug 和提出增强建议。 ## 许可证 该项目基于 [MIT License](./LICENSE) 授权。

标签：GitHub Actions, LLM防护, StruQ, 代码安全, 漏洞枚举, 自动笔记, 静态应用安全测试