sbom-tool/gh-guard
GitHub: sbom-tool/gh-guard
专为 Rust 项目设计的 Claude Code 供应链安全加固插件，提供从审计到落地的交互式 CI/CD 硬化能力。
Stars: 3 | Forks: 2
# GH-Guard
` — 文件生成器
使用自动检测到的项目值生成单个文件。在覆盖现有文件之前显示 unified diff。
| 目标 | 输出路径 |
|--------|------------|
| `ci-workflow` | `.github/workflows/ci.yml` |
| `publish-workflow` | `.github/workflows/publish.yml` |
| `codeql` | `.github/workflows/codeql.yml` |
| `scorecard` | `.github/workflows/scorecard.yml` |
| `fuzz` | `.github/workflows/fuzz.yml` |
| `deny-toml` | `deny.toml` |
| `rust-toolchain` | `rust-toolchain.toml` |
| `dependabot` | `.github/dependabot.yml` |
| `security-md` | `SECURITY.md` |
| `release-script` | `scripts/release.sh` |
| `osv-scanner` | `osv-scanner.toml` |
## 模板
使用 `{{PLACEHOLDER}}` 语法参数化的、经过生产环境验证的配置文件。值从 `Cargo.toml`、git remote 和 `cargo metadata` 自动检测：
| 占位符 | 来源 | 示例 |
|-------------|--------|---------|
| `{{CRATE_NAME}}` | `Cargo.toml` name 字段 | `my-tool` |
| `{{MSRV}}` | `rust-version` 或 `rust-toolchain.toml` | `1.82` |
| `{{REPO_OWNER}}` | Git remote URL | `my-org` |
| `{{REPO_NAME}}` | Git remote URL | `my-tool` |
| `{{CONTACT_EMAIL}}` | `Cargo.toml` authors 字段 | `me@example.com` |
| `{{FUZZ_TARGETS}}` | `fuzz/Cargo.toml` bin 条目 | `fuzz_parse,fuzz_decode` |
| `{{WORKSPACE_CRATES}}` | `cargo metadata --no-deps` (可发布, 依赖顺序) | `core,parser,cli` |
### 模板中的安全加固
所有工作流模板都遵循以下安全实践：
- **SHA 固定的 actions** 带有版本注释（例如，`# v4.2.2`）
- **工作流级别的 `permissions: read-all`**，每个 job 作用域限定
- 所有 checkout 步骤上的 **`persist-credentials: false`**
- **脚本注入预防** —— 用户控制的值通过环境变量传递，而不是内联的 `${{ }}`
- **并发组** —— 防止同一 branch/PR 上的并行运行
- **固定的 CLI 工具版本** —— `cargo-audit` 固定到特定版本并使用 `--locked`
- **`workflow_dispatch` 重新触发** —— publish workflow 支持针对失败发布的手动重新触发
## 技能
技能是在相关时自动加载的深度知识文档。它们编码了来自生产环境 Rust CI/CD 的宝贵经验：
| 技能 | 覆盖内容 |
|-------|---------------|
| **scorecard-checks** | 所有 18 项 OpenSSF Scorecard 检查，包含 Rust 特定的实施指导和评分策略 |
| **trusted-publishing** | OIDC 威胁模型、前置条件、crates.io 分步设置、故障排除 |
| **slsa-provenance** | 三 job publish/provenance/release 流水线、hash 生成、验证、常见陷阱 |
| **ci-pipeline** | Gate 模式、多 job 设计、缓存、SHA 固定、权限模型 |
| **release-automation** | 基于 PR 的发布流程、签名标签、CI 轮询竞态条件、分支保护兼容性 |
| **dependency-policy** | cargo-deny 配置、Dependabot 设置、osv-scanner 分层防御 |
| **fuzz-testing** | cargo-fuzz 设置、`Arbitrary` vs raw bytes、corpus 管理、CI 集成、覆盖率分析 |
| **migration-guide** | 级别检测算法、升级路径（Minimal 到 Standard 到 Hardened）、回滚程序 |
| **workspace-publishing** | Multi-crate 发布顺序、per-crate Trusted Publishing、版本同步 |
| **hardening-detection** | `/audit`、`/harden` 和 migration-guide 使用的共享级别检测算法 |
| **cargo-vet** | 供应链审计 —— 对第三方 crate 的人工审查证明 |
| **security-findings** | CodeQL、Scorecard、cargo-deny 和 Dependabot 发现的 SARIF 分类工作流 |
| **binary-releases** | 通过 cargo-dist、cross 或手动 CI 矩阵进行跨平台二进制分发 |
| **changelog** | 使用 git-cliff 和 conventional commits 自动生成 changelog |
## 加固目标
基于获得 OpenSSF Scorecard 7.5/10 的真实世界经验：
- 所有 GitHub Actions SHA 固定并带有版本注释
- 工作流级别的 `permissions: read-all`，每个 job 作用域限定
- Trusted Publishing (OIDC) —— 无长期有效的 API token
- SLSA L3 provenance 附加到 GitHub Releases
- cargo-deny 用于 license、ban、advisory 和 source 检查
- Dependabot 用于 cargo + github-actions 更新
- CodeQL 与 Rust 原生分析
- 使用 cargo-fuzz 进行 Fuzz testing
- 签名的 git tags (SSH ed25519 或 GPG)
- SECURITY.md 包含协调披露策略
## 架构
```
gh-guard/
commands/ # User-invocable slash commands
audit.md # /audit — gap analysis
harden.md # /harden — interactive wizard
generate.md # /generate — single file generator
check-updates.md # /check-updates — SHA staleness checker
verify.md # /verify — post-generation validation
skills/ # Contextual knowledge (auto-loaded)
binary-releases/
cargo-vet/
changelog/
ci-pipeline/
dependency-policy/
fuzz-testing/
hardening-detection/
migration-guide/
release-automation/
scorecard-checks/
security-findings/
slsa-provenance/
trusted-publishing/
workspace-publishing/
templates/ # Parameterized config files
workflows/
ci.yml
codeql.yml
fuzz.yml
publish.yml
scorecard.yml
deny.toml
dependabot.yml
osv-scanner.toml
release.sh
rust-toolchain.toml
SECURITY.md
VERSIONS.md # Pinned action version manifest (human-readable)
versions.json # Pinned action version manifest (machine-readable)
tests/ # Validation infrastructure
validate-templates.sh
fixtures/
examples/ # Sample output
audit-output.md
.gitignore
CLAUDE.md # Plugin instructions
LICENSE # MIT
README.md
SECURITY.md # Plugin security policy
```
## 关键注意事项
来自生产环境使用的宝贵经验：
1. **SLSA generator 必须使用 `@tag` 而不是 SHA** —— 可复用工作流需要标签引用才能进行证明签名
2. **不可变发布** —— provenance 必须在 GitHub Release *之前*生成（之后无法上传资产）
3. **标签保护** —— 错误的标签 = 新版本号（标签无法删除或更新）
4. **`gh pr checks --watch` 竞态** —— 如果检查尚未开始则立即返回；先轮询检查是否存在
5. **需要 `fetch-depth: 0`** —— 验证标签祖先的 publish workflow 在浅克隆下会出错
6. **Trusted Publishing 在 crates.io 配置** —— 不在仓库中；访问 crates.io/crates/NAME/settings
7. **osv-scanner.toml 不会传播** —— 子目录需要它们自己的副本
8. **CodeQL 默认设置冲突** —— 在使用自定义 workflow 之前，在仓库 Settings > Code Security 中禁用
9. **cargo-audit 需要 `--locked`** —— 防止传递依赖升级导致的 MSRV 问题
10. **cargo-deny v0.19 破坏性更改** —— 移除了 `vulnerability` 键；对 unmaintained/unsound 使用 `"all"` 或 `"workspace"`
11. **Workspace 发布顺序** —— 相互依赖的 crate 必须按依赖顺序发布，并留有约 60s 的索传播延迟
12. **`workflow_dispatch` 重新触发** —— 使用 `gh workflow run publish.yml -f tag=vX.Y.Z` 而不是 `gh run rerun`（后者使用原始 workflow 文件）
## 许可证
MIT
标签：cargo-deny, CI/CD 安全, Claude Code, DevSecOps, GitHub Actions, OpenSSF Scorecard, Python安全, Rust, SHA Pinning, SLSA, Trusted Publishing, 上游代理, 代码加固, 依赖审计, 可视化界面, 安全基线, 工作流模板, 插件, 教学环境, 数据投毒防御, 文档安全, 结构化查询, 网络流量审计, 自动化安全, 自动笔记, 软件供应链, 软件开发工具包