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

The repository already demonstrates several SSDF-aligned controls—pinned third-party actions in CI, release-time SBOM generation, a documented security reporting path, and broad automated testing—but it does not show any repository-level static application security testing or dependency-review gate for pull requests. That leaves a visible gap in early vulnerability discovery for code and dependency changes under NIST SP 800-218 SSDF v1.1, especially for `PW.7` and related `RV` readiness tasks.

**Action:** Security-minded maintainers should add a PR-time code and dependency analysis workflow, with passing checks visible on pull requests; accept when a pull request that introduces an unsafe code pattern or risky dependency change produces a failing or review-blocking security signal.

> **Advisory only:** This issue is non-binding guidance based on repository-observable evidence. It does **not** prove security, compliance, certification, endorsement, or SSDF conformance.

`target=github/gh-aw-mcpg`
`commit=e96f97b7676b01e14a501729341c0e0f4a0c3e4b`

## Repository and source verification

- Target repository: `github/gh-aw-mcpg`
- Analyzed commit: `e96f97b7676b01e14a501729341c0e0f4a0c3e4b`
- Verification date: 2026-09-14
- SSDF final publication used: NIST SP 800-218, **SSDF Version 1.1**
- Official project page: https://csrc.nist.gov/projects/ssdf
- Official final publication page: https://csrc.nist.gov/pubs/sp/800/218/final
- DOI: https://doi.org/10.6028/NIST.SP.800-218
- Baseline change note: NIST also lists SP 800-218A as a finalized **community profile** for generative AI and dual-use foundation models. It augments SP 800-218 but does not replace the base SSDF final publication for this repository-level review.

Machine-readable marker:
`[nist-ssdf-assessed:repo=github/gh-aw-mcpg;commit=e96f97b7676b01e14a501729341c0e0f4a0c3e4b;publication=NIST-SP-800-218-v1.1]`

## Scope, assumptions, inaccessible evidence, and limitations

- Scope is limited to the checked-out `target/` repository snapshot and bounded public GitHub metadata available to this worker.
- This is a repository-observable review only; organization-wide policies, training, staffing, production operations, incident handling, signing key custody, branch protection rules, Dependabot alerts, code scanning alerts, and private security tooling are outside direct verification unless surfaced in-repo.
- Open-issue deduplication and related-issue discovery in `githubnext/gh-aw-cao` could not be completed with `gh issue list` in this environment because the CLI returned `malformed version:` before producing results. Findings below therefore avoid claiming duplicate coverage.
- Draft or non-final SSDF material was not used for scoring. SP 800-218A is noted only as context, not as a scored baseline.
- Status values reflect evidence confidence, not conformance.

## PO / PS / PW / RV practice matrix

### PO — Prepare the Organization

- **PO.1 / PO.2 / PO.3 / PO.4 / PO.5 / PO.6 / PO.7** — Define security requirements, roles, implementation paths, tooling, and training.
- **Status:** `HUMAN_REVIEW_REQUIRED`
- **Evidence:** `CONTRIBUTING.md`, `AGENTS.md`, `README.md`, `Makefile`, and multiple CI workflows show documented build/test expectations and secure-operation concepts, but do not establish org-wide secure SDLC policy, role accountability, training, or enterprise governance.
- **Limitations:** Repository files cannot prove organizational policy adoption or personnel readiness.
- **Improvement:** Link this repository to an explicit secure-development policy or policy excerpt covering release, code review, and vulnerability-handling expectations. Reduces ambiguity in how local engineering practices map to the broader SDLC.

### PS — Protect the Software

- **PS.1.1 / PS.2.1 / PS.2.2** — Protect code and artifacts from unauthorized access/tampering; secure secrets and build environments.
- **Status:** `PARTIAL`
- **Evidence:** `.github/workflows/ci.yml` uses read-only `contents: read` in most jobs; `release.md` narrows some permissions and disables Go build cache for release security; actions are SHA-pinned in checked-in workflows; `SECURITY.md` directs private vulnerability reporting; release workflow generates and audits SBOM artifacts.
- **Limitations:** Branch protections, environment protections, artifact retention policies, attestations consumption, and secret-scanning coverage are not fully observable from the snapshot.
- **Improvement:** Publish a short repository security-controls document that maps build permissions, signing/attestation use, and artifact retention to expected trust boundaries. Reduces operational drift and reviewer uncertainty.

- **PS.3.1 / PS.3.2** — Archive provenance and integrity evidence for releases.
- **Status:** `OBSERVED`
- **Evidence:** `target/.github/workflows/release.md` grants `id-token: write` and `attestations: write`, generates SPDX and CycloneDX SBOMs, audits them for obvious secret strings, uploads them as artifacts, and attaches them to releases.
- **Limitations:** The review cannot confirm downstream verification or policy enforcement on consumers.
- **Improvement:** Document how release consumers should verify attestations/SBOMs. Reduces misuse of already-produced supply-chain evidence.

### PW — Produce Well-Secured Software

- **PW.1.1 / PW.1.2 / PW.1.3** — Use secure design and coding criteria.
- **Status:** `PARTIAL`
- **Evidence:** `README.md` and `AGENTS.md` describe guard policies, DIFC enforcement, restricted write sinks, secret redaction utilities, and secure defaults such as fail-fast validation and disabled `$ENV` access in jq utilities.
- **Limitations:** Repository documentation alone does not prove threat modeling or systematic secure-design review.
- **Improvement:** Capture a lightweight threat-model or security-architecture note for the gateway, proxy, and guard boundary. Reduces risk of unsafe design changes.

- **PW.4.1 / PW.4.2 / PW.4.3** — Review human-readable code and analyze it for vulnerabilities before release.
- **Status:** `PARTIAL`
- **Evidence:** `ci.yml` runs unit, integration, race, and Rust tests; `.golangci.yml` enables style/test linters; `CONTRIBUTING.md` requires tests and linting before PRs.
- **Limitations:** No repository-observable required review policy or dedicated security-review step is visible.
- **Improvement:** Require a documented security-sensitive review path for auth, guard, proxy, and release workflow changes. Reduces risk of high-impact logic regressions.

- **PW.7.1 / PW.7.2 / PW.7.3** — Use automated tools or services to detect vulnerabilities in code and dependencies and triage findings.
- **Status:** `GAP_FOUND`
- **Evidence:**
- `target/.golangci.yml` explicitly disables `gosec` and notes it can be enabled separately.
- The checked-in workflow set reviewed from `target/.github/workflows/` shows no CodeQL, dependency-review, Scorecards, `govulncheck`, `gosec`, `trivy`, `grype`, or equivalent PR security-analysis workflow.
- `target/.github/dependabot.yml` updates only the `github-actions` ecosystem weekly; no repository-observable dependency-review gate is present for pull requests.
- **Limitations:** Private GitHub Advanced Security configuration or external scanners might exist, but they are not evidenced here.
- **Improvement:** Add a pull-request security analysis workflow that covers both source and dependency changes, such as CodeQL plus dependency review for GitHub-hosted scanning, or an equivalent documented combination like `govulncheck`/`gosec` plus dependency diff gating. This reduces the chance that auth, proxy, workflow, or dependency regressions ship without automated security feedback.

### RV — Respond to Vulnerabilities

- **RV.1.1 / RV.1.2 / RV.1.3** — Identify, report, triage, and track vulnerabilities.
- **Status:** `PARTIAL`
- **Evidence:** `SECURITY.md` provides a private reporting path through coordinated disclosure; release process includes SBOM generation that can support later triage; Dependabot configuration exists for GitHub Actions updates.
- **Limitations:** No repository-observable SLA, severity taxonomy, or remediation workflow is documented; no code/dependency scanning feed is evident in-repo.
- **Improvement:** Document how reported vulnerabilities are triaged and linked to fixes/releases, including how automated findings are reviewed. Reduces response ambiguity.

- **RV.3.1** — Analyze root causes and update practices accordingly.
- **Status:** `HUMAN_REVIEW_REQUIRED`
- **Evidence:** None sufficient in-repo beyond general maintenance workflows.
- **Limitations:** Root-cause analysis is generally organizational and incident-specific.
- **Improvement:** Add a lightweight post-incident template or security-retrospective checklist. Reduces repeat vulnerabilities.

## Prioritized improvement backlog

1. **Add PR-time automated security analysis for code and dependency changes**
- **Priority:** P1
- **Status linkage:** `PW.7.1`, `PW.7.2`, `PW.7.3`, supports `RV.1.x`
- **Why this is first:** This is the clearest repository-observable gap with the highest risk reduction per unit effort. The project contains auth, proxying, guard enforcement, release automation, and container workflows, all of which benefit from continuous security scanning before merge.
- **Evidence:** `.golangci.yml` disables `gosec`; no CodeQL/dependency-review workflow was found; Dependabot coverage is limited to `github-actions` version updates.
- **Risk reduced:** Lowers the chance of merging code or dependency changes with known vulnerability patterns, unsafe API use, or risky dependency diffs.
- **Owner surface:** Security + maintainers of `.github/workflows/`, Go code under `internal/`, and release/build automation.
- **Dependencies:** Decide whether GitHub-native scanning (CodeQL + dependency review) or equivalent self-managed tooling is the preferred path.
- **Acceptance checks:**
- A PR receives automated security analysis on changed code and dependency manifests.
- Findings are visible as required or review-blocking checks before merge.
- The chosen toolchain and triage ownership are documented in-repo.

## Strengths worth preserving

- Actions in CI are commit-pinned, which reduces supply-chain drift from third-party action tags.
- Release automation already produces SPDX and CycloneDX SBOMs and attaches them to releases.
- Release workflow explicitly disables Go build cache during release jobs to reduce cache-poisoning concerns.
- The repository documents a private vulnerability-reporting path in `SECURITY.md`.
- Test coverage is broad across unit, integration, race, and Rust-guard jobs.

## Human-review questions

1. Is GitHub Advanced Security or another external SAST/SCA system already enforced outside the repository, and if so, should that enforcement be documented here?
2. Are branch protection rules requiring review from security-sensitive owners for `internal/auth`, `internal/proxy`, `internal/guard`, and release workflows?
3. Are release attestations currently verified by downstream consumers or internal policy gates, or only generated?
4. Should Dependabot coverage expand beyond `github-actions` to Go and container inputs, or is an alternative dependency-management system authoritative?

Agent prompt

Assign to Copilot and ask it to add a pull-request security-analysis workflow for `github/gh-aw-mcpg` that is proportionate to this repository's Go, Rust-guard, workflow, and container footprint.

Exact prompt:

Implement a PR-time security analysis workflow for this repository that closes the SSDF `PW.7` gap without creating noisy failures. Prefer GitHub-native capabilities when available. At minimum:
1. Add automated analysis for changed code and dependency changes on pull requests.
2. Cover Go source and dependency risk; if CodeQL is enabled, configure it for the repository; otherwise add an equivalent documented combination such as `govulncheck`/`gosec` plus dependency diff gating.
3. Keep permissions least-privilege and pin third-party actions by SHA.
4. Document the workflow, expected findings path, and triage owner in `CONTRIBUTING.md` or a security-focused doc.
5. Ensure the new checks are practical for maintainers and do not silently skip on normal pull requests.
6. Add or update focused tests/docs only where they validate the new workflow behavior.

Acceptance check: a test pull request that introduces a known unsafe pattern or risky dependency change should produce a visible security finding or failing security check before merge.

### 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/34909062054) · pi · gpt54 · 45 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:33 PM UTC

Start by reading the existing files under .github/workflows/, .golangci.yml, and .github/dependabot.yml to understand current checks and dependency coverage. Choose and document a PR-time code and dependency analysis approach covering the repository's Go, Rust, workflow, and container surfaces; done means pull requests receive visible security checks, risky changes produce a failing or blocking signal, and triage ownership is documented.

Written by the indexing model from the issue text.