github-security-report 0.15.0__tar.gz → 0.17.0__tar.gz

{github_security_report-0.15.0 → github_security_report-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.15.0
+Version: 0.17.0
 Summary: Security and quality reporting across GitHub organisations
 Project-URL: Homepage, https://github.com/lfreleng-actions/github-security-report-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github-security-report-action
@@ -36,8 +36,8 @@ Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.16.5; extra == 'dev'
-Requires-Dist: syrupy==6.0.0; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
+Requires-Dist: syrupy==6.1.1; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -101,6 +101,33 @@ if you want to probe everything regardless.
 Further sections report **configuration posture** and **freshness** as plain
 tables (org mode):
 
+- **CodeQL scan health** — two tables beneath **CodeQL: Results/Findings** (the
+  CodeQL alerts table), whose "Clean" says nothing about whether CodeQL is
+  still running:
+  - **Stale Configurations** lists every CodeQL configuration whose last scan
+    trails the default branch's newest commit by more than
+    `codeql_stale_days` (default 30) — the condition GitHub's tool status page
+    flags as *"Code Scanning results may be out of date"*. Each row names the
+    setup type (**Default**, GitHub-managed; or **Advanced**, a workflow in the
+    repository), the language, the last *successful* scan, and the cause:
+    analyses failing (a run that errors still uploads, but its results do not
+    count as a scan), default setup switched off, a workflow removed or
+    disabled, or an advanced workflow
+    **superseded** by default setup (GitHub rejects advanced CodeQL uploads
+    while default setup is on). An *orphaned* configuration will never scan
+    again; delete it from the tool status page once the live setup covers its
+    language.
+  - **Language Coverage** lists repositories where GitHub detects a
+    CodeQL-supported language that no current configuration scans — typically
+    an advanced workflow whose language matrix omits one the repository
+    contains, such as `actions` for its own workflows. On default setup GitHub
+    reports only the languages it is set to scan, so a detected language
+    deliberately left out of default setup is not visible to this check.
+
+  Both consider only repositories where CodeQL has run at least once; the rest
+  already appear in the Results/Findings not-enabled list. Finding a stale
+  configuration means reading each repository's whole CodeQL analysis history,
+  since GitHub cannot filter it by configuration.
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
@@ -118,6 +145,20 @@ tables (org mode):
   exposes no org-wide or GraphQL equivalent) and, like every other category,
   always collected; hide it with the `private_vulnerability_reporting` render
   toggle.
+- **Auto-merge** — repositories where the **Allow auto-merge** setting is off,
+  so a pull request cannot be queued to merge itself once its requirements are
+  met. The setting only offers the option: an auto-merging pull request still
+  waits for the required checks, reviews and branch protections the repository
+  already enforces, so enabling it relaxes nothing. What it removes is the
+  interval between a change becoming mergeable and somebody noticing — the
+  window a reviewed dependency update sits in while the vulnerability it fixes
+  stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
+  request; hide it with the `auto_merge` render toggle.
+
+The four enablement categories count the repositories with and without the
+feature (plus any whose state could not be read), and by default name whichever
+known list is shorter — see
+[Enabled or disabled repository lists](#enabled-or-disabled-repository-lists).
 
 ## Operating modes
 
@@ -182,6 +223,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
 
@@ -302,6 +344,7 @@ environment-variable name, never embedded.
     "include_test": false,
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
+    "codeql_stale_days": 30,
     "graph_batch": 10,
     "order": { "style": "auto" }
   },
@@ -326,6 +369,17 @@ individual output. Set a value to `0` to remove the limit entirely and show
 every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
+`report.codeql_stale_days` (default `30`, minimum `1`) is the CodeQL
+stale-configuration threshold: a configuration is stale once its last scan
+trails the default branch's newest commit by more than that many days. It is
+measured against the branch head rather than the clock, so a repository nobody
+has pushed to is not flagged just for being quiet. GitHub does not publish the
+threshold behind its own "may be out of date" warning; across the
+`lfreleng-actions` estate healthy configurations trailed their head by at most
+five days and abandoned ones by more than eighty, so the default sits well
+clear of both. The same threshold decides which configurations count as current
+for Language Coverage.
+
 The Releases / Tagging section has two independent freshness levers:
 
 - `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
@@ -353,7 +407,25 @@ organisation, as `--top-n` does.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
-exclusion is visible rather than silently dropped.
+exclusion is visible rather than silently dropped. Entries match repository
+names case-insensitively, as GitHub does.
+
+Every category reports those exclusions beneath its counts, so an
+organisation-wide list repeats under each one. `report.excluded_display`
+governs that line on every surface:
+
+| Value | Excluded line |
+| ----- | ------------- |
+| `always-show` (default) | Shown under every category |
+| `always-hide` | Never shown |
+| `conditional-hide` | Shown only for a category whose exclusions differ from the organisation's `exclude` list, and then in full |
+
+Hiding the line changes nothing else: every count is unaffected, and the report
+header's repository count already leaves excluded repositories out. So a clean
+category reads `All Clean` once no Excluded line qualifies it. Today every
+category reports the organisation's own list, so `conditional-hide` currently
+hides the same lines `always-hide` does. It differs once a category excludes
+repositories of its own. The `report.json` artifact always lists the exclusions.
 
 Archived and test repositories are excluded from analysis by default. Opt them
 back in with `report.include_archived` / `report.include_test` in the config, or
@@ -384,16 +456,17 @@ both true.
 
 The example above hides Zizmor on every surface, and keeps Releases / Tagging
 out of the terminal and Slack while still publishing it to the Markdown and HTML
-Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
-`aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
-`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
-other `report`
-settings, `categories` can be set
-globally and overridden per organisation (overrides merge key-by-key, so
-flipping one output leaves the rest untouched). The machine-readable
-`report.json` artifact always contains the complete dataset, regardless of these
-toggles.
+Pages output. The valid category keys are: `codeql`,
+`codeql_stale_configurations`, `codeql_language_coverage`, `scorecard`,
+`zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
+`dependabot_alerts_enabled`, `dependabot_updates_enabled`,
+`dependabot_cooldown`, `releases`, `mutable_releases`,
+`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
+`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
+`categories` can be set globally and overridden per organisation (overrides
+merge key-by-key, so flipping one output leaves the rest untouched). The
+machine-readable `report.json` artifact always contains the complete dataset,
+regardless of these toggles.
 
 When several organisations share one Slack channel they render into a single
 combined digest, so the per-org Slack toggles are unioned for that channel: a
@@ -454,6 +527,52 @@ Slack-style ceiling, but they still apply their own row limits — only the
 GitHub Pages report whenever `pages_url` is set and short enough to render as a
 link.
 
+### Enabled or disabled repository lists
+
+The four boolean feature categories — `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `private_vulnerability_reporting` and `auto_merge`
+— sort each repository into one of three buckets: enabled, not enabled, or
+**unknown** when the feature's state could not be read. The unknown bucket is
+counted but never named, and never treated as either side, so the enabled and
+not-enabled counts need not sum to the repositories analysed. Beneath the counts,
+one of the two known sides is named; `report.repo_list` chooses which, on every
+surface:
+
+| Value | Names |
+| ----- | ----- |
+| `auto` (default) | Whichever list is shorter |
+| `enabled` | The repositories with the feature on |
+| `disabled` | The repositories with the feature off |
+
+`auto` keeps a footer short whichever way an organisation leans: a feature
+nearly every repository has lists its few holdouts, and one almost none have
+lists its few adopters. Two cases resolve towards the actionable side: a tie
+names the repositories without the feature, and so does a category where
+*nothing* is enabled, since naming an empty list would print nothing where a
+reader wants the repositories to fix. Both sides are always counted, whichever is
+named.
+
+A category can override the global value:
+
+```json
+{
+  "report": {
+    "repo_list": "auto",
+    "categories": {
+      "dependabot_alerts_enabled": { "repo_list": "disabled" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Dependabot alerts always name the repositories to fix, and the other three
+feature categories name whichever side is shorter. `repo_list` applies only to
+those four categories; setting it on any other is a configuration error, since a
+table with qualitative columns has no enabled list to name. These categories
+render as a name list rather than a one-column table on every surface. The
+`report.json` artifact is unaffected.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest
@@ -1401,8 +1520,30 @@ uvx github-security-report remediate \
 # Limit to specific categories (repeatable).
 uvx github-security-report remediate --org lfreleng-actions \
   --category codeql --category private_vulnerability_reporting --apply
+
+# Limit to specific repositories, for any category (comma-separated and/or
+# repeatable; `name` in any configured org, or `owner/name`).
+uvx github-security-report remediate --org lfreleng-actions \
+  --repos dependamerge,python-nss-ng --apply
 ```
 
+`--repos` narrows the run itself, not just its output. Everything done per
+repository (the feature probes, the batched prefetch, the CodeQL history walk
+and every write) covers only the named repositories, so a targeted run skips
+the bulk of a full one. The organisation-wide alert sweeps are the exception:
+each is a single org-bulk request, so its cost follows the organisation's open
+alert backlog rather than its repository count. It combines with
+`--category`. Every name is checked against every configured organisation
+before anything is written: a name that matches no repository (almost always
+a typo), or one that matches only repositories the configuration excludes
+(the `exclude` list, archived, fork, template or test), stops the run with
+exit code 2 and says which. A bare name excluded in one organisation but in
+scope in another runs against the in-scope one only; naming a repository never
+brings an excluded one back. A `--repos` value that names nothing also stops
+the run, rather than falling back to every repository. The run then collects
+exactly the repositories that check validated, without listing the
+organisation again, and prints `Limited to:` beneath its heading.
+
 The remediable categories are the simple on/off features with a documented
 enablement endpoint:
 
@@ -1413,11 +1554,65 @@ enablement endpoint:
 | `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
+| `auto_merge` | The repository's "Allow auto-merge" setting |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+### Cleaning up stale CodeQL configurations
+
+One category is **destructive**, so it runs only when named. The no-argument
+run never includes it:
+
+```bash
+# Preview: which configurations would go, and which are refused and why.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations --apply
+```
+
+It acts on the rows of **CodeQL: Stale Configurations**, according to their
+cause:
+
+<!-- markdownlint-disable MD013 -->
+
+| Cause | Action |
+| ----- | ------ |
+| Default setup disabled; workflow removed; superseded by default setup; language removed from default setup | **Delete** the configuration: it can never upload again |
+| Workflow disabled after inactivity | **Re-enable** the workflow, restoring the scan |
+| Analyses failing, default setup changing state or not uploading, uploaded outside GitHub Actions, workflow disabled by hand, active but not uploading, or state unreadable | Reported only; needs a person |
+
+<!-- markdownlint-enable MD013 -->
+
+Deleting removes a configuration's analyses, which clears GitHub's *"Code
+Scanning results may be out of date"* warning but also removes its alert
+history. A deletion is therefore **refused**, in a dry run as in an apply,
+when:
+
+- no current configuration scans its language: the stale results are then
+  the only record of it, so add scanning for the language first (the refusal
+  names it, and **CodeQL: Language Coverage** lists the gap);
+- it would help close an open alert. This is judged across **every deletion
+  planned in the repository**, not one at a time: an alert held by two stale
+  configurations would close if both went, so both are refused, although
+  neither holds it alone. An alert also reported by a live configuration
+  blocks nothing;
+- the repository's open alerts cannot be read.
+
+Refusals are listed beside the work done and do not fail the run. Deletion is
+paced at one request a second across the whole run, as GitHub asks of
+mutating requests, and is resumable: an interrupted run's next pass picks up
+the remaining analyses. GitHub answers requests it will not authorise with
+`404`, so a deletion's `404` counts as already done only once the analysis
+also reads back as gone; a token that may not delete fails instead of
+reporting a cleanup that never happened. The token needs the classic `repo`
+scope. See [ADR-0005](docs/adr/0005-codeql-configuration-cleanup.md) for the
+reasoning.
+
 ## Bulk Remediation Scripts
 
 The standalone scripts below predate the `remediate` subcommand and remain for

{github_security_report-0.15.0 → github_security_report-0.17.0}/README.md

@@ -57,6 +57,33 @@ if you want to probe everything regardless.
 Further sections report **configuration posture** and **freshness** as plain
 tables (org mode):
 
+- **CodeQL scan health** — two tables beneath **CodeQL: Results/Findings** (the
+  CodeQL alerts table), whose "Clean" says nothing about whether CodeQL is
+  still running:
+  - **Stale Configurations** lists every CodeQL configuration whose last scan
+    trails the default branch's newest commit by more than
+    `codeql_stale_days` (default 30) — the condition GitHub's tool status page
+    flags as *"Code Scanning results may be out of date"*. Each row names the
+    setup type (**Default**, GitHub-managed; or **Advanced**, a workflow in the
+    repository), the language, the last *successful* scan, and the cause:
+    analyses failing (a run that errors still uploads, but its results do not
+    count as a scan), default setup switched off, a workflow removed or
+    disabled, or an advanced workflow
+    **superseded** by default setup (GitHub rejects advanced CodeQL uploads
+    while default setup is on). An *orphaned* configuration will never scan
+    again; delete it from the tool status page once the live setup covers its
+    language.
+  - **Language Coverage** lists repositories where GitHub detects a
+    CodeQL-supported language that no current configuration scans — typically
+    an advanced workflow whose language matrix omits one the repository
+    contains, such as `actions` for its own workflows. On default setup GitHub
+    reports only the languages it is set to scan, so a detected language
+    deliberately left out of default setup is not visible to this check.
+
+  Both consider only repositories where CodeQL has run at least once; the rest
+  already appear in the Results/Findings not-enabled list. Finding a stale
+  configuration means reading each repository's whole CodeQL analysis history,
+  since GitHub cannot filter it by configuration.
 - **Dependabot** — three tables: repositories with vulnerability **alerts not
   enabled**, repositories with **security updates not enabled**, and ecosystems
   with no update `cooldown` configured (mandatory; any value passes).
@@ -74,6 +101,20 @@ tables (org mode):
   exposes no org-wide or GraphQL equivalent) and, like every other category,
   always collected; hide it with the `private_vulnerability_reporting` render
   toggle.
+- **Auto-merge** — repositories where the **Allow auto-merge** setting is off,
+  so a pull request cannot be queued to merge itself once its requirements are
+  met. The setting only offers the option: an auto-merging pull request still
+  waits for the required checks, reviews and branch protections the repository
+  already enforces, so enabling it relaxes nothing. What it removes is the
+  interval between a change becoming mergeable and somebody noticing — the
+  window a reviewed dependency update sits in while the vulnerability it fixes
+  stays unpatched. Read from the batched GraphQL prefetch, so it costs no extra
+  request; hide it with the `auto_merge` render toggle.
+
+The four enablement categories count the repositories with and without the
+feature (plus any whose state could not be read), and by default name whichever
+known list is shorter — see
+[Enabled or disabled repository lists](#enabled-or-disabled-repository-lists).
 
 ## Operating modes
 
@@ -138,6 +179,7 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts, across every GitHub pattern category |
 | Issues | Open issues and their labels (GitHub Issues table) |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
+| Actions | Workflow state behind a stale CodeQL configuration |
 
 **Organization permissions:**
 
@@ -258,6 +300,7 @@ environment-variable name, never embedded.
     "include_test": false,
     "repo_min_age_days": 28,
     "release_max_age_days": 60,
+    "codeql_stale_days": 30,
     "graph_batch": 10,
     "order": { "style": "auto" }
   },
@@ -282,6 +325,17 @@ individual output. Set a value to `0` to remove the limit entirely and show
 every offender. Each can also be set at the CLI with `--top-n`,
 `--top-n-report`, `--top-n-cli`, and `--top-n-slack`.
 
+`report.codeql_stale_days` (default `30`, minimum `1`) is the CodeQL
+stale-configuration threshold: a configuration is stale once its last scan
+trails the default branch's newest commit by more than that many days. It is
+measured against the branch head rather than the clock, so a repository nobody
+has pushed to is not flagged just for being quiet. GitHub does not publish the
+threshold behind its own "may be out of date" warning; across the
+`lfreleng-actions` estate healthy configurations trailed their head by at most
+five days and abandoned ones by more than eighty, so the default sits well
+clear of both. The same threshold decides which configurations count as current
+for Language Coverage.
+
 The Releases / Tagging section has two independent freshness levers:
 
 - `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
@@ -309,7 +363,25 @@ organisation, as `--top-n` does.
 
 The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
-exclusion is visible rather than silently dropped.
+exclusion is visible rather than silently dropped. Entries match repository
+names case-insensitively, as GitHub does.
+
+Every category reports those exclusions beneath its counts, so an
+organisation-wide list repeats under each one. `report.excluded_display`
+governs that line on every surface:
+
+| Value | Excluded line |
+| ----- | ------------- |
+| `always-show` (default) | Shown under every category |
+| `always-hide` | Never shown |
+| `conditional-hide` | Shown only for a category whose exclusions differ from the organisation's `exclude` list, and then in full |
+
+Hiding the line changes nothing else: every count is unaffected, and the report
+header's repository count already leaves excluded repositories out. So a clean
+category reads `All Clean` once no Excluded line qualifies it. Today every
+category reports the organisation's own list, so `conditional-hide` currently
+hides the same lines `always-hide` does. It differs once a category excludes
+repositories of its own. The `report.json` artifact always lists the exclusions.
 
 Archived and test repositories are excluded from analysis by default. Opt them
 back in with `report.include_archived` / `report.include_test` in the config, or
@@ -340,16 +412,17 @@ both true.
 
 The example above hides Zizmor on every surface, and keeps Releases / Tagging
 out of the terminal and Slack while still publishing it to the Markdown and HTML
-Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
-`aislop`, `dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
-`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
-`mutable_releases`, `private_vulnerability_reporting`, `github_issues`. Like the
-other `report`
-settings, `categories` can be set
-globally and overridden per organisation (overrides merge key-by-key, so
-flipping one output leaves the rest untouched). The machine-readable
-`report.json` artifact always contains the complete dataset, regardless of these
-toggles.
+Pages output. The valid category keys are: `codeql`,
+`codeql_stale_configurations`, `codeql_language_coverage`, `scorecard`,
+`zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
+`dependabot_alerts_enabled`, `dependabot_updates_enabled`,
+`dependabot_cooldown`, `releases`, `mutable_releases`,
+`private_vulnerability_reporting`, `auto_merge`, `github_issues`,
+`pull_requests`, `pull_requests_assigned`. Like the other `report` settings,
+`categories` can be set globally and overridden per organisation (overrides
+merge key-by-key, so flipping one output leaves the rest untouched). The
+machine-readable `report.json` artifact always contains the complete dataset,
+regardless of these toggles.
 
 When several organisations share one Slack channel they render into a single
 combined digest, so the per-org Slack toggles are unioned for that channel: a
@@ -410,6 +483,52 @@ Slack-style ceiling, but they still apply their own row limits — only the
 GitHub Pages report whenever `pages_url` is set and short enough to render as a
 link.
 
+### Enabled or disabled repository lists
+
+The four boolean feature categories — `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `private_vulnerability_reporting` and `auto_merge`
+— sort each repository into one of three buckets: enabled, not enabled, or
+**unknown** when the feature's state could not be read. The unknown bucket is
+counted but never named, and never treated as either side, so the enabled and
+not-enabled counts need not sum to the repositories analysed. Beneath the counts,
+one of the two known sides is named; `report.repo_list` chooses which, on every
+surface:
+
+| Value | Names |
+| ----- | ----- |
+| `auto` (default) | Whichever list is shorter |
+| `enabled` | The repositories with the feature on |
+| `disabled` | The repositories with the feature off |
+
+`auto` keeps a footer short whichever way an organisation leans: a feature
+nearly every repository has lists its few holdouts, and one almost none have
+lists its few adopters. Two cases resolve towards the actionable side: a tie
+names the repositories without the feature, and so does a category where
+*nothing* is enabled, since naming an empty list would print nothing where a
+reader wants the repositories to fix. Both sides are always counted, whichever is
+named.
+
+A category can override the global value:
+
+```json
+{
+  "report": {
+    "repo_list": "auto",
+    "categories": {
+      "dependabot_alerts_enabled": { "repo_list": "disabled" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+Here Dependabot alerts always name the repositories to fix, and the other three
+feature categories name whichever side is shorter. `repo_list` applies only to
+those four categories; setting it on any other is a configuration error, since a
+table with qualitative columns has no enabled list to name. These categories
+render as a name list rather than a one-column table on every surface. The
+`report.json` artifact is unaffected.
+
 ### Per-category row ordering
 
 Each table ships a sensible default ordering — largest backlog first, stalest
@@ -1357,8 +1476,30 @@ uvx github-security-report remediate \
 # Limit to specific categories (repeatable).
 uvx github-security-report remediate --org lfreleng-actions \
   --category codeql --category private_vulnerability_reporting --apply
+
+# Limit to specific repositories, for any category (comma-separated and/or
+# repeatable; `name` in any configured org, or `owner/name`).
+uvx github-security-report remediate --org lfreleng-actions \
+  --repos dependamerge,python-nss-ng --apply
 ```
 
+`--repos` narrows the run itself, not just its output. Everything done per
+repository (the feature probes, the batched prefetch, the CodeQL history walk
+and every write) covers only the named repositories, so a targeted run skips
+the bulk of a full one. The organisation-wide alert sweeps are the exception:
+each is a single org-bulk request, so its cost follows the organisation's open
+alert backlog rather than its repository count. It combines with
+`--category`. Every name is checked against every configured organisation
+before anything is written: a name that matches no repository (almost always
+a typo), or one that matches only repositories the configuration excludes
+(the `exclude` list, archived, fork, template or test), stops the run with
+exit code 2 and says which. A bare name excluded in one organisation but in
+scope in another runs against the in-scope one only; naming a repository never
+brings an excluded one back. A `--repos` value that names nothing also stops
+the run, rather than falling back to every repository. The run then collects
+exactly the repositories that check validated, without listing the
+organisation again, and prints `Limited to:` beneath its heading.
+
 The remediable categories are the simple on/off features with a documented
 enablement endpoint:
 
@@ -1369,11 +1510,65 @@ enablement endpoint:
 | `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
 | `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
 | `private_vulnerability_reporting` | Private vulnerability reporting |
+| `auto_merge` | The repository's "Allow auto-merge" setting |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
 release freshness/mutability) are reported but not auto-remediated. Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
+### Cleaning up stale CodeQL configurations
+
+One category is **destructive**, so it runs only when named. The no-argument
+run never includes it:
+
+```bash
+# Preview: which configurations would go, and which are refused and why.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations
+
+# Apply.
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql_stale_configurations --apply
+```
+
+It acts on the rows of **CodeQL: Stale Configurations**, according to their
+cause:
+
+<!-- markdownlint-disable MD013 -->
+
+| Cause | Action |
+| ----- | ------ |
+| Default setup disabled; workflow removed; superseded by default setup; language removed from default setup | **Delete** the configuration: it can never upload again |
+| Workflow disabled after inactivity | **Re-enable** the workflow, restoring the scan |
+| Analyses failing, default setup changing state or not uploading, uploaded outside GitHub Actions, workflow disabled by hand, active but not uploading, or state unreadable | Reported only; needs a person |
+
+<!-- markdownlint-enable MD013 -->
+
+Deleting removes a configuration's analyses, which clears GitHub's *"Code
+Scanning results may be out of date"* warning but also removes its alert
+history. A deletion is therefore **refused**, in a dry run as in an apply,
+when:
+
+- no current configuration scans its language: the stale results are then
+  the only record of it, so add scanning for the language first (the refusal
+  names it, and **CodeQL: Language Coverage** lists the gap);
+- it would help close an open alert. This is judged across **every deletion
+  planned in the repository**, not one at a time: an alert held by two stale
+  configurations would close if both went, so both are refused, although
+  neither holds it alone. An alert also reported by a live configuration
+  blocks nothing;
+- the repository's open alerts cannot be read.
+
+Refusals are listed beside the work done and do not fail the run. Deletion is
+paced at one request a second across the whole run, as GitHub asks of
+mutating requests, and is resumable: an interrupted run's next pass picks up
+the remaining analyses. GitHub answers requests it will not authorise with
+`404`, so a deletion's `404` counts as already done only once the analysis
+also reads back as gone; a token that may not delete fails instead of
+reporting a cleanup that never happened. The token needs the classic `repo`
+scope. See [ADR-0005](docs/adr/0005-codeql-configuration-cleanup.md) for the
+reasoning.
+
 ## Bulk Remediation Scripts
 
 The standalone scripts below predate the `remediate` subcommand and remain for

{github_security_report-0.15.0 → github_security_report-0.17.0}/pyproject.toml

@@ -63,9 +63,9 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==6.0.0",
+  "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.5",
+  "ruff==0.16.8",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -95,9 +95,9 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==6.0.0",
+  "syrupy==6.1.1",
   "mypy==2.3.1",
-  "ruff==0.16.5",
+  "ruff==0.16.8",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.15.0 → github_security_report-0.17.0}/src/github_security_report/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.15.0'
-__version_tuple__ = version_tuple = (0, 15, 0)
+__version__ = version = '0.17.0'
+__version_tuple__ = version_tuple = (0, 17, 0)
 
 __commit_id__ = commit_id = None