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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.16.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
@@ -407,7 +407,8 @@ 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`
@@ -1519,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:
 
@@ -1537,6 +1560,59 @@ 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.16.0 → github_security_report-0.17.0}/README.md

@@ -363,7 +363,8 @@ 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`
@@ -1475,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:
 
@@ -1493,6 +1516,59 @@ 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.16.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.16.0'
-__version_tuple__ = version_tuple = (0, 16, 0)
+__version__ = version = '0.17.0'
+__version_tuple__ = version_tuple = (0, 17, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.16.0 → github_security_report-0.17.0}/src/github_security_report/cli/app.py

@@ -27,6 +27,7 @@ from github_security_report.cli.modes import (
 )
 from github_security_report.cli.options import OrgRunOptions, ReportOverrides
 from github_security_report.cli.outputs import TopNLimits
+from github_security_report.scope import RepoSelectionError, parse_repo_selection
 
 app = typer.Typer(
     name="github-security-report",
@@ -267,6 +268,7 @@ def report(
 # Derived from the remediator registry rather than restated, so adding a
 # remediable category cannot leave the help text naming the previous set.
 _REMEDIABLE_HELP = ", ".join(key.value for key in remediate_mod.REMEDIABLE)
+_EXPLICIT_HELP = ", ".join(key.value for key in remediate_mod.EXPLICIT_ONLY)
 
 
 @app.command()
@@ -288,7 +290,7 @@ def remediate(
     category: list[str] | None = typer.Option(
         None,
         "--category",
-        help=f"Remediable category to act on (repeatable; default: all). One of: {_REMEDIABLE_HELP}.",
+        help=f"Remediable category to act on (repeatable; default: all except the destructive {_EXPLICIT_HELP}, which run only when named). One of: {_REMEDIABLE_HELP}.",
     ),
     token_env: str | None = typer.Option(
         None,
@@ -300,14 +302,21 @@ def remediate(
         "--apply",
         help="Perform the writes. Without this flag remediate only previews (dry run).",
     ),
+    repos: list[str] | None = typer.Option(
+        None,
+        "--repos",
+        help="Limit every selected category to these repositories: comma-separated and/or repeatable, each 'name' (in any configured org) or 'owner/name'. Each org's repository list is checked first: a name matching nothing, a name matching only excluded repositories, or an incomplete list stops the run before any per-repository read or any write.",
+    ),
     no_color: bool = typer.Option(False, "--no-color", help="Disable coloured output."),
 ) -> None:
     """Enable security features on repositories that lack them.
 
     Runs the same collection the report uses, then switches on each selected
-    remediable feature wherever a repository has it confirmed off. Dry run by
-    default: pass --apply to make changes. Requires a write-capable token
-    (org admin), distinct from the read-only reporting PAT.
+    remediable feature wherever a repository has it confirmed off. Named
+    explicitly, codeql_stale_configurations also deletes orphaned CodeQL
+    configurations. Dry run by default: pass --apply to make changes. Requires
+    a write-capable token (org admin), distinct from the read-only reporting
+    PAT.
     """
     console = _console(no_color)
 
@@ -326,7 +335,22 @@ def remediate(
             markup=False,
         )
         raise typer.Exit(2)
-    categories = keys or list(remediate_mod.REMEDIABLE)
+    categories = keys or list(remediate_mod.DEFAULT_REMEDIABLE)
+
+    try:
+        selection = parse_repo_selection(repos or [])
+    except RepoSelectionError as exc:
+        # markup=False: the value is printed exactly as the user typed it.
+        console.print(f"--repos: {exc}", style="red", markup=False)
+        raise typer.Exit(2) from exc
+    if repos and not selection:
+        # An explicit narrowing must never widen to "every repository".
+        console.print(
+            "--repos: names no repository; omit it to act on every one",
+            style="red",
+            markup=False,
+        )
+        raise typer.Exit(2)
 
     cfg = _load_config(config_file, config_data, org, token_env, console=console)
     if cfg is None:
@@ -354,6 +378,7 @@ def remediate(
             token=token,
             categories=categories,
             apply=apply,
+            repos=selection,
         ),
     )
     raise typer.Exit(code)

{github_security_report-0.16.0 → github_security_report-0.17.0}/src/github_security_report/cli/modes.py

@@ -20,7 +20,7 @@ from typing import NoReturn
 import typer
 from rich.console import Console
 
-from github_security_report import collect, config, layout, runner
+from github_security_report import collect, config, layout, runner, scope
 from github_security_report import remediate as remediate_mod
 from github_security_report.categories import CategoryKey
 from github_security_report.cli import publish
@@ -36,7 +36,9 @@ from github_security_report.cli.outputs import (
     show,
 )
 from github_security_report.client import AuthError, GitHubClient, NetworkError
+from github_security_report.collect.protocols import ClientProtocol
 from github_security_report.config import Config, OrgConfig, ReportConfig
+from github_security_report.models import Repo
 from github_security_report.render import markdown as md_render
 from github_security_report.render import terminal as term_render
 from github_security_report.report import build_org_report
@@ -261,19 +263,35 @@ async def _run_remediate(
     token: str,
     categories: Sequence[CategoryKey],
     apply: bool,
+    repos: Sequence[scope.RepoRef] = (),
 ) -> int:
     """Collect each org's posture and enable (or preview enabling) features.
 
     A single write-capable token drives both the read (collection) and the
     writes for every configured org, so the per-org read ``token_env`` in the
-    config is intentionally bypassed. Returns 1 when any enable failed, else 0.
+    config is intentionally bypassed. ``repos``, when given, limits every
+    category to those repositories; the selection is checked against every
+    org before anything is read or written, and a name that matches nothing,
+    or only an excluded repository, stops the run. Returns 2 for a bad
+    selection, 1 when any write failed, else 0.
     """
     now = dt.datetime.now(dt.timezone.utc)
     failures = 0
     async with GitHubClient(token) as client:
-        for org_cfg in cfg.organizations:
+        selected = await _check_selection(client, cfg, repos, console=console)
+        if selected is None:
+            return 2
+        for index, org_cfg in enumerate(cfg.organizations):
+            if repos and index not in selected:
+                continue  # none of the named repositories live here
+            # The validated repositories themselves, so collection cannot
+            # silently lose one to a second, incomplete listing.
             report = await collect.collect_org(
-                client, org_cfg, org_cfg.report, generated_at=now
+                client,
+                org_cfg,
+                org_cfg.report,
+                generated_at=now,
+                selected=selected[index] if repos else None,
             )
             results = await remediate_mod.remediate_org(
                 client, report, categories=categories, apply=apply
@@ -286,6 +304,77 @@ async def _run_remediate(
                 console,
                 apply=apply,
                 top_n=org_cfg.report.cli_top_n,
+                # This entry's own validated repositories, not every selector:
+                # in a multi-org run each org names only what it collected.
+                limited_to=[r.name for r in selected[index]] if repos else [],
             )
             failures += sum(result.failures for result in results)
     return 1 if failures else 0
+
+
+async def _check_selection(
+    client: ClientProtocol,
+    cfg: Config,
+    repos: Sequence[scope.RepoRef],
+    *,
+    console: Console,
+) -> dict[int, tuple[Repo, ...]] | None:
+    """Each org entry's repositories a selection names, or None to stop.
+
+    Keyed by the entry's position in the configuration, holding only entries
+    with a match: a run collects exactly these, so an entry the selection
+    never touches is skipped. Keyed by position rather than name because the
+    configuration may list one organisation twice with different scoping;
+    each entry must act only on what its own configuration allows.
+
+    Every name must match a repository some configured org has in scope. A
+    name matching nothing is almost always a typo, and one matching only an
+    excluded repository (the exclude list, archived, fork, template, test)
+    must not bypass that exclusion, so both stop the run. So does any org
+    whose listing came back incomplete, since it may hide a repository a
+    selector names. Every problem is reported at once. An empty selection
+    returns an empty mapping, which callers read as "no selection".
+    """
+    if not repos:
+        return {}
+    usable: dict[scope.RepoRef, bool] = dict.fromkeys(repos, False)
+    excluded: dict[scope.RepoRef, list[str]] = {ref: [] for ref in repos}
+    touched: dict[int, tuple[Repo, ...]] = {}
+    problems: list[str] = []
+    for index, org_cfg in enumerate(cfg.organizations):
+        named = await collect.check_named_repos(client, org_cfg, org_cfg.report, repos)
+        if named.partial:
+            # A narrowed run must validate its whole target set, and an
+            # incomplete listing may hide a repository a selector names (a
+            # bare name can match in any org), so it cannot proceed on the
+            # matches it happened to see.
+            problems.append(
+                f"the repository listing for {org_cfg.name} was incomplete, so "
+                "the selection cannot be checked in full; try again"
+            )
+        for ref in repos:
+            if any(ref.matches(org_cfg.name, r.name) for r in named.in_scope):
+                usable[ref] = True
+            excluded[ref].extend(
+                f"{r.full_name} is excluded ({reason})"
+                for r, reason in named.excluded
+                if ref.matches(org_cfg.name, r.name)
+            )
+        if named.in_scope:
+            touched[index] = named.in_scope
+    # A bare name may be usable in one org and excluded in another: only a
+    # name with no usable match anywhere is a problem, so the run acts on the
+    # usable match and never on the excluded one.
+    for ref in repos:
+        if not usable[ref]:
+            problems.extend(excluded[ref])
+    unknown = [str(ref) for ref in repos if not usable[ref] and not excluded[ref]]
+    if unknown:
+        where = ", ".join(org_cfg.name for org_cfg in cfg.organizations)
+        problems.append(f"no repository named {', '.join(unknown)} in {where}")
+    if problems:
+        # markup=False: repository names come from the command line and the API.
+        for problem in problems:
+            console.print(f"--repos: {problem}", style="red", markup=False)
+        return None
+    return touched

{github_security_report-0.16.0 → github_security_report-0.17.0}/src/github_security_report/client/codeql_parsers.py

@@ -65,7 +65,9 @@ def latest_codeql_configurations(
     workflow that fails on every run read as current indefinitely. A
     configuration that has never once succeeded has no last scan at all
     (``None``), which makes it stale however recent its attempts. ``failing``
-    records whether the newest attempt errored.
+    records whether the newest attempt errored. Every analysis id in the
+    configuration is kept, newest first, which is the order GitHub requires
+    them deleted in.
     """
     grouped: dict[str, list[tuple[dt.datetime, Mapping[str, object]]]] = {}
     for analysis in analyses:
@@ -87,12 +89,19 @@ def _errored(analysis: Mapping[str, object]) -> bool:
     return isinstance(error, str) and bool(error.strip())
 
 
+def _analysis_id(analysis: Mapping[str, object]) -> int | None:
+    value = analysis.get("id")
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
 def _configuration(
     category: str, entries: list[tuple[dt.datetime, Mapping[str, object]]]
 ) -> CodeQLConfiguration:
     """One configuration from its analyses, newest first."""
     _newest_at, newest = entries[0]
     succeeded = [created for created, analysis in entries if not _errored(analysis)]
+    # Already newest first: the order GitHub requires them deleted in.
+    ids = [_analysis_id(analysis) for _created, analysis in entries]
     key = newest.get("analysis_key")
     return CodeQLConfiguration(
         category=category,
@@ -100,6 +109,7 @@ def _configuration(
         last_scan_at=succeeded[0] if succeeded else None,
         language=_analysis_language(newest),
         failing=_errored(newest),
+        analysis_ids=tuple(i for i in ids if i is not None),
     )
 
 

{github_security_report-0.16.0 → github_security_report-0.17.0}/src/github_security_report/client/reads.py

@@ -360,3 +360,51 @@ class ReadClient(OrgReadClient):
         readable = resp.status_code == 200
         await resp.aclose()  # only the status matters here
         return readable
+
+    async def codeql_alert_holders(
+        self, org: str, repo: str, branch: str
+    ) -> list[frozenset[str]] | None:
+        """Each open CodeQL alert's holding categories on ``branch``.
+
+        One entry per open alert: the categories of the configurations whose
+        instance of it is still open there. An instance already fixed holds
+        nothing open, so it is not counted. Deleting configurations closes every alert whose
+        holders they all belong to, so a cleanup judges its whole planned
+        deletion set against these, not one deletion at a time. ``None`` when
+        the alerts or any alert's instances could not be read in full: an
+        unknown answer must stop a deletion, never permit one.
+        """
+        base = f"{self._api_url}/repos/{org}/{repo}/code-scanning"
+        ref = f"refs/heads/{branch}"
+        # Filtered to the branch up front: only its alerts can be held open by
+        # a configuration on it, and each costs an instances read below.
+        status, alerts = await self._get_list(
+            f"{base}/alerts",
+            tool_name=CODE_SCANNING_TOOLS[SignalType.CODEQL],
+            state="open",
+            ref=ref,
+        )
+        if status != 200:
+            return None
+        holders: list[frozenset[str]] = []
+        for alert in alerts:
+            status, instances = await self._get_list(
+                f"{base}/alerts/{alert.get('number')}/instances", ref=ref
+            )
+            if status != 200:
+                return None
+            held_by: set[str] = set()
+            for instance in instances:
+                state = instance.get("state")
+                category = instance.get("category")
+                if state not in ("open", "fixed") or not isinstance(category, str):
+                    # An instance whose state or configuration is unknown could
+                    # be the one keeping the alert open; guessing would not
+                    # fail closed.
+                    return None
+                # Only an open instance holds the alert open: a configuration
+                # that has already fixed its instance keeps nothing alive.
+                if state == "open":
+                    held_by.add(category)
+            holders.append(frozenset(held_by))
+        return holders

{github_security_report-0.16.0 → github_security_report-0.17.0}/src/github_security_report/client/writes.py

@@ -12,14 +12,49 @@ and the remediation writes.
 
 from __future__ import annotations
 
+import asyncio
+from urllib.parse import quote
+
 import httpx
 
 from github_security_report.client.reads import ReadClient
 
+# Minimum spacing between cleanup mutations. GitHub asks integrations to leave
+# at least a second between mutating requests to avoid its secondary rate
+# limits, and a cleanup can issue hundreds across many configurations. A class
+# attribute so tests can set it to zero.
+_MUTATION_INTERVAL_SECONDS = 1.0
+
 
 class GitHubClient(ReadClient):
     """Thin async client over the GitHub REST + GraphQL APIs."""
 
+    mutation_interval_seconds: float = _MUTATION_INTERVAL_SECONDS
+    # Event-loop time of the last paced mutation; None before the first.
+    _last_mutation_at: float | None = None
+
+    async def _paced_mutation(
+        self, method: str, url: str, *, params: dict[str, str] | None = None
+    ) -> httpx.Response:
+        """Send one cleanup mutation, spaced from the previous one.
+
+        Client-wide rather than per call, so the spacing holds across targets:
+        the last deletion of one configuration and the first of the next are
+        as far apart as any two within one. The time is stamped when the
+        request *returns*, not when it starts: ``_request`` retries 5xx and
+        rate-limit responses itself, and a retry that lands late is still the
+        latest mutation GitHub saw, so the next must wait from it.
+        """
+        loop = asyncio.get_running_loop()
+        if self._last_mutation_at is not None:
+            wait = self._last_mutation_at + self.mutation_interval_seconds - loop.time()
+            if wait > 0:
+                await asyncio.sleep(wait)
+        try:
+            return await self._request(method, url, params=params)
+        finally:
+            self._last_mutation_at = loop.time()
+
     # ------------------------------------------------------------------ #
     # Remediation writes (enable a feature on one repository)
     # ------------------------------------------------------------------ #
@@ -154,3 +189,96 @@ class GitHubClient(ReadClient):
         note = "" if ok else self._write_note(resp)
         await resp.aclose()
         return ok, note
+
+    # ------------------------------------------------------------------ #
+    # CodeQL configuration cleanup
+    # ------------------------------------------------------------------ #
+    async def delete_codeql_analyses(
+        self, org: str, repo: str, analysis_ids: tuple[int, ...]
+    ) -> tuple[bool, str]:
+        """Delete one configuration's analyses, newest first. ``(ok, note)``.
+
+        GitHub deletes a configuration one analysis at a time, and only its
+        newest is deletable at any moment, so ``analysis_ids`` must arrive
+        newest first. ``confirm_delete`` permits removing the last one, which
+        is the point: the configuration itself goes with it.
+
+        The delete response's ``confirm_delete_url`` is documented to chain to
+        the next analysis, but in practice returns null while older analyses
+        remain, so the ids collected with the report drive the walk instead.
+
+        A ``404`` may mean the analysis is already gone (a previous,
+        interrupted run, or the listing lagging behind a deletion), but GitHub
+        also answers a token that may not delete with ``404``. So the analysis
+        is read back with the same token, which listed it moments ago: gone
+        there too means skip it, so a re-run resumes; still readable means the
+        delete was refused, and the walk stops with a failure rather than
+        reporting a cleanup that never happened. The note reports how many
+        were deleted.
+        """
+        deleted = 0
+        for analysis_id in analysis_ids:
+            resp = await self._paced_mutation(
+                "DELETE",
+                f"{self._api_url}/repos/{org}/{repo}/code-scanning/analyses/{analysis_id}",
+                params={"confirm_delete": "true"},
+            )
+            status = resp.status_code
+            stopped = f"stopped after {deleted} of {len(analysis_ids)}"
+            if status not in (200, 404):
+                note = self._write_note(resp)
+                await resp.aclose()
+                return False, f"{stopped}: {note}"
+            await resp.aclose()
+            if status == 404:
+                gone = await self._analysis_gone(org, repo, analysis_id)
+                if gone is not True:
+                    reason = (
+                        "delete refused (404) though the analysis still exists; "
+                        "check the token can delete code scanning analyses"
+                        if gone is False
+                        else "could not confirm the analysis was already gone"
+                    )
+                    return False, f"{stopped}: {reason}"
+            deleted += status == 200
+        noun = "analysis" if deleted == 1 else "analyses"
+        return True, f"{deleted} {noun} deleted"
+
+    async def _analysis_gone(
+        self, org: str, repo: str, analysis_id: int
+    ) -> bool | None:
+        """Whether an analysis no longer exists: True gone, False present.
+
+        ``None`` when the read itself fails otherwise, which a caller must not
+        mistake for either answer.
+        """
+        resp = await self._request(
+            "GET",
+            f"{self._api_url}/repos/{org}/{repo}/code-scanning/analyses/{analysis_id}",
+        )
+        status = resp.status_code
+        await resp.aclose()  # only the status matters here
+        if status == 404:
+            return True
+        if status == 200:
+            return False
+        return None
+
+    async def enable_workflow(self, org: str, repo: str, path: str) -> tuple[bool, str]:
+        """Re-enable the workflow at ``path``. Returns ``(ok, note)``.
+
+        ``PUT .../actions/workflows/{file}/enable`` answers ``204``; the
+        workflow is addressed by file name, which the API accepts in place of
+        its numeric id.
+        """
+        # Encoded as one path segment, as the read is: a "?" or "#" in the
+        # file name would otherwise end the URL path early.
+        name = quote(path.rsplit("/", 1)[-1], safe="")
+        resp = await self._paced_mutation(
+            "PUT",
+            f"{self._api_url}/repos/{org}/{repo}/actions/workflows/{name}/enable",
+        )
+        ok = resp.status_code == 204
+        note = "" if ok else self._write_note(resp)
+        await resp.aclose()
+        return ok, note