github-security-report 0.19.1__tar.gz → 0.20.0__tar.gz

{github_security_report-0.19.1 → github_security_report-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.19.1
+Version: 0.20.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
@@ -114,11 +114,14 @@ tables (org mode):
     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
+    disabled, 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.
+    while default setup is on), or a configuration **superseded within its
+    workflow**: the workflow file still runs, but a change to its job id or
+    language matrix moved the language to another category, which a current
+    configuration from that same file now scans. 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
@@ -156,6 +159,28 @@ tables (org mode):
   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.
+- **Dependabot: Malware Findings** — one row per open Dependabot alert whose
+  advisory GitHub classifies as
+  [malware](https://docs.github.com/en/code-security/concepts/supply-chain-security/malware-alerts)
+  rather than a vulnerability: a dependency to remove, not upgrade. Each row
+  names the package (linked to the alert), its ecosystem and manifest, the
+  severity and the alert's age, most severe and then oldest first. The alerts
+  come from the organisation-wide Dependabot sweep the alerts signal already
+  makes, so the table costs no extra request. The footer counts repositories:
+  a repository with Dependabot alerts off, or whose state could not be read,
+  cannot raise one and counts as **Alerts off or unreadable**, never as
+  **No findings**. When the sweep is incomplete, the malware it did return is
+  still listed and fails its repository; only the repositories with none in
+  hand are unknown. GitHub's API does not expose whether the malware alerts
+  feature itself is switched on, neither per repository nor in a code-security
+  configuration, so a repository without findings has no malicious package
+  reported, which does not confirm coverage: the feature may be off. The
+  footer says so on every surface, and `remediate` cannot enable it. To switch
+  it on for every repository now, create or edit a custom security
+  configuration in the organisation's settings with *Dependabot → Malware
+  alerts: Enabled* and apply it to all repositories. The report cannot verify
+  the result. See [ADR-0008](docs/adr/0008-dependabot-malware-alerts.md); hide
+  the table with the `malware_findings` render toggle.
 - **Code Quality** — repositories where
   [GitHub Code Quality](https://docs.github.com/en/code-security/concepts/code-quality/code-quality)
   is **Disabled**, or **Partial**: configured, but without a language the
@@ -176,6 +201,43 @@ tables (org mode):
   `python 30/32 · go 5/5 · javascript-typescript 10/12`. See
   [ADR-0006](docs/adr/0006-github-code-quality.md); hide it with the
   `code_quality` render toggle.
+- **Workflow Failures** — repositories whose GitHub Actions workflows failed
+  in the window, ranked by failed runs. The motivating case is the bulk
+  Dependabot merge whose integration tests need credentials, so they run
+  only once merged and never fail on the pull request; the table exists to
+  show which workflows fail, how often, and (in the detail table) whether a
+  pull request could have caught them. Each row gives **Failed** (runs that
+  concluded `failure`, `startup_failure`, `timed_out` or `action_required`),
+  **Runs** (every concluded run of every workflow in the repository),
+  **Fail %** (failed over failed *plus passed*, so skips never dilute it),
+  **Skipped** (skipped, cancelled, neutral and stale runs — a cancelled run
+  reached no verdict, and a bulk-merge round cancels hundreds of superseded
+  ones), **Retried** (runs that passed on a later attempt, a direct sign of
+  flakiness), **Workflows** (how many distinct workflows failed) and **Worst
+  workflow** (the one with the most failures, linked to its run history).
+  GitHub-managed workflows with no file in the repository to fix (Dependabot
+  updates, default-setup CodeQL, Copilot review) are left out unless
+  `workflow_runs.include_dynamic` is set. There is one table per time
+  window: seven days on the terminal and in Slack, and 7, 30 and 90 days on
+  GitHub Pages, where the later windows nest beneath the first. A repository
+  whose run listing could not be read this run (a token without Actions
+  read, a `5xx`) counts as **Unreadable**, never as failure-free, and a
+  footer note says when a window reaches further back than the stored
+  history does. The run history behind the table lives in a per-user
+  **run store**, so the first report against an organisation backfills the
+  longest window once and every later one asks GitHub only for what is new
+  — an unchanged repository costs a single conditional request that GitHub
+  answers `304` and does not charge. See
+  [Workflow run windows and store](#workflow-run-windows-and-store) and
+  [ADR-0007](docs/adr/0007-workflow-failures.md); hide it with the
+  `workflow_failures` render toggle. A per-workflow **detail** table
+  (`workflow_failures_detail`: workflow, file, failing job linked to its
+  newest log, pattern *persistent*/*intermittent*/*insufficient*, failing
+  triggers, and a **Reading** of *post-merge only*, *no PR runs*,
+  *everywhere* or *other*) is collected on every run but rendered nowhere
+  until `categories.workflow_failures_detail.enabled: true`; it stays off
+  Slack even then, being too wide for a chat digest, and is absent from
+  `report.json` while disabled.
 
 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
@@ -251,7 +313,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. *Optional* **write** reads the Code Quality setup, which GitHub gates behind write |
-| Actions | Workflow state behind a stale CodeQL configuration |
+| Actions | Workflow state behind a stale CodeQL configuration, and the workflow run history behind the Workflow Failures tables (the run listing, single-run re-reads, and the GraphQL read of a failed run's check suite) |
 
 **Organization permissions:**
 
@@ -271,7 +333,7 @@ organisations. Grant these scopes:
 
 | Scope | Used for |
 | ----- | -------- |
-| `repo` | Repository data, including private repositories |
+| `repo` | Repository data, including private repositories, and the workflow run history behind the Workflow Failures tables |
 | `security_events` | Code scanning, secret scanning, and Dependabot alerts (org-bulk and per-repo) |
 | `read:org` | Listing organisation repositories, and GitHub's secret-scanning pattern inventory (see below) |
 | `admin:org` | *Optional* — reading organisation rulesets for ruleset-based tool coverage. GitHub gates `GET /orgs/{org}/rulesets` behind the full `admin:org` scope; `read:org` and `write:org` return 404. Omit it to skip that one signal; everything else is unaffected. |
@@ -377,6 +439,9 @@ environment-variable name, never embedded.
     "issue_age_error_days": 60,
     "graph_batch": 10,
     "concurrency": 9,
+    "workflow_runs": {
+      "windows": { "cli": [7], "report": [7, 30, 90], "slack": [7] }
+    },
     "order": { "style": "auto" }
   },
   "organizations": [
@@ -492,8 +557,10 @@ Pages output. The valid category keys are: `codeql`,
 `zizmor`, `aislop`, `dependabot_alerts`, `secret_scanning`,
 `dependabot_alerts_enabled`, `dependabot_updates_enabled`,
 `dependabot_cooldown`, `releases`, `mutable_releases`,
-`private_vulnerability_reporting`, `auto_merge`, `code_quality`,
-`github_issues`, `pull_requests`, `pull_requests_assigned`. Like the other
+`private_vulnerability_reporting`, `auto_merge`, `malware_findings`,
+`code_quality`, `workflow_failures`, `workflow_failures_detail`, `github_issues`,
+`github_issues_assigned`, `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
@@ -695,9 +762,9 @@ By default the report sorts its sections into three bands:
 
 | Band | Contains | Why |
 | ---- | -------- | --- |
-| **Priority** | Secret Scanning, Dependabot: Security Alerts, CodeQL, Mutable Releases | Findings worth acting on today |
+| **Priority** | Secret Scanning, Dependabot: Malware Findings, Dependabot: Security Alerts, CodeQL, Mutable Releases | Findings worth acting on today |
 | **Middle** | Everything else | Neither urgent nor constant |
-| **BAU** | OpenSSF Scorecard, GitHub Issues, Pull Requests, Assigned to Me | Carry data every run, so none of it is news |
+| **BAU** | OpenSSF Scorecard, GitHub Issues, GitHub Issues: Assigned to Me, Pull Requests, Pull Requests: Assigned to Me | Carry data every run, so none of it is news |
 
 The bands are not fixed slots. **A band member with nothing to report moves
 into the middle**: a clean priority category is noise at the top of a page, and
@@ -771,6 +838,8 @@ cooldown) are not independently placeable. They render beneath the Dependabot
 Alerts signal on every surface and travel with it, since three near-identical
 headings adrift in the report would not say which signal they qualified.
 Naming one in an ordering list is rejected rather than accepted and ignored.
+The later windows of the Workflow Failures tables (30 and 90 days on GitHub
+Pages) nest beneath the 7-day table in the same way and share its position.
 
 ### GitHub Issues
 
@@ -1154,7 +1223,7 @@ scheduled run publishes this to Pages, whatever token it holds:
 This is not a configurable toggle. A published `Mine` is not a preference but a
 false statement, so there is nothing to opt into.
 
-### Assigned to Me
+### Pull Requests: Assigned to Me
 
 The `pull_requests_assigned` category repeats the Pull Requests table narrowed
 to pull requests assigned to the account the report ran as — the same columns
@@ -1194,6 +1263,35 @@ name the category as well: `--hide` outranks this toggle and cannot be
 countermanded by it. The input is empty by default, so this only matters if you
 have set it.
 
+### GitHub Issues: Assigned to Me
+
+The `github_issues_assigned` category does the same for issues: the GitHub
+Issues table narrowed to the open issues assigned to the account the report ran
+as, with the same columns. Everything above applies unchanged: "mine" follows
+the token, not a configured name; a bot or App token leaves the section absent;
+and it is **terminal-only by default**, so publishing it takes the same
+deliberate opt-in:
+
+```json
+{
+  "report": {
+    "categories": {
+      "github_issues_assigned": { "outputs": { "html": true } }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+The table reads the same window of each repository's oldest 25 open issues as
+GitHub Issues, so an issue assigned to you beyond that window, in a repository
+with a larger backlog, is not counted. Total is therefore the count of your
+issues *within* the window rather than GitHub's exact total, and a repository
+whose backlog exceeds the window with none of yours inside it counts as unknown
+rather than clean. `Oldest` reads `unknown` when an issue the run could not read
+precedes your oldest one in the window, since the unread issue may be older and
+yours.
+
 ### Hiding a category for one run
 
 `--hide <category>` (repeatable) suppresses a category on **every** output for
@@ -1212,9 +1310,10 @@ The Action exposes the same control through a `hide` input:
 ```
 
 It is **empty by default**, and does not need setting to keep the personal
-queue out of shared artifacts — `pull_requests_assigned` already defaults to the
-terminal only, so Pages, Markdown and Slack never render it, and `report.json`
-omits it for the same reason (see below). Leaving the input empty also keeps the
+queues out of shared artifacts — `pull_requests_assigned` and
+`github_issues_assigned` already default to the terminal only, so Pages,
+Markdown and Slack never render them, and `report.json` omits them for the same
+reason (see below). Leaving the input empty also keeps the
 Action compatible with whichever published version the runtime pin installs: a
 non-empty default would be passed to releases predating the flag, which reject
 it outright.
@@ -1463,13 +1562,20 @@ one line of what the run cost, for example
 <!-- markdownlint-disable MD013 -->
 
 ```text
-GitHub API for lfreleng-actions: 1402 requests (0 retries), 822 core points, 64 graphql points, 41.3 MiB received, 102.5 s
+GitHub API for lfreleng-actions: 1402 requests (REST 1338, GraphQL 64; 0 retries; 0 not modified), 822 core points, 64 graphql points, 0 rate-limit backoffs (0 s), 41.3 MiB received, 102.5 s
 ```
 
 <!-- markdownlint-enable MD013 -->
 
 The request count is every request the tool issued, including retries and
-attempts that never got an answer. The points come from GitHub's own
+attempts that never got an answer; the split names what was asked (a REST
+endpoint, the GraphQL endpoint, or the external Scorecard API), and `not
+modified` is how many conditional reads the run store made that GitHub
+answered `304` at no cost. The backoffs are the pauses GitHub's rate limiting
+forced, with the seconds slept for them. The same figures appear in the run
+summary printed before each report (see
+[Progress and run summary](#progress-and-run-summary)). The points come from
+GitHub's own
 `x-ratelimit-*` response headers rather than from counting: GitHub meters a
 token across more than one bucket per resource (alike requests seconds apart
 can carry different `x-ratelimit-reset` values with independent counters), so
@@ -1481,6 +1587,150 @@ bill. Nothing of this line reaches the rendered report or the step summary.
 > As with `graph_batch`, an empty input is not passed to the tool, so set
 > `GSR_CONCURRENCY` only once the pinned release supports `--concurrency`.
 
+### Workflow run windows and store
+
+The Workflow Failures tables are the one part of the report built from
+history rather than from a repository's current state, so they have their
+own block, `report.workflow_runs`, settable globally or per organisation
+like every other `report` key. Every key with its default:
+
+```json
+{
+  "report": {
+    "workflow_runs": {
+      "windows": { "cli": [7], "report": [7, 30, 90], "slack": [7] },
+      "retention_days": 90,
+      "backfill_days": 90,
+      "include_dynamic": false,
+      "exclude_workflows": [],
+      "collapse_matrix": true,
+      "persistent_threshold": 0.9,
+      "min_runs": 3,
+      "cache": true
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+`windows` maps each surface to the windows it shows, in days: `cli` is the
+terminal, `report` the GitHub Pages Markdown and HTML, and `slack` the
+digest. The terminal and Slack get the week; the published report adds the
+month and the quarter, where a reader has room to compare them. A table is
+built for every window any surface names, titled with its window (`Workflow
+Failures (30 days)`), and each surface draws its own. The map merges **per
+surface**, so an organisation that narrows the Slack windows keeps the
+inherited `report` ones; a list replaces the inherited list for that surface
+rather than adding to it.
+
+`retention_days` is how long the run store keeps a record and
+`backfill_days` how far back a repository never seen before is read. Both
+default to the **longest configured window** (90 days with the default
+windows), which is the most any table can use; `backfill_days` is bounded by
+the retention. A `retention_days` shorter than the longest window is
+**rejected** at load time rather than accepted: the store would prune
+records a table still shows, and the window would quietly cover less than
+its title claims.
+
+`include_dynamic` admits the GitHub-managed workflows (Dependabot updates,
+default-setup CodeQL, Copilot review), whose runs carry a `dynamic/` path
+and no file in the repository; they are left out by default because nobody
+can edit them. `exclude_workflows` is a list of globs matched against the
+workflow path (`.github/workflows/experimental-*.yaml`) for workflows whose
+failures are expected, such as a deliberately failing canary.
+`collapse_matrix` folds matrix legs (`Build (ubuntu-22.04)` and
+`Build (ubuntu-24.04)`) into one job name in the detail table.
+`persistent_threshold` and `min_runs` feed the detail table's **Pattern**
+column: a workflow failing at or above the threshold is *persistent* (fix
+the root cause), below it *intermittent* (harden the workflow), and with
+fewer than `min_runs` runs that reached a verdict *insufficient* to say. Both
+judge the same pass-or-fail population that Fail % does, so skips count
+towards neither.
+
+`cache` and `cache_dir` govern the **run store**, a SQLite file per
+organisation at
+
+```text
+$XDG_CACHE_HOME/github-security-report/<api-host>/<org>/runs.sqlite
+# or, when XDG_CACHE_HOME is unset:
+~/.cache/github-security-report/<api-host>/<org>/runs.sqlite
+```
+
+keyed by API host as well as organisation, since the same name can exist on
+github.com and on an enterprise instance. The store is a cache, never a
+source of truth: everything in it can be rebuilt from GitHub, a schema
+change between releases drops and recreates it rather than migrating it,
+and deleting the file costs exactly one backfill. `cache: false` keeps the
+store in memory for the run alone, so every window is re-read from GitHub
+and nothing is left behind; `cache_dir` relocates it.
+
+Four flags adjust this for one run, each mirrored as an action input:
+
+<!-- markdownlint-disable MD013 -->
+
+| Flag | Input | Effect |
+| ---- | ----- | ------ |
+| `--run-windows 7,30,90` | `run_windows` | Replaces the windows of **every** surface with one list, the shape a one-off investigation wants ("show me 14 days") |
+| `--no-run-cache` | `no_run_cache` | Keeps the store in memory for this run (`cache: false`) |
+| `--run-cache-dir PATH` | `run_cache_dir` | Relocates the store (`cache_dir`) |
+| `--refresh-runs` | `refresh_runs` | Ignores what the store holds and re-reads every repository for the longest window, at the cost of one backfill |
+
+<!-- markdownlint-enable MD013 -->
+
+Repo mode reads one repository's runs afresh each time into an in-memory
+store, and reads the `cli` windows alone (a week, by default) rather than the
+published report's quarter: a pull request's CI or a developer's shell should
+leave nothing behind, and a 90-day backfill for one table nobody publishes
+from that mode would be waste. `--run-windows` applies there; the three store
+flags are refused rather than accepted and ignored.
+
+In GitHub Actions the runner's home directory is discarded with the job, so
+the bundled `reporting.yaml` keeps the store in the Actions cache between
+runs, under a key unique to the run (`gsr-runs-${{ github.run_id }}`) with a
+`gsr-runs-` restore prefix that picks up the newest earlier store. A daily
+schedule keeps the entry inside GitHub's seven-day cache eviction. The save
+runs whatever the report step's outcome, because the store is written in
+transactions: a run that aborted part-way still leaves it consistent, and
+the repositories it did sync need not be re-read.
+
+The store is cached **encrypted**. It names every in-scope repository's
+branches, workflow files and failing jobs, private repositories included
+when the token can read them, and GitHub lets a pull request from a fork
+restore any cache saved on the default branch, which the `production`
+environment's protection rules do not cover. The workflow therefore
+encrypts the store with `openssl enc -aes-256-cbc -pbkdf2` under a key held
+in the environment's secret `GSR_RUN_STORE_KEY` (any long random string;
+`openssl rand -base64 48` makes one) before saving, and decrypts it after
+restoring. Without the secret the store is neither restored nor saved, a
+notice says so, and each run reads its windows from GitHub again — correct,
+only slower and dearer. A store that fails to decrypt, after a key rotation,
+is discarded with a warning and rebuilt. A caller's own workflow needs the
+same steps, or every scheduled run pays the backfill.
+
+The point of the store is that repeated runs are nearly free. Each sync
+presents the listing's ETag, so an unchanged repository answers `304`, which
+GitHub does not count against the rate limit; a changed one is read newest
+first down to the last run already held. Re-runs keep their original
+timestamp and so never cross that watermark, which is why each sync also
+re-reads the window's failure list (conditionally, with its own ETag) when
+the listing moved and re-reads any stored failure missing from it — a run
+leaves that list when a retry passes, and the table's **Retried** column is
+built from exactly those. Runs stored while still in progress are re-read
+until they conclude, at most fifty single-run reads per repository per sync.
+The failing jobs of each failed run come from one GraphQL query per fifty
+runs, costing a point apiece.
+
+Measured on `lfreleng-actions`, warm runs in the same hour: the full report
+cost 1,830 requests, 1,558 core rate-limit points and 116 s before this
+work; 1,130 requests, 849 points and 95 s once the code-scanning and
+repository-feature probes were consolidated onto pages the run already
+read; and 1,136 requests, 838 points and 82 s once the collection phases
+overlapped. The run store adds about one request per repository to a warm
+run, mostly free `304`s. A cold 90-day backfill, the first run against an
+organisation or any run without the cache, is about 1,500 requests, once;
+`--refresh-runs` and deleting the store each cost the same again. The store
+is about 25 MB for a 140-repository organisation.
+
 ### Pass/fail severity cutoff
 
 The severity-ranked signals (CodeQL, Scorecard, Zizmor, aislop, Dependabot
@@ -1560,6 +1810,11 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `hide` | No | `""` | Category keys to suppress on every output (space- or comma-separated). Overrides config, and is one-way: it cannot re-enable a disabled category |
 | `graph_batch` | No | `""` | Repositories per batched GraphQL prefetch query (minimum `1`; default: config, else `10`). Pass a repository or organisation variable such as `${{ vars.GSR_GRAPH_BATCH }}` to adjust it from settings. A batch that still fails is halved automatically, so this sets the starting size (see [GraphQL prefetch batch size](#graphql-prefetch-batch-size)) |
 | `concurrency` | No | `""` | Concurrent GitHub API requests per organisation (`1` to `32`; default: config, else `9`). Pass a repository or organisation variable such as `${{ vars.GSR_CONCURRENCY }}` to adjust it from settings (see [Client concurrency](#client-concurrency)) |
+| `run_windows` | No | `""` | Time windows, in days, for the Workflow Failures tables on every output (comma-separated, e.g. `7,30,90`; default: config, else `7` on the terminal and Slack and `7,30,90` on GitHub Pages; see [Workflow run windows and store](#workflow-run-windows-and-store)) |
+| `run_cache_dir` | No | `""` | Directory for the workflow-run store (default: `$XDG_CACHE_HOME/github-security-report`, i.e. `~/.cache/github-security-report` on a runner). Restore and save it with `actions/cache`, as the bundled `reporting.yaml` does, so each scheduled run reads only what is new |
+| `refresh_runs` | No | `false` | Re-read every repository's workflow runs for the longest window, ignoring what the run store already holds |
+| `no_run_cache` | No | `false` | Keep the workflow-run store in memory for this run instead of on disk, so every window is re-read from GitHub and nothing is left behind |
+| `no_progress` | No | `false` | Do not show the live progress line while collecting. The action runs under `CI`, where the line is already off; set this when running the CLI from the action's source on a terminal (see [Progress and run summary](#progress-and-run-summary)) |
 | `tool_version` | No | `""` | Published PyPI version to install. Empty (the default) uses the Dependabot-managed pin in `.github/runtime-pin/requirements.txt`; set a specific version to override. Ignored on pull requests or when `use_local_source` is `true` (both run from source) |
 | `use_local_source` | No | `false` | Run from the checked-out source instead of PyPI (for testing unreleased code from any event) |
 
@@ -1587,6 +1842,59 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+An org-mode run keeps its workflow-run store under
+`$XDG_CACHE_HOME/github-security-report` (`~/.cache/github-security-report`
+by default), so the first run against an organisation is slower than the
+rest; see [Workflow run windows and store](#workflow-run-windows-and-store).
+Repo mode leaves nothing behind.
+
+### Progress and run summary
+
+On an interactive terminal an org-mode run keeps one live line at the bottom
+of the screen while it collects: the organisation, the phase it is in, the
+repository count where the phase works per repository, the REST and GraphQL
+request counts with how many are in flight, and the elapsed time. A second
+line appears while GitHub has the run paused for a rate limit, and while the
+workflow-run store is being built for the first time, since that one-off
+dominates a cold run. Warnings logged in the meantime are held and replayed,
+in order, once the line comes down.
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+⠧ lfreleng-actions · probing repositories · 41/120 repos · REST 812 (9 in flight) · GraphQL 24 · 38.2 s
+⏳ rate limited by GitHub (core); resuming in 42 s
+```
+
+<!-- markdownlint-enable MD013 -->
+
+Before each organisation's report, a dim three-line summary says what the
+run cost and what the store holds, so a slow run explains itself without
+`--verbose`:
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+Run summary for lfreleng-actions
+  requests: 1 234 requests (REST 1 100 · GraphQL 120 · external 14 · 300 not modified) · 12.3 MiB · 95.2 s
+  rate limit: 980 core points · 230 graphql points · 0 backoffs
+  workflow-run store: 4.2 MiB · 12 340 runs · 180 repositories · this run: 180 synced, 160 unchanged, 340 written
+```
+
+<!-- markdownlint-enable MD013 -->
+
+The rate-limit line turns yellow when a backoff happened or a resource's
+remaining budget fell under a tenth of its limit. A first-time build of the
+store on disk is marked `built (first run)`; a run with `--no-run-cache`
+reads `in memory (not cached)` and, since its store is empty every time, is
+never a first run. The summary is for the terminal only: nothing of it
+reaches the Markdown, HTML, JSON or Slack output.
+
+The live line is off under `--no-progress`, when `CI` is set, when stdout is
+not a terminal, and with `--verbose`, whose log lines would fight it for the
+screen. The summary prints in every case. The same figures reach the log at
+`INFO` under `--verbose`.
+
 ### GitHub Enterprise Server
 
 The API endpoints honour the standard environment variables that GitHub
@@ -1696,7 +2004,10 @@ endpoint:
 | `codeql_stale_configurations` | Stale CodeQL cleanup (named only; deletes) |
 
 Qualitative findings (Scorecard, zizmor, open Dependabot alerts, cooldown,
-release freshness/mutability) are reported but not auto-remediated. Remediation
+release freshness/mutability) are reported but not auto-remediated. Dependabot
+malware alerts are not remediable either: GitHub exposes no API that reads or
+switches on the feature, so `remediate` leaves it out until one exists (see
+[ADR-0008](docs/adr/0008-dependabot-malware-alerts.md)). Remediation
 is organisation-scoped (`--scope org`, the default and only supported scope).
 
 The last two run **only when named** with `--category`, and the no-argument
@@ -1752,9 +2063,9 @@ cause:
 
 | Cause | Action |
 | ----- | ------ |
-| Default setup disabled; workflow removed; superseded by default setup; language removed from default setup | **Delete** the configuration: it can never upload again |
+| Default setup disabled; workflow removed; superseded by default setup; superseded within its workflow; 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 |
+| Analyses failing, default setup changing state or not uploading, uploaded outside GitHub Actions, workflow disabled by hand, active but not uploading, or state unreadable | Listed as skipped, with its cause; needs a person |
 
 <!-- markdownlint-enable MD013 -->
 
@@ -1773,15 +2084,16 @@ when:
   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.
+Refusals are listed beside the work done and do not fail the run. So is every
+row left for a person: each is listed as skipped, with its cause, so an
+operator can see what remains. 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