harden-github-actions
Harden GitHub Actions CI/CD workflows for supply-chain security — SHA-pin actions, least-privilege token permissions, verified toolchain installs, OpenSSF Scorecard, and SLSA provenance. Use when adding or auditing GitHub Actions workflows, before making a repository public, when a supply-chain review flags CI gaps, or when standardizing CI hardening across GitHub projects. GitHub-specific by design — GitLab CI and Forgejo Actions are out of scope.
jrjsmrtn · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jrjsmrtn/project-orchestration-skills --skill harden-github-actions技能说明
name: harden-github-actions description: Harden GitHub Actions CI/CD workflows for supply-chain security — SHA-pin actions, least-privilege token permissions, verified toolchain installs, OpenSSF Scorecard, and SLSA provenance. Use when adding or auditing GitHub Actions workflows, before making a repository public, when a supply-chain review flags CI gaps, or when standardizing CI hardening across GitHub projects. GitHub-specific by design — GitLab CI and Forgejo Actions are out of scope. metadata: author: "Georges Martin jrjsmrtn@gmail.com" version: "0.1.34" license: MIT
Harden GitHub Actions
Harden GitHub Actions CI/CD workflows against supply-chain attack: pin what runs, minimise what it can do, and verify what it fetches.
GitHub-specific by design. Unlike most orchestration skills, this one is deliberately bound to one forge. The hardening controls below are not portable concepts wearing GitHub syntax — they are properties of the GitHub Actions execution model itself: third-party actions resolved by mutable git ref, an ambient
GITHUB_TOKENwith repository-wide default scopes, and OIDC-backed SLSA provenance. It has a sibling,harden-gitlab-ci, which is not a translation of this skill: GitLab's risks sit in different places (include:/CI-Catalog components, and aCI_JOB_TOKENthat defaults to own-project-only — so there the work is keeping it scoped, the opposite posture from here). Forgejo Actions is Actions-compatible in shape but resolves actions against its instance's configured registry, so pinning guidance does not transfer unchanged (roadmap H9).
When to Use
- When adding GitHub Actions workflows to a project (after
setup-git-hooks) - When auditing existing
.github/workflows/before making a repository public - When a supply-chain review (or the
supply-chainskill) flags CI hardening gaps - When standardising CI hardening across GitHub projects
Not for: GitLab CI — use harden-gitlab-ci. Not for Forgejo/Gitea Actions — the controls do not carry over unchanged. Say so rather than approximating.
This skill hardens CI workflows. validate-quality-config only reads CI to confirm parity with local hooks — it does not check pinning, permissions, or provenance. The two are complementary.
Required Inputs
- Workflow files — the project's
.github/workflows/*.yml - Release model — does the project publish artifacts/images/packages (needs provenance + signing), or is it internal-only?
- Repository visibility — public or private (affects Scorecard
publish_resultsand OSSF publishing)
The Threat
A CI job runs third-party code (actions, installed tools) with a GITHUB_TOKEN and often OIDC. A mutable action tag (@v4) can be repointed to malicious code; an over-privileged token can push commits, publish packages, or exfiltrate secrets; an unverified curl | sh install can be swapped upstream. Hardening closes all three: pin, least-privilege, verify.
Workflow
Step 1: Inventory and triage
Find every workflow and the hardening gaps in it:
ls .github/workflows/
# Mutable action refs (should be zero — all must be SHA-pinned):
grep -rnE 'uses:.*@(v[0-9]|main|master|latest)' .github/workflows/
# Workflows missing a top-level permissions block:
for f in .github/workflows/*.yml; do grep -q '^permissions:' "$f" || echo "no permissions: $f"; done
# Floating tool versions:
grep -rnE 'version:\s*latest|@latest' .github/workflows/
Aim for a clean 3-way split: ci.yml (lint/test/build on push + PR), scorecard.yml (OpenSSF Scorecard on a schedule), and — only if the project ships artifacts — release.yml (SBOM + SLSA provenance + signing).
Step 2: SHA-pin every action
Pin every uses: to a full 40-character commit SHA with a trailing # vX.Y.Z comment for readability. Never rely on a mutable tag.
# Good — immutable, human-readable, Dependabot-updatable
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5.3.0
- uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
# Bad — mutable tag, can be repointed upstream
- uses: actions/checkout@v4
Resolve a tag to its commit SHA:
gh api repos/actions/checkout/commits/v4.2.2 --jq '.sha'
Keep pins current automatically with a Dependabot github-actions update block (see bootstrap-project / the dependency-update config). Dependabot preserves the # vX.Y.Z comment when it bumps a SHA.
The one sanctioned exception: reusable workflows that verify their own release tag — notably slsa-framework/slsa-github-generator — must be referenced by semantic version tag, not SHA (see Step 7). Document the exception in an ADR and in a comment on the line.
Step 3: Least-privilege token permissions
Set a read-only default at the top of every workflow, then elevate per job only where a job genuinely needs to write.
# top of the workflow
permissions:
contents: read
Elevate narrowly, in the specific job:
jobs:
# OpenSSF Scorecard
analysis:
permissions:
security-events: write # upload the SARIF result
id-token: write # publish results to the OSSF API
contents: read
# Release provenance / publish
provenance:
permissions:
actions: read # read the workflow path
id-token: write # mint the OIDC token for signing
contents: write # attach provenance to the release
# packages: write # add only if publishing to GHCR / a registry
Rule of thumb: default contents: read; add id-token: write only for OIDC signing/publish; add contents: write only for jobs that create releases/tags; add packages: write only for registry publish; add security-events: write only for SARIF upload.
Step 4: Harden the checkout
On an
阅读完整来源 ↗