| name | workflow-security-report |
| description | Triage a GitHub code-scanning (CodeQL) finding and produce an immutable Markdown triage report plus an index row, recommending remediation or dismissal, with a permalink pinned to the finding's commit SHA for every code reference so the report stays valid after the code moves. Use when triaging, dismissing, or remediating a code-scanning or CodeQL alert or finding; writing a security finding report; recording why an alert is a false positive or how it was fixed; or maintaining security/code-scanning/index.md and the SECURITY.md triage reference. Takes a finding number or finding URL, fetches details with the gh CLI, assumes the current repository when only a number is given, and refuses findings that do not exist or are already closed. Not for Dependabot or dependency alerts, secret-scanning alerts, runtime incident response, or writing a threat model. |
| license | MIT |
Triage a code-scanning finding
Turn an open GitHub code-scanning (CodeQL) alert into a Markdown triage report that recommends
remediation or dismissal, recorded under security/code-scanning/. Reports are immutable
once the finding is closed, so every reference to repository code is a permalink pinned to the
finding's commit SHA — it must still resolve after the code moves or the line shifts.
1. Resolve the finding
The argument is a finding number or a finding URL.
- URL
https://github.com/<owner>/<repo>/security/code-scanning/<n>: parse <owner>, <repo>, and
<n> from it.
- Bare number
<n>: the finding is in the current repository. Resolve it with
gh repo view --json nameWithOwner -q .nameWithOwner.
2. Fetch the finding and guard
gh api repos/<owner>/<repo>/code-scanning/alerts/<n>
Stop and tell the user — writing nothing — if:
- the call 404s (the finding does not exist, or you lack access); or
.state is not open (a dismissed or fixed finding is closed; its report is immutable and
must not be re-triaged).
If the finding's details have already been provided to you (for example pasted into the prompt), use
them directly and skip the gh call.
3. Pin to the commit SHA
The immutable anchor is .most_recent_instance.commit_sha. Every reference to repository code in the
report — the flagged line and anything you cite in your analysis — is a GitHub permalink built from it:
https://github.com/<owner>/<repo>/blob/<full-sha>/<path>#L<line>
and the commit itself links https://github.com/<owner>/<repo>/commit/<full-sha>. Never reference
code by branch name, HEAD, or a relative path — those drift; the SHA does not.
See reference.md for the full map from gh api fields to report fields (rule id, CWE,
tool version, severity, location columns, detection date).
4. Analyze and recommend
Read the flagged code at that SHA and decide:
- False positive → dismiss. Explain why the rule does not apply here (the taint premise fails, the
value is bounded, the path is unreachable, …) and recommend dismissing in the code-scanning UI.
- True positive → remediate. Describe the fix and, once it lands, the commit that makes it, and
recommend remediation.
Be concrete and verifiable — cite the surrounding code by permalink, not by assertion.
5. Write the report
Copy templates/report.md to security/code-scanning/<n>.md (create the
directory on first run) and fill every placeholder. Keep the section order: What CodeQL reported,
then Why this is a false positive or Remediation, then Resolution. Set Outcome to
False positive, Remediated, or Pending — use Pending while the recommendation is made but the
finding is still open.
6. Update the index
If security/code-scanning/index.md does not exist, create it from
templates/index.md. Append one row linking the finding's GitHub alert, its
./<n>.md report, and the Outcome.
7. Ensure the SECURITY.md reference
Make sure the repository's SECURITY.md points at the triage index. If it lacks the section, add:
## Code scanning triage
CodeQL findings are triaged in
[`security/code-scanning/index.md`](security/code-scanning/index.md), with a report per finding
recording why it was dismissed or how it was remediated.
If SECURITY.md does not exist at all, tell the user rather than inventing a full security policy, and
offer to create one containing this section.
Immutability rules
- Never edit a report whose finding is closed. When CodeQL re-detects the same issue after code moves,
it closes the old alert and opens a new number — that gets a new report which cross-links the
old one by number and
./<n>.md, rather than an edit to the closed report.
- Because every code reference is a SHA permalink, the report keeps resolving after the code moves —
that is the whole point of pinning.
