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

This review found strong repository-level security hygiene in `github/gh-aw`, but one high-confidence SSDF gap remains: releases are promoted and container images are published without repository-observable artifact signing or provenance attestation. That weakens downstream verification of what was shipped.

**Action:** Security/release maintainers should add signed release attestations for published artifacts and document the verification path; acceptance check: the release/publish workflows emit signed provenance or equivalent attestations for `gh-aw` release artifacts and the gh-aw-node image, and the verification steps are documented in-repo.

> **Advisory only:** This issue is non-binding guidance based on repository-observable evidence. It does **not** prove security, compliance, certification, endorsement, or SSDF conformance.

`[software-development-practices:nist-ssdf] github/gh-aw@b68dba0ae6b4422e4a520ce66e30b88c8313713b`

- **Target repository:** `github/gh-aw`
- **Analyzed commit:** `b68dba0ae6b4422e4a520ce66e30b88c8313713b`
- **Source verification date:** `2026-09-13`
- **Final publication version:** `NIST SP 800-218 Version 1.1`
- **Official URLs:** `https://csrc.nist.gov/projects/ssdf`, `https://csrc.nist.gov/pubs/sp/800/218/final`, `https://doi.org/10.6028/NIST.SP.800-218`

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

## Scope, assumptions, and limitations

- This is a repository-only advisory review against the current **final** SSDF publication observed on 2026-09-13.
- The NIST SSDF project page also references `SP 800-218A` as a finalized **community profile** for generative AI and dual-use foundation models. That augments SP 800-218 but does not replace the core final SSDF baseline used here.
- A repository snapshot cannot establish organization-wide implementation for staffing, training, incident response execution, segregation of duties, or private infrastructure controls. Those items are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED` where appropriate.
- Branch protection details could not be retrieved with the available token (`403 Resource not accessible by integration`), so branch-protection-dependent conclusions remain `NOT_ASSESSED`.
- Open-issue duplicate checks in the review repository were partially limited by transient GitHub CLI failures (`HTTP 502: resource labeling failed`). This review therefore omits any claim that all prior guidance is already tracked.
- No draft SSDF publication was used for scoring.

## Practice matrix

### PO — Prepare the Organization

| Practice / task | Status | Evidence | Limitations / assumptions | Improvement and reduced risk |
| --- | --- | --- | --- | --- |
| `PO.1` Define and use secure software development requirements | `PARTIAL` | `README.md` and docs emphasize sandboxed, read-only agent jobs and safe outputs; `SECURITY.md` documents coordinated disclosure and SBOM generation; many workflows pin action SHAs. | Repository evidence shows secure-development intent, but not complete organizational requirements management. | Consolidate repo-level secure release requirements, including artifact authenticity and provenance checks, to reduce release process drift. |
| `PO.2` Implement roles and responsibilities | `HUMAN_REVIEW_REQUIRED` | `CODEOWNERS` names maintainers; `CONTRIBUTING.md` explains a core-team mediated contribution model. | Does not prove security role separation, training, or approval authority. | Confirm human approval points for release and security exceptions to reduce single-actor process risk. |
| `PO.3` Implement supporting tooling and workflows | `OBSERVED` | `.github/workflows/ci.yml`, `codeql.yml`, `security-scan.yml`, `license-check.yml`, `link-check.yml`, `install.yml`; `Makefile` exposes `security-scan`, `test-security`, fuzzing, and SBOM targets. | Tool presence does not prove every control runs effectively on every change path. | Preserve current scanner/test automation; it reduces defect introduction and security-regression risk. |
| `PO.4` Provide secure development environment and criteria | `PARTIAL` | `CONTRIBUTING.md` requires Dev Container/Codespaces and discourages unsupported local environments. | Environment hardening, identity, and endpoint controls are not repository-observable. | Add explicit secure-release environment requirements for signing/attestation to reduce build-environment ambiguity. |

### PS — Protect the Software

| Practice / task | Status | Evidence | Limitations / assumptions | Improvement and reduced risk |
| --- | --- | --- | --- | --- |
| `PS.1` Protect all forms of code from unauthorized access and tampering | `PARTIAL` | Pinned action SHAs across workflows; `permissions:` are commonly explicit and least-privilege in `ci.yml`, `codeql.yml`, and `security-scan.yml`; `CODEOWNERS` exists. | Could not verify branch protection/rulesets with current token; no org access-control evidence. | Verify and document protected-branch/ruleset expectations to reduce unauthorized change risk. |
| `PS.2` Provide a mechanism for verifying software release integrity | `GAP_FOUND` | `SECURITY.md` describes SBOM generation on release; `publish-safe-outputs-node.yml` publishes images with metadata labels; `promote-release.yml` updates release state. No repository-observable workflow evidence of artifact signing, Sigstore/Cosign use, SLSA provenance, or release attestation generation/verification was found. | Absence is based on repository snapshot and bounded text/workflow inspection; external release platform controls could exist but were not observable here. | Add signed provenance/attestations for release binaries and published images, and document verification. This reduces tampering, substitution, and supply-chain trust gaps for downstream consumers. |
| `PS.3` Archive and protect each software release | `PARTIAL` | Releases and release-promotion workflow exist; SBOM generation is documented in `SECURITY.md`. | Retention, escrow, and long-term archive protections are not observable. | Attach attestations/SBOMs consistently to releases to strengthen historical traceability. |

### PW — Produce Well-Secured Software

| Practice / task | Status | Evidence | Limitations / assumptions | Improvement and reduced risk |
| --- | --- | --- | --- | --- |
| `PW.1` Design software to meet security requirements and minimize vulnerabilities | `PARTIAL` | Architecture/security guidance in `README.md` and docs; ADRs under `docs/adr/` show security design decisions. | Repository review cannot prove systematic threat modeling coverage. | Keep ADR-backed security decisions current to reduce architectural regression risk. |
| `PW.2` Review the software design to verify compliance with security requirements | `PARTIAL` | ADRs and dedicated workflows such as `security-review.md`, `security-compliance.md`, and policy-focused docs indicate structured review. | Presence of workflows/docs does not prove consistent human review execution. | Tie release authenticity requirements into design review criteria to catch supply-chain omissions earlier. |
| `PW.3` Reuse existing, well-secured software when feasible | `OBSERVED` | Extensive use of pinned upstream actions; Dependabot covers Go, npm, pip, Docker, and GitHub Actions in `.github/dependabot.yml`. | Does not prove supplier risk evaluation depth. | Preserve pinning and update hygiene to reduce dependency compromise exposure. |
| `PW.4` Create source code following secure coding practices | `OBSERVED` | `Makefile` provides `test-security`, fuzzing, `security-gosec`, `security-govulncheck`; `.golangci.yml` comments document separate gosec handling; CodeQL and SARIF uploads run in dedicated workflows. | Repository review cannot prove complete coverage of all languages/paths. | Preserve these gates; they reduce common coding and dependency vulnerability risk. |
| `PW.5` Evaluate and improve code before release | `OBSERVED` | `ci.yml` runs tests, audits, compile checks, and validation jobs; `codeql.yml` and `security-scan.yml` run on schedule and manual dispatch; `license-check.yml` adds supply-chain policy checking. | Some workflows are path-scoped or scheduled, so not every control necessarily blocks every release. | Extend pre-release gating to require attestation generation/verification, reducing unverified release risk. |
| `PW.6` Reassess and update toolchains/components | `OBSERVED` | Dependabot config, scheduled security scans, and `.grype.yaml` with scoped documented exceptions show active component hygiene and risk acceptance discipline. | Risk acceptance quality still needs human review. | Preserve CVE-scoped exception discipline to reduce unnoticed inherited risk. |
| `PW.7` Deliver well-secured software releases | `PARTIAL` | Release/install workflows exist, with explicit permissions and testing; SBOM generation is documented. | Lack of observable signing/attestation prevents stronger conclusion on release integrity. | Implement signed release provenance to reduce consumer uncertainty and supply-chain spoofing risk. |

### RV — Respond to Vulnerabilities

| Practice / task | Status | Evidence | Limitations / assumptions | Improvement and reduced risk |
| --- | --- | --- | --- | --- |
| `RV.1` Identify and confirm vulnerabilities on an ongoing basis | `OBSERVED` | `codeql.yml` daily schedule; `security-scan.yml` daily gosec/govulncheck; Dependabot; multiple security audit workflows. | Public repo evidence does not show private alert triage SLAs. | Preserve current scanning cadence to reduce dwell time for known flaws. |
| `RV.2` Assess, prioritize, and remediate vulnerabilities | `PARTIAL` | `.grype.yaml` records scoped, reasoned risk acceptances; `SECURITY.md` explains reporting path; numerous security workflows exist. | Cannot observe private advisory handling or remediation SLAs. | Add explicit release attestation work to remediation backlog because it closes a verified integrity gap. |
| `RV.3` Analyze root causes and improve future prevention | `PARTIAL` | ADRs document security-driven changes and rationale, including dependency/confused-deputy mitigations in docs. | Cannot verify org-wide post-incident practice. | Capture any future release-integrity incidents or near-misses in ADRs to reduce recurrence. |

## Prioritized improvement backlog

1. **Add signed provenance and artifact attestations for release outputs**
- **Priority:** P1
- **SSDF provenance:** `PS.2`, `PW.7`, supports `PO.1`
- **Status:** Untracked in this repository-observable review
- **Evidence:** `promote-release.yml` promotes releases; `publish-safe-outputs-node.yml` builds and pushes `ghcr.io/github/gh-aw-node`; `SECURITY.md` documents SBOM creation, but no repository-observable signing/attestation workflow or verification docs were found.
- **Risk rationale:** Consumers cannot independently verify that the published binary/image came from the expected source and workflow, increasing tampering, substitution, and supply-chain trust risk.
- **Owner surface:** Release engineering / security maintainers
- **Dependencies:** Choose attestation format/tooling (e.g. GitHub artifact attestations, Sigstore/Cosign, or equivalent), decide which artifacts are in scope, and update release documentation.
- **Acceptance checks:**
- Release workflow emits signed provenance/attestation for published `gh-aw` artifacts.
- Container publish workflow emits signed provenance/attestation for `ghcr.io/github/gh-aw-node`.
- Repository docs show how maintainers and consumers verify those attestations.
- Any exceptions are documented with scope and approval.

## Strengths worth preserving

- Daily CodeQL, gosec, and govulncheck workflows provide broad continuous vulnerability discovery.
- Dependabot coverage spans GitHub Actions, Go, npm, pip, and Docker ecosystems.
- Action SHAs are pinned broadly, reducing supply-chain drift.
- `.grype.yaml` shows disciplined, CVE-scoped, reasoned risk acceptance rather than blanket suppression.
- `CONTRIBUTING.md` sets a controlled contribution model and standardized development environment expectations.

## Human-review questions

1. Are release artifacts or container images already signed or attested outside this repository, and if so, can that verification path be made repository-visible?
2. What branch protection/ruleset controls are enforced on `main`, and do they block release-affecting workflow changes without review?
3. Which release artifacts are authoritative for consumers (`gh` extension binary, container image, release assets), and should all of them share one attestation policy?
4. Are there organization-level retention, revocation, and key-management requirements that should be referenced from this repository?

Evidence notes

- `SECURITY.md` includes coordinated disclosure guidance and says SBOMs are generated on every release.
- `.github/dependabot.yml` schedules weekly updates across `github-actions`, `gomod`, `npm`, `pip`, and `docker` ecosystems.
- `.github/workflows/codeql.yml` runs daily and uploads security findings.
- `.github/workflows/security-scan.yml` runs daily `gosec` and `govulncheck` with SARIF upload.
- `.github/workflows/license-check.yml` checks dependency licenses and uploads a report.
- `.github/workflows/promote-release.yml` can promote a release but shows no signing/attestation step.
- `.github/workflows/publish-safe-outputs-node.yml` publishes a container image with labels and digest-aware logic but no observable signing/attestation step.
- Branch protection API call was inaccessible with the available token, so that evidence remains unavailable.

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34748150600) · pi · gpt54 · 56.5 AIC · ⊞ 9.1K · [◷](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 13, 2026, 8:43 AM UTC

Start by reading promote-release.yml, publish-safe-outputs-node.yml, and the release guidance in SECURITY.md to understand the existing artifact and image publishing paths. Add signed provenance or equivalent attestations for published gh-aw artifacts and gh-aw-node, then document how maintainers and consumers verify them and confirm any exceptions are scoped and approved.

Written by the indexing model from the issue text.