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

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

The repository already shows strong secure-development basics across disclosure, CI, pinned actions, and documented contribution controls. The highest-confidence untracked gap is the absence of repository-visible software composition / dependency review and artifact provenance checks in CI, which leaves dependency and release-integrity regressions easier to miss before merge or release.

**Action:** Assign to a maintainer to add bounded dependency-review and build-provenance verification coverage in CI, and accept when pull requests that change dependencies trigger automated review gates and release/build outputs have documented verification checks.

`githubnext/gh-aw-cao` analyzed at commit `6b178f6356706bd489da95123bf15a8a7cc94e9e`.

Machine-readable marker: ``

## Source verification
- Verification date: 2026-09-14
- Final publication used: NIST SP 800-218, Secure Software Development Framework (SSDF) Version 1.1
- Official publication URL: https://csrc.nist.gov/pubs/sp/800/218/final
- Official SSDF project URL: https://csrc.nist.gov/projects/ssdf
- DOI: https://doi.org/10.6028/NIST.SP.800-218
- Final-publication status: verified from official NIST final publication page during this run
- Draft notice: no newer final revision was verified during this run; drafts, if any, were not used for scoring

## Scope, assumptions, and limitations
- Scope: repository-observable evidence in the checked-out `target/` snapshot and bounded GitHub repository metadata for `githubnext/gh-aw-cao`
- Target checkout used as authoritative snapshot: `target/`
- Assumption: repository files and metadata are accurate representations of current public configuration at the analyzed commit
- Inaccessible evidence treated as non-authoritative: organization training records, internal SDLC procedures, private branch-protection details beyond available API access, private alerts, private incidents, secret-scanning data, deployment controls, and human approval practices outside checked-in evidence
- Branch protection detail limitation: the available credential returned HTTP 403 for the branch-protection endpoint, so branch-protection conclusions remain limited to repository-observable workflow and contribution evidence
- Open issue search limitation: `gh issue list` succeeded but `gh search issues` failed in this environment with `malformed version`; duplicate tracking was checked against the available open-issue listing rather than code search
- SSDF is risk-based and organization-integrated; repository-only observations cannot establish organization-wide implementation or conformance

## PO / PS / PW / RV practice-to-evidence matrix

### PO — Prepare the Organization

- **PO.1 / PO.1.1–PO.1.3** — Define and communicate security requirements for software development
- Status: `PARTIAL`
- Evidence: `SECURITY.md` defines a private vulnerability reporting path; `AGENTS.md`, `docs/admission.md`, and `docs/control-policy-specification.md` document operational safety boundaries and control policy expectations
- Limitations: repository evidence does not establish broader organizational policy, secure coding standards, or required security criteria across all SDLC stages
- Improvement: add a concise checked-in secure-development policy/reference that links repository controls to release, dependency, and review expectations; reduces ambiguity and drift in project-specific security expectations

- **PO.2 / PO.2.1** — Implement roles and responsibilities for the SSDF
- Status: `PARTIAL`
- Evidence: `.github/CODEOWNERS` assigns `* @github/next`; `README.md` and `SUPPORT.md` identify GitHub Next as maintainer; `CONTRIBUTING.md` defines core-team and community contribution paths
- Limitations: repository evidence does not identify security-specific responsibilities, escalation ownership, or separation of duties
- Improvement: document security-relevant owner surfaces for releases, dependency updates, and incident triage; reduces response ambiguity during security-sensitive changes

- **PO.3 / PO.3.1** — Provide security education and guidance to developers
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: contribution guidance in `CONTRIBUTING.md`; operational safety guidance in `AGENTS.md`
- Limitations: training completion, role-based instruction, and recurring security education are not repository-observable
- Improvement: link contributor docs to secure coding, dependency, and release verification guidance; reduces onboarding gaps for contributors

### PS — Protect the Software

- **PS.1 / PS.1.1–PS.1.2** — Protect code and related data from unauthorized access and tampering
- Status: `PARTIAL`
- Evidence: workflows routinely set `persist-credentials: false`; many workflows pin GitHub Actions by commit SHA; `workflow-contracts.yml`, `cid.yml`, and `docs.yml` run CI on pushes/PRs; local composite action `.github/actions/setup-gh-aw/action.yml` resolves a pinned compiler version from checked-in policy
- Limitations: branch-protection settings were not readable; repository review cannot verify environment hardening, secret management implementation, or maintainer access controls
- Improvement: publish a short repository security-controls overview including required review gates and release authority; reduces uncertainty around tamper-resistance expectations

- **PS.2 / PS.2.1** — Provide a mechanism for protecting each software release's integrity
- Status: `PARTIAL`
- Evidence: release workflow exists at `.github/workflows/release.lock.yml`; many workflows pin third-party actions by commit SHA
- Limitations: no repository-visible SBOM generation, release signing, provenance attestation, or verification step was found in checked-in workflows searched during this run
- Improvement: add provenance attestation and verification for release artifacts and published deliverables; reduces risk of undetected artifact tampering and weakens supply-chain ambiguity

- **PS.3 / PS.3.1** — Archive and protect provenance data for software artifacts
- Status: `PARTIAL`
- Evidence: documentation and workflows emphasize run provenance and exact workflow SHA linkage (`docs/admission.md`, CAO lock metadata, control-plane correlation)
- Limitations: this is workflow/run provenance, not end-to-end artifact provenance for released software packages or site artifacts
- Improvement: retain verifiable artifact provenance tied to builds/releases; reduces forensic gaps after release issues

### PW — Produce Well-Secured Software

- **PW.1 / PW.1.1–PW.1.3** — Use well-secured development environments
- Status: `PARTIAL`
- Evidence: workflows use explicit permissions blocks, pinned actions, read-only defaults in many jobs, and isolated CI tasks; `action-lint.yml` runs `actionlint` and `zizmor` to review workflow risks
- Limitations: repository evidence cannot prove runner hardening, workstation controls, or build-environment baselines outside GitHub Actions
- Improvement: preserve and expand automated workflow hardening checks; reduces CI configuration regressions

- **PW.2 / PW.2.1–PW.2.2** — Design software to meet security requirements and minimize vulnerabilities
- Status: `PARTIAL`
- Evidence: architecture and control docs (`docs/architecture*.md`, `docs/admission.md`, `docs/control-policy-specification.md`) define fail-closed and authority-boundary behavior; `AGENTS.md` requires fail-closed behavior and explicit policy boundaries
- Limitations: repository review cannot determine whether all threat models, abuse cases, or security design reviews are complete
- Improvement: preserve architecture decision records for security-significant design changes; reduces future erosion of core trust boundaries

- **PW.4 / PW.4.1** — Review code to find and eliminate vulnerabilities
- Status: `PARTIAL`
- Evidence: CI validation exists in `workflow-contracts.yml`, `cid.yml`, and `action-lint.yml`; contribution guidance requires focused tests and validation
- Limitations: branch-protection and mandatory reviewer enforcement were not observable with current credentials; no repository-visible dedicated dependency-review gate was found
- Improvement: add an automated dependency-review job for pull requests that modify lockfiles/manifests; reduces risk from unnoticed vulnerable or over-privileged dependency changes

- **PW.6 / PW.6.1–PW.6.3** — Test executable code and reusable components
- Status: `PARTIAL`
- Evidence: extensive unit, integration, load, SVG, docs, and Playwright tests are defined in `package.json`, `workflow-contracts.yml`, `cid.yml`, `actions.yml`, and `docs.yml`
- Limitations: no repository-visible SAST, dependency scanning gate, or artifact provenance verification step was found in checked-in workflows searched during this run
- Improvement: add security-focused automated checks alongside existing functional suites; reduces likelihood that vulnerable dependencies or build-integrity regressions reach default branch

- **PW.8 / PW.8.1–PW.8.4** — Reuse well-secured software components and manage third-party components
- Status: `GAP_FOUND`
- Evidence: the repository has `package.json` and lockfiles (`package-lock.json`, `dashboard/site/package-lock.json`), but no checked-in workflow using GitHub dependency review, SBOM generation, CodeQL dependency analysis, or equivalent repository-visible component risk gate was found in `.github/workflows/`; grep across workflows and docs found no active dependency-review/provenance/SBOM workflow for this repository’s own CI
- Limitations: GitHub may still run platform-native alerting outside checked-in workflows, but this review found no repository-visible preventive gate on dependency changes
- Improvement: add pull-request dependency review plus release/build provenance checks; reduces supply-chain risk from vulnerable, malicious, or unexpectedly broad dependency updates

### RV — Respond to Vulnerabilities

- **RV.1 / RV.1.1–RV.1.3** — Identify and confirm vulnerabilities on an ongoing basis
- Status: `PARTIAL`
- Evidence: `SECURITY.md` provides a private intake path; support docs direct security reports away from public issues; dependabot automation/workflows are present in the repository
- Limitations: private alert triage, advisory handling, and SLA evidence are not repository-observable; this run did not verify Dependabot alert configuration beyond repository files and workflow presence
- Improvement: document repository-level expectations for validating and prioritizing vulnerability reports; reduces ambiguity in triage flow

- **RV.2 / RV.2.1–RV.2.3** — Assess, prioritize, and remediate vulnerabilities
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: issue-driven maintenance model in `SUPPORT.md` and `CONTRIBUTING.md`; security reports route privately through `SECURITY.md`
- Limitations: prioritization criteria, remediation SLAs, and exception handling are not repository-observable
- Improvement: document public-facing remediation expectations for repository consumers where appropriate; reduces uncertainty after report intake

- **RV.3 / RV.3.1–RV.3.2** — Analyze root causes and improve future practices
- Status: `PARTIAL`
- Evidence: repository includes operational review packages and docs emphasizing evidence, follow-up, and policy correction; CI and docs are extensive enough to support regression prevention
- Limitations: repository evidence does not prove post-incident root-cause review practice for security events specifically
- Improvement: add a lightweight security incident retrospective template or checklist; reduces recurrence risk after confirmed vulnerabilities

## Prioritized improvement backlog

1. **Add dependency review and provenance verification to CI**
- SSDF linkage: `PW.8`, `PW.4`, `PW.6`, `PS.2`, `PS.3`
- Priority: High
- Evidence: repository has multiple npm manifests/lockfiles and substantial CI, but no repository-visible dependency-review, SBOM, or artifact-provenance verification workflow was found
- Risk rationale: third-party dependency and build-output integrity changes are common supply-chain entry points; existing functional CI may pass while introducing vulnerable or unexpected packages or unverifiable release outputs
- Owner surface: maintainers of `.github/workflows/`, release pipeline, and package manifests
- Dependencies: select one proportionate mechanism compatible with current workflow topology, such as GitHub dependency review for PRs and provenance attestation/verification for release or docs/dashboard artifacts
- Acceptance checks:
- pull requests that modify dependency manifests or lockfiles trigger an automated review gate that surfaces risky changes
- release/build workflows generate or verify provenance for shipped artifacts, or explicitly document the chosen alternative control
- contributor docs point maintainers to the new review signal and failure handling

Agent prompt

Review `githubnext/gh-aw-cao` for a minimal, proportionate SSDF improvement that adds repository-visible dependency review and artifact provenance verification without widening authority boundaries.

Requirements:
1. Add a pull-request CI check that runs only when dependency manifests or lockfiles change and reports risky dependency changes in a maintainable way.
2. Add a repository-visible provenance or attestation verification step for the release path or another shipped artifact path already used by this repository, or document an explicit alternative if native provenance is not yet practical.
3. Keep permissions least-privilege, pin actions by SHA, and preserve existing CI behavior.
4. Update contributor or maintainer docs so humans know when the new checks run and what a failure means.
5. Add or update focused tests/validation as needed.

Constraints:
- Follow `AGENTS.md` and do not edit generated `.lock.yml` files directly; edit markdown workflow sources when applicable and run `npm run compile` if those sources change.
- Do not add broad new SDLC mandates; keep the change scoped to dependency and release integrity evidence.
- Preserve review-mode and fail-closed repository conventions.

Deliverables:
- code/workflow changes
- concise rationale in docs
- validation notes listing commands run

## Strengths worth preserving
- Private vulnerability reporting path is clearly documented in `SECURITY.md`
- CI coverage is broad and includes unit, integration, load, docs, mobile, and workflow-lint validation
- Many workflows use explicit permissions and pin actions by commit SHA
- Contribution and operational docs consistently emphasize bounded authority, fail-closed behavior, and reviewed control policy
- Workflow hardening checks already include `actionlint` and `zizmor`

## Human-review questions
- Are dependency alerts, advisories, or platform-native dependency policies already enforced outside checked-in workflows, and if so should a repository-visible gate be added for transparency?
- Which shipped artifacts for this repository most need provenance guarantees first: npm-related outputs, documentation/site artifacts, dashboard artifacts, or release bundles?
- Are branch-protection rules and reviewer requirements strong enough to treat current code review evidence as a preventive control for security-sensitive changes?
- Is there an existing organization-standard provenance/signing approach that this repository should reuse instead of introducing a custom pattern?

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

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34909121730) · pi · gpt54 · 34.8 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 14, 2026, 11:34 PM UTC

Start by reading the existing workflows under .github/workflows/, especially release.lock.yml, and inspect package.json plus package-lock.json and dashboard/site/package-lock.json. Review current CI validation and release behavior, then define dependency-change review and build/release provenance verification coverage. Done means dependency-changing pull requests trigger automated review gates and release or build outputs have documented verification checks.

Written by the indexing model from the issue text.