{
  "markdown": "# GH-Guard\n\n<p align=\"center\">\n  <img src=\"assets/gh-guard-banner.jpg\" alt=\"GH-Guard: Without vs With — from manual YAML and unpinned actions to production-tested templates, SHA-pinned actions, Trusted Publishing, SLSA L3 provenance, and layered dependency defense\" width=\"700\">\n</p>\n\nCI/CD supply chain hardening plugin for [Claude Code](https://claude.com/claude-code), designed for Rust projects.\n\nGH-Guard packages production-tested CI/CD security configurations into reusable templates and guided workflows. It helps Rust OSS maintainers achieve high [OpenSSF Scorecard](https://scorecard.dev) scores, set up [Trusted Publishing](https://blog.rust-lang.org/2023/11/09/crates-io-trusted-publishing.html), generate [SLSA L3](https://slsa.dev) provenance, and configure comprehensive dependency auditing.\n\n## Installation\n\n**From the Claude Code plugin registry:**\n\n```\n/plugin install gh-guard\n```\n\n**Or manually** — add to your Claude Code settings (`~/.claude/settings.json`):\n\n```json\n{\n  \"plugins\": [\n    \"~/path/to/gh-guard\"\n  ]\n}\n```\n\n## Quick Start\n\n```\n# Audit your project's supply chain security posture\n/audit\n\n# Interactively harden your project\n/harden\n\n# Generate a specific config file\n/generate ci-workflow\n/generate publish-workflow\n/generate deny-toml\n\n# Check for outdated SHA pins\n/check-updates\n\n# Validate generated configs\n/verify\n```\n\n## Commands\n\n### `/audit` — Gap Analysis\n\nScans your repository and produces a structured gap analysis:\n- Checks for expected files (workflows, deny.toml, SECURITY.md, etc.)\n- Scores against OpenSSF Scorecard checks\n- Classifies your current hardening level (Minimal / Standard / Hardened)\n- Identifies SHA-pinning gaps, missing permissions, Cargo.lock issues\n- Flags dangerous workflow patterns (`pull_request_target`, `workflow_run` with untrusted input, script injection via PR title/body)\n- Detects workspace projects and validates publish ordering\n- Outputs prioritized recommendations with template references\n\n### `/harden` — Interactive Wizard\n\nGuides you through hardening at three levels:\n\n| Level | Components |\n|-------|-----------|\n| **Minimal** | CI workflow + cargo-deny + Dependabot + SECURITY.md |\n| **Standard** | + Trusted Publishing + CodeQL + Scorecard + release script |\n| **Hardened** | + SLSA L3 provenance + fuzz testing + osv-scanner |\n\nDetects your current hardening level and offers upgrade mode — generating only the delta files needed to reach the next level. Supports workspace projects with per-crate Trusted Publishing guidance.\n\n### `/check-updates` — SHA Pin Checker\n\nChecks deployed workflows for outdated action SHAs and CLI tool versions:\n- Compares pinned SHAs against latest tags via the GitHub API\n- Detects outdated CLI tool versions (cargo-audit, cargo-fuzz)\n- Shows what's out of date with current vs latest comparison\n- Offers to apply updates automatically\n- Respects the SLSA generator exception (must use `@tag`, not SHA)\n\n### `/verify` — Post-Generation Validation\n\nValidates that generated configs are syntactically correct, internally consistent, and ready to deploy:\n- YAML/TOML syntax validation\n- SHA pin completeness and version comment presence\n- Cross-file consistency (MSRV, gate job, fuzz targets)\n- `cargo-deny check` dry run (if installed)\n- `release.sh --dry-run` validation\n\n### `/generate <target>` — File Generator\n\nGenerates a single file with auto-detected project values. Shows a unified diff before overwriting existing files.\n\n| Target | Output Path |\n|--------|------------|\n| `ci-workflow` | `.github/workflows/ci.yml` |\n| `publish-workflow` | `.github/workflows/publish.yml` |\n| `codeql` | `.github/workflows/codeql.yml` |\n| `scorecard` | `.github/workflows/scorecard.yml` |\n| `fuzz` | `.github/workflows/fuzz.yml` |\n| `deny-toml` | `deny.toml` |\n| `rust-toolchain` | `rust-toolchain.toml` |\n| `dependabot` | `.github/dependabot.yml` |\n| `security-md` | `SECURITY.md` |\n| `release-script` | `scripts/release.sh` |\n| `osv-scanner` | `osv-scanner.toml` |\n\n## Templates\n\nProduction-tested config files parameterized with `{{PLACEHOLDER}}` syntax. Values are auto-detected from `Cargo.toml`, git remote, and `cargo metadata`:\n\n| Placeholder | Source | Example |\n|-------------|--------|---------|\n| `{{CRATE_NAME}}` | `Cargo.toml` name field | `my-tool` |\n| `{{MSRV}}` | `rust-version` or `rust-toolchain.toml` | `1.82` |\n| `{{REPO_OWNER}}` | Git remote URL | `my-org` |\n| `{{REPO_NAME}}` | Git remote URL | `my-tool` |\n| `{{CONTACT_EMAIL}}` | `Cargo.toml` authors field | `me@example.com` |\n| `{{FUZZ_TARGETS}}` | `fuzz/Cargo.toml` bin entries | `fuzz_parse,fuzz_decode` |\n| `{{WORKSPACE_CRATES}}` | `cargo metadata --no-deps` (publishable, dependency order) | `core,parser,cli` |\n\n### Security Hardening in Templates\n\nAll workflow templates follow these security practices:\n\n- **SHA-pinned actions** with version comments (e.g., `# v4.2.2`)\n- **`permissions: read-all`** at workflow level, scoped per-job\n- **`persist-credentials: false`** on all checkout steps\n- **Script injection prevention** — user-controlled values passed via environment variables, not inline `${{ }}`\n- **Concurrency groups** — prevent parallel runs on the same branch/PR\n- **Pinned CLI tool versions** — `cargo-audit` pinned to specific version with `--locked`\n- **`workflow_dispatch` retrigger** — publish workflow supports manual retrigger for failed publishes\n\n## Skills\n\nSkills are deep knowledge documents loaded automatically when relevant. They encode hard-won lessons from production Rust CI/CD:\n\n| Skill | What It Covers |\n|-------|---------------|\n| **scorecard-checks** | All 18 OpenSSF Scorecard checks with Rust-specific guidance, Dangerous-Workflow risk analysis (`pull_request_target` + `workflow_run`), and defense-in-depth recommendations |\n| **trusted-publishing** | OIDC threat model, prerequisites, step-by-step crates.io setup, troubleshooting |\n| **slsa-provenance** | Three-job publish/provenance/release pipeline, hash generation, verification, common pitfalls |\n| **ci-pipeline** | Gate pattern, multi-job design, caching, SHA pinning with real-world incident context (Trivy tag hijacking), permissions model |\n| **release-automation** | PR-based release flow, signed tags, CI polling race condition, branch protection compatibility |\n| **dependency-policy** | cargo-deny configuration, Dependabot setup, osv-scanner layered defense |\n| **fuzz-testing** | cargo-fuzz setup, `Arbitrary` vs raw bytes, corpus management, CI integration, coverage analysis |\n| **migration-guide** | Level detection algorithm, upgrade paths (Minimal to Standard to Hardened), rollback procedures |\n| **workspace-publishing** | Multi-crate publish ordering, per-crate Trusted Publishing, version synchronization |\n| **hardening-detection** | Shared level detection algorithm used by `/audit`, `/harden`, and migration-guide |\n| **cargo-vet** | Supply chain audits — human review attestation for third-party crates |\n| **security-findings** | SARIF triage workflow for CodeQL, Scorecard, cargo-deny, and Dependabot findings + compromised action incident response playbook (Detect/Rotate/Audit/Report) |\n| **binary-releases** | Cross-platform binary distribution via cargo-dist, cross, or manual CI matrix |\n| **changelog** | Automated changelog generation with git-cliff and conventional commits |\n\n## Hardening Targets\n\nBased on real-world experience achieving OpenSSF Scorecard 7.5/10:\n\n- All GitHub Actions SHA-pinned with version comments\n- `permissions: read-all` at workflow level, scoped per-job\n- Trusted Publishing (OIDC) — no long-lived API tokens\n- SLSA L3 provenance attached to GitHub Releases\n- cargo-deny for license, ban, advisory, and source checks\n- Dependabot for cargo + github-actions updates\n- CodeQL with Rust native analysis\n- Fuzz testing with cargo-fuzz\n- Signed git tags (SSH ed25519 or GPG)\n- SECURITY.md with coordinated disclosure policy\n\n## Architecture\n\n```\ngh-guard/\n  commands/           # User-invocable slash commands\n    audit.md          # /audit — gap analysis\n    harden.md         # /harden — interactive wizard\n    generate.md       # /generate — single file generator\n    check-updates.md  # /check-updates — SHA staleness checker\n    verify.md         # /verify — post-generation validation\n  skills/             # Contextual knowledge (auto-loaded)\n    binary-releases/\n    cargo-vet/\n    changelog/\n    ci-pipeline/\n    dependency-policy/\n    fuzz-testing/\n    hardening-detection/\n    migration-guide/\n    release-automation/\n    scorecard-checks/\n    security-findings/\n    slsa-provenance/\n    trusted-publishing/\n    workspace-publishing/\n  templates/          # Parameterized config files\n    workflows/\n      ci.yml\n      codeql.yml\n      fuzz.yml\n      publish.yml\n      scorecard.yml\n    deny.toml\n    dependabot.yml\n    osv-scanner.toml\n    release.sh\n    rust-toolchain.toml\n    SECURITY.md\n    VERSIONS.md       # Pinned action version manifest (human-readable)\n    versions.json     # Pinned action version manifest (machine-readable)\n  tests/              # Validation infrastructure\n    validate-templates.sh\n    fixtures/\n  examples/           # Sample output\n    audit-output.md\n  .gitignore\n  CLAUDE.md           # Plugin instructions\n  LICENSE             # MIT\n  README.md\n  SECURITY.md         # Plugin security policy\n```\n\n## Critical Gotchas\n\nHard-won lessons from production use:\n\n1. **SLSA generator MUST use `@tag` not SHA** — the reusable workflow requires tag references for attestation signing\n2. **Immutable releases** — provenance must be generated BEFORE the GitHub Release (can't upload assets after)\n3. **Tag protection** — wrong tag = new version number (tags can't be deleted or updated)\n4. **`gh pr checks --watch` race** — returns immediately if checks haven't started; poll for check existence first\n5. **`fetch-depth: 0` required** — publish workflows that verify tag ancestry break with shallow clones\n6. **Trusted Publishing configured at crates.io** — not in the repo; visit crates.io/crates/NAME/settings\n7. **osv-scanner.toml doesn't propagate** — child directories need their own copies\n8. **CodeQL default setup conflicts** — disable in repo Settings > Code Security before using a custom workflow\n9. **cargo-audit needs `--locked`** — prevents MSRV issues from transitive dependency upgrades\n10. **cargo-deny v0.19 breaking change** — removed `vulnerability` key; use `\"all\"` or `\"workspace\"` for unmaintained/unsound\n11. **Workspace publish ordering** — inter-dependent crates must publish in dependency order with ~60s delay for index propagation\n12. **`workflow_dispatch` retrigger** — use `gh workflow run publish.yml -f tag=vX.Y.Z` instead of `gh run rerun` (which uses the original workflow file)\n13. **Tag signatures detect hijacking** — when reviewing action updates, check that tags have GPG/SSH signatures. The Trivy tag hijacking (March 2026) was detectable because force-pushed tags lacked original GPG signatures, had impossible parent-child date relationships, and showed \"0 commits to master since this release\"\n\n## License\n\nMIT\n",
  "bytes": 11047,
  "sha": "d2721dd572ee58c8e6c9ab50e59e08a37b71f4850ee0a509e0c2c6d0ec6ae6fa",
  "repo_slug": "sbom-tool/gh-guard",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sbom_tool_gh_guard_gh_guard_95597fea/readme"
}