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

This advisory review found strong repository-visible SSDF practices in `github/gh-aw-mcpg` (pinned Actions, scoped workflow permissions, release-time SBOM generation, documented security reporting, and broad automated tests), but one high-confidence gap remains: no repository-visible automated code/vulnerability analysis step such as `govulncheck` or `gosec` runs in CI.

**Action:** Maintainers should add a CI-enforced Go security scanning job (for example `govulncheck` and/or a tuned `gosec` run) and verify it blocks regressions by failing on newly introduced findings in pull requests.

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

- Target repository: `github/gh-aw-mcpg`
- Analyzed commit: `fa3123ed86d68d8cb636be823d0896f25a948191`
- Source verification date: 2026-09-11
- Final publication version: NIST SP 800-218 Version 1.1 (final)
- 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`

## Scope, assumptions, and limitations

- Scope: repository-observable evidence in the provided `target/` snapshot and bounded public GitHub metadata only.
- This review assesses the current final SSDF publication. The SSDF project page also references `SP 800-218A`, but that is an augmenting community profile for AI and does not replace the final baseline assessed here.
- Missing organization-wide evidence (training, policy execution, incident handling outside the repo, production controls, staff onboarding, private scanners, branch protections, secret-scanning alerts, Dependabot alerts, code scanning alerts, release environment protections, and internal attestations processing) is marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED`, not treated as a repository failure.
- GitHub issue search in the safe-output repository was attempted but the bounded `gh issue list` call failed with `HTTP 502: resource labeling failed`; recommendations below therefore omit any claim that the backlog is fully deduplicated against existing tracking issues.
- Conclusions require human review because SSDF is risk-based and intended to be integrated into an organization's SDLC.

## PO / PS / PW / RV practice matrix

### PO — Prepare the Organization

- **PO.1 / PO.2 / PO.3 / PO.4 / PO.5 — Define security requirements, roles, tooling, policies, and implementation expectations**
- Status: `HUMAN_REVIEW_REQUIRED`
- Evidence: `README.md`, `CONTRIBUTING.md`, `docs/aw-security.md`, and workflow files document security architecture, contribution/testing expectations, and release steps.
- Limitations: Repository content cannot prove organization-wide policy approval, role assignments, training completion, supplier requirements, or enterprise SDLC governance.
- Improvement: Confirm whether these repository documents are mapped to org-level secure development policy and training records; reduces risk of inconsistent or informal practice adoption.

- **PO.3.1 / PO.3.2 — Define and use criteria for software security checks and toolchains**
- Status: `PARTIAL`
- Evidence: `Makefile` and `.github/workflows/ci.yml` run `go vet`, `gofmt`, `golangci-lint`, unit tests, integration tests, Rust guard tests, and race tests; `.golangci.yml` sets `modules-download-mode: readonly`; `go mod verify` runs in CI.
- Limitations: Security-specific static analysis is not enforced; `.golangci.yml` explicitly disables `gosec` and comments that it can be enabled separately.
- Improvement: Add a dedicated security-analysis stage with tuned findings policy; reduces risk that code-level weaknesses or vulnerable dependencies ship without automated review.

### PS — Protect the Software

- **PS.1.1 / PS.2.1 — Protect code and build environments from unauthorized access and tampering**
- Status: `PARTIAL`
- Evidence: Workflow permissions are scoped per job in `.github/workflows/ci.yml` and `.github/workflows/container.yml`; most CI jobs use `contents: read`; release workflow requests stronger permissions only for release tasks; Actions are pinned to full commit SHAs in `ci.yml` and `container.yml`.
- Limitations: Repository snapshot cannot confirm branch protection, required reviewers, environment protection rules, OIDC audience restrictions, or runner hardening.
- Improvement: Human reviewers should verify branch protection and protected release environments align with least privilege; reduces risk of unauthorized code or release changes.

- **PS.3.1 / PS.3.2 — Archive and protect release artifacts and provenance-relevant data**
- Status: `PARTIAL`
- Evidence: `release.md` generates SPDX and CycloneDX SBOMs, uploads them as artifacts, and attaches them to releases; release job requests `attestations: write`; release artifacts and checksums are published.
- Limitations: No repository-visible step was found that actually creates/verifies provenance attestations or signs release artifacts/images.
- Improvement: Evaluate adding release provenance generation/verification if it fits deployment needs; reduces supply-chain tampering risk.

### PW — Produce Well-Secured Software

- **PW.4.1 / PW.4.2 / PW.4.3 — Verify software through automated tests, review, and analysis**
- Status: `PARTIAL`
- Evidence: `ci.yml` runs unit, integration, race, and Rust guard tests; `go mod verify` is enforced; `golangci-lint` runs with selected linters; extensive tests exist under `internal/` and `test/`.
- Limitations: No repository-visible `govulncheck`, `gosec`, CodeQL, or equivalent automated security-analysis workflow was found; `grep` found no `govulncheck` usage and `.golangci.yml` disables `gosec`.
- Improvement: Add automated vulnerability and security-code scanning to CI; reduces risk of exploitable implementation flaws and known-vulnerable packages bypassing general quality gates.

- **PW.8.1 / PW.8.2 — Generate and maintain software release information such as SBOMs**
- Status: `OBSERVED`
- Evidence: `SECURITY.md` states SBOMs are generated on every release; `release.md` includes two `anchore/sbom-action@v0.24.2` steps for SPDX and CycloneDX and attaches outputs to releases.
- Limitations: Repository evidence does not show downstream consumer validation of SBOM accuracy.
- Improvement: Preserve current release-SBOM automation and periodically verify coverage against all shipped artifacts; reduces blind spots in dependency transparency.

### RV — Respond to Vulnerabilities

- **RV.1.1 / RV.1.2 / RV.1.3 — Receive, analyze, and handle vulnerability reports**
- Status: `PARTIAL`
- Evidence: `SECURITY.md` gives a coordinated disclosure email path and instructs reporters not to use public issues.
- Limitations: Repository-only evidence cannot show internal triage SLAs, remediation workflow, customer notification criteria, or post-incident learning loops.
- Improvement: Human reviewers should confirm the documented intake path is backed by triage ownership and measurable response procedures; reduces risk of delayed or inconsistent vulnerability handling.

## Prioritized improvement backlog

1. **Add CI-enforced automated security analysis for Go code and dependencies**
- SSDF linkage: `PO.3.2`, `PW.4.1`, `PW.4.2`, `PW.4.3`
- Priority: High
- Status: `GAP_FOUND`
- Evidence:
- `.github/workflows/ci.yml` runs quality and test jobs but no security-analysis job.
- `.golangci.yml` explicitly disables `gosec` and suggests separate enablement.
- Repository search found no `govulncheck` usage.
- Risk rationale: General linting and tests do not reliably detect insecure coding patterns or known vulnerable modules; this leaves avoidable weaknesses undetected until later lifecycle stages.
- Owner surface: Repository maintainers / release engineering.
- Dependencies: Decide whether to use `govulncheck`, tuned `gosec`, CodeQL, or a layered combination; establish triage criteria for acceptable findings.
- Acceptance checks:
- A pull-request-triggered workflow step runs at least one security-analysis tool against the Go codebase.
- New actionable findings fail CI or are explicitly triaged with documented suppression rationale.
- Tool configuration is checked in and maintained with the repo.
- Recommended implementation options:
- Add `govulncheck ./...` in CI for dependency and reachable-vuln analysis.
- Re-enable `gosec` with repository-tuned exclusions, or add a dedicated `gosec` job outside `golangci-lint`.
- Optionally add CodeQL if organizationally standard, but do not rely on a draft or unstated enterprise control.

Agent prompt
Add repository-visible automated security analysis to `github/gh-aw-mcpg` CI in a proportionate way. Prefer a dedicated workflow job or CI stage that runs `govulncheck ./...` and either a tuned `gosec` run or another checked-in security analyzer appropriate for a Go project. Keep existing lint/test jobs intact. If you enable `gosec`, tune exclusions narrowly and document each suppression. Make the job fail on new actionable findings, update contributing docs so maintainers know how to run the checks locally, and keep workflow permissions least-privilege and Actions pinned. Include tests or validation updates as needed.

## Strengths worth preserving

- Pinned GitHub Actions commit SHAs in core workflows reduce action-supply-chain drift.
- CI includes multiple verification modes: unit, integration, Rust guard, and race testing.
- `go mod verify` and read-only module download mode improve dependency integrity checks.
- Release workflow generates SPDX and CycloneDX SBOMs and publishes them with releases.
- `SECURITY.md` provides a non-public coordinated disclosure path.
- Security architecture is explicitly documented in `docs/aw-security.md`.

## Human-review questions

1. Are branch protection, required checks, and release-environment protections configured to match the least-privilege intent visible in workflow files?
2. Does the organization already run private CodeQL, secret scanning, dependency alert triage, or provenance generation outside the repository, and if so should any evidence be made repository-visible?
3. Is the `attestations: write` permission in the release workflow currently justified by a hidden attestation step elsewhere, or should artifact/image provenance generation be added or the permission reduced?
4. Are vulnerability intake, triage ownership, and remediation SLAs documented outside the repo, and are maintainers trained on them?

### 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/34622809065) · pi · gpt54 · 41.7 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

Start with .github/workflows/ci.yml and .golangci.yml to understand the existing Go checks and disabled gosec configuration. Review CONTRIBUTING.md for local check guidance, then add a pull-request security-analysis stage using the stated tool options while preserving existing jobs and least-privilege permissions. Done means the checked-in configuration runs against the Go code, fails on new actionable findings or records documented suppressions, and has matching contributor guidance.

Written by the indexing model from the issue text.