github-security-report 0.1.0__tar.gz → 0.3.0__tar.gz

{github_security_report-0.1.0 → github_security_report-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-security-report
-Version: 0.1.0
+Version: 0.3.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
@@ -34,9 +34,9 @@ Provides-Extra: dev
 Requires-Dist: mypy==2.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.15.16; extra == 'dev'
+Requires-Dist: ruff==0.15.18; extra == 'dev'
 Requires-Dist: syrupy==5.3.2; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
@@ -70,9 +70,16 @@ states and rendered worst-first:
 
 - **Offenders** — enabled with open findings (a ranked table row).
 - **Clean** — enabled with zero findings (a count beneath the table).
-- **Not enabled** — supported but switched off (a nag list prompting you to
-  enable it).
-- **Unknown** — indeterminate (insufficient permission), footnoted separately.
+- **Not enabled** — supported but switched off (a counted "disabled" footer
+  line, with the affected repositories named).
+- **Unknown** — indeterminate (insufficient permission), counted separately.
+
+Every category renders the same **standardised summary footer** beneath its
+table: remediation-first count lines (failures, disabled, unknown, then the
+healthy pass line, then excluded). The pass line reads **"All <state>"** when
+nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
+stay brevity-first; the explanatory per-category description and documentation
+link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
 
 The single GitHub code-scanning feed is partitioned by `tool.name` into CodeQL,
 Scorecard, and zizmor; Scorecard prefers the external aggregate score and falls
@@ -86,10 +93,14 @@ tables (org mode):
 - **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).
-- **Releases / Tagging** — repositories overdue a release or tag, ranked by a
-  hidden compound staleness score. Repositories younger than
-  `release_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted.
+- **Releases / Tagging** — repositories overdue a release or tag, ranked by
+  release/tag staleness (repository age never affects ordering; a repository
+  with no release or tag ranks highest). Repositories younger than
+  `repo_min_age_days` (default 28; `0` includes all) and those in
+  `releases_exclude` are omitted. A repository is flagged only when its newest
+  release or tag is older than `release_max_age_days` (default 60; `0` flags
+  every eligible repository), so a repository released or tagged within that
+  window counts as recently maintained and drops out of the table.
 
 ## Operating modes
 
@@ -109,11 +120,20 @@ Repo mode needs nothing beyond the workflow's ephemeral `GITHUB_TOKEN`. Org mode
 needs a Personal Access Token; choose **one** of the two options below depending
 on how many organisations the report covers.
 
-All required access is **read-only**. The tool degrades any read it is not
-permitted to make to an "unknown" status rather than reporting a repository as
-clean, so an under-scoped token surfaces as unknowns in the report instead of
+Almost all required access is **read-only**. The tool degrades any read it is
+not permitted to make to an "unknown" status rather than reporting a repository
+as clean, so an under-scoped token surfaces as unknowns in the report instead of
 silently wrong results — start minimal and widen if you see unknowns.
 
+The **one** exception is organisation-ruleset coverage. GitHub gates the
+org-rulesets endpoint behind an org-admin permission (classic `admin:org` scope,
+or fine-grained Administration **write**), even though the tool only reads it.
+That coverage is **optional**: it detects tools enforced through an org ruleset
+(for example a required-workflow or code-scanning ruleset). Without it that one
+signal is skipped and every other part of the report is unaffected, so the
+minimal tokens below omit it. Grant the org-admin permission only if you want
+ruleset-based tool coverage.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -131,14 +151,15 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
-**Organization permissions** (Read-only):
+**Organization permissions:**
 
-| Permission | Used for |
-| ---------- | -------- |
-| Administration | Organisation rulesets (detect tools enabled via a required workflow) |
+| Permission | Access | Used for |
+| ---------- | ------ | -------- |
+| Administration | Read and write | *Optional* — organisation rulesets (detect tools enforced through an org ruleset). GitHub gates this endpoint behind Administration **write**; omit it to keep the token read-only and skip ruleset-based tool coverage. |
 
-> A fine-grained token cannot span organisations. For a report covering more
-> than one org, use a classic PAT (below).
+> Read-only is enough for everything except the optional ruleset coverage
+> above. A fine-grained token cannot span organisations. For a report covering
+> more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
 
@@ -150,7 +171,8 @@ organisations. Grant these scopes:
 | ----- | -------- |
 | `repo` | Repository data, including private repositories |
 | `security_events` | Code scanning, secret scanning, and Dependabot alerts (org-bulk and per-repo) |
-| `read:org` | Listing organisation repositories and reading organisation rulesets |
+| `read:org` | Listing organisation repositories |
+| `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. |
 
 > For organisations that enforce SSO, the PAT must be **SSO-authorised** for
 > each target organisation, or the org-level endpoints return `403` (reported as
@@ -207,7 +229,8 @@ environment-variable name, never embedded.
     "top_n_slack": 10,
     "include_archived": false,
     "include_test": false,
-    "release_min_age_days": 28
+    "repo_min_age_days": 28,
+    "release_max_age_days": 60
   },
   "organizations": [
     {
@@ -226,17 +249,102 @@ environment-variable name, never embedded.
 `top_n` controls how many offenders are shown per signal. It is the shared
 default for all three outputs; set any of `top_n_report` (GitHub Pages),
 `top_n_cli` (terminal), or `top_n_slack` (Slack digest) to override an
-individual output. Each can also be set at the CLI with `--top-n`,
+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.release_min_age_days` (default `28`, `0` = include all) and the per-org
-`releases_exclude` tune the Releases / Tagging section; they can be overridden
-locally with `--release-min-age-days` and the repeatable `--releases-exclude`.
+The Releases / Tagging section has two independent freshness levers:
+
+- `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
+  period that omits **brand-new repositories** — those *created* within that
+  many days — before a release or tag is expected of them. CLI:
+  `--repo-min-age-days`.
+- `report.release_max_age_days` (default `60`; `0` = flag everything) is the
+  release-staleness threshold: a repository is only flagged when its newest
+  release **or** tag is older than that many days (a repository with neither is
+  always flagged). Tune it to match your release cadence so actively released
+  repositories drop out of the table. CLI: `--release-max-age-days`.
+
+The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
+named repositories from the section entirely.
+
+> The former `release_min_age_days` key was a misleading name for
+> `repo_min_age_days` (it gates *repository* age, not *release* age). It is
+> still accepted as a deprecated alias and emits a warning; prefer
+> `repo_min_age_days`.
 
 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.
 
+### Per-category render toggles
+
+Every reporting category can be switched on or off, globally and per output
+surface, under `report.categories`. Data is **always** collected; these toggles
+govern presentation only. Each category key takes an `enabled` switch (highest
+precedence — `false` hides it everywhere) and a lower-precedence `outputs` map
+for the four surfaces (`cli`, `slack`, `markdown`, `html`). Everything defaults
+to `true`, so an omitted category or key stays fully enabled. A category is
+rendered on a surface only when `enabled` **and** that surface's toggle are
+both true.
+
+```json
+{
+  "report": {
+    "categories": {
+      "zizmor": { "enabled": false },
+      "releases": { "outputs": { "cli": false, "slack": false } }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+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`,
+`dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
+`mutable_releases`. 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
+category appears if **any** contributing org would show it on Slack. An org-level
+Slack disable therefore does not suppress a category in a shared-channel digest
+unless every org sharing that channel also disables it (this mirrors the
+most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
+and HTML surfaces are per-org and are not affected by this union.
+
+### Pass/fail severity cutoff
+
+The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use a
+`fail_severity` cutoff to decide when a repository counts as a failure. A
+repository is flagged as an offender only when it carries a finding **at or
+above** the cutoff; findings below it fold into the clean count. Severities run
+(lowest to highest) `informational`, `low`, `medium`, `high`, `critical` —
+`informational` being the new sub-low rung that SARIF `note`/`none` findings
+(the bulk of a tool like Zizmor) normalise to.
+
+The global default cutoff is `medium`, so `low` and `informational` findings
+pass. Zizmor defaults to `low` (only `informational` passes). Override the
+cutoff per category under `report.categories.<key>.fail_severity`:
+
+```json
+{
+  "report": {
+    "categories": {
+      "codeql": { "fail_severity": "low" },
+      "zizmor": { "fail_severity": "informational" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
 `slack.channel` is optional. The action's `slack_channel` input (wired to the
 `SLACK_CHANNEL_ID` variable in `reporting.yaml`) overrides it, so the channel
 can live as an org/repo variable rather than in the config JSON. It must be the
@@ -276,10 +384,10 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `output_dir` | No | — | Directory for Pages output (org mode) |
 | `pages_url` | No | — | Published Pages URL (used in the Slack link) |
 | `slack_channel` | No | — | Slack channel ID; overrides the config `slack.channel` (e.g. the `SLACK_CHANNEL_ID` variable) |
-| `top_n` | No | `10` | Offenders per signal across all outputs (shared default) |
-| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (overrides `top_n`) |
-| `top_n_cli` | No | — | Offenders per signal in the terminal output (overrides `top_n`) |
-| `top_n_slack` | No | — | Offenders per signal in the Slack digest (overrides `top_n`) |
+| `top_n` | No | `10` | Offenders per signal across all outputs (shared default; `0` = no limit) |
+| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (`0` = no limit; overrides `top_n`) |
+| `top_n_cli` | No | — | Offenders per signal in the terminal output (`0` = no limit; overrides `top_n`) |
+| `top_n_slack` | No | — | Offenders per signal in the Slack digest (`0` = no limit; overrides `top_n`) |
 | `fail_threshold` | No | `none` | `none`/`low`/`medium`/`high`/`critical`/`any` (repo mode) |
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `tool_version` | No | `0.1.0` | Published PyPI version (ignored on pull requests) |
@@ -309,6 +417,46 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Bulk Remediation Scripts
+
+The report ends with **nag lists** — repositories where a supported feature is
+switched off. Where GitHub exposes the relevant toggle through its REST API,
+the [`scripts/`](scripts/) directory ships standalone helpers that clear a whole
+nag list in one pass instead of clicking through each repository's settings.
+They reuse the tool's own scoping rules
+([`src/github_security_report/scope.py`](src/github_security_report/scope.py)),
+so they act on exactly the repositories the report does. See
+[`scripts/README.md`](scripts/README.md) for full details.
+
+Each script is a self-contained [PEP 723](https://peps.python.org/pep-0723/)
+program: `uv run` resolves its inline dependencies on the fly — no project
+install required.
+
+### `enable_dependabot_security_updates.py`
+
+Enables **Dependabot security updates** (and the prerequisite alerts) across an
+organisation, clearing the "Dependabot: Security Updates" nag list. It reads
+the current state of each repository, enables the feature where it is off, and
+verifies the result.
+
+```bash
+# An org-admin token is required (classic PAT with repo admin / admin:org).
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+```
+
+`--config` reads the organisation name and exclusions straight from the
+reporting tool's JSON config, so the script and the report never drift. The
+operation is **dry-run by default** (these are privileged writes) and reversible
+via `DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## Development
 
 ```bash

{github_security_report-0.1.0 → github_security_report-0.3.0}/README.md

@@ -26,9 +26,16 @@ states and rendered worst-first:
 
 - **Offenders** — enabled with open findings (a ranked table row).
 - **Clean** — enabled with zero findings (a count beneath the table).
-- **Not enabled** — supported but switched off (a nag list prompting you to
-  enable it).
-- **Unknown** — indeterminate (insufficient permission), footnoted separately.
+- **Not enabled** — supported but switched off (a counted "disabled" footer
+  line, with the affected repositories named).
+- **Unknown** — indeterminate (insufficient permission), counted separately.
+
+Every category renders the same **standardised summary footer** beneath its
+table: remediation-first count lines (failures, disabled, unknown, then the
+healthy pass line, then excluded). The pass line reads **"All <state>"** when
+nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
+stay brevity-first; the explanatory per-category description and documentation
+link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
 
 The single GitHub code-scanning feed is partitioned by `tool.name` into CodeQL,
 Scorecard, and zizmor; Scorecard prefers the external aggregate score and falls
@@ -42,10 +49,14 @@ tables (org mode):
 - **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).
-- **Releases / Tagging** — repositories overdue a release or tag, ranked by a
-  hidden compound staleness score. Repositories younger than
-  `release_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted.
+- **Releases / Tagging** — repositories overdue a release or tag, ranked by
+  release/tag staleness (repository age never affects ordering; a repository
+  with no release or tag ranks highest). Repositories younger than
+  `repo_min_age_days` (default 28; `0` includes all) and those in
+  `releases_exclude` are omitted. A repository is flagged only when its newest
+  release or tag is older than `release_max_age_days` (default 60; `0` flags
+  every eligible repository), so a repository released or tagged within that
+  window counts as recently maintained and drops out of the table.
 
 ## Operating modes
 
@@ -65,11 +76,20 @@ Repo mode needs nothing beyond the workflow's ephemeral `GITHUB_TOKEN`. Org mode
 needs a Personal Access Token; choose **one** of the two options below depending
 on how many organisations the report covers.
 
-All required access is **read-only**. The tool degrades any read it is not
-permitted to make to an "unknown" status rather than reporting a repository as
-clean, so an under-scoped token surfaces as unknowns in the report instead of
+Almost all required access is **read-only**. The tool degrades any read it is
+not permitted to make to an "unknown" status rather than reporting a repository
+as clean, so an under-scoped token surfaces as unknowns in the report instead of
 silently wrong results — start minimal and widen if you see unknowns.
 
+The **one** exception is organisation-ruleset coverage. GitHub gates the
+org-rulesets endpoint behind an org-admin permission (classic `admin:org` scope,
+or fine-grained Administration **write**), even though the tool only reads it.
+That coverage is **optional**: it detects tools enforced through an org ruleset
+(for example a required-workflow or code-scanning ruleset). Without it that one
+signal is skipped and every other part of the report is unaffected, so the
+minimal tokens below omit it. Grant the org-admin permission only if you want
+ruleset-based tool coverage.
+
 ### Single organisation — fine-grained PAT
 
 A fine-grained PAT is bound to one resource owner, so it works for a report
@@ -87,14 +107,15 @@ organisation and **Repository access** set to *All repositories*, then grant:
 | Secret scanning alerts | Open secret-scanning alerts |
 | Administration | Dependabot enablement + security-updates status, and effective branch rules |
 
-**Organization permissions** (Read-only):
+**Organization permissions:**
 
-| Permission | Used for |
-| ---------- | -------- |
-| Administration | Organisation rulesets (detect tools enabled via a required workflow) |
+| Permission | Access | Used for |
+| ---------- | ------ | -------- |
+| Administration | Read and write | *Optional* — organisation rulesets (detect tools enforced through an org ruleset). GitHub gates this endpoint behind Administration **write**; omit it to keep the token read-only and skip ruleset-based tool coverage. |
 
-> A fine-grained token cannot span organisations. For a report covering more
-> than one org, use a classic PAT (below).
+> Read-only is enough for everything except the optional ruleset coverage
+> above. A fine-grained token cannot span organisations. For a report covering
+> more than one org, use a classic PAT (below).
 
 ### Multiple organisations — classic PAT
 
@@ -106,7 +127,8 @@ organisations. Grant these scopes:
 | ----- | -------- |
 | `repo` | Repository data, including private repositories |
 | `security_events` | Code scanning, secret scanning, and Dependabot alerts (org-bulk and per-repo) |
-| `read:org` | Listing organisation repositories and reading organisation rulesets |
+| `read:org` | Listing organisation repositories |
+| `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. |
 
 > For organisations that enforce SSO, the PAT must be **SSO-authorised** for
 > each target organisation, or the org-level endpoints return `403` (reported as
@@ -163,7 +185,8 @@ environment-variable name, never embedded.
     "top_n_slack": 10,
     "include_archived": false,
     "include_test": false,
-    "release_min_age_days": 28
+    "repo_min_age_days": 28,
+    "release_max_age_days": 60
   },
   "organizations": [
     {
@@ -182,17 +205,102 @@ environment-variable name, never embedded.
 `top_n` controls how many offenders are shown per signal. It is the shared
 default for all three outputs; set any of `top_n_report` (GitHub Pages),
 `top_n_cli` (terminal), or `top_n_slack` (Slack digest) to override an
-individual output. Each can also be set at the CLI with `--top-n`,
+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.release_min_age_days` (default `28`, `0` = include all) and the per-org
-`releases_exclude` tune the Releases / Tagging section; they can be overridden
-locally with `--release-min-age-days` and the repeatable `--releases-exclude`.
+The Releases / Tagging section has two independent freshness levers:
+
+- `report.repo_min_age_days` (default `28`, `0` = include all) is a grace
+  period that omits **brand-new repositories** — those *created* within that
+  many days — before a release or tag is expected of them. CLI:
+  `--repo-min-age-days`.
+- `report.release_max_age_days` (default `60`; `0` = flag everything) is the
+  release-staleness threshold: a repository is only flagged when its newest
+  release **or** tag is older than that many days (a repository with neither is
+  always flagged). Tune it to match your release cadence so actively released
+  repositories drop out of the table. CLI: `--release-max-age-days`.
+
+The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
+named repositories from the section entirely.
+
+> The former `release_min_age_days` key was a misleading name for
+> `repo_min_age_days` (it gates *repository* age, not *release* age). It is
+> still accepted as a deprecated alias and emits a warning; prefer
+> `repo_min_age_days`.
 
 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.
 
+### Per-category render toggles
+
+Every reporting category can be switched on or off, globally and per output
+surface, under `report.categories`. Data is **always** collected; these toggles
+govern presentation only. Each category key takes an `enabled` switch (highest
+precedence — `false` hides it everywhere) and a lower-precedence `outputs` map
+for the four surfaces (`cli`, `slack`, `markdown`, `html`). Everything defaults
+to `true`, so an omitted category or key stays fully enabled. A category is
+rendered on a surface only when `enabled` **and** that surface's toggle are
+both true.
+
+```json
+{
+  "report": {
+    "categories": {
+      "zizmor": { "enabled": false },
+      "releases": { "outputs": { "cli": false, "slack": false } }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+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`,
+`dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
+`mutable_releases`. 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
+category appears if **any** contributing org would show it on Slack. An org-level
+Slack disable therefore does not suppress a category in a shared-channel digest
+unless every org sharing that channel also disables it (this mirrors the
+most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
+and HTML surfaces are per-org and are not affected by this union.
+
+### Pass/fail severity cutoff
+
+The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use a
+`fail_severity` cutoff to decide when a repository counts as a failure. A
+repository is flagged as an offender only when it carries a finding **at or
+above** the cutoff; findings below it fold into the clean count. Severities run
+(lowest to highest) `informational`, `low`, `medium`, `high`, `critical` —
+`informational` being the new sub-low rung that SARIF `note`/`none` findings
+(the bulk of a tool like Zizmor) normalise to.
+
+The global default cutoff is `medium`, so `low` and `informational` findings
+pass. Zizmor defaults to `low` (only `informational` passes). Override the
+cutoff per category under `report.categories.<key>.fail_severity`:
+
+```json
+{
+  "report": {
+    "categories": {
+      "codeql": { "fail_severity": "low" },
+      "zizmor": { "fail_severity": "informational" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
 `slack.channel` is optional. The action's `slack_channel` input (wired to the
 `SLACK_CHANNEL_ID` variable in `reporting.yaml`) overrides it, so the channel
 can live as an org/repo variable rather than in the config JSON. It must be the
@@ -232,10 +340,10 @@ and the Slack **bot token** is consumed by the workflow, not the CLI.
 | `output_dir` | No | — | Directory for Pages output (org mode) |
 | `pages_url` | No | — | Published Pages URL (used in the Slack link) |
 | `slack_channel` | No | — | Slack channel ID; overrides the config `slack.channel` (e.g. the `SLACK_CHANNEL_ID` variable) |
-| `top_n` | No | `10` | Offenders per signal across all outputs (shared default) |
-| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (overrides `top_n`) |
-| `top_n_cli` | No | — | Offenders per signal in the terminal output (overrides `top_n`) |
-| `top_n_slack` | No | — | Offenders per signal in the Slack digest (overrides `top_n`) |
+| `top_n` | No | `10` | Offenders per signal across all outputs (shared default; `0` = no limit) |
+| `top_n_report` | No | — | Offenders per signal in the GitHub Pages output (`0` = no limit; overrides `top_n`) |
+| `top_n_cli` | No | — | Offenders per signal in the terminal output (`0` = no limit; overrides `top_n`) |
+| `top_n_slack` | No | — | Offenders per signal in the Slack digest (`0` = no limit; overrides `top_n`) |
 | `fail_threshold` | No | `none` | `none`/`low`/`medium`/`high`/`critical`/`any` (repo mode) |
 | `force_notify` | No | `false` | Post to Slack regardless of `report_day` |
 | `tool_version` | No | `0.1.0` | Published PyPI version (ignored on pull requests) |
@@ -265,6 +373,46 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Bulk Remediation Scripts
+
+The report ends with **nag lists** — repositories where a supported feature is
+switched off. Where GitHub exposes the relevant toggle through its REST API,
+the [`scripts/`](scripts/) directory ships standalone helpers that clear a whole
+nag list in one pass instead of clicking through each repository's settings.
+They reuse the tool's own scoping rules
+([`src/github_security_report/scope.py`](src/github_security_report/scope.py)),
+so they act on exactly the repositories the report does. See
+[`scripts/README.md`](scripts/README.md) for full details.
+
+Each script is a self-contained [PEP 723](https://peps.python.org/pep-0723/)
+program: `uv run` resolves its inline dependencies on the fly — no project
+install required.
+
+### `enable_dependabot_security_updates.py`
+
+Enables **Dependabot security updates** (and the prerequisite alerts) across an
+organisation, clearing the "Dependabot: Security Updates" nag list. It reads
+the current state of each repository, enables the feature where it is off, and
+verifies the result.
+
+```bash
+# An org-admin token is required (classic PAT with repo admin / admin:org).
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+```
+
+`--config` reads the organisation name and exclusions straight from the
+reporting tool's JSON config, so the script and the report never drift. The
+operation is **dry-run by default** (these are privileged writes) and reversible
+via `DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## Development
 
 ```bash

{github_security_report-0.1.0 → github_security_report-0.3.0}/pyproject.toml

@@ -59,13 +59,13 @@ Issues = "https://github.com/lfreleng-actions/github-security-report-action/issu
 
 [project.optional-dependencies]
 dev = [
-  "pytest==9.0.3",
+  "pytest==9.1.1",
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==5.3.2",
   "mypy==2.1.0",
-  "ruff==0.15.16",
+  "ruff==0.15.18",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -91,13 +91,13 @@ include = ["src", "README.md", "LICENSE*", "pyproject.toml"]
 
 [dependency-groups]
 dev = [
-  "pytest==9.0.3",
+  "pytest==9.1.1",
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
   "syrupy==5.3.2",
   "mypy==2.1.0",
-  "ruff==0.15.16",
+  "ruff==0.15.18",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]

{github_security_report-0.1.0 → github_security_report-0.3.0}/scripts/README.md

@@ -5,6 +5,58 @@
 
 # Scripts
 
+## `enable_dependabot_security_updates.py`
+
+Bulk-enables **Dependabot security updates** across an organisation, clearing
+the "Dependabot: Security Updates" nag list the reporting tool produces. It
+drives three REST endpoints per repository:
+
+- `PUT /repos/{owner}/{repo}/vulnerability-alerts` — Dependabot *alerts* (the
+  prerequisite; idempotent).
+- `PUT /repos/{owner}/{repo}/automated-security-fixes` — Dependabot *security
+  updates*.
+- `GET /repos/{owner}/{repo}/automated-security-fixes` — current state, read
+  before and after each change.
+
+By default the scope matches the reporting tool (it reuses the same fork /
+template / archived / test-name / explicit-exclude rules from
+[`../src/github_security_report/scope.py`](../src/github_security_report/scope.py)),
+and likewise skips empty repositories, which the reporting tool already drops
+at the listing stage. The `--include-empty` flag deliberately widens that scope
+to act on empty repositories the report never includes. Pass `--config` to read
+the org name and exclusions straight from the tool's JSON config so the two
+never drift.
+
+It is a self-contained [PEP 723](https://peps.python.org/pep-0723/) script; `uv`
+resolves its inline dependencies (`httpx`, `rich`) on the fly.
+
+### Run
+
+```bash
+# An org-admin token is required (e.g. a classic PAT with repo admin /
+# admin:org). The god token export publishes it as $GITHUB_TOKEN:
+source ~/.secrets.github.classic.god
+
+# Dry run (default): previews exactly what would change, touches nothing.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json
+
+# Apply: switch the feature on for every in-scope repository.
+uv run scripts/enable_dependabot_security_updates.py \
+  --config ~/.config/github-security-report/config.json --apply
+
+# Or drive it from flags, with a different token variable:
+uv run scripts/enable_dependabot_security_updates.py \
+  --org lfreleng-actions --token-env SECURITY_REPORT_PAT \
+  --exclude project-reporting-artifacts --apply
+```
+
+**Dry-run by default.** These are privileged writes, so the script previews
+unless you pass `--apply`. Useful extra flags: `--repo` (operate on named repos
+only, skipping scope), `--limit N`, and `--include-archived` /
+`--include-test` / `--include-empty`. The operation is reversible via
+`DELETE /repos/{owner}/{repo}/automated-security-fixes`.
+
 ## `phase0_capability_spike.py` (throwaway)
 
 A self-contained [PEP 723](https://peps.python.org/pep-0723/) spike that