github-security-report 0.5.0__tar.gz → 0.6.0__tar.gz

{github_security_report-0.5.0 → github_security_report-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-security-report
-Version: 0.5.0
+Version: 0.6.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
@@ -29,7 +29,7 @@ Requires-Dist: jinja2==3.1.6
 Requires-Dist: jsonschema==4.26.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: rich==15.0.0
-Requires-Dist: typer==0.26.7
+Requires-Dist: typer==0.26.8
 Provides-Extra: dev
 Requires-Dist: mypy==2.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
@@ -37,7 +37,7 @@ Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
 Requires-Dist: ruff==0.15.20; extra == 'dev'
-Requires-Dist: syrupy==5.3.3; extra == 'dev'
+Requires-Dist: syrupy==5.3.4; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -335,8 +335,11 @@ The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use 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.
+`informational` being the sub-low rung for SARIF `none` findings and
+unclassifiable alerts. Zizmor's SARIF `note` findings normalise to `low`
+(zizmor emits its Low findings at `note`, and the organisation scan pipeline's
+`--min-severity low` floor keeps informational findings out of the uploaded
+SARIF), matching the ruleset-enforced PR gate that blocks on note-and-above.
 
 The global default cutoff is `medium`, so `low` and `informational` findings
 pass. Zizmor defaults to `low` (only `informational` passes). Override the
@@ -426,8 +429,57 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Remediation
+
+The `remediate` subcommand is the in-tool counterpart to the report: it runs the
+same collection, then switches on each selected security feature wherever a
+repository has it **confirmed off**. Only the offenders the report already
+surfaces are acted on — repositories whose state could not be read are counted
+as *unknown* and are never written to, so remediation never blind-writes.
+
+It is **dry run by default** (these are privileged writes); pass `--apply` to
+make changes. A single **write-capable** org-admin token (from `--token-env`,
+default `GITHUB_TOKEN`) drives both the read and the writes across every
+configured organisation, so it bypasses the per-org read-only `token_env` in the
+config.
+
+```bash
+# An org-admin token is required: a classic PAT with the `repo` scope
+# (administers repository security settings) plus `read:org` to enumerate repos.
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uvx github-security-report remediate --org lfreleng-actions
+
+# Apply: enable every remediable feature that is off, across all configured orgs.
+uvx github-security-report remediate \
+  --config ~/.config/github-security-report/config.json --apply
+
+# Limit to specific categories (repeatable).
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql --category private_vulnerability_reporting --apply
+```
+
+The remediable categories are the simple on/off features with a documented
+enablement endpoint:
+
+| `--category` | Enables |
+|---|---|
+| `codeql` | CodeQL default setup (provisioned asynchronously) |
+| `secret_scanning` | Secret scanning |
+| `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
+| `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
+| `private_vulnerability_reporting` | Private vulnerability reporting |
+
+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).
+
 ## Bulk Remediation Scripts
 
+The standalone scripts below predate the `remediate` subcommand and remain for
+ad-hoc, single-feature runs. For most workflows, prefer `remediate` above.
+
 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
@@ -449,7 +501,8 @@ 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).
+# An org-admin token is required: a classic PAT with the `repo` scope
+# (administers repository security settings) plus `read:org` to enumerate repos.
 source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
 
 # Dry run (default): preview every change, touch nothing.

{github_security_report-0.5.0 → github_security_report-0.6.0}/README.md

@@ -291,8 +291,11 @@ The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use 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.
+`informational` being the sub-low rung for SARIF `none` findings and
+unclassifiable alerts. Zizmor's SARIF `note` findings normalise to `low`
+(zizmor emits its Low findings at `note`, and the organisation scan pipeline's
+`--min-severity low` floor keeps informational findings out of the uploaded
+SARIF), matching the ruleset-enforced PR gate that blocks on note-and-above.
 
 The global default cutoff is `medium`, so `low` and `informational` findings
 pass. Zizmor defaults to `low` (only `informational` passes). Override the
@@ -382,8 +385,57 @@ uvx github-security-report report
 uvx github-security-report report --org lfreleng-actions
 ```
 
+## Remediation
+
+The `remediate` subcommand is the in-tool counterpart to the report: it runs the
+same collection, then switches on each selected security feature wherever a
+repository has it **confirmed off**. Only the offenders the report already
+surfaces are acted on — repositories whose state could not be read are counted
+as *unknown* and are never written to, so remediation never blind-writes.
+
+It is **dry run by default** (these are privileged writes); pass `--apply` to
+make changes. A single **write-capable** org-admin token (from `--token-env`,
+default `GITHUB_TOKEN`) drives both the read and the writes across every
+configured organisation, so it bypasses the per-org read-only `token_env` in the
+config.
+
+```bash
+# An org-admin token is required: a classic PAT with the `repo` scope
+# (administers repository security settings) plus `read:org` to enumerate repos.
+source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
+
+# Dry run (default): preview every change, touch nothing.
+uvx github-security-report remediate --org lfreleng-actions
+
+# Apply: enable every remediable feature that is off, across all configured orgs.
+uvx github-security-report remediate \
+  --config ~/.config/github-security-report/config.json --apply
+
+# Limit to specific categories (repeatable).
+uvx github-security-report remediate --org lfreleng-actions \
+  --category codeql --category private_vulnerability_reporting --apply
+```
+
+The remediable categories are the simple on/off features with a documented
+enablement endpoint:
+
+| `--category` | Enables |
+|---|---|
+| `codeql` | CodeQL default setup (provisioned asynchronously) |
+| `secret_scanning` | Secret scanning |
+| `dependabot_alerts_enabled` | Dependabot vulnerability alerts |
+| `dependabot_updates_enabled` | Dependabot security updates (plus alerts) |
+| `private_vulnerability_reporting` | Private vulnerability reporting |
+
+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).
+
 ## Bulk Remediation Scripts
 
+The standalone scripts below predate the `remediate` subcommand and remain for
+ad-hoc, single-feature runs. For most workflows, prefer `remediate` above.
+
 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
@@ -405,7 +457,8 @@ 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).
+# An org-admin token is required: a classic PAT with the `repo` scope
+# (administers repository security settings) plus `read:org` to enumerate repos.
 source ~/.secrets.github.classic.god   # exports $GITHUB_TOKEN
 
 # Dry run (default): preview every change, touch nothing.

{github_security_report-0.5.0 → github_security_report-0.6.0}/pyproject.toml

@@ -45,7 +45,7 @@ keywords = [
 ]
 dependencies = [
   "httpx[http2]==0.28.1",
-  "typer==0.26.7",
+  "typer==0.26.8",
   "rich==15.0.0",
   "jinja2==3.1.6",
   "jsonschema==4.26.0",
@@ -63,7 +63,7 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==5.3.3",
+  "syrupy==5.3.4",
   "mypy==2.1.0",
   "ruff==0.15.20",
   "types-jsonschema==4.26.0.20260518",
@@ -95,7 +95,7 @@ dev = [
   "pytest-asyncio==1.4.0",
   "pytest-cov==7.1.0",
   "respx==0.23.1",
-  "syrupy==5.3.3",
+  "syrupy==5.3.4",
   "mypy==2.1.0",
   "ruff==0.15.20",
   "types-jsonschema==4.26.0.20260518",

{github_security_report-0.5.0 → github_security_report-0.6.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.5.0'
-__version_tuple__ = version_tuple = (0, 5, 0)
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.5.0 → github_security_report-0.6.0}/src/github_security_report/categories.py

@@ -105,8 +105,9 @@ _CATEGORIES: dict[CategoryKey, CategoryMeta] = {
             "Zizmor static analysis of GitHub Actions workflows, ranked "
             "worst-first by severity."
         ),
-        # Zizmor's advisory "note" findings normalise to informational; only
-        # those pass. A low-or-higher zizmor finding is treated as a failure.
+        # zizmor emits its Low findings at SARIF level "note", which
+        # normalises to LOW (see severity.py), so any zizmor finding fails --
+        # matching the ruleset-enforced PR gate that blocks on note-and-above.
         fail_severity=Severity.LOW,
     ),
     CategoryKey.DEPENDABOT_ALERTS: CategoryMeta(

{github_security_report-0.5.0 → github_security_report-0.6.0}/src/github_security_report/cli.py

@@ -17,7 +17,7 @@ import logging
 import os
 import re
 import sys
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Mapping, Sequence
 from dataclasses import replace
 from pathlib import Path
 from typing import NoReturn
@@ -26,6 +26,7 @@ import typer
 from rich.console import Console
 
 from github_security_report import __version__, collect, config, gitctx, runner
+from github_security_report import remediate as remediate_mod
 from github_security_report.categories import CategoryKey
 from github_security_report.client import GitHubClient, NetworkError
 from github_security_report.config import Config, OrgConfig, ReportConfig
@@ -423,6 +424,43 @@ async def _run_repo(owner: str, repo_name: str, *, token_env: str, console: Cons
     return 0
 
 
+async def _run_remediate(
+    cfg: Config,
+    *,
+    console: Console,
+    token: str,
+    categories: Sequence[CategoryKey],
+    apply: bool,
+) -> 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.
+    """
+    now = dt.datetime.now(dt.timezone.utc)
+    failures = 0
+    async with GitHubClient(token) as client:
+        for org_cfg in cfg.organizations:
+            report = await collect.collect_org(
+                client, org_cfg, org_cfg.report, generated_at=now
+            )
+            results = await remediate_mod.remediate_org(
+                client, report, categories=categories, apply=apply
+            )
+            # Honour the org's configured terminal offender limit, the same
+            # cap the report's CLI output uses, so large orgs stay readable.
+            term_render.render_remediation(
+                report.org,
+                results,
+                console,
+                apply=apply,
+                top_n=org_cfg.report.cli_top_n,
+            )
+            failures += sum(result.failures for result in results)
+    return 1 if failures else 0
+
+
 def _repo_outputs(signals: list[RepoSignal], fail_threshold: str) -> dict[str, str]:
     outputs = {s.signal.value + "_open": str(s.counts.total) for s in signals}
     outputs["failed"] = "true" if runner.should_fail(signals, fail_threshold) else "false"
@@ -540,5 +578,75 @@ def report(
     raise typer.Exit(code)
 
 
+@app.command()
+def remediate(
+    config_file: str | None = typer.Option(None, "--config", "-c", help="Path to a JSON config file."),
+    config_data: str | None = typer.Option(None, "--config-data", help="Raw or base64 JSON config (vars/secrets)."),
+    org: str | None = typer.Option(None, "--org", help="Single organisation (shorthand for org mode)."),
+    scope: str = typer.Option("org", "--scope", help="Only 'org' is supported; remediation is organisation-scoped."),
+    category: list[str] | None = typer.Option(None, "--category", help="Remediable category to act on (repeatable; default: all). One of: codeql, secret_scanning, dependabot_alerts_enabled, dependabot_updates_enabled, private_vulnerability_reporting."),
+    token_env: str = typer.Option("GITHUB_TOKEN", "--token-env", help="Env var holding a WRITE-capable org-admin PAT. Used for both reading posture and enabling features across every configured org."),
+    apply: bool = typer.Option(False, "--apply", help="Perform the writes. Without this flag remediate only previews (dry run)."),
+    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.
+    """
+    plain = no_color or bool(os.environ.get("CI")) or not sys.stdout.isatty()
+    console = Console(no_color=plain, highlight=False)
+
+    if scope != "org":
+        console.print("[red]remediate supports only --scope org[/red]")
+        raise typer.Exit(2)
+
+    keys, unknown = remediate_mod.parse_categories(category or [])
+    if unknown:
+        valid = ", ".join(key.value for key in remediate_mod.REMEDIABLE)
+        # markup=False: the user-supplied --category values are printed
+        # literally, so bracketed input cannot be interpreted as Rich markup.
+        console.print(
+            f"Unknown --category: {', '.join(unknown)}. Valid values: {valid}",
+            style="red",
+            markup=False,
+        )
+        raise typer.Exit(2)
+    categories = keys or list(remediate_mod.REMEDIABLE)
+
+    cfg = _load_config(config_file, config_data, org, token_env, console=console)
+    if cfg is None:
+        console.print(
+            "[red]No configuration: provide --config, --config-data or --org.[/red]"
+        )
+        raise typer.Exit(2)
+
+    token = os.environ.get(token_env, "").strip()
+    if not token:
+        # markup=False guards the user-supplied --token-env value.
+        console.print(
+            f"No token in ${token_env} (a write-capable org-admin PAT is required).",
+            style="red",
+            markup=False,
+        )
+        raise typer.Exit(2)
+
+    try:
+        code = asyncio.run(
+            _run_remediate(
+                cfg,
+                console=console,
+                token=token,
+                categories=categories,
+                apply=apply,
+            )
+        )
+    except NetworkError as exc:
+        _abort_network(console, exc)
+    raise typer.Exit(code)
+
+
 if __name__ == "__main__":  # pragma: no cover
     app()

{github_security_report-0.5.0 → github_security_report-0.6.0}/src/github_security_report/client.py

@@ -782,6 +782,129 @@ class GitHubClient:
         await resp.aclose()  # release the connection once the body is read
         return bool(data.get("enabled"))
 
+    # ------------------------------------------------------------------ #
+    # Remediation writes (enable a feature on one repository)
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _write_note(resp: httpx.Response) -> str:
+        """A short ``"<status> <body>"`` note for a failed write (truncated).
+
+        Only the first slice of the body is processed: the body is capped at 80
+        characters (after a short numeric status prefix), so normalising the
+        whole body -- which may be a large HTML or JSON error page -- would
+        allocate for output that is discarded anyway.
+        """
+        body = " ".join(resp.text[:200].split())
+        return f"{resp.status_code} {body[:80]}".strip()
+
+    async def enable_dependabot_alerts(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]:
+        """Enable Dependabot vulnerability alerts. Returns ``(ok, note)``.
+
+        ``PUT .../vulnerability-alerts`` is idempotent and returns ``204``; any
+        other status is a failure whose note carries the status and body.
+        """
+        resp = await self._request(
+            "PUT", f"{self._api_url}/repos/{org}/{repo}/vulnerability-alerts"
+        )
+        ok = resp.status_code == 204
+        note = "" if ok else self._write_note(resp)
+        await resp.aclose()
+        return ok, note
+
+    async def enable_dependabot_security_updates(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]:
+        """Enable Dependabot security updates. Returns ``(ok, note)``.
+
+        Alerts are the prerequisite, so they are enabled first (idempotent
+        ``204``); then ``PUT .../automated-security-fixes`` (``204``). Either
+        step failing aborts and returns that step's status note.
+        """
+        ok, note = await self.enable_dependabot_alerts(org, repo)
+        if not ok:
+            return False, f"vulnerability-alerts -> {note}"
+        resp = await self._request(
+            "PUT", f"{self._api_url}/repos/{org}/{repo}/automated-security-fixes"
+        )
+        fixed = resp.status_code == 204
+        fnote = (
+            ""
+            if fixed
+            else f"automated-security-fixes -> {self._write_note(resp)}"
+        )
+        await resp.aclose()
+        return fixed, fnote
+
+    async def enable_private_vulnerability_reporting(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]:
+        """Enable private vulnerability reporting (``PUT``, ``204``).
+
+        Returns ``(ok, note)``; a classic PAT needs the ``repo`` scope (write).
+        """
+        resp = await self._request(
+            "PUT",
+            f"{self._api_url}/repos/{org}/{repo}/private-vulnerability-reporting",
+        )
+        ok = resp.status_code == 204
+        note = "" if ok else self._write_note(resp)
+        await resp.aclose()
+        return ok, note
+
+    async def enable_codeql_default_setup(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]:
+        """Enable CodeQL default setup. Returns ``(ok, note)``.
+
+        ``PATCH .../code-scanning/default-setup`` with ``{"state":
+        "configured"}`` usually provisions a scan asynchronously and returns
+        ``202`` with a run URL, but can also return ``200`` when the update is
+        applied synchronously; both are treated as success. A ``202`` means
+        "accepted", not "already scanning", so it keeps an async hint.
+        Repositories with no CodeQL-supported languages, or with Actions
+        disabled, return a 4xx; those are reported as failures but are
+        non-fatal to the rest of the run.
+        """
+        resp = await self._request(
+            "PATCH",
+            f"{self._api_url}/repos/{org}/{repo}/code-scanning/default-setup",
+            json={"state": "configured"},
+        )
+        ok = resp.status_code in (200, 202)
+        if not ok:
+            note = self._write_note(resp)
+        elif resp.status_code == 202:
+            note = "accepted (async)"
+        else:
+            note = ""
+        await resp.aclose()
+        return ok, note
+
+    async def enable_secret_scanning(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]:
+        """Enable secret scanning. Returns ``(ok, note)``.
+
+        ``PATCH /repos/{o}/{r}`` with the repository's ``security_and_analysis``
+        block returns the updated repository (``200``); any other status is a
+        failure whose note carries the status and body.
+        """
+        resp = await self._request(
+            "PATCH",
+            f"{self._api_url}/repos/{org}/{repo}",
+            json={
+                "security_and_analysis": {
+                    "secret_scanning": {"status": "enabled"},
+                },
+            },
+        )
+        ok = resp.status_code == 200
+        note = "" if ok else self._write_note(resp)
+        await resp.aclose()
+        return ok, note
+
     async def repo_graph_batch(
         self, org: str, names: list[str]
     ) -> dict[str, RepoGraphData]:

github_security_report-0.6.0/src/github_security_report/remediate.py

@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Remediation: switch on security features that repositories lack.
+
+The report identifies repositories where a remediable security feature is off.
+This module turns those features on via the GitHub REST API, acting only on the
+confirmed-off, in-scope offenders the report already surfaced -- never on
+repositories whose state could not be read (those are counted as *unknown* and
+never appear as offenders, so the collection step doubles as the "read state"
+that the never-blind-write rule requires). It is dry-run oriented: the CLI
+previews the work by default and writes only when asked to apply.
+
+The set of remediable categories is deliberately narrower than the report. Only
+categories that are a simple on/off feature with a documented enablement
+endpoint are here; qualitative findings (Scorecard, zizmor, open alerts,
+cooldown, release freshness/mutability) are reported but not auto-remediated.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from github_security_report.categories import (
+    CategoryKey,
+    CategoryMeta,
+    category_meta,
+)
+from github_security_report.models import Repo, SignalType
+from github_security_report.report import OrgReport, TableSection
+
+
+class RemediationClient(Protocol):
+    """The write surface a remediator needs (a subset of ``GitHubClient``).
+
+    Each method enables one feature on one repository and returns
+    ``(ok, note)``: ``ok`` is whether the write succeeded, and ``note`` carries
+    a short diagnostic (an error status/body on failure, or a hint such as
+    ``"accepted (async)"`` on success). Tests supply an in-memory fake.
+    """
+
+    async def enable_dependabot_alerts(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]: ...
+
+    async def enable_dependabot_security_updates(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]: ...
+
+    async def enable_private_vulnerability_reporting(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]: ...
+
+    async def enable_codeql_default_setup(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]: ...
+
+    async def enable_secret_scanning(
+        self, org: str, repo: str
+    ) -> tuple[bool, str]: ...
+
+
+# Actions a repository outcome can carry. "would enable" is the dry-run preview;
+# "enabled" and "FAILED" are the two terminal states after an apply.
+_WOULD_ENABLE = "would enable"
+_ENABLED = "enabled"
+_FAILED = "FAILED"
+
+
+@dataclass(frozen=True)
+class RepoOutcome:
+    """The result of (planning to) enable one feature on one repository."""
+
+    name: str
+    action: str  # "would enable" | "enabled" | "FAILED"
+    note: str = ""
+
+    @property
+    def failed(self) -> bool:
+        return self.action == _FAILED
+
+
+@dataclass(frozen=True)
+class CategoryRemediation:
+    """Every repository outcome for one remediated category."""
+
+    category: CategoryMeta
+    outcomes: tuple[RepoOutcome, ...]
+
+    @property
+    def failures(self) -> int:
+        return sum(1 for o in self.outcomes if o.failed)
+
+
+# --------------------------------------------------------------------------- #
+# Offender extraction
+# --------------------------------------------------------------------------- #
+def _nag_offenders(signal: SignalType) -> Callable[[OrgReport], list[Repo]]:
+    """Offenders for a signal category: its NAG (feature-disabled) repos."""
+
+    def _get(report: OrgReport) -> list[Repo]:
+        return [
+            repo
+            for section in report.sections
+            if section.signal is signal
+            for repo in section.nag_repos
+        ]
+
+    return _get
+
+
+def _find_table(report: OrgReport, key: CategoryKey) -> TableSection | None:
+    """The posture table for ``key`` (Dependabot sub-tables or the PVR table)."""
+    candidates = list(report.dependabot_tables)
+    if report.private_vulnerability_reporting is not None:
+        candidates.append(report.private_vulnerability_reporting)
+    for table in candidates:
+        if table.category.key is key:
+            return table
+    return None
+
+
+def _table_offenders(key: CategoryKey) -> Callable[[OrgReport], list[Repo]]:
+    """Offenders for a posture-table category: the table's listed repos."""
+
+    def _get(report: OrgReport) -> list[Repo]:
+        table = _find_table(report, key)
+        return [row.repo for row in table.rows] if table is not None else []
+
+    return _get
+
+
+# --------------------------------------------------------------------------- #
+# Registry
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class _Remediator:
+    key: CategoryKey
+    offenders: Callable[[OrgReport], list[Repo]]
+    enable: Callable[[RemediationClient, str, str], Awaitable[tuple[bool, str]]]
+
+
+_REMEDIATORS: tuple[_Remediator, ...] = (
+    _Remediator(
+        CategoryKey.CODEQL,
+        _nag_offenders(SignalType.CODEQL),
+        lambda c, o, r: c.enable_codeql_default_setup(o, r),
+    ),
+    _Remediator(
+        CategoryKey.SECRET_SCANNING,
+        _nag_offenders(SignalType.SECRET_SCANNING),
+        lambda c, o, r: c.enable_secret_scanning(o, r),
+    ),
+    _Remediator(
+        CategoryKey.DEPENDABOT_ALERTS_ENABLED,
+        _table_offenders(CategoryKey.DEPENDABOT_ALERTS_ENABLED),
+        lambda c, o, r: c.enable_dependabot_alerts(o, r),
+    ),
+    _Remediator(
+        CategoryKey.DEPENDABOT_UPDATES_ENABLED,
+        _table_offenders(CategoryKey.DEPENDABOT_UPDATES_ENABLED),
+        lambda c, o, r: c.enable_dependabot_security_updates(o, r),
+    ),
+    _Remediator(
+        CategoryKey.PRIVATE_VULNERABILITY_REPORTING,
+        _table_offenders(CategoryKey.PRIVATE_VULNERABILITY_REPORTING),
+        lambda c, o, r: c.enable_private_vulnerability_reporting(o, r),
+    ),
+)
+
+_BY_KEY: dict[CategoryKey, _Remediator] = {r.key: r for r in _REMEDIATORS}
+
+# The remediable category keys, in the order they are acted on and rendered.
+REMEDIABLE: tuple[CategoryKey, ...] = tuple(r.key for r in _REMEDIATORS)
+
+
+def parse_categories(values: Iterable[str]) -> tuple[list[CategoryKey], list[str]]:
+    """Map user-supplied category strings to keys.
+
+    Returns ``(keys, unknown)``: the resolved remediable keys (de-duplicated,
+    input order preserved) and any values that are not remediable category
+    names. The caller reports ``unknown`` and, when it is empty, acts on
+    ``keys`` (or every remediable category when the user selected none).
+    """
+    valid = {key.value: key for key in REMEDIABLE}
+    keys: list[CategoryKey] = []
+    unknown: list[str] = []
+    for value in values:
+        key = valid.get(value)
+        if key is None:
+            unknown.append(value)
+        elif key not in keys:
+            keys.append(key)
+    return keys, unknown
+
+
+async def remediate_org(
+    client: RemediationClient,
+    report: OrgReport,
+    *,
+    categories: Sequence[CategoryKey] | None = None,
+    apply: bool,
+) -> list[CategoryRemediation]:
+    """Enable (or, in dry run, preview enabling) features across one org report.
+
+    Acts on every selected category (defaulting to all remediable categories),
+    in the canonical :data:`REMEDIABLE` order. In dry run every offender yields
+    a ``"would enable"`` outcome and no write is issued; with ``apply`` each
+    offender is written and yields ``"enabled"`` or ``"FAILED"`` with the
+    write's diagnostic note. Categories are always represented (with an empty
+    outcome list when they have no offenders) so the renderer can show that a
+    selected category had nothing to do.
+
+    Raises :class:`ValueError` if ``categories`` contains a key that is not
+    remediable, rather than failing later with an opaque ``KeyError``.
+    Duplicate keys are collapsed so a feature is never enabled twice in a run.
+    """
+    requested = list(categories) if categories is not None else list(REMEDIABLE)
+    invalid = [key for key in requested if key not in _BY_KEY]
+    if invalid:
+        names = ", ".join(key.value for key in invalid)
+        raise ValueError(f"not remediable: {names}")
+    # De-duplicate (a caller may repeat a key) while preserving first-seen
+    # order; the canonical sort below then fixes the acting/rendering order.
+    selected: list[CategoryKey] = []
+    for key in requested:
+        if key not in selected:
+            selected.append(key)
+    order = {rem.key: i for i, rem in enumerate(_REMEDIATORS)}
+    results: list[CategoryRemediation] = []
+    for key in sorted(selected, key=lambda k: order[k]):
+        rem = _BY_KEY[key]
+        outcomes: list[RepoOutcome] = []
+        for repo in rem.offenders(report):
+            if not apply:
+                outcomes.append(RepoOutcome(repo.name, _WOULD_ENABLE))
+                continue
+            ok, note = await rem.enable(client, report.org, repo.name)
+            outcomes.append(
+                RepoOutcome(repo.name, _ENABLED if ok else _FAILED, note)
+            )
+        results.append(
+            CategoryRemediation(
+                category=category_meta(key), outcomes=tuple(outcomes)
+            )
+        )
+    return results

{github_security_report-0.5.0 → github_security_report-0.6.0}/src/github_security_report/render/terminal.py

@@ -14,11 +14,13 @@ from collections.abc import Callable, Sequence
 from dataclasses import replace
 
 from rich.console import Console
+from rich.markup import escape
 from rich.table import Table
 
 from github_security_report.categories import CategoryKey
 from github_security_report.models import Repo, RepoSignal, SignalType
 from github_security_report.render import markdown
+from github_security_report.remediate import CategoryRemediation
 from github_security_report.report import (
     SUMMARY_EMOJI,
     OrgReport,
@@ -260,3 +262,76 @@ def render_orgs(
 ) -> None:
     for org in orgs:
         render_org(org, console, top_n=top_n)
+
+
+def render_remediation(
+    org: str,
+    results: Sequence[CategoryRemediation],
+    console: Console,
+    *,
+    apply: bool,
+    top_n: int | None = None,
+) -> None:
+    """Render a remediation run: one block per category, with a trailing summary.
+
+    Mirrors the report's inline style rather than a table: each category names
+    the repositories it would enable / enabled (honouring ``top_n``) and lists
+    any failures one per line with their diagnostic. Dry run prints a leading
+    notice; apply mode prints none (the writes finish before this renders), and
+    a trailing summary totals the work across categories.
+    """
+    console.rule(f"[bold]Remediation: {escape(org)}[/bold]")
+    # In apply mode the writes have already happened by the time this renders,
+    # so a pre-amble banner would be misleading; only the dry-run notice (shown
+    # before nothing is changed) is useful.
+    if not apply:
+        console.print(
+            "[bold yellow]DRY RUN[/bold yellow] — no changes made. Re-run with "
+            "[bold]--apply[/bold] to enable features.\n"
+        )
+
+    planned = 0
+    changed = 0
+    failed = 0
+    for result in results:
+        console.print(f"[bold]{result.category.title}[/bold]")
+        # Classify by run mode and each outcome's own failed flag rather than
+        # by the action string, so the renderer owns no copy of the action
+        # vocabulary defined in remediate.py.
+        failures = [o for o in result.outcomes if o.failed]
+        succeeded = [o for o in result.outcomes if not o.failed]
+        would = succeeded if not apply else []
+        enabled = succeeded if apply else []
+        if not result.outcomes:
+            console.print("  [green]Nothing to remediate[/green]")
+        if would:
+            names = _truncated_names([o.name for o in would], top_n)
+            console.print(
+                f"  [yellow]→[/yellow] {len(would)} would enable: {escape(names)}"
+            )
+        if enabled:
+            names = _truncated_names([o.name for o in enabled], top_n)
+            console.print(
+                f"  [green]{SUMMARY_EMOJI['pass']}[/green] {len(enabled)} enabled: "
+                f"{escape(names)}"
+            )
+        for outcome in failures:
+            detail = f": {escape(outcome.note)}" if outcome.note else ""
+            console.print(
+                f"  [red]{SUMMARY_EMOJI['fail']}[/red] {escape(outcome.name)} "
+                f"failed{detail}"
+            )
+        planned += len(would)
+        changed += len(enabled)
+        failed += len(failures)
+        console.print()
+
+    if apply:
+        console.print(
+            f"[bold]Summary:[/bold] {changed} enabled, {failed} failed."
+        )
+    else:
+        console.print(
+            f"[bold]Summary:[/bold] {planned} to enable (dry run). Re-run with "
+            "[bold]--apply[/bold] to make changes."
+        )

{github_security_report-0.5.0 → github_security_report-0.6.0}/src/github_security_report/severity.py

@@ -12,10 +12,17 @@ in the code-scanning feed:
 
 To present a single, uniform set of severity columns across every table (as the
 design requires), the SARIF level is normalised onto the security scale when no
-security severity is present: error -> high, warning -> medium, and note/none ->
-informational (the sub-low rung, so a category's ``fail_severity`` cutoff can
-treat these advisory findings as non-actionable). Dependabot's
-``security_advisory.severity`` maps directly.
+security severity is present: error -> high, warning -> medium, note -> low,
+and none -> informational. Dependabot's ``security_advisory.severity`` maps
+directly.
+
+The ``note`` mapping mirrors zizmor's own SARIF encoder, which emits both its
+Low and Informational findings at SARIF level ``note`` (Medium -> ``warning``,
+High -> ``error``). The organisation scan pipeline runs zizmor with
+``--min-severity low``, so informational findings never reach the uploaded
+SARIF: every ``note`` alert in code scanning is a genuine Low finding, and the
+ruleset-enforced PR gate blocks on it. Mapping ``note`` below LOW would
+(and previously did) under-state the estate's posture relative to that gate.
 """
 
 from __future__ import annotations
@@ -26,9 +33,9 @@ from enum import IntEnum
 class Severity(IntEnum):
     """Ordered severity. Higher value == more severe (worst-first sorting).
 
-    ``INFORMATIONAL`` is the lowest rung (below ``LOW``): SARIF ``note``/``none``
-    findings -- the bulk of a tool like zizmor -- normalise here, so a category
-    can choose to treat them as non-actionable via its ``fail_severity`` cutoff.
+    ``INFORMATIONAL`` is the lowest rung (below ``LOW``): SARIF ``none``
+    findings and unclassifiable alerts normalise here, so a category can
+    choose to treat them as non-actionable via its ``fail_severity`` cutoff.
     """
 
     INFORMATIONAL = 0
@@ -51,14 +58,16 @@ _SECURITY_NAMES: dict[str, Severity] = {
     "low": Severity.LOW,
 }
 
-# SARIF level -> security scale, used only as a fallback (zizmor). The SARIF
-# vocabulary has no distinct "low": ``note`` (and the rare ``none``) carry the
-# advisory, non-actionable findings, so they normalise to INFORMATIONAL -- below
-# LOW -- letting a category's fail_severity cutoff exclude them.
+# SARIF level -> security scale, used only as a fallback (zizmor). zizmor's
+# SARIF encoder emits Low AND Informational findings as ``note``, but the scan
+# pipeline's --min-severity low floor keeps informational findings out of the
+# SARIF entirely, so a ``note`` alert is a genuine Low finding (matching the
+# ruleset-enforced PR gate, which blocks on note-and-above). The rare ``none``
+# level stays at INFORMATIONAL.
 _SARIF_LEVEL_NAMES: dict[str, Severity] = {
     "error": Severity.HIGH,
     "warning": Severity.MEDIUM,
-    "note": Severity.INFORMATIONAL,
+    "note": Severity.LOW,
     "none": Severity.INFORMATIONAL,
 }