github-security-report 0.11.2__tar.gz → 0.11.3__tar.gz

{github_security_report-0.11.2 → github_security_report-0.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github-security-report
-Version: 0.11.2
+Version: 0.11.3
 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

{github_security_report-0.11.2 → github_security_report-0.11.3}/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.11.2'
-__version_tuple__ = version_tuple = (0, 11, 2)
+__version__ = version = '0.11.3'
+__version_tuple__ = version_tuple = (0, 11, 3)
 
 __commit_id__ = commit_id = None

{github_security_report-0.11.2 → github_security_report-0.11.3}/src/github_security_report/client/__init__.py

@@ -11,8 +11,9 @@ See ``docs/BRIEF.md`` sections 9, 13 and ``docs/phase0-findings.md``.
 The implementation is split across ``endpoints`` (environment-resolved API URLs
 and the shared retry/backoff policy), ``queries`` (GraphQL documents),
 ``parsers`` (pure header/node parsing), ``transport`` (connection lifecycle and
-the retrying request primitives), ``reads`` (the reporting reads) and ``writes``
-(the remediation writes plus the public :class:`GitHubClient`). This module
+the retrying request primitives), ``org_reads`` (the reads issued once per
+organisation), ``reads`` (the per-repository reads) and ``writes`` (the
+remediation writes plus the public :class:`GitHubClient`). This module
 re-exports the public surface, so importing from
 ``github_security_report.client`` is unchanged.
 """
@@ -32,6 +33,7 @@ from github_security_report.client.endpoints import (
     SCORECARD_API,
     _https_endpoint,
 )
+from github_security_report.client.org_reads import OrgReadClient
 from github_security_report.client.parsers import (
     _last_published,
     _next_page_url,
@@ -66,6 +68,7 @@ __all__ = [
     "SCORECARD_API",
     "GitHubClient",
     "NetworkError",
+    "OrgReadClient",
     "ReadClient",
     "Transport",
     "_CODE_SCANNING_SIGNAL_TOOLS",

github_security_report-0.11.3/src/github_security_report/client/org_reads.py

@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Org-scope GitHub reads: repository listing, bulk sweeps and prefetch.
+
+:class:`OrgReadClient` holds the reads issued once per organisation -- the
+repository listing, the org-bulk alert sweeps, the org ruleset fetch and the
+batched GraphQL prefetch -- leaving the per-repository probes to
+:class:`~github_security_report.client.reads.ReadClient`, which extends it.
+Methods return raw parsed JSON (and HTTP status where the status itself is the
+signal, e.g. 404 = feature disabled).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from github_security_report.client.endpoints import BULK_KINDS
+from github_security_report.client.parsers import _parse_iso, _parse_repo_node
+from github_security_report.client.queries import _REPO_GRAPH_FRAGMENT
+from github_security_report.client.transport import NetworkError, Transport
+from github_security_report.models import Repo, RepoGraphData
+
+log = logging.getLogger(__name__)
+
+
+def _aliases_with_errors(errors: object, alias_count: int) -> set[str]:
+    """Alias keys implicated by a batched query's ``errors`` array.
+
+    GitHub reports a *field-level* failure with HTTP 200: the alias is still a
+    populated dictionary, the field that failed is null, and an ``errors``
+    entry carries its path (e.g. ``["r3", "latestRelease"]``). Parsing such a
+    node would convert a read failure into a confident negative -- a nulled
+    ``latestRelease`` is indistinguishable from "never released" -- so the
+    whole alias is treated as unreadable rather than partially trusted.
+
+    The alias is failed wholesale rather than per field: a finer-grained flag
+    per field would have to be threaded through every table to be honest
+    about which half of a row is trustworthy, whereas one unknown repository
+    is already a state every table renders correctly.
+
+    An error whose path names no alias cannot be attributed, so it implicates
+    every alias in the batch: with no way to tell which repositories it
+    touched, treating any of them as successfully read would be a guess.
+    """
+    all_aliases = {f"r{i}" for i in range(alias_count)}
+    if not isinstance(errors, list):
+        return set()
+    affected: set[str] = set()
+    for entry in errors:
+        path = entry.get("path") if isinstance(entry, dict) else None
+        head = path[0] if isinstance(path, list) and path else None
+        if isinstance(head, str) and head in all_aliases:
+            affected.add(head)
+        else:
+            return all_aliases
+    return affected
+
+
+class OrgReadClient(Transport):
+    """The org-scope reads: listing, bulk sweeps, rulesets and prefetch."""
+
+    # ------------------------------------------------------------------ #
+    # Repositories
+    # ------------------------------------------------------------------ #
+    async def list_org_repos(self, org: str) -> tuple[int, list[Repo]]:
+        """List an organisation's repositories, skipping disabled/empty ones.
+
+        Returns the listing status alongside the repos: a non-200 (a failed or
+        mid-pagination-truncated listing) means the set is incomplete, so the
+        caller can flag a partial report rather than silently omitting repos
+        (and their offenders).
+        """
+        status, raws = await self._get_list(
+            f"{self._api_url}/orgs/{org}/repos", type="all"
+        )
+        repos: list[Repo] = []
+        for raw in raws:
+            if raw.get("disabled") or raw.get("size", 0) == 0:
+                log.info("skipping %s: disabled or empty", raw.get("full_name"))
+                continue
+            repos.append(
+                Repo(
+                    name=raw["name"],
+                    full_name=raw["full_name"],
+                    html_url=raw["html_url"],
+                    archived=raw.get("archived", False),
+                    fork=raw.get("fork", False),
+                    is_template=raw.get("is_template", False),
+                    private=raw.get("private", False),
+                    created_at=_parse_iso(raw.get("created_at")),
+                )
+            )
+        return status, repos
+
+    # ------------------------------------------------------------------ #
+    # Org-bulk alert sweeps
+    # ------------------------------------------------------------------ #
+    async def org_bulk_alerts(self, org: str, kind: str) -> tuple[int, list[dict]]:
+        """Sweep all open alerts of one kind across the org.
+
+        Returns the first-page HTTP status alongside the alerts so callers can
+        tell an authoritative empty result (200 ``[]``) apart from an unreadable
+        sweep (403/404/5xx), which must never be reported as "clean".
+        """
+        path = BULK_KINDS[kind]
+        return await self._get_list(f"{self._api_url}/orgs/{org}/{path}", state="open")
+
+    # ------------------------------------------------------------------ #
+    # Organisation rulesets (workflow-driven tool enablement)
+    # ------------------------------------------------------------------ #
+    async def org_workflow_rulesets(self, org: str) -> tuple[int, list[dict]]:
+        """Active, branch-targeted org rulesets, each with full rule details.
+
+        Returns ``(status, details)``; status is the org-rulesets list status
+        (e.g. 403 when the token lacks org access) so coverage can degrade
+        gracefully. The list endpoint returns summaries, so each active branch
+        ruleset is fetched in detail to expose its rules and conditions.
+        """
+        status, summaries = await self._get_list(f"{self._api_url}/orgs/{org}/rulesets")
+        if status != 200:
+            return status, []
+        details: list[dict] = []
+        for summary in summaries:
+            if summary.get("enforcement") != "active":
+                continue
+            if summary.get("target") not in (None, "branch"):
+                continue
+            resp = await self._request(
+                "GET", f"{self._api_url}/orgs/{org}/rulesets/{summary['id']}"
+            )
+            if resp.status_code == 200:
+                details.append(resp.json())
+            await resp.aclose()  # release the connection once the body is read
+        return 200, details
+
+    # ------------------------------------------------------------------ #
+    # Batched per-repo prefetch (one query for many repositories)
+    # ------------------------------------------------------------------ #
+    async def repo_graph_batch(
+        self, org: str, names: list[str]
+    ) -> dict[str, RepoGraphData]:
+        """Prefetch per-repo data for many repositories in one GraphQL query.
+
+        Returns a ``RepoGraphData`` per requested name. This data is
+        load-bearing for whole report sections (releases/tags, Dependabot
+        enablement, open issues), and its defaults are indistinguishable from
+        confident negatives ("never released"), so a wholly failed query --
+        a non-200 response that survived the shared retry/backoff policy, or
+        a 200 carrying no ``data`` object -- raises :class:`NetworkError` to
+        abort the run rather than fabricating results. A repository that
+        cannot be fully read -- a ``null`` alias, or a populated alias whose
+        ``errors`` entry shows a field failed to resolve -- degrades to
+        ``RepoGraphData(unreadable=True)`` so downstream tables report it as
+        unknown. An empty ``names`` issues no request.
+        """
+        # Seed every requested name as unreadable; only a successfully parsed
+        # alias replaces its entry, so nothing failed can masquerade as read.
+        out = {name: RepoGraphData(unreadable=True) for name in names}
+        if not names:
+            return out
+        aliases = "\n".join(
+            f"  r{i}: repository(owner: $owner, name: $n{i}) {{ ...RepoData }}"
+            for i in range(len(names))
+        )
+        var_decls = "".join(f", $n{i}: String!" for i in range(len(names)))
+        query = (
+            f"query($owner: String!{var_decls}) {{\n{aliases}\n}}\n"
+            f"{_REPO_GRAPH_FRAGMENT}"
+        )
+        variables: dict[str, str] = {"owner": org}
+        for i, name in enumerate(names):
+            variables[f"n{i}"] = name
+        resp = await self._request(
+            "POST",
+            self._graphql_url,
+            json={"query": query, "variables": variables},
+        )
+        if resp.status_code != 200:
+            status = resp.status_code
+            await resp.aclose()  # unread body would leak a pooled connection
+            raise NetworkError(
+                f"GraphQL prefetch for {org} failed with HTTP {status} after "
+                "exhausting retries; aborting because the release/tag, "
+                "Dependabot-enablement and open-issues data for "
+                f"{len(names)} repositories would otherwise be fabricated "
+                "from defaults (e.g. reported as never released)."
+            )
+        body = resp.json()
+        data = body.get("data")
+        await resp.aclose()  # release the connection once the body is read
+        # GitHub answers a partially-refused query with HTTP 200: the readable
+        # aliases populated, the rest null or missing individual fields, and an
+        # ``errors`` array explaining why. The paths are both logged for
+        # diagnosis and used to fail the affected aliases, since a field nulled
+        # by a failed read is indistinguishable from a genuine absence.
+        errors = body.get("errors")
+        errored_aliases = _aliases_with_errors(errors, len(names))
+        if errors:
+            log.warning(
+                "GraphQL prefetch for %s returned %d error(s); affected data is "
+                "reported as unknown: %s",
+                org,
+                len(errors),
+                "; ".join(
+                    f"{'.'.join(str(p) for p in (e.get('path') or []))}: "
+                    f"{e.get('message', '')}"
+                    for e in errors[:5]
+                    if isinstance(e, dict)
+                ),
+            )
+        if not isinstance(data, dict):
+            # HTTP 200 with no data object at all: the whole batch failed
+            # (e.g. a timed-out or refused query). Same stakes as a non-200.
+            raise NetworkError(
+                f"GraphQL prefetch for {org} returned no data for any of "
+                f"{len(names)} repositories; aborting rather than reporting "
+                "fabricated defaults. "
+                f"errors={errors!r}"
+            )
+        for i, name in enumerate(names):
+            alias = f"r{i}"
+            if alias in errored_aliases:
+                # A field of this alias failed to resolve, so its null fields
+                # cannot be told apart from genuine absences. Leave the
+                # pre-seeded unreadable default in place.
+                continue
+            node = data.get(alias)
+            if isinstance(node, dict):
+                out[name] = _parse_repo_node(node)
+        unreadable = sorted(name for name, d in out.items() if d.unreadable)
+        if unreadable:
+            log.warning(
+                "GraphQL prefetch for %s could not read %d repositories "
+                "(reported as unknown): %s",
+                org,
+                len(unreadable),
+                ", ".join(unreadable),
+            )
+        return out

{github_security_report-0.11.2 → github_security_report-0.11.3}/src/github_security_report/client/reads.py

@@ -1,10 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 The Linux Foundation
-"""Read-only GitHub API surface: repo listing, sweeps, probes and prefetch.
+"""Per-repository GitHub reads: enabled-probes, alerts and posture flags.
 
-:class:`ReadClient` adds every reporting read to :class:`Transport`. Methods
-return raw parsed JSON (and HTTP status where the status itself is the signal,
-e.g. 404 = feature disabled).
+:class:`ReadClient` completes the reporting read surface by adding the reads
+issued once per repository to the org-scope reads of
+:class:`~github_security_report.client.org_reads.OrgReadClient`. Methods return
+raw parsed JSON (and HTTP status where the status itself is the signal, e.g.
+404 = feature disabled).
 """
 
 from __future__ import annotations
@@ -12,100 +14,19 @@ from __future__ import annotations
 import asyncio
 import logging
 
-from github_security_report.client.endpoints import BULK_KINDS
-from github_security_report.client.parsers import _parse_iso, _parse_repo_node
+from github_security_report.client.org_reads import OrgReadClient
+from github_security_report.client.parsers import _parse_iso
 from github_security_report.client.queries import (
     _CODE_SCANNING_SIGNAL_TOOLS,
     _DEPENDABOT_ENABLED_QUERY,
-    _REPO_GRAPH_FRAGMENT,
 )
-from github_security_report.client.transport import NetworkError, Transport
-from github_security_report.models import Repo, RepoGraphData
+from github_security_report.models import Repo
 
 log = logging.getLogger(__name__)
 
 
-def _aliases_with_errors(errors: object, alias_count: int) -> set[str]:
-    """Alias keys implicated by a batched query's ``errors`` array.
-
-    GitHub reports a *field-level* failure with HTTP 200: the alias is still a
-    populated dictionary, the field that failed is null, and an ``errors``
-    entry carries its path (e.g. ``["r3", "latestRelease"]``). Parsing such a
-    node would convert a read failure into a confident negative -- a nulled
-    ``latestRelease`` is indistinguishable from "never released" -- so the
-    whole alias is treated as unreadable rather than partially trusted.
-
-    The alias is failed wholesale rather than per field: a finer-grained flag
-    per field would have to be threaded through every table to be honest
-    about which half of a row is trustworthy, whereas one unknown repository
-    is already a state every table renders correctly.
-
-    An error whose path names no alias cannot be attributed, so it implicates
-    every alias in the batch: with no way to tell which repositories it
-    touched, treating any of them as successfully read would be a guess.
-    """
-    all_aliases = {f"r{i}" for i in range(alias_count)}
-    if not isinstance(errors, list):
-        return set()
-    affected: set[str] = set()
-    for entry in errors:
-        path = entry.get("path") if isinstance(entry, dict) else None
-        head = path[0] if isinstance(path, list) and path else None
-        if isinstance(head, str) and head in all_aliases:
-            affected.add(head)
-        else:
-            return all_aliases
-    return affected
-
-
-class ReadClient(Transport):
-    """The reporting reads: sweeps, per-repo probes and batched prefetch."""
-
-    # ------------------------------------------------------------------ #
-    # Repositories
-    # ------------------------------------------------------------------ #
-    async def list_org_repos(self, org: str) -> tuple[int, list[Repo]]:
-        """List an organisation's repositories, skipping disabled/empty ones.
-
-        Returns the listing status alongside the repos: a non-200 (a failed or
-        mid-pagination-truncated listing) means the set is incomplete, so the
-        caller can flag a partial report rather than silently omitting repos
-        (and their offenders).
-        """
-        status, raws = await self._get_list(
-            f"{self._api_url}/orgs/{org}/repos", type="all"
-        )
-        repos: list[Repo] = []
-        for raw in raws:
-            if raw.get("disabled") or raw.get("size", 0) == 0:
-                log.info("skipping %s: disabled or empty", raw.get("full_name"))
-                continue
-            repos.append(
-                Repo(
-                    name=raw["name"],
-                    full_name=raw["full_name"],
-                    html_url=raw["html_url"],
-                    archived=raw.get("archived", False),
-                    fork=raw.get("fork", False),
-                    is_template=raw.get("is_template", False),
-                    private=raw.get("private", False),
-                    created_at=_parse_iso(raw.get("created_at")),
-                )
-            )
-        return status, repos
-
-    # ------------------------------------------------------------------ #
-    # Org-bulk alert sweeps
-    # ------------------------------------------------------------------ #
-    async def org_bulk_alerts(self, org: str, kind: str) -> tuple[int, list[dict]]:
-        """Sweep all open alerts of one kind across the org.
-
-        Returns the first-page HTTP status alongside the alerts so callers can
-        tell an authoritative empty result (200 ``[]``) apart from an unreadable
-        sweep (403/404/5xx), which must never be reported as "clean".
-        """
-        path = BULK_KINDS[kind]
-        return await self._get_list(f"{self._api_url}/orgs/{org}/{path}", state="open")
+class ReadClient(OrgReadClient):
+    """The reporting reads: org sweeps plus the per-repository probes."""
 
     # ------------------------------------------------------------------ #
     # Per-repo enabled-probes
@@ -226,34 +147,6 @@ class ReadClient(Transport):
         await resp.aclose()  # release the connection once the body is read
         return 200, score
 
-    # ------------------------------------------------------------------ #
-    # Repository rulesets (workflow-driven tool enablement)
-    # ------------------------------------------------------------------ #
-    async def org_workflow_rulesets(self, org: str) -> tuple[int, list[dict]]:
-        """Active, branch-targeted org rulesets, each with full rule details.
-
-        Returns ``(status, details)``; status is the org-rulesets list status
-        (e.g. 403 when the token lacks org access) so coverage can degrade
-        gracefully. The list endpoint returns summaries, so each active branch
-        ruleset is fetched in detail to expose its rules and conditions.
-        """
-        status, summaries = await self._get_list(f"{self._api_url}/orgs/{org}/rulesets")
-        if status != 200:
-            return status, []
-        details: list[dict] = []
-        for summary in summaries:
-            if summary.get("enforcement") != "active":
-                continue
-            if summary.get("target") not in (None, "branch"):
-                continue
-            resp = await self._request(
-                "GET", f"{self._api_url}/orgs/{org}/rulesets/{summary['id']}"
-            )
-            if resp.status_code == 200:
-                details.append(resp.json())
-            await resp.aclose()  # release the connection once the body is read
-        return 200, details
-
     async def repo_branch_rules(
         self, org: str, repo: str, branch: str
     ) -> tuple[int, list[dict]]:
@@ -361,105 +254,3 @@ class ReadClient(Transport):
         data = resp.json()
         await resp.aclose()  # release the connection once the body is read
         return bool(data.get("enabled"))
-
-    async def repo_graph_batch(
-        self, org: str, names: list[str]
-    ) -> dict[str, RepoGraphData]:
-        """Prefetch per-repo data for many repositories in one GraphQL query.
-
-        Returns a ``RepoGraphData`` per requested name. This data is
-        load-bearing for whole report sections (releases/tags, Dependabot
-        enablement, open issues), and its defaults are indistinguishable from
-        confident negatives ("never released"), so a wholly failed query --
-        a non-200 response that survived the shared retry/backoff policy, or
-        a 200 carrying no ``data`` object -- raises :class:`NetworkError` to
-        abort the run rather than fabricating results. A repository that
-        cannot be fully read -- a ``null`` alias, or a populated alias whose
-        ``errors`` entry shows a field failed to resolve -- degrades to
-        ``RepoGraphData(unreadable=True)`` so downstream tables report it as
-        unknown. An empty ``names`` issues no request.
-        """
-        # Seed every requested name as unreadable; only a successfully parsed
-        # alias replaces its entry, so nothing failed can masquerade as read.
-        out = {name: RepoGraphData(unreadable=True) for name in names}
-        if not names:
-            return out
-        aliases = "\n".join(
-            f"  r{i}: repository(owner: $owner, name: $n{i}) {{ ...RepoData }}"
-            for i in range(len(names))
-        )
-        var_decls = "".join(f", $n{i}: String!" for i in range(len(names)))
-        query = (
-            f"query($owner: String!{var_decls}) {{\n{aliases}\n}}\n"
-            f"{_REPO_GRAPH_FRAGMENT}"
-        )
-        variables: dict[str, str] = {"owner": org}
-        for i, name in enumerate(names):
-            variables[f"n{i}"] = name
-        resp = await self._request(
-            "POST",
-            self._graphql_url,
-            json={"query": query, "variables": variables},
-        )
-        if resp.status_code != 200:
-            status = resp.status_code
-            await resp.aclose()  # unread body would leak a pooled connection
-            raise NetworkError(
-                f"GraphQL prefetch for {org} failed with HTTP {status} after "
-                "exhausting retries; aborting because the release/tag, "
-                "Dependabot-enablement and open-issues data for "
-                f"{len(names)} repositories would otherwise be fabricated "
-                "from defaults (e.g. reported as never released)."
-            )
-        body = resp.json()
-        data = body.get("data")
-        await resp.aclose()  # release the connection once the body is read
-        # GitHub answers a partially-refused query with HTTP 200: the readable
-        # aliases populated, the rest null or missing individual fields, and an
-        # ``errors`` array explaining why. The paths are both logged for
-        # diagnosis and used to fail the affected aliases, since a field nulled
-        # by a failed read is indistinguishable from a genuine absence.
-        errors = body.get("errors")
-        errored_aliases = _aliases_with_errors(errors, len(names))
-        if errors:
-            log.warning(
-                "GraphQL prefetch for %s returned %d error(s); affected data is "
-                "reported as unknown: %s",
-                org,
-                len(errors),
-                "; ".join(
-                    f"{'.'.join(str(p) for p in (e.get('path') or []))}: "
-                    f"{e.get('message', '')}"
-                    for e in errors[:5]
-                    if isinstance(e, dict)
-                ),
-            )
-        if not isinstance(data, dict):
-            # HTTP 200 with no data object at all: the whole batch failed
-            # (e.g. a timed-out or refused query). Same stakes as a non-200.
-            raise NetworkError(
-                f"GraphQL prefetch for {org} returned no data for any of "
-                f"{len(names)} repositories; aborting rather than reporting "
-                "fabricated defaults. "
-                f"errors={errors!r}"
-            )
-        for i, name in enumerate(names):
-            alias = f"r{i}"
-            if alias in errored_aliases:
-                # A field of this alias failed to resolve, so its null fields
-                # cannot be told apart from genuine absences. Leave the
-                # pre-seeded unreadable default in place.
-                continue
-            node = data.get(alias)
-            if isinstance(node, dict):
-                out[name] = _parse_repo_node(node)
-        unreadable = sorted(name for name, d in out.items() if d.unreadable)
-        if unreadable:
-            log.warning(
-                "GraphQL prefetch for %s could not read %d repositories "
-                "(reported as unknown): %s",
-                org,
-                len(unreadable),
-                ", ".join(unreadable),
-            )
-        return out

{github_security_report-0.11.2 → github_security_report-0.11.3}/src/github_security_report/client/writes.py

@@ -2,11 +2,12 @@
 # SPDX-FileCopyrightText: 2026 The Linux Foundation
 """Remediation writes, and the public :class:`GitHubClient` façade.
 
-``GitHubClient`` completes the linear ``Transport -> ReadClient ->
-GitHubClient`` chain. The chain exists so each layer stays a readable size --
-connection/retry mechanics, reporting reads, and remediation writes are
-separable concerns -- while callers still get a single object, because one
-client instance serves both the reporting reads and the remediation writes.
+``GitHubClient`` completes the linear ``Transport -> OrgReadClient ->
+ReadClient -> GitHubClient`` chain. The chain exists so each layer stays a
+readable size -- connection/retry mechanics, org-scope reads, per-repository
+reads, and remediation writes are separable concerns -- while callers still get
+a single object, because one client instance serves both the reporting reads
+and the remediation writes.
 """
 
 from __future__ import annotations

github_security_report-0.11.3/src/github_security_report/posture/__init__.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Dependabot configuration posture and release/tag staleness.
+
+These reporting categories sit outside the four-state per-signal model: they are
+configuration-posture and freshness checks rendered as plain tables.
+
+- **Dependabot** (beneath the open-alert table): three plain tables -- repos
+  with vulnerability **alerts** not enabled, repos with **security updates** not
+  enabled (two separate single-feature tables, not a combined matrix), and
+  configured ecosystems that set no update *cooldown* (a mandatory requirement
+  here -- any cooldown value passes). Only the two features GitHub exposes a
+  public per-repository API for are checked.
+- **Releases / Tagging**: repositories that have gone too long without a release
+  or tag. Repositories younger than a configurable age are excluded (0 = none
+  excluded); specific repositories can also be excluded on demand. Releases and
+  tags are reported in separate columns and the rows are ranked by release/tag
+  staleness alone (repository age only gates scope): a missing release or tag
+  counts as the worst possible signal, so a repo with neither ranks first. The
+  ranking key itself is never displayed.
+
+The implementation is split across ``facts`` (the :class:`RepoPosture` record
+every table reads), ``enablement`` (the boolean feature checks and the
+Dependabot cooldown check) and ``releases`` (the release/tag freshness and
+release-immutability tables). This module re-exports the public surface, so
+importing from ``github_security_report.posture`` is unchanged.
+"""
+
+from __future__ import annotations
+
+from github_security_report.posture.enablement import (
+    build_alerts_table,
+    build_cooldown_table,
+    build_dependabot_tables,
+    build_pvr_table,
+    build_security_updates_table,
+    cooldown_missing_ecosystems,
+)
+from github_security_report.posture.facts import RepoPosture
+from github_security_report.posture.releases import (
+    build_mutable_releases_table,
+    build_releases_table,
+    is_release_excluded,
+)
+
+__all__ = [
+    "RepoPosture",
+    "is_release_excluded",
+    "cooldown_missing_ecosystems",
+    "build_dependabot_tables",
+    "build_releases_table",
+    "build_mutable_releases_table",
+    "build_alerts_table",
+    "build_security_updates_table",
+    "build_cooldown_table",
+    "build_pvr_table",
+]

github_security_report-0.11.3/src/github_security_report/posture/enablement.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Configuration-posture tables: feature enablement and update cooldowns.
+
+Every table here is built from the boolean (or indeterminate) configuration
+facts on :class:`RepoPosture`: the two Dependabot features GitHub exposes a
+public per-repository API for, the private-vulnerability-reporting flag, and
+the per-ecosystem cooldown declared in a repository's ``dependabot.yml``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+import yaml
+
+from github_security_report.categories import CategoryKey, category_meta
+from github_security_report.posture.facts import RepoPosture
+from github_security_report.report import TableRow, TableSection
+
+log = logging.getLogger(__name__)
+
+
+def cooldown_missing_ecosystems(dependabot_yaml: str) -> tuple[str, ...]:
+    """Ecosystems in a ``dependabot.yml`` that declare no ``cooldown``.
+
+    Any ``cooldown`` value passes. Returns the ``package-ecosystem`` of each
+    ``updates`` entry that omits a cooldown, de-duplicated and ordered. A
+    malformed document yields an empty tuple (treated as "nothing to flag").
+    """
+    try:
+        data = yaml.safe_load(dependabot_yaml)
+    except yaml.YAMLError as exc:  # malformed config; do not crash the run
+        log.warning("could not parse dependabot.yml: %s", exc)
+        return ()
+    if not isinstance(data, dict):
+        return ()
+    updates = data.get("updates")
+    if not isinstance(updates, list):
+        return ()
+    missing: list[str] = []
+    for entry in updates:
+        if not isinstance(entry, dict):
+            continue
+        ecosystem = entry.get("package-ecosystem")
+        if not isinstance(ecosystem, str) or not ecosystem:
+            continue
+        if "cooldown" not in entry and ecosystem not in missing:
+            missing.append(ecosystem)
+    return tuple(missing)
+
+
+def _build_feature_table(
+    postures: list[RepoPosture],
+    *,
+    category_key: CategoryKey,
+    columns: tuple[str, ...],
+    enabled_of: Callable[[RepoPosture], bool | None],
+) -> TableSection:
+    """A single-feature enablement table (offenders = feature confirmed off).
+
+    Shared by the Dependabot alerts and security-updates checks: both list the
+    repositories where one boolean feature is explicitly disabled and report the
+    enabled/not-enabled/indeterminate split as the standardised footer counts.
+    An indeterminate (``None``) reading counts towards neither pass nor fail; it
+    becomes the unknown count, so an empty table never over-claims that every
+    repository is enabled.
+    """
+    rows = [
+        TableRow(repo=p.repo, cells=())
+        for p in sorted(postures, key=lambda p: p.repo.name)
+        if enabled_of(p) is False
+    ]
+    not_enabled = sum(1 for p in postures if enabled_of(p) is False)
+    enabled = sum(1 for p in postures if enabled_of(p) is True)
+    indeterminate = sum(1 for p in postures if enabled_of(p) is None)
+    return TableSection(
+        category=category_meta(category_key),
+        columns=columns,
+        rows=rows,
+        pass_count=enabled,
+        fail_count=not_enabled,
+        unknown_count=indeterminate,
+    )
+
+
+def build_alerts_table(postures: list[RepoPosture]) -> TableSection:
+    """Repositories where Dependabot vulnerability alerts are not enabled."""
+    return _build_feature_table(
+        postures,
+        category_key=CategoryKey.DEPENDABOT_ALERTS_ENABLED,
+        columns=("Repository",),
+        enabled_of=lambda p: p.dependabot_alerts,
+    )
+
+
+def build_security_updates_table(postures: list[RepoPosture]) -> TableSection:
+    """Repositories where Dependabot security updates are not enabled."""
+    return _build_feature_table(
+        postures,
+        category_key=CategoryKey.DEPENDABOT_UPDATES_ENABLED,
+        columns=("Repository",),
+        enabled_of=lambda p: p.security_updates,
+    )
+
+
+def build_cooldown_table(postures: list[RepoPosture]) -> TableSection:
+    """A table of repositories/ecosystems that configure no update cooldown."""
+    rows = [
+        TableRow(repo=p.repo, cells=(joined,), sort_values=(joined,))
+        for p in sorted(postures, key=lambda p: p.repo.name)
+        if p.cooldown_missing and (joined := ", ".join(p.cooldown_missing))
+    ]
+    missing = sum(1 for p in postures if p.cooldown_missing)
+    with_cooldown = sum(
+        1 for p in postures if p.has_dependabot_config and not p.cooldown_missing
+    )
+    # An unreadable prefetch means the dependabot.yml itself is unknown, not
+    # absent -- count it as unknown rather than silently dropping the repo.
+    indeterminate = sum(1 for p in postures if p.graph_unreadable)
+    return TableSection(
+        category=category_meta(CategoryKey.DEPENDABOT_COOLDOWN),
+        columns=("Repository", "Ecosystems without cooldown"),
+        rows=rows,
+        pass_count=with_cooldown,
+        fail_count=missing,
+        unknown_count=indeterminate,
+    )
+
+
+def build_dependabot_tables(postures: list[RepoPosture]) -> list[TableSection]:
+    """All extra Dependabot posture tables, in render order.
+
+    The alerts and security-updates enablement checks are deliberately two
+    separate single-feature tables (rather than one multi-column matrix): with
+    only two public-API features the matrix read as contradictory.
+    """
+    return [
+        build_alerts_table(postures),
+        build_security_updates_table(postures),
+        build_cooldown_table(postures),
+    ]
+
+
+def build_pvr_table(postures: list[RepoPosture]) -> TableSection:
+    """Repositories where private vulnerability reporting is not enabled.
+
+    Like the Dependabot enablement tables this is a single-boolean feature
+    check, so it reuses :func:`_build_feature_table`: offenders are repositories
+    where the feature is confirmed off; an indeterminate (``None``) reading
+    counts towards neither side of the standardised summary footer. The table is
+    always built (the flag is probed for every repository); the per-category
+    render toggle governs whether it is shown.
+    """
+    return _build_feature_table(
+        postures,
+        category_key=CategoryKey.PRIVATE_VULNERABILITY_REPORTING,
+        columns=("Repository",),
+        enabled_of=lambda p: p.private_vulnerability_reporting,
+    )

github_security_report-0.11.3/src/github_security_report/posture/facts.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""The per-repository facts the posture and freshness tables are built from."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from github_security_report.models import ReleaseRef, Repo
+
+
+@dataclass
+class RepoPosture:
+    """Per-repository configuration/freshness facts for the extra sections."""
+
+    repo: Repo
+    # True when the batched GraphQL prefetch could not read this repository at
+    # all: the release/tag and dependabot.yml facts below are then unknown, not
+    # absent, and the tables must count the repository as unknown rather than
+    # render confident negatives such as "never released".
+    graph_unreadable: bool = False
+    # Dependabot repo-level feature flags (None = indeterminate).
+    dependabot_alerts: bool | None = None
+    security_updates: bool | None = None
+    # GitHub "private vulnerability reporting" enablement (None = indeterminate).
+    private_vulnerability_reporting: bool | None = None
+    # Ecosystems declared in .github/dependabot.yml that set no cooldown.
+    cooldown_missing: tuple[str, ...] = ()
+    # True when .github/dependabot.yml exists and declares version updates.
+    has_dependabot_config: bool = False
+    # Releases / tagging (UTC; None = none found).
+    latest_release_at: dt.datetime | None = None
+    latest_tag_at: dt.datetime | None = None
+    # Release identities for the immutability check (None = absent).
+    latest_release: ReleaseRef | None = None
+    last_published_release: ReleaseRef | None = None

github_security_report-0.11.2/src/github_security_report/posture.py → github_security_report-0.11.3/src/github_security_report/posture/releases.py

@@ -1,99 +1,32 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 The Linux Foundation
-"""Dependabot configuration posture and release/tag staleness.
+"""Release/tag freshness and release-immutability tables.
 
-These reporting categories sit outside the four-state per-signal model: they are
-configuration-posture and freshness checks rendered as plain tables.
-
-- **Dependabot** (beneath the open-alert table): three plain tables -- repos
-  with vulnerability **alerts** not enabled, repos with **security updates** not
-  enabled (two separate single-feature tables, not a combined matrix), and
-  configured ecosystems that set no update *cooldown* (a mandatory requirement
-  here -- any cooldown value passes). Only the two features GitHub exposes a
-  public per-repository API for are checked.
-- **Releases / Tagging**: repositories that have gone too long without a release
-  or tag. Repositories younger than a configurable age are excluded (0 = none
-  excluded); specific repositories can also be excluded on demand. Releases and
-  tags are reported in separate columns and the rows are ranked by release/tag
-  staleness alone (repository age only gates scope): a missing release or tag
-  counts as the worst possible signal, so a repo with neither ranks first. The
-  ranking key itself is never displayed.
+Repositories that have gone too long without a release or tag, and releases
+that remain mutable. Repositories younger than a configurable age are excluded
+(0 = none excluded); specific repositories can also be excluded on demand.
 """
 
 from __future__ import annotations
 
 import datetime as dt
-import logging
-from collections.abc import Callable
-from dataclasses import dataclass
-
-import yaml
 
 from github_security_report.categories import CategoryKey, category_meta
 from github_security_report.models import ReleaseRef, Repo
+from github_security_report.posture.facts import RepoPosture
 from github_security_report.report import TableRow, TableSection
 
-log = logging.getLogger(__name__)
-
 # Aware sentinel so releases lacking a publish timestamp sort oldest (last) when
 # ordering most-recent-first, without ever comparing a naive and aware value.
 _MIN_AWARE = dt.datetime.min.replace(tzinfo=dt.timezone.utc)
 
 
-@dataclass
-class RepoPosture:
-    """Per-repository configuration/freshness facts for the extra sections."""
-
-    repo: Repo
-    # True when the batched GraphQL prefetch could not read this repository at
-    # all: the release/tag and dependabot.yml facts below are then unknown, not
-    # absent, and the tables must count the repository as unknown rather than
-    # render confident negatives such as "never released".
-    graph_unreadable: bool = False
-    # Dependabot repo-level feature flags (None = indeterminate).
-    dependabot_alerts: bool | None = None
-    security_updates: bool | None = None
-    # GitHub "private vulnerability reporting" enablement (None = indeterminate).
-    private_vulnerability_reporting: bool | None = None
-    # Ecosystems declared in .github/dependabot.yml that set no cooldown.
-    cooldown_missing: tuple[str, ...] = ()
-    # True when .github/dependabot.yml exists and declares version updates.
-    has_dependabot_config: bool = False
-    # Releases / tagging (UTC; None = none found).
-    latest_release_at: dt.datetime | None = None
-    latest_tag_at: dt.datetime | None = None
-    # Release identities for the immutability check (None = absent).
-    latest_release: ReleaseRef | None = None
-    last_published_release: ReleaseRef | None = None
-
-
-def cooldown_missing_ecosystems(dependabot_yaml: str) -> tuple[str, ...]:
-    """Ecosystems in a ``dependabot.yml`` that declare no ``cooldown``.
-
-    Any ``cooldown`` value passes. Returns the ``package-ecosystem`` of each
-    ``updates`` entry that omits a cooldown, de-duplicated and ordered. A
-    malformed document yields an empty tuple (treated as "nothing to flag").
-    """
-    try:
-        data = yaml.safe_load(dependabot_yaml)
-    except yaml.YAMLError as exc:  # malformed config; do not crash the run
-        log.warning("could not parse dependabot.yml: %s", exc)
-        return ()
-    if not isinstance(data, dict):
-        return ()
-    updates = data.get("updates")
-    if not isinstance(updates, list):
-        return ()
-    missing: list[str] = []
-    for entry in updates:
-        if not isinstance(entry, dict):
-            continue
-        ecosystem = entry.get("package-ecosystem")
-        if not isinstance(ecosystem, str) or not ecosystem:
-            continue
-        if "cooldown" not in entry and ecosystem not in missing:
-            missing.append(ecosystem)
-    return tuple(missing)
+def _age_days(when: dt.datetime | None, now: dt.datetime) -> int | None:
+    """Whole days between ``when`` and ``now`` (>= 0), or None when absent."""
+    if when is None:
+        return None
+    delta = (now - when).days
+    return max(delta, 0)
 
 
 def is_release_excluded(
@@ -119,14 +52,6 @@ def is_release_excluded(
     )
 
 
-def _age_days(when: dt.datetime | None, now: dt.datetime) -> int | None:
-    """Whole days between ``when`` and ``now`` (>= 0), or None when absent."""
-    if when is None:
-        return None
-    delta = (now - when).days
-    return max(delta, 0)
-
-
 def _release_is_current(
     release_age: int | None, tag_age: int | None, release_max_age_days: int
 ) -> bool:
@@ -157,116 +82,6 @@ def _age_cell(age: int | None) -> str:
     return f"{age} days ago"
 
 
-def _build_feature_table(
-    postures: list[RepoPosture],
-    *,
-    category_key: CategoryKey,
-    columns: tuple[str, ...],
-    enabled_of: Callable[[RepoPosture], bool | None],
-) -> TableSection:
-    """A single-feature enablement table (offenders = feature confirmed off).
-
-    Shared by the Dependabot alerts and security-updates checks: both list the
-    repositories where one boolean feature is explicitly disabled and report the
-    enabled/not-enabled/indeterminate split as the standardised footer counts.
-    An indeterminate (``None``) reading counts towards neither pass nor fail; it
-    becomes the unknown count, so an empty table never over-claims that every
-    repository is enabled.
-    """
-    rows = [
-        TableRow(repo=p.repo, cells=())
-        for p in sorted(postures, key=lambda p: p.repo.name)
-        if enabled_of(p) is False
-    ]
-    not_enabled = sum(1 for p in postures if enabled_of(p) is False)
-    enabled = sum(1 for p in postures if enabled_of(p) is True)
-    indeterminate = sum(1 for p in postures if enabled_of(p) is None)
-    return TableSection(
-        category=category_meta(category_key),
-        columns=columns,
-        rows=rows,
-        pass_count=enabled,
-        fail_count=not_enabled,
-        unknown_count=indeterminate,
-    )
-
-
-def build_alerts_table(postures: list[RepoPosture]) -> TableSection:
-    """Repositories where Dependabot vulnerability alerts are not enabled."""
-    return _build_feature_table(
-        postures,
-        category_key=CategoryKey.DEPENDABOT_ALERTS_ENABLED,
-        columns=("Repository",),
-        enabled_of=lambda p: p.dependabot_alerts,
-    )
-
-
-def build_security_updates_table(postures: list[RepoPosture]) -> TableSection:
-    """Repositories where Dependabot security updates are not enabled."""
-    return _build_feature_table(
-        postures,
-        category_key=CategoryKey.DEPENDABOT_UPDATES_ENABLED,
-        columns=("Repository",),
-        enabled_of=lambda p: p.security_updates,
-    )
-
-
-def build_cooldown_table(postures: list[RepoPosture]) -> TableSection:
-    """A table of repositories/ecosystems that configure no update cooldown."""
-    rows = [
-        TableRow(repo=p.repo, cells=(joined,), sort_values=(joined,))
-        for p in sorted(postures, key=lambda p: p.repo.name)
-        if p.cooldown_missing and (joined := ", ".join(p.cooldown_missing))
-    ]
-    missing = sum(1 for p in postures if p.cooldown_missing)
-    with_cooldown = sum(
-        1 for p in postures if p.has_dependabot_config and not p.cooldown_missing
-    )
-    # An unreadable prefetch means the dependabot.yml itself is unknown, not
-    # absent -- count it as unknown rather than silently dropping the repo.
-    indeterminate = sum(1 for p in postures if p.graph_unreadable)
-    return TableSection(
-        category=category_meta(CategoryKey.DEPENDABOT_COOLDOWN),
-        columns=("Repository", "Ecosystems without cooldown"),
-        rows=rows,
-        pass_count=with_cooldown,
-        fail_count=missing,
-        unknown_count=indeterminate,
-    )
-
-
-def build_dependabot_tables(postures: list[RepoPosture]) -> list[TableSection]:
-    """All extra Dependabot posture tables, in render order.
-
-    The alerts and security-updates enablement checks are deliberately two
-    separate single-feature tables (rather than one multi-column matrix): with
-    only two public-API features the matrix read as contradictory.
-    """
-    return [
-        build_alerts_table(postures),
-        build_security_updates_table(postures),
-        build_cooldown_table(postures),
-    ]
-
-
-def build_pvr_table(postures: list[RepoPosture]) -> TableSection:
-    """Repositories where private vulnerability reporting is not enabled.
-
-    Like the Dependabot enablement tables this is a single-boolean feature
-    check, so it reuses :func:`_build_feature_table`: offenders are repositories
-    where the feature is confirmed off; an indeterminate (``None``) reading
-    counts towards neither side of the standardised summary footer. The table is
-    always built (the flag is probed for every repository); the per-category
-    render toggle governs whether it is shown.
-    """
-    return _build_feature_table(
-        postures,
-        category_key=CategoryKey.PRIVATE_VULNERABILITY_REPORTING,
-        columns=("Repository",),
-        enabled_of=lambda p: p.private_vulnerability_reporting,
-    )
-
-
 def build_releases_table(
     postures: list[RepoPosture],
     *,
@@ -425,17 +240,3 @@ def build_mutable_releases_table(postures: list[RepoPosture]) -> TableSection:
         fail_count=finding_count,
         unknown_count=indeterminate_count,
     )
-
-
-__all__ = [
-    "RepoPosture",
-    "is_release_excluded",
-    "cooldown_missing_ecosystems",
-    "build_dependabot_tables",
-    "build_releases_table",
-    "build_mutable_releases_table",
-    "build_alerts_table",
-    "build_security_updates_table",
-    "build_cooldown_table",
-    "build_pvr_table",
-]