[software-development-practices:nist-ssdf] github/gh-aw-actions repository guidance

github/gh-aw-actions has several repository-visible SSDF strengths already in place: a published security policy, pinned GitHub Action SHAs, and checksum-verified installer scripts. The main high-confidence gap is release-integrity evidence for the artifacts this repository distributes. The repository snapshot does not show release-attestation or provenance verification for shipped `gh-aw` setup assets, so downstream users cannot easily verify who built a release or whether a published artifact matches a reviewed source revision.

**Action:** Repository maintainers should add a release provenance/attestation workflow for shipped action and CLI-install artifacts, and accept this issue when a public release path emits verifiable provenance linked to the released commit and release assets.

> Advisory only: this review is repository-observable, non-binding, and does **not** prove security, compliance, certification, endorsement, or SSDF conformance.

`[software-development-practices:nist-ssdf] target=github/gh-aw-actions commit=045beb2d14bda8d0c1f2e83b41527f63770d2855 publication=NIST SP 800-218 Version 1.1`

## Target and source verification
- Target repository: `github/gh-aw-actions`
- Analyzed commit: `045beb2d14bda8d0c1f2e83b41527f63770d2855`
- Source verification date: `2026-09-15`
- Final publication assessed: `NIST SP 800-218 Version 1.1`
- Official SSDF project page: `https://csrc.nist.gov/projects/ssdf`
- Final publication URL: `https://csrc.nist.gov/pubs/sp/800/218/final`
- DOI: `https://doi.org/10.6028/NIST.SP.800-218`
- Non-final notice: The SSDF project page also references finalized SP 800-218A community-profile material for generative AI. That publication augments SP 800-218 and was **not** used as the baseline because this review scores the repository against the core final SSDF publication, not a profile or draft.

## Scope, assumptions, inaccessible evidence, and limitations
- Scope is limited to repository-visible evidence in the checked-out `target/` snapshot and bounded GitHub metadata readable in this run.
- SSDF is organization-wide and risk-based. Repository evidence alone cannot establish whether training, staffing, separation of duties, incident handling, or deployment controls are implemented elsewhere.
- Optional/private evidence that was not accessible in this run is marked `NOT_ASSESSED` or `HUMAN_REVIEW_REQUIRED` rather than treated as a failure.
- GitHub API access for some repository settings returned transient `HTTP 502 resource labeling failed`, so branch-protection and Actions-policy evidence could not be confirmed directly in this run.
- No draft SSDF requirements were used for scoring.

## Practice matrix

### PO — Prepare the Organization
- **PO.1 / PO.2 / PO.3** — Define security requirements, roles, and supporting processes.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: `target/README.md` describes the repository purpose; `target/CODEOWNERS` identifies maintainers; `target/SECURITY.md` defines public vulnerability reporting.
- Limitations: Repository content cannot prove secure-development policy, training, staffing, or org-wide role execution.
- Improvement: Keep maintainership and security-reporting paths current to reduce coordination and intake risk.
- **PO.4** — Define and use criteria for software security checks and gates.
- Status: `PARTIAL`
- Evidence: `target/.github/workflows/ci.yml` runs `zizmor` and compat validation on pull requests and pushes; workflows set minimal explicit permissions and pin third-party actions by SHA.
- Limitations: Unable to confirm required-branch enforcement or whether additional gates exist outside the repository.
- Improvement: Publish branch-protection/gating expectations in docs or workflow status requirements to reduce the risk of unenforced checks.
- **PO.5** — Implement and maintain secure development environments.
- Status: `PARTIAL`
- Evidence: `target/setup/setup.sh`, `target/setup/post.js`, and related scripts include runtime isolation handling, cleanup, checksum verification, and credential-cleaning helpers.
- Limitations: A repository review cannot verify runner hardening or operator practices.
- Improvement: Continue documenting environment assumptions and least-privilege expectations to reduce build-environment drift.

### PS — Protect the Software
- **PS.1** — Protect all forms of code from unauthorized access and tampering.
- Status: `PARTIAL`
- Evidence: `target/.github/workflows/ci.yml` uses `persist-credentials: false`; action references are SHA-pinned; `target/CODEOWNERS` exists.
- Limitations: Direct confirmation of branch protection, signed-commit requirements, and environment protection rules was unavailable.
- Improvement: Verify and document repository protection settings to reduce unauthorized-change risk.
- **PS.2** — Provide a mechanism for verifying software release integrity and provenance.
- Status: `GAP_FOUND`
- Evidence: `target/SECURITY.md` documents SBOM generation for releases, and installer scripts in `target/setup-cli/install.sh` and `target/setup-cli/install.ps1` verify downloaded checksums. However, the repository-visible workflows and docs do **not** show release provenance, artifact attestation, or equivalent verifiable linkage from published release assets back to the reviewed source/build.
- Limitations: A private release pipeline outside the repository could exist, but no repository-visible evidence supports that for this target.
- Improvement: Add public release provenance or artifact attestations for published assets so consumers can verify origin and tamper resistance; this reduces software-supply-chain substitution and rebuild-trust risk.
- **PS.3** — Archive and protect each release and its provenance.
- Status: `PARTIAL`
- Evidence: `target/SECURITY.md` says SBOMs are generated on every release and attached to releases as assets.
- Limitations: No visible evidence of retained provenance/attestation records or release-verification procedure.
- Improvement: Retain SBOM plus provenance together per release to reduce future investigation and recall friction.

### PW — Produce Well-Secured Software
- **PW.1** — Use well-secured design practices.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: Repository purpose is narrow and README-scoped; scripts include explicit checksum validation and permission checks.
- Limitations: Design review artifacts and threat models are not repository-visible.
- Improvement: Preserve narrow runtime scope and explicit trust boundaries to reduce feature creep and misuse.
- **PW.2** — Review the software design to detect and evaluate security risks.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: `zizmor` workflow provides some workflow-focused review automation.
- Limitations: No repository-visible threat-model or design-review record.
- Improvement: Record lightweight security design notes for higher-risk release and setup paths to reduce overlooked trust-boundary issues.
- **PW.4** — Reuse well-secured software components.
- Status: `OBSERVED`
- Evidence: `target/.github/workflows/ci.yml` pins marketplace actions by commit SHA; installer scripts validate checksums before executing downloaded binaries.
- Limitations: Full dependency governance outside checked-in scripts was not assessed.
- Improvement: Preserve pinning and checksum verification to reduce dependency substitution risk.
- **PW.6 / PW.7** — Configure tools and check code for vulnerabilities and weaknesses.
- Status: `PARTIAL`
- Evidence: `target/.github/workflows/ci.yml` runs `zizmor`; setup JS package includes tests and typecheck scripts in `target/setup/js/package.json`.
- Limitations: No visible CodeQL/dependency-review/secret-scanning workflow in the checked snapshot; GitHub Advanced Security configuration was not directly readable.
- Improvement: Evaluate whether additional automated code and dependency analysis is already enabled elsewhere; if not, consider adding it to reduce silent defect introduction risk.
- **PW.8** — Reproducible and well-controlled builds/releases.
- Status: `PARTIAL`
- Evidence: Sync workflow validates refs and pins source provenance when syncing from `github/gh-aw`; install scripts verify release checksums.
- Limitations: No visible release-build attestation or documented reproducibility claims.
- Improvement: Pair release builds with attestation/provenance to reduce ambiguity over build origin.

### RV — Respond to Vulnerabilities
- **RV.1** — Identify and confirm vulnerabilities on an ongoing basis.
- Status: `PARTIAL`
- Evidence: `target/SECURITY.md` provides a coordinated disclosure path; `target/.github/workflows/daily-runtime-threat-scan.lock.yml` shows an automated recurring runtime threat scan.
- Limitations: Private alert intake and triage tooling were not accessible.
- Improvement: Preserve recurring review coverage and disclosure intake to reduce detection lag.
- **RV.2 / RV.3** — Assess, prioritize, remediate, and analyze root causes.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: Public security-reporting policy exists.
- Limitations: Repository evidence cannot prove internal triage SLAs, remediation governance, or lessons-learned practices.
- Improvement: Track remediation expectations internally to reduce response inconsistency.

## Prioritized improvement backlog
1. **Publish verifiable release provenance for distributed assets**
- Priority: `P1`
- SSDF linkage: `PS.2`, `PS.3`, `PW.8`
- Status: `untracked in current repository guidance issues found by this run`
- Evidence:
- `target/SECURITY.md` promises release SBOMs.
- `target/setup-cli/install.sh` and `target/setup-cli/install.ps1` verify checksums for downloaded binaries.
- Repository-visible workflows do not show artifact attestation, signed provenance, or a public verification path for release outputs.
- Risk reduced: Lowers the chance that consumers install a substituted or opaque release artifact whose checksum file alone does not establish trusted build origin.
- Owner surface: Release engineering / repository maintainers.
- Dependencies: Access to the repository’s release workflow and chosen provenance mechanism.
- Proportionate implementation options:
- GitHub artifact attestations tied to release assets and source commit; or
- another public, verifiable provenance/signing mechanism that binds artifacts, build workflow identity, and source revision.
- Acceptance checks:
- A repository-visible workflow emits provenance/attestation for release assets.
- Release documentation links to a public verification procedure.
- At least one current release exposes both SBOM and provenance materials traceable to the released commit.

## Strengths worth preserving
- Public `SECURITY.md` with coordinated disclosure instructions.
- Minimal-permission workflows and pinned action SHAs in `target/.github/workflows/ci.yml`.
- Checksum verification in `target/setup-cli/install.sh`, `target/setup-cli/install.ps1`, and related installer scripts.
- Existing recurring runtime-threat-scan workflow for suspicious runtime changes.

## Human-review questions
- Are branch protection, required reviews, and status checks enforced on `main`, and should those expectations be documented publicly?
- Is release provenance already generated outside the visible snapshot, and if so, can maintainers expose a public verification path for consumers?
- Are additional automated analyses such as dependency review, code scanning, or secret scanning already enabled at the organization level and therefore intentionally omitted from repository workflows?

### Control Plane
- Correlation ID: `34982002103-297`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run URL: `https://github.com/githubnext/gh-aw-cao/actions/runs/34982002103`

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34982614418) · pi · gpt54 · 79.7 AIC · ⊞ 9.4K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Fsoftware-development-practices-nist-ssdf%22&type=issues)
> - [x] expires on Oct 15, 2026, 2:41 PM UTC

Start by reading target/SECURITY.md and inspecting the release-related workflows under target/.github/workflows, along with checksum handling in target/setup-cli/install.sh and target/setup-cli/install.ps1. Trace how release assets and SBOMs are published, then document the public verification path. Done means a visible workflow emits provenance for release assets, documentation explains verification, and one current release links its SBOM and provenance to the released commit.

Written by the indexing model from the issue text.