github-security-report 0.8.0__tar.gz → 0.10.0__tar.gz

{github_security_report-0.8.0 → github_security_report-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-security-report
-Version: 0.8.0
+Version: 0.10.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,14 +29,14 @@ 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.8
+Requires-Dist: typer==0.27.0
 Provides-Extra: dev
 Requires-Dist: mypy==2.3.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.1.1; extra == 'dev'
 Requires-Dist: respx==0.23.1; extra == 'dev'
-Requires-Dist: ruff==0.15.21; extra == 'dev'
+Requires-Dist: ruff==0.15.22; extra == 'dev'
 Requires-Dist: syrupy==5.5.3; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'

{github_security_report-0.8.0 → github_security_report-0.10.0}/pyproject.toml

@@ -45,7 +45,7 @@ keywords = [
 ]
 dependencies = [
   "httpx[http2]==0.28.1",
-  "typer==0.26.8",
+  "typer==0.27.0",
   "rich==15.0.0",
   "jinja2==3.1.6",
   "jsonschema==4.26.0",
@@ -65,7 +65,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==5.5.3",
   "mypy==2.3.0",
-  "ruff==0.15.21",
+  "ruff==0.15.22",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -97,7 +97,7 @@ dev = [
   "respx==0.23.1",
   "syrupy==5.5.3",
   "mypy==2.3.0",
-  "ruff==0.15.21",
+  "ruff==0.15.22",
   "types-jsonschema==4.26.0.20260518",
   "types-PyYAML==6.0.12.20250915",
 ]
@@ -136,6 +136,10 @@ skip_empty = true
 
 [tool.mypy]
 python_version = "3.10"
+# The whole first-party tree, so a bare 'mypy' checks what the pre-commit hook
+# checks. Tests are deliberately included: they are held to the same standard
+# as the package.
+files = ["src", "tests", "scripts"]
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false

{github_security_report-0.8.0 → github_security_report-0.10.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.8.0'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.10.0'
+__version_tuple__ = version_tuple = (0, 10, 0)
 
 __commit_id__ = commit_id = None

{github_security_report-0.8.0 → github_security_report-0.10.0}/src/github_security_report/categories.py

@@ -67,9 +67,9 @@ class CategoryMeta:
     # A repository fails (appears as an offender) only when it carries a finding
     # at or above this rung; findings below it fold into the clean count. The
     # global default is MEDIUM, so Low and Informational findings pass; a
-    # category may lower it (Zizmor uses LOW, so only Informational passes).
-    # Meaningful only for the severity-ranked signals; binary categories ignore
-    # it. Overridable per category via the JSON config.
+    # category may lower it (Zizmor uses INFORMATIONAL, so every finding
+    # counts). Meaningful only for the severity-ranked signals; binary
+    # categories ignore it. Overridable per category via the JSON config.
     fail_severity: Severity = Severity.MEDIUM
 
 
@@ -93,7 +93,8 @@ _CATEGORIES: dict[CategoryKey, CategoryMeta] = {
         url="https://github.com/ossf/scorecard",
         description=(
             "OpenSSF Scorecard supply-chain health scores (a lower score is "
-            "weaker), ranked weakest-first."
+            "weaker). Ranked by the worst severity rung present in the table "
+            "(most findings at that rung first), then weakest score first."
         ),
     ),
     CategoryKey.ZIZMOR: CategoryMeta(
@@ -106,10 +107,18 @@ _CATEGORIES: dict[CategoryKey, CategoryMeta] = {
             "Zizmor static analysis of GitHub Actions workflows, ranked "
             "worst-first by severity."
         ),
-        # 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,
+        # The organisation scan pipeline runs zizmor with an
+        # 'informational' floor, so every finding it can report reaches the
+        # SARIF. Match that here: any zizmor finding counts, at any
+        # severity. This mirrors the ruleset-enforced PR gate, which blocks
+        # on any finding regardless of level.
+        #
+        # zizmor emits both Low and Informational findings at SARIF level
+        # "note", and the code-scanning alerts API exposes only that level
+        # (not zizmor's own severity property), so the two are
+        # indistinguishable here. Cutting at INFORMATIONAL sidesteps the
+        # ambiguity: both surface either way.
+        fail_severity=Severity.INFORMATIONAL,
     ),
     CategoryKey.AISLOP: CategoryMeta(
         key=CategoryKey.AISLOP,

{github_security_report-0.8.0 → github_security_report-0.10.0}/src/github_security_report/models.py

@@ -5,8 +5,8 @@
 Encodes the Phase 0 design (see ``docs/BRIEF.md`` and
 ``docs/phase0-findings.md``): the six ranked signals, the four-state per-report
 classification, severity counts with hierarchical worst-first ordering, and the
-ranking rules (alert tables sort by severity descending; Scorecard by score
-ascending).
+ranking rules (alert tables sort by severity descending; Scorecard by its worst
+populated severity rung descending, then by score ascending).
 """
 
 from __future__ import annotations
@@ -16,7 +16,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 
 from github_security_report.categories import CategoryKey, CategoryMeta, category_meta
-from github_security_report.severity import Severity
+from github_security_report.severity import RUNGS_WORST_FIRST, Severity
 
 
 class SignalType(str, Enum):
@@ -66,7 +66,13 @@ class SignalType(str, Enum):
 
     @property
     def sort_ascending(self) -> bool:
-        """Scorecard ranks by score ascending (lower == worse); others descend."""
+        """Whether lower is worse for this signal's primary metric.
+
+        True only for Scorecard, whose aggregate score runs the opposite way to
+        a finding count (lower == weaker). The score is Scorecard's *secondary*
+        key: ``rank_offenders`` leads on the worst severity rung present in the
+        table and uses the score to order repositories within that rung.
+        """
         return self is SignalType.SCORECARD
 
 
@@ -177,6 +183,22 @@ class SeverityCounts:
     def total(self) -> int:
         return self.critical + self.high + self.medium + self.low + self.informational
 
+    def at(self, rung: Severity) -> int:
+        """The count at exactly one severity rung.
+
+        Attribute access rather than a ``by_rung`` lookup, so the ranking hot
+        path does not build a dict per comparison.
+        """
+        if rung is Severity.CRITICAL:
+            return self.critical
+        if rung is Severity.HIGH:
+            return self.high
+        if rung is Severity.MEDIUM:
+            return self.medium
+        if rung is Severity.LOW:
+            return self.low
+        return self.informational
+
     def at_or_above(self, cutoff: Severity) -> int:
         """Count of findings whose severity is at least ``cutoff``.
 
@@ -185,14 +207,12 @@ class SeverityCounts:
         category's ``fail_severity`` cutoff. Findings below the cutoff (e.g.
         informational-only) do not count towards a failure.
         """
-        by_rung = {
-            Severity.CRITICAL: self.critical,
-            Severity.HIGH: self.high,
-            Severity.MEDIUM: self.medium,
-            Severity.LOW: self.low,
-            Severity.INFORMATIONAL: self.informational,
-        }
-        return sum(count for rung, count in by_rung.items() if rung >= cutoff)
+        return sum(count for rung, count in self.by_rung.items() if rung >= cutoff)
+
+    @property
+    def by_rung(self) -> dict[Severity, int]:
+        """Per-severity counts keyed by rung, in worst-first iteration order."""
+        return {rung: self.at(rung) for rung in RUNGS_WORST_FIRST}
 
     @property
     def weighted(self) -> int:
@@ -236,12 +256,41 @@ class RepoSignal:
         return self.state is RepoState.OFFENDER
 
 
+# The rungs eligible to lead the Scorecard ordering, worst-first.
+# ``INFORMATIONAL`` is deliberately absent: it is the non-actionable rung, so it
+# never displaces the score as the primary key.
+LEAD_RUNGS: tuple[Severity, ...] = tuple(
+    rung for rung in RUNGS_WORST_FIRST if rung is not Severity.INFORMATIONAL
+)
+
+
+def lead_rung(offenders: list[RepoSignal]) -> Severity | None:
+    """The worst severity rung any offender actually carries.
+
+    Returns ``None`` when no offender carries a finding at Low or above, in
+    which case there is no severity tier worth leading on.
+    """
+    return next(
+        (rung for rung in LEAD_RUNGS if any(s.counts.at(rung) for s in offenders)),
+        None,
+    )
+
+
 def rank_offenders(signals: list[RepoSignal]) -> list[RepoSignal]:
     """Sort offenders worst-first for a single signal.
 
     Alert-based signals sort by the hierarchical severity key descending, with
-    total as a tiebreaker. Scorecard sorts by aggregate score ascending (lower
-    == worse). Repo name breaks remaining ties, ascending.
+    total as a tiebreaker.
+
+    Scorecard sorts on two tiers: the count at the worst severity rung present
+    anywhere in the table (descending), then the aggregate score (ascending,
+    lower == worse). The leading rung cascades -- Critical, else High, else
+    Medium, else Low -- so the rung that actually discriminates between
+    repositories leads, and a lone Critical can never be buried mid-table by a
+    weaker repository with a lower score. When no offender carries a finding at
+    Low or above, the score alone orders the table.
+
+    Repo name breaks remaining ties, ascending.
 
     Numeric components are negated so the whole sort runs ascending (no
     ``reverse=True``); that keeps the name tiebreaker correctly ascending even
@@ -252,9 +301,11 @@ def rank_offenders(signals: list[RepoSignal]) -> list[RepoSignal]:
         return []
     signal = offenders[0].signal
     if signal.sort_ascending:
+        rung = lead_rung(offenders)
         return sorted(
             offenders,
             key=lambda s: (
+                -s.counts.at(rung) if rung is not None else 0,
                 s.score if s.score is not None else float("inf"),
                 s.repo.name,
             ),

{github_security_report-0.8.0 → github_security_report-0.10.0}/src/github_security_report/severity.py

@@ -19,10 +19,13 @@ 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.
+``--min-severity informational``, so both tiers reach the uploaded SARIF and a
+``note`` alert may be either. The code-scanning alerts API exposes only the
+SARIF level -- not the ``zizmor/severity`` property carried in the raw SARIF --
+so the two cannot be separated here. ``note`` therefore stays at LOW rather
+than INFORMATIONAL, which errs towards over- rather than under-stating the
+estate's posture; the zizmor category cuts at INFORMATIONAL (see
+``categories.py``) so both tiers are reported regardless of where this maps.
 """
 
 from __future__ import annotations
@@ -49,6 +52,18 @@ class Severity(IntEnum):
         return self.name.lower()
 
 
+# The canonical worst-first rung order, for the severity columns and for every
+# worst-first ranking. Declared once so display order and ranking order cannot
+# drift apart.
+RUNGS_WORST_FIRST: tuple[Severity, ...] = (
+    Severity.CRITICAL,
+    Severity.HIGH,
+    Severity.MEDIUM,
+    Severity.LOW,
+    Severity.INFORMATIONAL,
+)
+
+
 # Direct names on the security-severity scale (CodeQL, Scorecard, Dependabot).
 _SECURITY_NAMES: dict[str, Severity] = {
     "critical": Severity.CRITICAL,
@@ -59,11 +74,13 @@ _SECURITY_NAMES: dict[str, Severity] = {
 }
 
 # SARIF level -> security scale, used only as a fallback (zizmor, aislop).
-# 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). aislop uses
-# the same three levels. The rare ``none`` level stays at INFORMATIONAL.
+# zizmor's SARIF encoder emits Low AND Informational findings as ``note``, and
+# the scan pipeline's --min-severity informational floor lets both through, so
+# a ``note`` alert may be either tier. The alerts API does not expose zizmor's
+# own severity property, so they are indistinguishable here; ``note`` maps to
+# LOW to avoid under-stating, and the zizmor category's INFORMATIONAL cutoff
+# ensures both are reported. aislop uses the same three levels. The rare
+# ``none`` level stays at INFORMATIONAL.
 _SARIF_LEVEL_NAMES: dict[str, Severity] = {
     "error": Severity.HIGH,
     "warning": Severity.MEDIUM,