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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-security-report
-Version: 0.2.0
+Version: 0.3.0
 Summary: Security and quality reporting across GitHub organisations
 Project-URL: Homepage, https://github.com/lfreleng-actions/github-security-report-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github-security-report-action
@@ -34,9 +34,9 @@ Provides-Extra: dev
 Requires-Dist: mypy==2.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==9.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.17; extra == 'dev'
+Requires-Dist: ruff==0.15.18; extra == 'dev'
 Requires-Dist: syrupy==5.3.2; extra == 'dev'
 Requires-Dist: types-jsonschema==4.26.0.20260518; extra == 'dev'
 Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
@@ -70,9 +70,16 @@ states and rendered worst-first:
 
 - **Offenders** — enabled with open findings (a ranked table row).
 - **Clean** — enabled with zero findings (a count beneath the table).
-- **Not enabled** — supported but switched off (a nag list prompting you to
-  enable it).
-- **Unknown** — indeterminate (insufficient permission), footnoted separately.
+- **Not enabled** — supported but switched off (a counted "disabled" footer
+  line, with the affected repositories named).
+- **Unknown** — indeterminate (insufficient permission), counted separately.
+
+Every category renders the same **standardised summary footer** beneath its
+table: remediation-first count lines (failures, disabled, unknown, then the
+healthy pass line, then excluded). The pass line reads **"All <state>"** when
+nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
+stay brevity-first; the explanatory per-category description and documentation
+link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
 
 The single GitHub code-scanning feed is partitioned by `tool.name` into CodeQL,
 Scorecard, and zizmor; Scorecard prefers the external aggregate score and falls
@@ -90,9 +97,10 @@ tables (org mode):
   release/tag staleness (repository age never affects ordering; a repository
   with no release or tag ranks highest). Repositories younger than
   `repo_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted. Set `release_max_age_days` to only flag
-  repositories whose newest release or tag is older than that many days
-  (default `0` = flag every eligible repository).
+  `releases_exclude` are omitted. A repository is flagged only when its newest
+  release or tag is older than `release_max_age_days` (default 60; `0` flags
+  every eligible repository), so a repository released or tagged within that
+  window counts as recently maintained and drops out of the table.
 
 ## Operating modes
 
@@ -222,7 +230,7 @@ environment-variable name, never embedded.
     "include_archived": false,
     "include_test": false,
     "repo_min_age_days": 28,
-    "release_max_age_days": 0
+    "release_max_age_days": 60
   },
   "organizations": [
     {
@@ -251,10 +259,10 @@ The Releases / Tagging section has two independent freshness levers:
   period that omits **brand-new repositories** — those *created* within that
   many days — before a release or tag is expected of them. CLI:
   `--repo-min-age-days`.
-- `report.release_max_age_days` (default `0` = flag everything) is the
+- `report.release_max_age_days` (default `60`; `0` = flag everything) is the
   release-staleness threshold: a repository is only flagged when its newest
   release **or** tag is older than that many days (a repository with neither is
-  always flagged). Raise it to match your release cadence so actively released
+  always flagged). Tune it to match your release cadence so actively released
   repositories drop out of the table. CLI: `--release-max-age-days`.
 
 The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
@@ -269,6 +277,74 @@ The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
 exclusion is visible rather than silently dropped.
 
+### Per-category render toggles
+
+Every reporting category can be switched on or off, globally and per output
+surface, under `report.categories`. Data is **always** collected; these toggles
+govern presentation only. Each category key takes an `enabled` switch (highest
+precedence — `false` hides it everywhere) and a lower-precedence `outputs` map
+for the four surfaces (`cli`, `slack`, `markdown`, `html`). Everything defaults
+to `true`, so an omitted category or key stays fully enabled. A category is
+rendered on a surface only when `enabled` **and** that surface's toggle are
+both true.
+
+```json
+{
+  "report": {
+    "categories": {
+      "zizmor": { "enabled": false },
+      "releases": { "outputs": { "cli": false, "slack": false } }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+The example above hides Zizmor on every surface, and keeps Releases / Tagging
+out of the terminal and Slack while still publishing it to the Markdown and HTML
+Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
+`dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
+`mutable_releases`. Like the other `report` settings, `categories` can be set
+globally and overridden per organisation (overrides merge key-by-key, so
+flipping one output leaves the rest untouched). The machine-readable
+`report.json` artifact always contains the complete dataset, regardless of these
+toggles.
+
+When several organisations share one Slack channel they render into a single
+combined digest, so the per-org Slack toggles are unioned for that channel: a
+category appears if **any** contributing org would show it on Slack. An org-level
+Slack disable therefore does not suppress a category in a shared-channel digest
+unless every org sharing that channel also disables it (this mirrors the
+most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
+and HTML surfaces are per-org and are not affected by this union.
+
+### Pass/fail severity cutoff
+
+The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use a
+`fail_severity` cutoff to decide when a repository counts as a failure. A
+repository is flagged as an offender only when it carries a finding **at or
+above** the cutoff; findings below it fold into the clean count. Severities run
+(lowest to highest) `informational`, `low`, `medium`, `high`, `critical` —
+`informational` being the new sub-low rung that SARIF `note`/`none` findings
+(the bulk of a tool like Zizmor) normalise to.
+
+The global default cutoff is `medium`, so `low` and `informational` findings
+pass. Zizmor defaults to `low` (only `informational` passes). Override the
+cutoff per category under `report.categories.<key>.fail_severity`:
+
+```json
+{
+  "report": {
+    "categories": {
+      "codeql": { "fail_severity": "low" },
+      "zizmor": { "fail_severity": "informational" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
 `slack.channel` is optional. The action's `slack_channel` input (wired to the
 `SLACK_CHANNEL_ID` variable in `reporting.yaml`) overrides it, so the channel
 can live as an org/repo variable rather than in the config JSON. It must be the

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

@@ -26,9 +26,16 @@ states and rendered worst-first:
 
 - **Offenders** — enabled with open findings (a ranked table row).
 - **Clean** — enabled with zero findings (a count beneath the table).
-- **Not enabled** — supported but switched off (a nag list prompting you to
-  enable it).
-- **Unknown** — indeterminate (insufficient permission), footnoted separately.
+- **Not enabled** — supported but switched off (a counted "disabled" footer
+  line, with the affected repositories named).
+- **Unknown** — indeterminate (insufficient permission), counted separately.
+
+Every category renders the same **standardised summary footer** beneath its
+table: remediation-first count lines (failures, disabled, unknown, then the
+healthy pass line, then excluded). The pass line reads **"All <state>"** when
+nothing needs attention, or **"N <state>"** otherwise. The terminal and Slack
+stay brevity-first; the explanatory per-category description and documentation
+link are shown only on the richer Markdown and HTML (GitHub Pages) outputs.
 
 The single GitHub code-scanning feed is partitioned by `tool.name` into CodeQL,
 Scorecard, and zizmor; Scorecard prefers the external aggregate score and falls
@@ -46,9 +53,10 @@ tables (org mode):
   release/tag staleness (repository age never affects ordering; a repository
   with no release or tag ranks highest). Repositories younger than
   `repo_min_age_days` (default 28; `0` includes all) and those in
-  `releases_exclude` are omitted. Set `release_max_age_days` to only flag
-  repositories whose newest release or tag is older than that many days
-  (default `0` = flag every eligible repository).
+  `releases_exclude` are omitted. A repository is flagged only when its newest
+  release or tag is older than `release_max_age_days` (default 60; `0` flags
+  every eligible repository), so a repository released or tagged within that
+  window counts as recently maintained and drops out of the table.
 
 ## Operating modes
 
@@ -178,7 +186,7 @@ environment-variable name, never embedded.
     "include_archived": false,
     "include_test": false,
     "repo_min_age_days": 28,
-    "release_max_age_days": 0
+    "release_max_age_days": 60
   },
   "organizations": [
     {
@@ -207,10 +215,10 @@ The Releases / Tagging section has two independent freshness levers:
   period that omits **brand-new repositories** — those *created* within that
   many days — before a release or tag is expected of them. CLI:
   `--repo-min-age-days`.
-- `report.release_max_age_days` (default `0` = flag everything) is the
+- `report.release_max_age_days` (default `60`; `0` = flag everything) is the
   release-staleness threshold: a repository is only flagged when its newest
   release **or** tag is older than that many days (a repository with neither is
-  always flagged). Raise it to match your release cadence so actively released
+  always flagged). Tune it to match your release cadence so actively released
   repositories drop out of the table. CLI: `--release-max-age-days`.
 
 The per-org `releases_exclude` (CLI `--releases-exclude`, repeatable) drops
@@ -225,6 +233,74 @@ The per-org `exclude` list removes repositories from analysis entirely; they are
 reported as **excluded** (distinct from "not enabled"), so an intentional
 exclusion is visible rather than silently dropped.
 
+### Per-category render toggles
+
+Every reporting category can be switched on or off, globally and per output
+surface, under `report.categories`. Data is **always** collected; these toggles
+govern presentation only. Each category key takes an `enabled` switch (highest
+precedence — `false` hides it everywhere) and a lower-precedence `outputs` map
+for the four surfaces (`cli`, `slack`, `markdown`, `html`). Everything defaults
+to `true`, so an omitted category or key stays fully enabled. A category is
+rendered on a surface only when `enabled` **and** that surface's toggle are
+both true.
+
+```json
+{
+  "report": {
+    "categories": {
+      "zizmor": { "enabled": false },
+      "releases": { "outputs": { "cli": false, "slack": false } }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
+The example above hides Zizmor on every surface, and keeps Releases / Tagging
+out of the terminal and Slack while still publishing it to the Markdown and HTML
+Pages output. The valid category keys are: `codeql`, `scorecard`, `zizmor`,
+`dependabot_alerts`, `secret_scanning`, `dependabot_alerts_enabled`,
+`dependabot_updates_enabled`, `dependabot_cooldown`, `releases`,
+`mutable_releases`. Like the other `report` settings, `categories` can be set
+globally and overridden per organisation (overrides merge key-by-key, so
+flipping one output leaves the rest untouched). The machine-readable
+`report.json` artifact always contains the complete dataset, regardless of these
+toggles.
+
+When several organisations share one Slack channel they render into a single
+combined digest, so the per-org Slack toggles are unioned for that channel: a
+category appears if **any** contributing org would show it on Slack. An org-level
+Slack disable therefore does not suppress a category in a shared-channel digest
+unless every org sharing that channel also disables it (this mirrors the
+most-generous `top_n` rule applied to the same grouping). The terminal, Markdown
+and HTML surfaces are per-org and are not affected by this union.
+
+### Pass/fail severity cutoff
+
+The severity-ranked signals (CodeQL, Scorecard, Zizmor, Dependabot alerts) use a
+`fail_severity` cutoff to decide when a repository counts as a failure. A
+repository is flagged as an offender only when it carries a finding **at or
+above** the cutoff; findings below it fold into the clean count. Severities run
+(lowest to highest) `informational`, `low`, `medium`, `high`, `critical` —
+`informational` being the new sub-low rung that SARIF `note`/`none` findings
+(the bulk of a tool like Zizmor) normalise to.
+
+The global default cutoff is `medium`, so `low` and `informational` findings
+pass. Zizmor defaults to `low` (only `informational` passes). Override the
+cutoff per category under `report.categories.<key>.fail_severity`:
+
+```json
+{
+  "report": {
+    "categories": {
+      "codeql": { "fail_severity": "low" },
+      "zizmor": { "fail_severity": "informational" }
+    }
+  },
+  "organizations": [{ "name": "lfreleng-actions" }]
+}
+```
+
 `slack.channel` is optional. The action's `slack_channel` input (wired to the
 `SLACK_CHANNEL_ID` variable in `reporting.yaml`) overrides it, so the channel
 can live as an org/repo variable rather than in the config JSON. It must be the

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

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

{github_security_report-0.2.0 → github_security_report-0.3.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.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

github_security_report-0.3.0/src/github_security_report/categories.py

@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Report category metadata.
+
+A single, render-surface-agnostic registry describing every reporting category
+the tool produces. Each category carries its display title, the pass/fail
+vocabulary used in the standardised summary footer, a documentation URL, and a
+default human description. Renderers read this registry instead of hard-coding
+per-category headings, labels and explanatory text, so a wording change here
+flows to the terminal, Slack, Markdown and HTML surfaces at once.
+
+The registry deliberately holds no behaviour and imports nothing from the rest
+of the package except the leaf ``severity`` module (which itself imports nothing
+from the package), so both the domain models and the renderers can depend on it
+without a cycle. ``key`` values are the stable identifiers used by the
+per-category configuration toggles, so treat them as part of the config
+contract: rename with care.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from github_security_report.severity import Severity
+
+
+class CategoryKey(str, Enum):
+    """Stable identifier for one reporting category (also the config key)."""
+
+    CODEQL = "codeql"
+    SCORECARD = "scorecard"
+    ZIZMOR = "zizmor"
+    DEPENDABOT_ALERTS = "dependabot_alerts"
+    SECRET_SCANNING = "secret_scanning"
+    DEPENDABOT_ALERTS_ENABLED = "dependabot_alerts_enabled"
+    DEPENDABOT_UPDATES_ENABLED = "dependabot_updates_enabled"
+    DEPENDABOT_COOLDOWN = "dependabot_cooldown"
+    RELEASES = "releases"
+    MUTABLE_RELEASES = "mutable_releases"
+
+
+@dataclass(frozen=True)
+class CategoryMeta:
+    """Display and documentation metadata for one reporting category.
+
+    ``pass_label`` names the healthy state (e.g. ``"Clean"``, ``"Immutable"``)
+    and is what the summary footer reports as ``All <pass_label>`` when nothing
+    needs attention. ``fail_label`` names the actionable state for categories
+    with a binary pass/fail axis (enablement, cooldown, mutability, release
+    freshness); it is ``None`` for the severity-ranked signals, whose offenders
+    are enumerated in the table itself rather than as a single failure count.
+    ``description`` is the default explanatory text shown beneath the table on
+    the Markdown and HTML surfaces; a builder may override it at runtime when
+    the wording depends on configuration (e.g. the release-age thresholds).
+    """
+
+    key: CategoryKey
+    title: str
+    pass_label: str
+    fail_label: str | None
+    url: str
+    description: str = ""
+    # The lowest finding severity that counts as a failure for this category.
+    # 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.
+    fail_severity: Severity = Severity.MEDIUM
+
+
+_CATEGORIES: dict[CategoryKey, CategoryMeta] = {
+    CategoryKey.CODEQL: CategoryMeta(
+        key=CategoryKey.CODEQL,
+        title="CodeQL",
+        pass_label="Clean",
+        fail_label=None,
+        url="https://codeql.github.com/",
+        description=(
+            "CodeQL code-scanning findings, ranked worst-first by severity. "
+            "Each row shows a repository's open-alert counts."
+        ),
+    ),
+    CategoryKey.SCORECARD: CategoryMeta(
+        key=CategoryKey.SCORECARD,
+        title="OpenSSF Scorecard",
+        pass_label="Clean",
+        fail_label=None,
+        url="https://github.com/ossf/scorecard",
+        description=(
+            "OpenSSF Scorecard supply-chain health scores (a lower score is "
+            "weaker), ranked weakest-first."
+        ),
+    ),
+    CategoryKey.ZIZMOR: CategoryMeta(
+        key=CategoryKey.ZIZMOR,
+        title="Zizmor Static Analysis",
+        pass_label="Clean",
+        fail_label=None,
+        url="https://github.com/zizmorcore/zizmor",
+        description=(
+            "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.
+        fail_severity=Severity.LOW,
+    ),
+    CategoryKey.DEPENDABOT_ALERTS: CategoryMeta(
+        key=CategoryKey.DEPENDABOT_ALERTS,
+        title="Dependabot: Security Alerts",
+        pass_label="Clean",
+        fail_label=None,
+        url=(
+            "https://docs.github.com/en/code-security/dependabot/"
+            "dependabot-alerts/about-dependabot-alerts"
+        ),
+        description=(
+            "Open Dependabot alerts for vulnerable dependencies, counted by "
+            "severity per repository."
+        ),
+    ),
+    CategoryKey.SECRET_SCANNING: CategoryMeta(
+        key=CategoryKey.SECRET_SCANNING,
+        title="Secret scanning",
+        pass_label="Clean",
+        fail_label=None,
+        url=(
+            "https://docs.github.com/en/code-security/secret-scanning/"
+            "about-secret-scanning"
+        ),
+        description=(
+            "Open secret-scanning alerts. Each row shows a repository's count "
+            "of detected, unresolved secrets."
+        ),
+    ),
+    CategoryKey.DEPENDABOT_ALERTS_ENABLED: CategoryMeta(
+        key=CategoryKey.DEPENDABOT_ALERTS_ENABLED,
+        title="Dependabot: Alerts Enabled",
+        pass_label="Enabled",
+        fail_label="Not enabled",
+        url=(
+            "https://docs.github.com/en/code-security/dependabot/"
+            "dependabot-alerts/configuring-dependabot-alerts"
+        ),
+        description=(
+            "Repositories with Dependabot security alerts disabled. Enable "
+            "them so vulnerable dependencies surface as alerts."
+        ),
+    ),
+    CategoryKey.DEPENDABOT_UPDATES_ENABLED: CategoryMeta(
+        key=CategoryKey.DEPENDABOT_UPDATES_ENABLED,
+        title="Dependabot: Security Updates",
+        pass_label="Enabled",
+        fail_label="Not enabled",
+        url=(
+            "https://docs.github.com/en/code-security/concepts/"
+            "supply-chain-security/dependabot-security-updates"
+        ),
+        description=(
+            "Repositories with Dependabot security updates disabled. Enable "
+            "them so fixes for vulnerable dependencies arrive as pull requests "
+            "automatically."
+        ),
+    ),
+    CategoryKey.DEPENDABOT_COOLDOWN: CategoryMeta(
+        key=CategoryKey.DEPENDABOT_COOLDOWN,
+        title="Dependabot: Cooldown Settings",
+        pass_label="Enabled",
+        fail_label="Without cooldown",
+        url=(
+            "https://docs.github.com/en/code-security/reference/"
+            "supply-chain-security/dependabot-options-reference#cooldown-"
+        ),
+        description=(
+            "Repositories whose Dependabot configuration omits an update "
+            "cooldown. A cooldown is mandatory; any cooldown value passes. "
+            "Repositories with no Dependabot configuration do not appear here."
+        ),
+    ),
+    CategoryKey.RELEASES: CategoryMeta(
+        key=CategoryKey.RELEASES,
+        title="Releases / Tagging",
+        pass_label="Current",
+        fail_label="Overdue",
+        url=(
+            "https://docs.github.com/en/repositories/"
+            "releasing-projects-on-github/about-releases"
+        ),
+        description=(
+            "Repositories ranked by combined release and tag staleness "
+            "(oldest first). A repository with neither a release nor a tag "
+            "ranks highest."
+        ),
+    ),
+    CategoryKey.MUTABLE_RELEASES: CategoryMeta(
+        key=CategoryKey.MUTABLE_RELEASES,
+        title="Mutable Releases",
+        pass_label="Immutable",
+        fail_label="Mutable",
+        url=(
+            "https://docs.github.com/en/code-security/concepts/"
+            "supply-chain-security/immutable-releases"
+        ),
+        description=(
+            "Repositories whose latest or last-published release is mutable. "
+            "Republish them as immutable releases so a published artifact "
+            "cannot change after the fact."
+        ),
+    ),
+}
+
+
+def category_meta(key: CategoryKey) -> CategoryMeta:
+    """The :class:`CategoryMeta` for ``key`` (registry lookup)."""
+    return _CATEGORIES[key]
+
+
+def all_categories() -> tuple[CategoryMeta, ...]:
+    """Every category's metadata, in registry (render) order."""
+    return tuple(_CATEGORIES.values())