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

This repository already shows several strong SSDF-aligned controls—pinned GitHub Actions, `persist-credentials: false` on checkouts, a published `SECURITY.md`, `CODEOWNERS`, explicit CI validation (`npm run check`, Playwright, lint, typecheck), and least-privilege workflow permissions in many jobs. The main repository-observable gap against the current final NIST SSDF remains dependency update governance: the repo has package manifests and Dependabot-related package workflows, but no repository-level `.github/dependabot.yml`, so automated dependency update coverage is not evident for the repository itself.

**Action:** Repository maintainers should add and enable a repository-level `.github/dependabot.yml` that covers the root npm workspace and `dashboard/site/`, then verify that Dependabot opens update PRs on schedule and that at least one update PR is observed after enablement.

> **Advisory only:** This issue is non-binding and does **not** prove security, compliance, certification, endorsement, or NIST SSDF conformance. It is a repository-observable review intended to help maintainers prioritize improvements. Organization-wide practices, private controls, staffing, training, and incident operations require human review.

## Repository and source baseline

- Target repository: `githubnext/gh-aw-cao`
- Analyzed target commit: `5b53362284c6f4313fee469afc1b17cac600ec8e`
- Source verification date: `2026-09-15`
- Final SSDF publication assessed: **NIST SP 800-218 Version 1.1 (final)**
- Official SSDF project page: `https://csrc.nist.gov/projects/ssdf`
- Official final publication: `https://csrc.nist.gov/pubs/sp/800/218/final`
- DOI: `https://doi.org/10.6028/NIST.SP.800-218`

### Control Plane

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

## Scope, assumptions, and limitations

- Scope is limited to repository-observable evidence in the `target/` checkout and bounded repository metadata for `githubnext/gh-aw-cao`.
- The NIST SSDF project page currently also references **SP 800-218A** as a finalized community profile for generative AI. That profile augments SP 800-218 and is **not** the baseline used for this repository review.
- No newer final revision of SP 800-218 was verified from the official NIST pages fetched during this run.
- Organization-wide practices, training, separation-of-duties, deployment environment hardening, secret management operations, incident handling, and internal approval workflows are outside repository-only visibility and are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED` where applicable.
- GitHub issue search for pre-existing tracking was attempted, but the GitHub API returned `HTTP 502: resource labeling failed`; duplicate risk is therefore low-confidence rather than fully eliminated.
- GitHub security-and-analysis details visible through the available metadata were limited; no private alerts or confidential security telemetry were accessed.

## PO / PS / PW / RV practice matrix

### PO — Prepare the Organization

- **PO.1: Define security requirements for software development** — `PARTIAL`
- **Tasks:** `PO.1.1`, `PO.1.2`, `PO.1.3`
- **Evidence:** repository has contributor-facing governance docs (`README.md`, `CONTRIBUTING.md`, `SECURITY.md`), centralized workflow/policy docs under `docs/`, and CODEOWNERS in `.github/CODEOWNERS`.
- **Limitations:** repository evidence cannot confirm enterprise security requirement sources, role-specific policy dissemination, or whether requirements are complete.
- **Improvement:** document a short repository-specific secure development baseline or link map from contributor docs to required security controls; this reduces ambiguity and onboarding drift.

- **PO.2: Implement roles and responsibilities** — `PARTIAL`
- **Tasks:** `PO.2.1`, `PO.2.2`
- **Evidence:** `.github/CODEOWNERS` routes ownership to `@github/next`; workflow and package structure imply clear maintainer surfaces.
- **Limitations:** cannot verify review enforcement, escalation paths, or separation of duties from repository contents alone.
- **Improvement:** confirm branch protection and required reviewer settings in GitHub repository configuration; this reduces risk of unreviewed critical changes.

- **PO.3: Implement supporting tooling and workflows** — `OBSERVED`
- **Tasks:** `PO.3.1`, `PO.3.2`, `PO.3.3`, `PO.3.4`
- **Evidence:** extensive GitHub Actions automation; `workflow-contracts.yml` runs `npm run check`; dashboard CI runs typecheck/lint/unit/e2e/performance; `action-lint.yml` checks Actions files with `actionlint` and `zizmor`; `copilot-setup-steps.yml` standardizes tool setup.
- **Limitations:** tooling effectiveness over time still requires human review of failure handling and operational usage.
- **Improvement:** preserve the current centralized validation pattern; it reduces regressions from inconsistent local practices.

### PS — Protect the Software

- **PS.1: Protect all forms of code from unauthorized access and tampering** — `PARTIAL`
- **Tasks:** `PS.1.1`, `PS.1.2`, `PS.1.3`
- **Evidence:** `actions/checkout` steps commonly set `persist-credentials: false`; many workflows pin actions by full commit SHA; Pages deploy uses explicit job permissions and `id-token: write` only where needed.
- **Limitations:** repository review cannot verify branch protections, signed commits, environment protection rules, or access-control administration.
- **Improvement:** verify and document protected-branch requirements for workflow and policy files; this reduces tampering risk on control-plane logic.

- **PS.2: Provide a mechanism for verifying software release integrity** — `PARTIAL`
- **Tasks:** `PS.2.1`, `PS.2.2`
- **Evidence:** repository compiles workflow locks deterministically (`gh aw compile --strict --no-check-update --schedule-seed githubnext/gh-aw-cao`), checks patch formatting, pins actions by SHA, and uses artifact uploads for review/deployment flows.
- **Limitations:** no repository-observable signed release provenance, published attestations, or end-user verification procedure was confirmed in the inspected files.
- **Improvement:** add lightweight release provenance documentation or attestation strategy for published artifacts and Pages builds; this reduces integrity-verification ambiguity.

### PW — Produce Well-Secured Software

- **PW.1: Design software to meet security requirements and mitigate risks** — `PARTIAL`
- **Tasks:** `PW.1.1`, `PW.1.2`, `PW.1.3`
- **Evidence:** architecture and safety guidance exist in `README.md`, `docs/execution-and-safety.md`, `docs/control-policy-specification.md`, `docs/deployment-and-governance.md`, and `AGENTS.md`; workflows emphasize fail-closed behavior and narrow permissions.
- **Limitations:** repository contents cannot prove systematic threat modeling or design-review completion for all changes.
- **Improvement:** add a compact security design checklist for new workflow packages and dashboard features; this reduces omission risk during feature design.

- **PW.2: Review and test the software to identify vulnerabilities and verify compliance with requirements** — `OBSERVED`
- **Tasks:** `PW.2.1`, `PW.2.2`, `PW.2.3`
- **Evidence:** `workflow-contracts.yml` runs `npm run check`; dashboard CI runs lint, typecheck, unit, e2e, and performance scenarios; `action-lint.yml` runs `actionlint` and `zizmor`; `svg-contrast-check.yml` and `dashboard-deployed-integration.yml` extend verification breadth.
- **Limitations:** no repository-observable static application security test such as CodeQL was confirmed in the inspected workflow set.
- **Improvement:** consider adding repository-owned code scanning if the codebase threat model justifies it; this would improve earlier detection of implementation flaws.

- **PW.3: Reuse existing, well-secured software when feasible** — `GAP_FOUND`
- **Tasks:** `PW.3.1`, `PW.3.2`
- **Evidence:** root `package.json` and `dashboard/site/package.json` declare external dependencies; the repository contains a Dependabot package workflow (`.github/workflows/dependabot.md`) for fleet operations, but no repository-level `.github/dependabot.yml` was present in `target/.github/`, and `gh api repos/githubnext/gh-aw-cao/contents/.github/dependabot.yml` returned `404`.
- **Limitations:** a different dependency automation mechanism could exist outside repository-visible configuration, but none was evident in the assessed snapshot.
- **Improvement:** **add repository-level Dependabot configuration covering both npm dependency roots**; this reduces exposure time to known-vulnerable transitive and direct dependencies and supports timely update review.

### RV — Respond to Vulnerabilities

- **RV.1: Identify and confirm vulnerabilities on an ongoing basis** — `PARTIAL`
- **Tasks:** `RV.1.1`, `RV.1.2`, `RV.1.3`
- **Evidence:** `SECURITY.md` provides a private reporting channel; some workflows request `security-events: read` and `vulnerability-alerts: read`, showing platform integration awareness.
- **Limitations:** repository review cannot verify alert triage cadence, private advisory handling, SLA targets, or monitoring coverage.
- **Improvement:** document repository-specific expectations for dependency/security alert triage ownership and response timing; this reduces ambiguity during vulnerability intake.

- **RV.2: Assess, prioritize, and remediate vulnerabilities** — `HUMAN_REVIEW_REQUIRED`
- **Tasks:** `RV.2.1`, `RV.2.2`, `RV.2.3`
- **Evidence:** issue-driven maintenance workflows and security reporting guidance exist.
- **Limitations:** remediation prioritization and patch governance are operational processes not provable from repository contents alone.
- **Improvement:** maintain an internal severity-to-remediation SLA and verify it against recent incidents; this reduces inconsistent response decisions.

- **RV.3: Analyze root causes and improve future practices** — `HUMAN_REVIEW_REQUIRED`
- **Tasks:** `RV.3.1`, `RV.3.2`
- **Evidence:** the repository has several self-care and investigation workflows that suggest a culture of continuous improvement.
- **Limitations:** no repository-only evidence can confirm formal root-cause analysis after security incidents.
- **Improvement:** standardize post-incident learning capture for security-relevant defects; this reduces repeat classes of failure.

## Prioritized improvement backlog

1. **Add repository-level Dependabot configuration for both npm dependency roots**
- **Priority:** High
- **SSDF provenance:** `PW.3.1`, `PW.3.2`; also supports `RV.1.1`
- **Evidence:** `package.json` and `dashboard/site/package.json` exist; `.github/dependabot.yml` was absent from the target snapshot; API read for `.github/dependabot.yml` returned `404`.
- **Risk rationale:** without repository-visible automated update scheduling, vulnerable direct or transitive dependencies may remain outdated longer, especially in a repo with multiple npm dependency roots and CI-critical toolchains.
- **Owner surface:** repository maintainers / security-conscious build owners.
- **Dependencies:** choose update cadence, assignees/reviewers, and grouping strategy; confirm whether GitHub-native Dependabot is the intended mechanism.
- **Acceptance checks:**
- `.github/dependabot.yml` exists in the repository root;
- it includes at least the `/` and `/dashboard/site` npm ecosystems;
- update schedule is defined;
- maintainers can point to at least one subsequent Dependabot PR or dashboard entry showing the automation is active.
- Agent prompt

Add a repository-level `.github/dependabot.yml` for `githubnext/gh-aw-cao` that enables GitHub Dependabot version updates for both npm dependency roots: the repository root (`/`) and `dashboard/site`. Use a conservative weekly schedule, keep the file minimal and readable, and avoid changing any unrelated files. Include sensible labels if the repository already uses a dependency-maintenance label pattern; otherwise omit labels. After drafting the file, summarize why it improves NIST SSDF PW.3 / RV.1 coverage and list the exact acceptance checks.

## Strengths worth preserving

- Published private vulnerability reporting path in `SECURITY.md`.
- `CODEOWNERS` ownership routing for the repository.
- Strong CI breadth across root and dashboard surfaces, including linting, typechecking, unit/integration/e2e/performance coverage.
- Consistent use of pinned action SHAs in inspected workflows.
- Frequent use of `persist-credentials: false` and explicit workflow/job permissions.
- Deterministic workflow compilation and lockfile discipline for workflow sources.

## Human-review questions

- Are branch protections and required reviewers enforced for workflow, policy, and package-source files?
- Is repository dependency update automation intentionally handled outside `.github/dependabot.yml`, and if so, is it equivalent in coverage and timeliness?
- Are release artifacts, Pages deployments, or generated workflow locks covered by provenance or attestation controls outside this repository snapshot?
- Is code scanning intentionally omitted, or is it configured elsewhere and not visible in the checked-out snapshot?

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34982556248) · pi · gpt54 · 60.3 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 reviewing package.json and dashboard/site/package.json, then inspect the existing .github workflow guidance for dependency automation. Add the repository-level .github/dependabot.yml covering npm at / and /dashboard/site with a defined schedule. Done means the configuration exists, is valid, and a subsequent Dependabot update PR or dashboard entry confirms it is active.

Written by the indexing model from the issue text.