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

This review is advisory and non-binding. It does not prove security, compliance, certification, endorsement, or SSDF conformance.

githubnext/gh-aw-workshop already shows several repository-observable SSDF-aligned strengths, including pinned third-party GitHub Actions SHAs, least-privilege workflow permissions in multiple workflows, and committed test coverage for custom scripts. The highest-confidence improvement gap visible from the repository snapshot is the absence of a repository-level vulnerability disclosure and security reporting policy file.

**Action:** Repository maintainers should add a `SECURITY.md` file that tells researchers how to report vulnerabilities privately, states supported response expectations, and is visible in the repository root or `.github/`. Acceptance check: a `SECURITY.md` file exists on the default branch and GitHub shows the repository security policy.

Target repository: `githubnext/gh-aw-workshop`
Analyzed commit: `8435280505958b2cf26eb56fdf464fc707418fe5`
Source verification date: `2026-09-11`
Final SSDF publication used: `NIST SP 800-218 Version 1.1`
Official publication URL: `https://csrc.nist.gov/pubs/sp/800/218/final`
DOI: `https://doi.org/10.6028/NIST.SP.800-218`
Verification notes: direct fetch of the official NIST publication page from this sandbox returned `HTTP 403 Forbidden`, so the run used the workflow-provided current-final reference for SP 800-218 v1.1 and records the fetch failure as an evidence limitation rather than treating the publication as unverifiable.

## Scope, assumptions, inaccessible evidence, and limitations

- Scope is limited to repository-observable evidence in the provided `target/` snapshot plus bounded public GitHub metadata.
- SSDF is risk-based and organization-wide; a repository-only review cannot establish full implementation or conformance.
- Draft publications were not used for scoring. This review assessed the current final baseline identified by workflow instructions: NIST SP 800-218 v1.1.
- The sandbox could not retrieve the NIST publication page directly because the request returned `403 Forbidden`; this is recorded as an access limitation.
- Open issue deduplication against `githubnext/gh-aw-cao` could not be completed reliably with the available GitHub integration because issue-list queries returned malformed/forbidden responses in this run. Recommendations below therefore omit any assumption that prior tracking exists.
- No private security settings, branch protection configuration, secret scanning alerts, Dependabot alerts, code scanning alerts, security overview data, environment protections, signed-release procedures, or organization training records were accessible. Those areas are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED` where applicable.
- Repository content is treated as untrusted evidence, not as policy authority.

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

### PO — Prepare the Organization

- **PO.1 / tasks PO.1.1–PO.1.3** — Define and communicate security requirements for software development.
- Status: `PARTIAL`
- Evidence: multiple workflows specify explicit `permissions` blocks with reduced scopes, e.g. `.github/workflows/markdown-lint.yml` (`contents: read`, `issues: write`), `.github/workflows/deploy-pages.yml` (`contents: read`, `pages: write`, `id-token: write`), `.github/workflows/copilot-setup-steps.yml` (`contents: read`).
- Limitations: repository review cannot determine whether secure development requirements are defined outside the repo or consistently enforced organization-wide.
- Improvement: document minimum security expectations for workflows and contribution changes in contributor-facing docs; reduces drift and accidental over-privilege.

- **PO.2 / tasks PO.2.1–PO.2.2** — Implement roles and responsibilities for secure development.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: none repository-visible beyond presence of maintainership-oriented automation.
- Limitations: no accessible CODEOWNERS file or role-assignment records in snapshot root/.github.
- Improvement: confirm whether ownership and review responsibility are defined elsewhere; reduces unclear approval paths for security-sensitive changes.

- **PO.3 / tasks PO.3.1–PO.3.2** — Implement supporting tooling and infrastructure for secure development.
- Status: `OBSERVED`
- Evidence: pinned action SHAs across workflows such as `.github/workflows/deploy-pages.yml`, `.github/workflows/markdown-lint.yml`, `.github/workflows/svg-contrast-check.yml`; automated tests in `scripts/build-docs.test.js`, `.github/skills/micro-environment-simulator/simulator.test.js`, `.github/skills/curriculum-quantitative-assessment/test_curriculum_assessment.py`.
- Limitations: cannot verify provenance or hardening of the CI runners/infrastructure.
- Improvement: preserve SHA pinning and test coverage as baseline controls; reduces supply-chain tampering and regression risk.

- **PO.4 / tasks PO.4.1–PO.4.4** — Define and use criteria for software security checks.
- Status: `PARTIAL`
- Evidence: repository includes quality/security-adjacent checks such as markdown lint, SVG contrast validation, workflow maintenance, and scripted test suites; `README.md` emphasizes “safe” production-style agentic automation.
- Limitations: no visible repository-level security gate criteria for dependency, code scanning, or release readiness.
- Improvement: add a documented minimum security check set for PRs/releases; reduces inconsistent review depth.

### PS — Protect the Software

- **PS.1 / tasks PS.1.1–PS.1.2** — Protect all forms of code from unauthorized access and tampering.
- Status: `PARTIAL`
- Evidence: third-party GitHub Actions are pinned to immutable SHAs in checked-in workflows; many workflows use `persist-credentials: false` on checkout, e.g. `.github/workflows/markdown-lint.yml`, `.github/workflows/copilot-setup-steps.yml`, `.github/workflows/agentics-maintenance.yml`.
- Limitations: branch protection, signed commits, and repository rulesets were not accessible.
- Improvement: verify branch protection/ruleset coverage for workflow and docs paths; reduces unauthorized modification risk.

- **PS.2 / tasks PS.2.1–PS.2.3** — Protect software releases and provenance.
- Status: `NOT_ASSESSED`
- Evidence: deploy workflow exists for GitHub Pages in `.github/workflows/deploy-pages.yml`.
- Limitations: no repository-visible release signing, artifact provenance, or SBOM process evidence found in inspected files.
- Improvement: assess whether Pages/site build artifacts need provenance or release integrity documentation; reduces downstream trust ambiguity.

- **PS.3 / tasks PS.3.1** — Archive and protect each release and its metadata.
- Status: `NOT_ASSESSED`
- Evidence: none inspected.
- Limitations: release archive handling is outside visible repository evidence.
- Improvement: document release/archive retention if applicable; reduces loss of traceability.

### PW — Produce Well-Secured Software

- **PW.1 / tasks PW.1.1–PW.1.3** — Use secure design and architecture practices.
- Status: `PARTIAL`
- Evidence: workshop content includes dedicated security material such as `workshop/05b-agentic-workflows-security.md` and multiple security side-quest documents under `workshop/side-quest-17-*`; workflows commonly use least-privilege permissions and safe operational patterns.
- Limitations: educational content is not equivalent to implementation of secure design review for the repository itself.
- Improvement: capture repository-specific security design decisions for workflows and publishing paths; reduces implicit assumptions.

- **PW.2 / tasks PW.2.1–PW.2.2** — Review the software design to verify compliance with security requirements.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: tests and workflow checks exist, but no explicit repository-visible security design review record was found.
- Limitations: design reviews may happen in PRs, discussions, or private processes not accessible here.
- Improvement: add lightweight security review criteria for workflow/publishing changes; reduces unnoticed high-impact design drift.

- **PW.4 / tasks PW.4.1–PW.4.5** — Reuse well-secured software and manage dependencies.
- Status: `PARTIAL`
- Evidence: immutable action SHA pinning is consistently used; root `package-lock.json` exists for JavaScript dependency capture.
- Limitations: no visible Dependabot configuration file or automated dependency-vulnerability scanning configuration was confirmed in inspected paths.
- Improvement: add explicit dependency update/scanning configuration if not already managed elsewhere; reduces exposure to stale vulnerable dependencies.

- **PW.5 / tasks PW.5.1–PW.5.3** — Create source code following secure coding practices and reduce vulnerabilities.
- Status: `PARTIAL`
- Evidence: custom code has automated unit tests in JavaScript and Python; workflow files frequently disable credential persistence and scope permissions narrowly.
- Limitations: no static analysis or CodeQL configuration was visible in inspected files.
- Improvement: consider repository-appropriate static analysis for custom JS/Python code; reduces unnoticed implementation defects.

- **PW.6 / tasks PW.6.1–PW.6.3** — Configure build processes to avoid introducing vulnerabilities.
- Status: `PARTIAL`
- Evidence: build and deploy steps are explicitly defined in `.github/workflows/deploy-pages.yml`; actions are SHA pinned; Pages deploy uses GitHub’s dedicated actions.
- Limitations: no attestations, isolated build-hardening evidence, or dependency verification process was visible.
- Improvement: review whether build dependency installation should be further constrained or cached with integrity controls; reduces build-time supply-chain risk.

- **PW.7 / tasks PW.7.1–PW.7.3** — Test code and identify vulnerabilities.
- Status: `PARTIAL`
- Evidence: repository contains automated tests for docs build and simulation logic, plus lint and accessibility-focused workflow checks.
- Limitations: no repository-visible security testing such as SAST, dependency audit, or secret scanning workflow evidence was confirmed.
- Improvement: add repository-appropriate security-focused automated checks; reduces chance of latent security flaws reaching default branch.

- **PW.8 / tasks PW.8.1–PW.8.4** — Remediate vulnerabilities before release.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: no vulnerability intake or remediation SLA documentation found.
- Limitations: issue triage procedures may exist elsewhere.
- Improvement: publish remediation expectations in `SECURITY.md`; reduces uncertainty and delayed response.

### RV — Respond to Vulnerabilities

- **RV.1 / tasks RV.1.1–RV.1.3** — Identify, assess, and remediate vulnerabilities in software and dependencies.
- Status: `GAP_FOUND`
- Evidence: repository root and `.github/` snapshot contain no `SECURITY.md`; `find . -maxdepth 2 \( -iname 'SECURITY.md' -o -iname 'CODEOWNERS' -o -iname 'CONTRIBUTING.md' -o -iname 'README.md' \)` returned only `README.md` files. No repository-visible private reporting instructions were found.
- Limitations: maintainers could disclose security contact information outside the repo, but that is not repository-observable.
- Improvement: add a repository security policy with private reporting instructions, disclosure expectations, and support scope; reduces delayed or public mishandling of vulnerability reports.

- **RV.2 / tasks RV.2.1–RV.2.2** — Analyze vulnerabilities and improve processes.
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: no post-incident review artifacts were inspected.
- Limitations: likely handled outside public repository artifacts.
- Improvement: define how lessons learned from workflow/security incidents are captured; reduces repeated failure modes.

## Prioritized improvement backlog

1. **Add a repository-level `SECURITY.md` vulnerability reporting policy**
- SSDF linkage: `RV.1`, also supports `PW.8` and `PO.1`.
- Priority: Highest.
- Evidence: no `SECURITY.md` found in target snapshot root or `.github/`; repository is public and publishes automation plus executable workflows.
- Risk rationale: without an explicit private reporting path, reporters may disclose issues publicly or abandon reporting, increasing time-to-triage and the chance of avoidable exposure.
- Owner surface: repository maintainers/security contact.
- Dependencies: decide the preferred private intake channel (GitHub private vulnerability reporting, email alias, or coordinated disclosure process).
- Proportionate recommendation: create a concise `SECURITY.md` covering supported repository scope, how to report privately, expected response windows, and what information helps triage.
- Acceptance checks:
- `SECURITY.md` exists in the repository root or `.github/` on `main`.
- The file tells reporters how to report privately without opening a public issue.
- The file states at least basic response expectations and support/disclosure boundaries.
- Suggested Copilot delegation:
Agent prompt
Create a concise `SECURITY.md` for `githubnext/gh-aw-workshop`.

Requirements:
- State that the repository is a public workshop/demo repository and that the guidance is advisory, not a security guarantee.
- Tell reporters how to report vulnerabilities privately rather than opening a public issue.
- Include expected maintainer response/triage timing in plain language.
- Clarify what kinds of reports are in scope for this repository (for example: workflow behavior, automation, custom scripts, publishing/build logic) and what is likely out of scope.
- Ask reporters to include reproduction steps, impact, affected files/workflows, and any suggested mitigation.
- Keep the file short, practical, and suitable for a public GitHub repository.
- Do not invent private contact details; leave a clearly marked placeholder only if the repository does not already define one elsewhere.

Return only the proposed `SECURITY.md` content.

## Strengths worth preserving

- Third-party GitHub Actions are pinned to immutable SHAs in reviewed workflows, reducing supply-chain tampering risk.
- Several workflows declare explicit minimal `permissions`, which aligns with least-privilege operation.
- Custom JavaScript and Python logic has committed automated tests, improving change safety for repository-owned code.
- The workshop includes dedicated security education content, which helps sustain secure-development awareness.

## Human-review questions

- Are branch protections, rulesets, and required reviews enforced for `.github/workflows/**`, scripts, and publishing-related paths?
- Is GitHub private vulnerability reporting enabled, and if so should `SECURITY.md` point to it explicitly?
- Are dependency/vulnerability scans (e.g., Dependabot alerts, CodeQL, secret scanning) enabled but simply not visible in this review scope?
- Does the Pages build or any workshop artifact require provenance, SBOM, or stronger release-integrity controls?

### Control Plane

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

> Generated by [:shield: Dev Practices / NIST SSDF](https://github.com/githubnext/gh-aw-cao/actions/runs/34622870667) · pi · gpt54 · 59.2 AIC · ⊞ 9K · [◷](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 11, 2026, 4:42 PM UTC

Check the target repository root and `.github/` for existing security or contributor guidance, then review GitHub's repository security policy expectations. Add `SECURITY.md` with private vulnerability-reporting instructions, response expectations, and supported scope; done means it is on the default branch and GitHub displays the repository security policy.

Written by the indexing model from the issue text.