github-security-report 0.1.0__py3-none-any.whl

github_security_report/posture.py

@@ -0,0 +1,264 @@
+# 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; a hidden compound sort score (the sum
+  of the release-staleness and tag-staleness day counts, so a repo with neither
+  counts its age twice) ranks the worst offenders first but is never displayed.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging
+from dataclasses import dataclass
+
+import yaml
+
+from github_security_report.models import Repo
+from github_security_report.report import TableRow, TableSection
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class RepoPosture:
+    """Per-repository configuration/freshness facts for the extra sections."""
+
+    repo: Repo
+    # Dependabot repo-level feature flags (None = indeterminate).
+    dependabot_alerts: bool | None = None
+    security_updates: 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
+
+
+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 is_release_excluded(
+    repo: Repo,
+    *,
+    generated_at: dt.datetime,
+    min_age_days: int,
+    exclude: frozenset[str] | set[str] | tuple[str, ...],
+) -> bool:
+    """Whether a repository is left out of the Releases / Tagging requirement.
+
+    A repository is excluded when its name is in ``exclude`` (never released /
+    not consumed externally) or when it was created within ``min_age_days``
+    (``0`` disables the age hold, so every repository is included). Used both to
+    skip the release/tag probes during collection and to filter the rendered
+    table, keeping the two decisions identical.
+    """
+    if repo.name in exclude:
+        return True
+    repo_age = _age_days(repo.created_at, generated_at)
+    return min_age_days > 0 and repo_age is not None and repo_age < min_age_days
+
+
+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 _age_cell(age: int | None) -> str:
+    if age is None:
+        return "never"
+    if age == 0:
+        return "today"
+    if age == 1:
+        return "1 day ago"
+    return f"{age} days ago"
+
+
+def build_alerts_table(postures: list[RepoPosture]) -> TableSection:
+    """Repositories where Dependabot vulnerability alerts are not enabled."""
+    rows = [
+        TableRow(repo=p.repo, cells=())
+        for p in sorted(postures, key=lambda p: p.repo.name)
+        if p.dependabot_alerts is False
+    ]
+    return TableSection(
+        title="Alerts Not Enabled",
+        columns=("Repository",),
+        rows=rows,
+        empty_note="No in-scope repository has Dependabot alerts confirmed disabled.",
+    )
+
+
+def build_security_updates_table(postures: list[RepoPosture]) -> TableSection:
+    """Repositories where Dependabot security updates are not enabled."""
+    rows = [
+        TableRow(repo=p.repo, cells=())
+        for p in sorted(postures, key=lambda p: p.repo.name)
+        if p.security_updates is False
+    ]
+    return TableSection(
+        title="Dependabot: Security Updates",
+        columns=("Repositories NOT Enabled",),
+        rows=rows,
+        empty_note=(
+            "No in-scope repository has Dependabot security updates confirmed "
+            "disabled."
+        ),
+    )
+
+
+def build_cooldown_table(postures: list[RepoPosture]) -> TableSection:
+    """A table of repositories/ecosystems that configure no update cooldown."""
+    rows = [
+        TableRow(repo=p.repo, cells=(", ".join(p.cooldown_missing),))
+        for p in sorted(postures, key=lambda p: p.repo.name)
+        if p.cooldown_missing
+    ]
+    return TableSection(
+        title="Dependabot: Cooldown Settings",
+        columns=("Repository", "Ecosystems without cooldown"),
+        rows=rows,
+        empty_note=(
+            "Every configured Dependabot ecosystem sets an update cooldown."
+        ),
+        note=(
+            "A cooldown is mandatory; any cooldown value passes. Repositories "
+            "with no Dependabot configuration are not listed here."
+        ),
+    )
+
+
+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_releases_table(
+    postures: list[RepoPosture],
+    *,
+    generated_at: dt.datetime,
+    min_age_days: int = 28,
+    exclude: tuple[str, ...] = (),
+) -> TableSection:
+    """The Releases / Tagging table, oldest-overall first.
+
+    Repositories created within ``min_age_days`` are excluded (0 = none
+    excluded), as are any whose name is in ``exclude``. Ranking uses a hidden
+    compound score = release-staleness-days + tag-staleness-days, where an
+    absent release or tag contributes the full repository age (so a repository
+    with neither effectively counts its age twice).
+    """
+    excluded = frozenset(exclude)
+    ranked: list[tuple[int, RepoPosture, int | None, int | None]] = []
+    for posture in postures:
+        repo = posture.repo
+        if is_release_excluded(
+            repo,
+            generated_at=generated_at,
+            min_age_days=min_age_days,
+            exclude=excluded,
+        ):
+            continue
+        repo_age = _age_days(repo.created_at, generated_at)
+        release_age = _age_days(posture.latest_release_at, generated_at)
+        tag_age = _age_days(posture.latest_tag_at, generated_at)
+        # Absent release/tag contributes the full repository age; an unknown
+        # creation date falls back to the staleness we do know (or zero).
+        fallback = repo_age if repo_age is not None else 0
+        compound = (release_age if release_age is not None else fallback) + (
+            tag_age if tag_age is not None else fallback
+        )
+        ranked.append((compound, posture, release_age, tag_age))
+    ranked.sort(key=lambda item: (-item[0], item[1].repo.name))
+    rows = [
+        TableRow(
+            repo=posture.repo,
+            cells=(_age_cell(release_age), _age_cell(tag_age)),
+        )
+        for _compound, posture, release_age, tag_age in ranked
+    ]
+    if min_age_days > 0:
+        age_note = (
+            f"Repositories created within {min_age_days} day(s) are excluded. "
+        )
+    else:
+        age_note = "All repositories are included (no minimum age). "
+    return TableSection(
+        title="Releases / Tagging",
+        columns=("Repository", "Last release", "Last tag"),
+        rows=rows,
+        empty_note=(
+            "No repositories to report (all were excluded by the minimum age "
+            "or the exclusion list)."
+        ),
+        note=(
+            age_note
+            + "Ranked by combined release and tag staleness (oldest first). "
+            "A repository with neither a release nor a tag ranks highest."
+        ),
+    )
+
+
+__all__ = [
+    "RepoPosture",
+    "is_release_excluded",
+    "cooldown_missing_ecosystems",
+    "build_dependabot_tables",
+    "build_releases_table",
+    "build_alerts_table",
+    "build_security_updates_table",
+    "build_cooldown_table",
+]

github_security_report/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. This package ships inline type information.

github_security_report/render/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Rendering of reports to Markdown, terminal, Slack, and HTML."""

github_security_report/render/html.py

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""HTML rendering (Jinja2 + Simple-DataTables).
+
+Renders each organisation to a single scrollable page with sortable/searchable
+tables (Simple-DataTables, version-pinned), and a card-grid index linking to
+every org -- the GitHub Pages layout. See ``docs/BRIEF.md`` section 11.
+"""
+
+from __future__ import annotations
+
+import re
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from github_security_report.models import RepoSignal, SignalType
+from github_security_report.render import markdown
+from github_security_report.report import (
+    OrgReport,
+    SignalSection,
+    TableSection,
+    truncate,
+)
+
+# Pinned, not @latest (a security tool must not load a floating CDN asset).
+DATATABLES_VERSION = "9.0.3"
+# Subresource Integrity (sha384) for the exact pinned files: the browser
+# verifies the fetched bytes against these, so a compromised/substituted CDN
+# asset is rejected. Regenerate if DATATABLES_VERSION changes, e.g.:
+#   curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A
+DATATABLES_CSS_SRI = "sha384-xnK68E/OAsSGcbvbeWEOyhjix2K7rBxt8Eytj/Ow9zuPG7WwFGGqMPQ8SbexlsL0"
+DATATABLES_JS_SRI = "sha384-JYQd44jQWQbU+FdjWIUlbjzENGRHPdOQcj7dAgjJEvSyt2js5lE85kaPOdC53JVu"
+
+_env = Environment(
+    loader=PackageLoader("github_security_report", "templates"),
+    autoescape=select_autoescape(["html", "j2"]),
+)
+
+
+# Anything outside this set is replaced; this also strips path separators and
+# dots, so a hostile org name (e.g. "../etc") cannot escape the output dir.
+_SLUG_UNSAFE = re.compile(r"[^a-z0-9_-]+")
+
+
+def slugify(org: str) -> str:
+    """Lowercase, filesystem- and URL-safe slug for an organisation name.
+
+    The result is used to build on-disk Pages paths (``output_dir / slug``) and
+    URLs, so it must never contain path separators or ``..``. Any character
+    outside ``[a-z0-9_-]`` (including ``/``, ``.`` and whitespace) collapses to
+    a single ``-``; a value that reduces to empty falls back to ``"org"``.
+    """
+    slug = _SLUG_UNSAFE.sub("-", org.strip().lower()).strip("-")
+    return slug or "org"
+
+
+def _row_cells(sig: RepoSignal) -> list[str]:
+    # Reuse the Markdown row shape (public API), dropping the leading repo cell.
+    return markdown.row_cells(sig)[1:]
+
+
+def _table_context(section: TableSection, top_n: int | None = None) -> dict:
+    """Context for a generic posture/freshness table (Dependabot, releases)."""
+    rows, hidden = truncate(section.rows, top_n)
+    return {
+        "title": section.title,
+        "columns": list(section.columns),
+        "rows": [
+            {"name": row.repo.name, "url": row.repo.html_url, "cells": list(row.cells)}
+            for row in rows
+        ],
+        "hidden": hidden,
+        "empty_note": section.empty_note,
+        "note": section.note,
+    }
+
+
+def _section_context(section: SignalSection, top_n: int | None = None) -> dict:
+    offenders, hidden = truncate(section.offenders, top_n)
+    nag, nag_hidden = truncate(section.nag_repos, top_n)
+    return {
+        "title": section.signal.heading,
+        "columns": markdown.columns(section.signal),
+        "rows": [
+            {"name": s.repo.name, "url": s.repo.html_url, "cells": _row_cells(s)}
+            for s in offenders
+        ],
+        "hidden": hidden,
+        "clean_count": section.clean_count,
+        "nag": [{"name": r.name, "url": r.html_url} for r in nag],
+        "nag_hidden": nag_hidden,
+        "unknown_count": section.unknown_count,
+    }
+
+
+def render_org_html(org: OrgReport, *, top_n: int | None = None) -> str:
+    template = _env.get_template("report.html.j2")
+    sections: list[dict] = []
+    for section in org.sections:
+        ctx = _section_context(section, top_n)
+        # The Dependabot posture sub-tables render beneath the Dependabot
+        # Alerts section, inside the same card.
+        if section.signal is SignalType.DEPENDABOT:
+            ctx["extra_tables"] = [
+                _table_context(t, top_n) for t in org.dependabot_tables
+            ]
+        sections.append(ctx)
+    excluded_shown, excluded_hidden = truncate(org.excluded_repos, top_n)
+    return str(
+        template.render(
+            org=org.org,
+            repo_count=org.repo_count,
+            generated_at=org.generated_at.strftime("%Y-%m-%d %H:%M UTC"),
+            partial=org.partial,
+            excluded=[
+                {"name": r.name, "url": r.html_url} for r in excluded_shown
+            ],
+            excluded_total=len(org.excluded_repos),
+            excluded_hidden=excluded_hidden,
+            sections=sections,
+            releases=_table_context(org.releases, top_n) if org.releases else None,
+            datatables_version=DATATABLES_VERSION,
+            datatables_css_sri=DATATABLES_CSS_SRI,
+            datatables_js_sri=DATATABLES_JS_SRI,
+        )
+    )
+
+
+def render_index_html(orgs: list[OrgReport]) -> str:
+    template = _env.get_template("index.html.j2")
+    generated_at = (
+        max(o.generated_at for o in orgs).strftime("%Y-%m-%d %H:%M UTC") if orgs else ""
+    )
+    return str(
+        template.render(
+            orgs=[
+                {"name": o.org, "slug": slugify(o.org), "repo_count": o.repo_count}
+                for o in orgs
+            ],
+            generated_at=generated_at,
+        )
+    )

github_security_report/render/markdown.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Canonical Markdown rendering.
+
+One heading per signal, immediately followed by a table of offenders
+(worst-first), then a clean count, a nag list, and an unknown-status footnote.
+This is the canonical artifact; Slack and the job summary derive from the same
+report model. See ``docs/BRIEF.md`` sections 4-6, 11.
+"""
+
+from __future__ import annotations
+
+from github_security_report.models import Repo, RepoSignal, SignalType
+from github_security_report.report import (
+    OrgReport,
+    Report,
+    SignalSection,
+    TableSection,
+    truncate,
+)
+
+
+def _link(repo: Repo) -> str:
+    return f"[{repo.name}]({repo.html_url})"
+
+
+def _columns(signal: SignalType) -> list[str]:
+    if signal is SignalType.SECRET_SCANNING:
+        return ["Repository", "Open"]
+    if signal is SignalType.SCORECARD:
+        return ["Repository", "Score", "Critical", "High", "Medium", "Low"]
+    return ["Repository", "Critical", "High", "Medium", "Low", "Total"]
+
+
+def _row(sig: RepoSignal) -> list[str]:
+    c = sig.counts
+    if sig.signal is SignalType.SECRET_SCANNING:
+        return [_link(sig.repo), str(c.total)]
+    if sig.signal is SignalType.SCORECARD:
+        score = f"{sig.score:.1f}" if sig.score is not None else "—"
+        return [_link(sig.repo), score, str(c.critical), str(c.high), str(c.medium), str(c.low)]
+    return [_link(sig.repo), str(c.critical), str(c.high), str(c.medium), str(c.low), str(c.total)]
+
+
+def _table(section: SignalSection, top_n: int | None = None) -> list[str]:
+    cols = _columns(section.signal)
+    aligns = ["---"] + ["---:"] * (len(cols) - 1)
+    lines = ["| " + " | ".join(cols) + " |", "| " + " | ".join(aligns) + " |"]
+    offenders, hidden = truncate(section.offenders, top_n)
+    for sig in offenders:
+        lines.append("| " + " | ".join(_row(sig)) + " |")
+    if hidden:
+        lines.append("")
+        lines.append(f"_… and {hidden} more_")
+    return lines
+
+
+# Public, render-surface-agnostic accessors for the per-signal table shape, so
+# other renderers (e.g. HTML) do not reach into this module's private helpers.
+def columns(signal: SignalType) -> list[str]:
+    """Column headings for a signal's offender table (repository first)."""
+    return _columns(signal)
+
+
+def row_cells(sig: RepoSignal) -> list[str]:
+    """Cells for one offender row (the repository link is the first cell)."""
+    return _row(sig)
+
+
+def render_section(section: SignalSection, *, top_n: int | None = None) -> str:
+    lines = [f"## {section.signal.heading}", ""]
+    if section.offenders:
+        lines.extend(_table(section, top_n))
+        lines.append("")
+    if section.clean_count:
+        lines.append(f"✅ {section.clean_count} repositories clean")
+        lines.append("")
+    if section.nag_repos:
+        nag, hidden = truncate(section.nag_repos, top_n)
+        lines.append("**Not enabled** — enable to appear in future reports:")
+        lines.append("")
+        lines.extend(f"- {_link(r)}" for r in nag)
+        if hidden:
+            lines.append(f"- _… and {hidden} more_")
+        lines.append("")
+    if section.unknown_count:
+        lines.append(
+            f"ℹ️ {section.unknown_count} repositories with unknown status "
+            "(insufficient permission or a transient read failure)"
+        )
+        lines.append("")
+    if not (
+        section.offenders
+        or section.clean_count
+        or section.nag_repos
+        or section.unknown_count
+    ):
+        lines.append("_No data available._")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_table_section(
+    section: TableSection, *, level: int = 3, top_n: int | None = None
+) -> str:
+    """Render a generic posture/freshness table at the given heading level."""
+    heading = "#" * level
+    lines = [f"{heading} {section.title}", ""]
+    rows, hidden = truncate(section.rows, top_n)
+    if rows:
+        aligns = ["---"] * len(section.columns)
+        lines.append("| " + " | ".join(section.columns) + " |")
+        lines.append("| " + " | ".join(aligns) + " |")
+        for row in rows:
+            cells = [_link(row.repo), *row.cells]
+            lines.append("| " + " | ".join(cells) + " |")
+        lines.append("")
+        if hidden:
+            lines.append(f"_… and {hidden} more_")
+            lines.append("")
+        if section.note:
+            # The note describes a populated table; omit it when empty.
+            lines.append(f"_{section.note}_")
+            lines.append("")
+    elif section.empty_note:
+        lines.append(f"✅ {section.empty_note}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_org(org: OrgReport, *, top_n: int | None = None) -> str:
+    when = org.generated_at.strftime("%Y-%m-%d %H:%M UTC")
+    parts = [
+        f"# Security report: {org.org}",
+        "",
+        f"_{org.repo_count} repositories analysed · generated {when}_",
+        "",
+    ]
+    if org.partial:
+        parts.append(
+            "> ⚠️ **Incomplete:** the repository listing could not be fully "
+            "read, so some repositories may be missing from this report."
+        )
+        parts.append("")
+    if org.excluded_repos:
+        shown, hidden = truncate(org.excluded_repos, top_n)
+        names = ", ".join(f"`{r.name}`" for r in shown)
+        if hidden:
+            names += f" … (+{hidden} more)"
+        parts.append(
+            f"⏩ **Excluded from analysis ({len(org.excluded_repos)}):** {names}"
+        )
+        parts.append("")
+    for section in org.sections:
+        parts.append(render_section(section, top_n=top_n))
+        # The Dependabot configuration-posture sub-tables nest beneath the
+        # Dependabot signal heading.
+        if section.signal is SignalType.DEPENDABOT:
+            parts.extend(
+                render_table_section(table, level=3, top_n=top_n)
+                for table in org.dependabot_tables
+            )
+    if org.releases is not None:
+        parts.append(render_table_section(org.releases, level=2, top_n=top_n))
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def render_report(report: Report, *, top_n: int | None = None) -> str:
+    return (
+        "\n\n".join(render_org(org, top_n=top_n) for org in report.orgs).rstrip()
+        + "\n"
+    )