diff --git a/.github/skills/security-advisory-compat-enforcer/SKILL.md b/.github/skills/security-advisory-compat-enforcer/SKILL.md new file mode 100644 index 00000000000..b9b04515d19 --- /dev/null +++ b/.github/skills/security-advisory-compat-enforcer/SKILL.md @@ -0,0 +1,117 @@ +--- +name: security-advisory-compat-enforcer +description: Review a GitHub security advisory and safely update .github/aw/compat.json with evidence-backed version enforcement. +--- + +# Security Advisory Compatibility Enforcer + +Use this skill to translate a GitHub repository security advisory into the +smallest safe update to `.github/aw/compat.json`. + +## Required inputs + +Record the repository, GHSA identifier, requested enforcement policy, and any +patched version supplied by the user. Treat a user-supplied version as a target +to verify, not as evidence for advisory details. + +## Evidence retrieval + +1. Attempt authenticated retrieval first: + `gh api repos/OWNER/REPO/security-advisories/GHSA-ID`. +2. If authentication is unavailable or access fails, try the public global + advisory endpoint: `gh api advisories/GHSA-ID` (or its equivalent REST URL). +3. Record the endpoint and outcome of each attempt. If both sources are + inaccessible, state that explicitly. Never infer or invent the affected + package, vulnerable range, severity, CVE, publication state, or patched + version. +4. Verify the proposed patched version independently. Prefer a published + repository release or tag, then package-registry metadata when applicable. + Cite the exact URL or command result. Do not update compatibility policy if + the target cannot be verified, unless the user explicitly directs use of a + supplied target despite inaccessible advisory metadata; document that + limitation without converting it into fabricated advisory evidence. + +## Choose the correct policy field + +- `minimumVersion` is a hard floor: activation fails for every compiler version + below it. Change it only when the requested remediation is a universal + minimum-version enforcement. +- `blockedVersions` rejects listed versions exactly. Change it only when + evidence or explicit instructions identify exact versions to deny and a + continuous minimum floor would be inaccurate. +- `minRecommendedVersion` only warns below the value. Change it only for an + explicitly requested recommendation, never as a substitute for enforcement. +- Agent rows under `agent-compat-v1` select compatible agent versions; they are + unrelated to compiler security enforcement unless separate evidence requires + an agent compatibility change. + +## Write remediation guidance + +Provide concise, actionable remediation in `.github/aw/compat.md` and the final +report. Follow established security-advisory terminology: + +1. Identify the affected product or component, GHSA identifier, CVE identifier + when assigned, affected versions, and first fixed or unaffected version. + Use exact bounded ranges and do not broaden the advisory's claims. +2. State the permanent remediation in imperative language. Give exact, + copyable upgrade and regeneration commands verified against official + documentation. For compiler advisories, explain whether existing generated + workflows must be recompiled and redeployed; blocking a vulnerable version + prevents execution but does not repair generated artifacts. +3. Separate remediation from mitigations and workarounds. Include a temporary + measure only when the advisory documents it. If the retrieved advisory does + not identify one, say so without claiming that no workaround exists. +4. Include a verification step that checks the installed version and any + regenerated artifacts. Do not treat a successful install alone as proof that + deployed workflows were remediated. +5. Link the advisory, fixed release, and authoritative upgrade documentation. + Mention severity, CVSS, known exploitation, CISA KEV status, deadlines, or + urgency only when verified from authoritative evidence. + +Do not invent commands, CVE identifiers, affected configurations, mitigations, +or timelines. If remediation details cannot be verified, identify the missing +evidence and leave the instructions explicitly incomplete. + +## Safe edit procedure + +1. Parse the current JSON and record all four policy areas above. +2. Compare semantic versions numerically. A minimum is monotonic: never lower a + non-empty `minimumVersion` or `minRecommendedVersion`. Stop and report a + requested downgrade rather than applying it. +3. Make the narrowest evidence-backed edit. Preserve `blockedVersions`, + `minRecommendedVersion`, every `agent-compat-v1` row, key ordering, and + formatting unless the selected policy specifically requires changing them. +4. When changing `blockedVersions`, update `.github/aw/compat.md` in the same + change. Account for every blocked version, state why each version or + contiguous range is blocked, link to the corresponding advisory, and provide + the remediation and verification steps defined above. +5. Review the final diff and reject unrelated changes. + +## Required validation + +Before reporting completion: + +1. Run the repository's `Validate compat.json structure and version formats` + task from `.github/workflows/cgo.yml`. +2. Validate `.github/aw/compat.json` against + `.github/aw/compat.schema.json` with a JSON Schema Draft 7 validator. JSON + parsing or ad hoc field checks are not substitutes for schema validation. +3. Confirm `.github/aw/compat.md` accounts for every `blockedVersions` entry + and that each documented range links to its advisory. +4. Exercise the runtime policy semantics with versions immediately below, at, + and above the changed boundary; confirm only the intended hard-fail, warning, + or exact-block behavior changed. +5. Confirm semantic-version monotonicity and byte-for-byte preservation of + unrelated policy fields and agent rows. + +Do not claim validation that was not run. If repository constraints prohibit a +required check, report it as outstanding. + +## Report + +Cite advisory retrieval attempts and patched-version verification. State which +field changed, old and new values, why that policy is correct, which fields were +preserved, and the compatibility task, schema, documentation, and runtime +validation results. Include the remediation, any advisory-supported temporary +mitigation, and verification steps. Clearly separate verified facts, +user-provided inputs, and unavailable advisory details. diff --git a/pkg/linters/compat_schema_test.go b/pkg/linters/compat_schema_test.go new file mode 100644 index 00000000000..fec3742e1a3 --- /dev/null +++ b/pkg/linters/compat_schema_test.go @@ -0,0 +1,27 @@ +//go:build !integration + +package linters_test + +import ( + "encoding/json" + "os" + "testing" + + "github.com/github/gh-aw/pkg/parser" + "github.com/stretchr/testify/require" +) + +func TestCompatJSONConformsToSchema(t *testing.T) { + schemaJSON, err := os.ReadFile("../../.github/aw/compat.schema.json") + require.NoError(t, err) + + schema, err := parser.CompileSchema(string(schemaJSON), "https://github.com/github/gh-aw/.github/aw/compat.schema.json") + require.NoError(t, err) + + configJSON, err := os.ReadFile("../../.github/aw/compat.json") + require.NoError(t, err) + + var config any + require.NoError(t, json.Unmarshal(configJSON, &config)) + require.NoError(t, schema.Validate(config)) +}