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

This advisory review found strong repository-visible secure-development controls, but one high-confidence improvement remains: add a repository security policy so reporters and maintainers have a canonical intake and disclosure path. Today the repository shows extensive pinned CI, scoped permissions, and review-mode safety controls, but no `SECURITY.md` or equivalent repository-visible disclosure instructions were found.

**Action:** Security or repository maintainers should add and publish a `SECURITY.md` for `githubnext/gh-aw-cao`; acceptance is a merged policy file at the repository root or `.github/SECURITY.md` that explains how to report vulnerabilities, supported versions or support expectations, and the maintainer response path.

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

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

## Scope, assumptions, and limitations

- Scope: repository-visible evidence in the provided `target/` snapshot and bounded GitHub-readable metadata only.
- Assessed against the current final SSDF publication verified from official NIST pages on `2026-09-14`.
- No newer final SSDF revision was identified from the official project page during this run; drafts, if any, were treated as non-final and not scored.
- The `gh` issue-search/read path was unreliable during this run (`HTTP 502: resource labeling failed`), so existing open guidance issues could not be verified through GitHub API responses. Treat deduplication confidence as limited.
- Repository-level evidence cannot establish organization-wide training, staffing, incident handling, environment isolation, deployment governance, or enterprise conformance. Those items are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED` where appropriate.
- No private alerts, secret-scanning results, internal tickets, or confidential operational records were inspected.

## PO / PS / PW / RV practice matrix

### PO — Prepare the Organization

- **PO.1 / PO.1.1–PO.1.3 — Define and document security requirements for software development**
- Status: `PARTIAL`
- Evidence: `target/docs/execution-and-safety.md` documents role boundaries, fail-closed behavior, standard control envelope, and worker/orchestrator invariants; `target/software-development-practices/README.md` states outputs are advisory and bounded; `target/.github/workflows/cao.json` constrains allowed owners/repositories and package modes.
- Limitations: repository evidence shows technical guardrails, but not the full organizational policy set, stakeholder approvals, or external requirement mapping.
- Improvement: map these repository controls to an explicit secure-development policy index or security policy entry point; this reduces ambiguity when maintainers need to interpret or extend controls.

- **PO.2 / PO.2.1–PO.2.3 — Implement roles and responsibilities**
- Status: `PARTIAL`
- Evidence: `target/docs/execution-and-safety.md` defines CAO admission runtime, shared control, orchestrator, and worker responsibilities and disallowed authority.
- Limitations: repository does not show staff assignment, training completion, or review-accountability processes.
- Improvement: link named maintainer/reviewer responsibility surfaces from repository policy docs; this reduces handoff and decision ambiguity.

- **PO.3 / PO.3.1–PO.3.3 — Implement supporting tooling and workflows**
- Status: `OBSERVED`
- Evidence: `target/.github/workflows/workflow-contracts.yml` runs `npm run check`; `target/.github/workflows/cid.yml` runs typecheck, lint, unit, Playwright, and performance scenarios; `target/.github/workflows/action-lint.yml` runs `actionlint` and `zizmor`; `target/package.json` defines compile, typecheck, test, load, SVG, and docs validation scripts.
- Limitations: repository evidence cannot establish the completeness of external environment hardening or runner administration.
- Improvement: preserve pinned and multi-layer validation as the baseline because it reduces regression and workflow-misconfiguration risk.

### PS — Protect the Software

- **PS.1 / PS.1.1–PS.1.2 — Protect code from unauthorized access and tampering**
- Status: `PARTIAL`
- Evidence: broad use of `persist-credentials: false` in workflow checkouts; pinned third-party actions by commit in `workflow-contracts.yml`, `cid.yml`, `docs.yml`, and `action-lint.yml`; read-only defaults and scoped job permissions are declared in multiple workflows.
- Limitations: branch protection, environment protection rules, secret policies, and repository access settings were not accessible in reliable metadata during this run.
- Improvement: publish repository-visible security reporting and maintenance policy so external reporters and contributors know the trusted intake path; this reduces disclosure mishandling risk.

- **PS.2 / PS.2.1–PS.2.2 — Protect all forms of code and prevent unauthorized changes**
- Status: `PARTIAL`
- Evidence: `target/.github/workflows/action-lint.yml` runs `actionlint` and `zizmor`; `target/.github/actions/setup-gh-aw/action.yml` pins `github/gh-aw-actions/setup-cli` by commit; `target/package.json` enforces deterministic `gh aw compile` with a fixed schedule seed.
- Limitations: no repository-visible artifact signing, release provenance, or branch-rule evidence was inspected.
- Improvement: document release and change-integrity expectations in maintainers’ security guidance; this reduces inconsistent handling of sensitive changes.

- **PS.3 / PS.3.1 — Archive and protect each software release**
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: `target/.github/workflows/release.md` validates package state before preparing a draft release and limits the agent write to updating release description text.
- Limitations: repository evidence does not prove archival retention, provenance guarantees, or downstream distribution protections.
- Improvement: confirm with release owners whether archival/provenance controls outside the repository satisfy SSDF expectations.

### PW — Produce Well-Secured Software

- **PW.1 / PW.1.1–PW.1.3 — Use well-secured software development practices**
- Status: `OBSERVED`
- Evidence: `target/.github/workflows/workflow-contracts.yml` runs full validation; `target/.github/workflows/cid.yml` covers lint, typecheck, tests, E2E, and performance; `target/docs/execution-and-safety.md` requires fail-closed behavior and prohibits authority widening.
- Limitations: secure coding training and human review quality are outside repository-observable scope.
- Improvement: preserve the existing layered checks because they reduce the chance of insecure workflow and application changes reaching default branches.

- **PW.2 / PW.2.1–PW.2.3 — Review and analyze the software to identify vulnerabilities and verify requirements**
- Status: `PARTIAL`
- Evidence: `target/.github/workflows/action-lint.yml` statically analyzes workflow definitions; CI runs unit/integration/load/docs/SVG checks; worker packages include explicit compliance and security-oriented workflows.
- Limitations: no repository-visible CodeQL workflow or repository security-policy file was found; vulnerability-alert and security-event read permissions exist in the SSDF workflow definition, but actual scanning configuration was not evidenced from the target snapshot.
- Improvement: add a visible security policy first; separately, maintainers should decide whether code scanning coverage is intentionally handled elsewhere.

- **PW.4 / PW.4.1–PW.4.4 — Reuse existing, well-secured software and manage dependencies**
- Status: `PARTIAL`
- Evidence: GitHub Actions dependencies are pinned by commit across sampled workflows; `target/package.json` specifies direct dependencies and overrides `undici`; `target/.github/actions/setup-gh-aw/action.yml` resolves a specific declared CLI version from policy.
- Limitations: no repository-visible Dependabot configuration file or dependency review workflow was found in the checked snapshot, though package content indicates a dedicated dependabot package exists.
- Improvement: ensure dependency update policy remains repository-visible and discoverable to maintainers; this reduces stale-dependency handling risk.

- **PW.6 / PW.6.1–PW.6.3 — Configure the build process to improve executable security**
- Status: `PARTIAL`
- Evidence: CI validates with deterministic compile seed (`target/package.json`), read-only permissions are common, and `target/docs/execution-and-safety.md` states AI agent jobs do not receive Pages deployment permission while conventional jobs own `pages: write` and `id-token: write`.
- Limitations: repository-observable evidence does not prove hermetic builds, provenance attestations, or complete isolation of every build environment.
- Improvement: consider documenting which release/build integrity controls are intentionally out-of-repo versus in-repo; this reduces review uncertainty.

### RV — Respond to Vulnerabilities

- **RV.1 / RV.1.1–RV.1.3 — Identify and confirm vulnerabilities on an ongoing basis**
- Status: `PARTIAL`
- Evidence: the SSDF worker and related security/compliance packages request `security-events: read` and `vulnerability-alerts: read`; `action-lint.yml` creates durable reporting for workflow lint failures on `main`.
- Limitations: repository evidence does not show the public intake path for external vulnerability reports, triage SLAs, or private alert operations.
- Improvement: publish a repository security policy with reporting guidance and support expectations; this reduces delays and misrouting for externally discovered vulnerabilities.

- **RV.2 / RV.2.1–RV.2.3 — Assess, prioritize, and remediate vulnerabilities**
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: issue-based follow-up patterns exist for workflow lint and package guidance; repository contains operational observability and governance documentation.
- Limitations: remediation SLAs, ownership queues, severity models, and out-of-band coordination are not repository-observable.
- Improvement: align `SECURITY.md` with the actual triage owner and process to reduce uncertainty in vulnerability handling.

- **RV.3 / RV.3.1–RV.3.2 — Analyze root causes and improve processes**
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: ADRs, control-plane documentation, and package-maintained guidance workflows show a pattern of documented improvement decisions.
- Limitations: repository evidence cannot prove post-incident root-cause review practices or lessons-learned loops for vulnerabilities.
- Improvement: ask maintainers whether vulnerability retrospectives are captured in ADRs, issues, or private incident records.

## Prioritized improvement backlog

1. **Add a repository security policy (`SECURITY.md`) and enable GitHub Security Policy visibility**
- Priority: `P1`
- Status: `GAP_FOUND`
- Primary SSDF mapping: `RV.1.1`, `RV.1.2`, `RV.2.1`, `PS.1.1`
- Evidence: no `SECURITY.md` or `.github/SECURITY.md` was found in the checked `target/` snapshot (`find target -path '*/SECURITY.md'` returned none); no repository-visible alternative intake document was identified in sampled root and docs files.
- Risk rationale: without a canonical public intake path, vulnerability reporters may disclose issues through the wrong channel or omit critical information, increasing response delay and disclosure-handling risk.
- Owner surface: repository security maintainers / core maintainers.
- Dependencies: confirm who receives reports, what channels are supported, and whether support-version guidance is meaningful for this repository.
- Acceptance checks:
- a `SECURITY.md` exists at the repository root or `.github/SECURITY.md`;
- it names the supported reporting channel(s) and what reporters should include;
- it states support/version expectations or explicitly says how the project handles version support;
- it avoids secrets and private operational details;
- repository settings expose the security policy to users if supported.
- Suggested content scope: concise vulnerability reporting instructions, expected acknowledgement window, supported disclosure path, and links to any broader organization policy.
- Safe delegation: yes.

Agent prompt

Add a concise `SECURITY.md` for this repository. Use repository-observable context only. The file should:

- state that security reports must not be filed publicly;
- provide the approved reporting channel or, if the repository relies on an organization-wide policy, link to that policy clearly;
- explain what information reporters should include;
- state support/version expectations appropriate for this repository, or explicitly explain that the project evaluates reports against the current default branch and active maintained release line(s);
- avoid promises the repository cannot keep and avoid exposing private operational details;
- fit the repository’s existing documentation tone.

Acceptance check: a new `SECURITY.md` is present at the repository root or `.github/SECURITY.md`, is short and scannable, and gives maintainers and reporters an unambiguous vulnerability disclosure path.

## Strengths worth preserving

- Extensive workflow pinning by commit reduces supply-chain drift in CI.
- Repeated use of `persist-credentials: false` limits credential exposure in automation.
- The repository documents explicit fail-closed control-plane invariants and authority boundaries in `docs/execution-and-safety.md`.
- CI coverage is broad and layered, including type checking, unit/integration/load testing, dashboard E2E, performance scenarios, docs builds, and workflow linting.
- The Dev Practices package already frames guidance as advisory and non-binding, which appropriately limits unsupported claims.

## Human-review questions

- Is vulnerability intake intentionally handled by a broader GitHub or GitHub Next policy that should be linked here?
- Are branch protection, rulesets, and release provenance controls configured in repository settings but simply not visible in the checked snapshot?
- Is dependency update governance intentionally centralized through a package-generated workflow that was not directly visible as a repository-level configuration file in this snapshot?
- Should a future iteration add repository-visible documentation describing code-scanning ownership if scanning is configured outside this repository?

### Control Plane

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

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34795120987) · pi · gpt54 · 33.8 AIC · ⊞ 9.3K · [◷](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, 1:17 AM UTC

Review the repository's existing root and docs guidance, including target/docs/execution-and-safety.md and target/software-development-practices/README.md, then confirm the maintainer reporting and response path. Add SECURITY.md at the repository root or .github/SECURITY.md with vulnerability reporting instructions, supported versions or support expectations, and the response path; done means the policy is merged and repository-visible.

Written by the indexing model from the issue text.