chore(ci): read secret scanning alerts with an optional SECURITY_SCAN_TOKEN

.github/workflows/README.md

@@ -14,6 +14,7 @@ Workflows that automate dependency remediation and give the team Slack visibilit
 ## Setup
 
 - Add repo secret `SECURITY_ALERTS_SLACK_WEBHOOK` (a Slack incoming webhook URL) — required by `security-findings-notify.yml`, `stale-bot-pr-notify.yml`, `outdated-kilo-deps.yml` and `stale-alerts-report.yml`.
+- Optional repo secret `SECURITY_SCAN_TOKEN`: a token with the `secret_scanning_alerts` scope. Without it, `security-findings-notify.yml` tries the default token and skips secret scanning with a warning if that fails.
 - Optional repo variables to override defaults: `SECURITY_SLA_CRITICAL_DAYS` (15), `SECURITY_SLA_HIGH_DAYS` (30), `SECURITY_SLA_MEDIUM_DAYS` (90), `SECURITY_SLA_LOW_DAYS` (180), `SECURITY_MIN_SEVERITY` (`high`; set to `medium` or `low` to report more), `STALE_BOT_PR_DAYS` (3).
 
 ## How it works
@@ -42,7 +43,7 @@ They don't call each other or trigger off PR creation. Each one wakes up on its
 |---|---|---|
 | Dependabot alerts | `security-findings-notify.yml`, `stale-alerts-report.yml` | Needs the `vulnerability-alerts: read` permission. |
 | Code scanning alerts | `security-findings-notify.yml` | Needs `security-events: read`. Alerts without a security severity are quality findings and are skipped. If the API returns an error, the run logs a warning and continues. |
-| Secret scanning alerts | `security-findings-notify.yml` | The default `GITHUB_TOKEN` cannot read these on every plan. If the API returns an error, the run logs a warning and continues. Add a token with the `secret_scanning_alerts` scope if you need this source. |
+| Secret scanning alerts | `security-findings-notify.yml` | The default `GITHUB_TOKEN` cannot read these on every plan. If the API returns an error, the run logs a warning and continues. To enable this source, add the repo secret `SECURITY_SCAN_TOKEN` (a token with the `secret_scanning_alerts` scope). The workflow uses it for this one call only. |
 | Findings of the Kilo Security Agent (the "Unreachable" and "Exploitable" labels) | None | They live in the private `Kilo-Org/cloud` stack. A repo workflow cannot read them. |
 
 The helper scripts are `script/kilocode/bot-prs.ts` (duplicate grouping) and `script/kilocode/stale-alerts.ts` (stale alert check). Both have tests next to them. Run `bun test bot-prs.test.ts stale-alerts.test.ts` from `script/kilocode/`.

.github/workflows/security-findings-notify.yml

@@ -33,6 +33,10 @@ jobs:
       - id: build
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Optional. The default token cannot read secret scanning alerts on
+          # every plan. A token with the secret_scanning_alerts scope is used
+          # for that one call only. Without it, the call uses GH_TOKEN.
+          SECRET_SCAN_TOKEN: ${{ secrets.SECURITY_SCAN_TOKEN }}
           REPO: ${{ github.repository }}
           # 15 matches an observed real critical deadline; 30 is a guess.
           CRIT_DAYS: ${{ vars.SECURITY_SLA_CRITICAL_DAYS || '15' }}
@@ -54,13 +58,13 @@ jobs:
 
           # Code scanning returns 404 when it is not enabled, and secret
           # scanning is not readable with the default GITHUB_TOKEN on every
-          # plan. A source that cannot be read is skipped with a warning, so it
+          # plan (set the SECURITY_SCAN_TOKEN secret to fix that). A source that cannot be read is skipped with a warning, so it
           # never hides the Dependabot findings.
           if ! code=$(fetch code-scanning/alerts 2>/dev/null); then
             echo "::warning::could not read code scanning alerts, skipping them"
             code='[]'
           fi
-          if ! secrets=$(fetch secret-scanning/alerts 2>/dev/null); then
+          if ! secrets=$(GH_TOKEN="${SECRET_SCAN_TOKEN:-$GH_TOKEN}" fetch secret-scanning/alerts 2>/dev/null); then
             echo "::warning::could not read secret scanning alerts, skipping them"
             secrets='[]'
           fi