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

github_security_report/runner.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""CLI support: mode resolution, fail-threshold, and GitHub Actions I/O.
+
+Pure helpers kept out of the Typer command so they can be unit-tested. See
+``docs/BRIEF.md`` sections 9-12.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import secrets
+from enum import Enum
+
+from github_security_report.models import RepoSignal
+from github_security_report.severity import Severity
+
+log = logging.getLogger(__name__)
+
+# GitHub Actions output names are alphanumeric plus '-'/'_'. Validating the key
+# (not just the value) stops a non-identifier key -- e.g. one containing a
+# newline, '=' or '<<' -- from corrupting $GITHUB_OUTPUT or injecting outputs.
+_OUTPUT_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
+
+
+class Mode(str, Enum):
+    ORG = "org"
+    REPO = "repo"
+
+
+class ModeError(RuntimeError):
+    """Raised when an operating mode cannot be resolved."""
+
+
+def resolve_mode(
+    requested: str,
+    *,
+    has_org_config: bool,
+    detected_repo: tuple[str, str] | None,
+) -> Mode:
+    """Resolve the operating mode, logging the outcome loudly.
+
+    Precedence: an explicit ``org``/``repo`` request wins; ``auto`` resolves to
+    org when org config is present, else repo when a repository was detected.
+    """
+    requested = requested.lower()
+    if requested == "org":
+        if not has_org_config:
+            raise ModeError("scope 'org' requires organisation configuration")
+        mode = Mode.ORG
+    elif requested == "repo":
+        if detected_repo is None:
+            raise ModeError("scope 'repo' requires a detected/--specified repository")
+        mode = Mode.REPO
+    elif requested == "auto":
+        if has_org_config:
+            mode = Mode.ORG
+        elif detected_repo is not None:
+            mode = Mode.REPO
+        else:
+            raise ModeError(
+                "cannot resolve scope: provide config (org mode) or run inside a "
+                "GitHub checkout (repo mode)"
+            )
+    else:
+        raise ModeError(f"unknown scope: {requested!r}")
+    log.info("resolved operating mode: %s", mode.value)
+    return mode
+
+
+_THRESHOLDS = {
+    "none": None,
+    "low": Severity.LOW,
+    "medium": Severity.MEDIUM,
+    "high": Severity.HIGH,
+    "critical": Severity.CRITICAL,
+}
+
+
+def _max_severity(sig: RepoSignal) -> Severity | None:
+    c = sig.counts
+    if c.critical:
+        return Severity.CRITICAL
+    if c.high:
+        return Severity.HIGH
+    if c.medium:
+        return Severity.MEDIUM
+    if c.low:
+        return Severity.LOW
+    return None
+
+
+def should_fail(signals: list[RepoSignal], threshold: str) -> bool:
+    """Whether the run should fail given a severity threshold (repo-mode gate).
+
+    ``none`` never fails; ``any`` fails on any offender; a severity name fails
+    when any offending signal has a finding at or above that severity.
+    """
+    threshold = threshold.lower()
+    if threshold == "none":
+        return False
+    if threshold == "any":
+        return any(s.is_offender for s in signals)
+    if threshold not in _THRESHOLDS:
+        raise ModeError(f"unknown fail threshold: {threshold!r}")
+    floor = _THRESHOLDS[threshold]
+    assert floor is not None
+    return any(
+        s.is_offender and (sev := _max_severity(s)) is not None and sev >= floor
+        for s in signals
+    )
+
+
+def write_github_output(values: dict[str, str], path: str | None = None) -> None:
+    """Append ``key=value`` pairs to ``$GITHUB_OUTPUT`` (multiline-safe).
+
+    Multiline values use a unique random delimiter per value, regenerated if it
+    ever collides with the value, to prevent output-file injection.
+    """
+    target = path or os.environ.get("GITHUB_OUTPUT")
+    if not target:
+        return
+    with open(target, "a", encoding="utf-8") as handle:
+        for key, value in values.items():
+            if not _OUTPUT_KEY.match(key):
+                # A non-identifier key would corrupt the output file; skip it
+                # loudly rather than write something injectable.
+                log.error("refusing to write unsafe GITHUB_OUTPUT key: %r", key)
+                continue
+            if "\n" in value:
+                delimiter = f"ghadelim_{secrets.token_hex(16)}"
+                while delimiter in value:
+                    delimiter = f"ghadelim_{secrets.token_hex(16)}"
+                handle.write(f"{key}<<{delimiter}\n{value}\n{delimiter}\n")
+            else:
+                handle.write(f"{key}={value}\n")
+
+
+def append_step_summary(markdown: str, path: str | None = None) -> None:
+    """Append Markdown to ``$GITHUB_STEP_SUMMARY`` if available."""
+    target = path or os.environ.get("GITHUB_STEP_SUMMARY")
+    if not target:
+        return
+    with open(target, "a", encoding="utf-8") as handle:
+        handle.write(markdown.rstrip() + "\n")

github_security_report/scope.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Repository scoping and exclusions.
+
+Default in-scope set: non-archived, non-fork, non-template source repos. Test
+repositories are excluded by **token-delimited** matching (a ``test``/``tests``
+segment after splitting on ``-_./``), never a raw substring -- so ``latest``,
+``attestation`` and ``contest`` are not dropped. Archived and test repos never
+appear in nag lists. Every exclusion is logged with its reason so nothing is
+dropped silently. See ``docs/BRIEF.md`` section 7.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+from github_security_report.models import Repo
+
+log = logging.getLogger(__name__)
+
+_SEGMENT_SPLIT = re.compile(r"[-_./]+")
+_TEST_SEGMENTS = {"test", "tests"}
+
+
+def is_test_named(name: str) -> bool:
+    """True when a name segment is exactly ``test`` or ``tests``.
+
+    Token-delimited, not substring: ``test-action`` and ``foo_test`` match;
+    ``latest-tag``, ``attestation`` and ``contest`` do not.
+    """
+    segments = {seg.lower() for seg in _SEGMENT_SPLIT.split(name) if seg}
+    return bool(segments & _TEST_SEGMENTS)
+
+
+@dataclass(frozen=True)
+class ScopeDecision:
+    repo: Repo
+    included: bool
+    reason: str = ""
+
+
+def decide(
+    repo: Repo,
+    *,
+    include_archived: bool = False,
+    include_test: bool = False,
+    exclude: frozenset[str] | set[str] | tuple[str, ...] = (),
+) -> ScopeDecision:
+    """Decide whether a single repository is in scope, with a reason."""
+    if repo.name in exclude:
+        return ScopeDecision(repo, False, "explicitly excluded")
+    if repo.fork:
+        return ScopeDecision(repo, False, "fork")
+    if repo.is_template:
+        return ScopeDecision(repo, False, "template")
+    if repo.archived and not include_archived:
+        return ScopeDecision(repo, False, "archived")
+    if is_test_named(repo.name) and not include_test:
+        return ScopeDecision(repo, False, "test repository")
+    return ScopeDecision(repo, True)
+
+
+def filter_repos(
+    repos: list[Repo],
+    *,
+    include_archived: bool = False,
+    include_test: bool = False,
+    exclude: tuple[str, ...] = (),
+) -> list[Repo]:
+    """Return the in-scope repositories, logging every exclusion and reason."""
+    exclude_set = set(exclude)
+    kept: list[Repo] = []
+    for repo in repos:
+        decision = decide(
+            repo,
+            include_archived=include_archived,
+            include_test=include_test,
+            exclude=exclude_set,
+        )
+        if decision.included:
+            kept.append(repo)
+        else:
+            log.info("excluding %s: %s", repo.full_name, decision.reason)
+    log.info("%d repositories in scope (of %d)", len(kept), len(repos))
+    return kept
+
+
+def in_nag_scope(repo: Repo) -> bool:
+    """Whether a repo may appear in nag lists.
+
+    Archived and test repos are **never** nagged -- you cannot, or would not,
+    enable tooling on them -- even when they are otherwise reported (e.g. under
+    ``include_archived``/``include_test``).
+    """
+    return not (repo.archived or is_test_named(repo.name))

github_security_report/severity.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Severity scale and normalisation.
+
+Phase 0 (see ``docs/phase0-findings.md``) established two severity vocabularies
+in the code-scanning feed:
+
+- ``rule.security_severity_level`` -- critical / high / medium / low -- used by
+  CodeQL and Scorecard, and the primary ranking key.
+- ``rule.severity`` -- error / warning / note -- the SARIF level, the only axis
+  zizmor populates.
+
+To present a single, uniform set of severity columns across every table (as the
+design requires), the SARIF level is normalised onto the security scale when no
+security severity is present: error -> high, warning -> medium, note -> low.
+Dependabot's ``security_advisory.severity`` maps directly.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    """Ordered severity. Higher value == more severe (worst-first sorting)."""
+
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    @property
+    def label(self) -> str:
+        return self.name.lower()
+
+
+# Direct names on the security-severity scale (CodeQL, Scorecard, Dependabot).
+_SECURITY_NAMES: dict[str, Severity] = {
+    "critical": Severity.CRITICAL,
+    "high": Severity.HIGH,
+    "medium": Severity.MEDIUM,
+    "moderate": Severity.MEDIUM,  # Dependabot uses "moderate"
+    "low": Severity.LOW,
+}
+
+# SARIF level -> security scale, used only as a fallback (zizmor).
+_SARIF_LEVEL_NAMES: dict[str, Severity] = {
+    "error": Severity.HIGH,
+    "warning": Severity.MEDIUM,
+    "note": Severity.LOW,
+    "none": Severity.LOW,
+}
+
+
+def from_name(value: str | None) -> Severity | None:
+    """Parse a security-severity name (critical/high/medium/low/moderate)."""
+    if not value:
+        return None
+    return _SECURITY_NAMES.get(value.strip().lower())
+
+
+def from_sarif_level(value: str | None) -> Severity | None:
+    """Parse a SARIF level (error/warning/note) onto the security scale."""
+    if not value:
+        return None
+    return _SARIF_LEVEL_NAMES.get(value.strip().lower())
+
+
+def from_code_scanning(
+    security_severity_level: str | None,
+    sarif_severity: str | None,
+) -> Severity:
+    """Resolve a code-scanning alert's severity.
+
+    Prefers ``security_severity_level``; falls back to the SARIF ``severity``
+    (the zizmor case). Defaults to ``LOW`` when neither is recognised so a
+    finding is never silently dropped from ranking.
+    """
+    return (
+        from_name(security_severity_level)
+        or from_sarif_level(sarif_severity)
+        or Severity.LOW
+    )

github_security_report/templates/index.html.j2

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Security reports</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif;
+      line-height: 1.6; color: #333;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh; padding: 2rem 1rem;
+    }
+    .container { max-width: 1100px; margin: 0 auto; }
+    header { background: #fff; border-radius: 12px; padding: 2rem; margin-bottom: 2rem;
+             box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+    header h1 { font-size: 2.25rem; color: #2d3748; }
+    header .subtitle { color: #718096; margin-top: 0.25rem; }
+    header .meta { color: #718096; font-size: 0.9rem; margin-top: 1rem;
+                  padding-top: 1rem; border-top: 1px solid #e2e8f0; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.5rem; }
+    .card { background: #fff; border-radius: 12px; padding: 1.5rem; box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+            transition: transform 0.2s ease, box-shadow 0.2s ease; }
+    .card:hover { transform: translateY(-4px); box-shadow: 0 8px 16px rgba(102,126,234,0.25); }
+    .card h2 { font-size: 1.25rem; color: #2d3748; }
+    .card .count { color: #718096; font-size: 0.9rem; margin: 0.5rem 0 1rem; }
+    .btn { display: inline-block; background: #667eea; color: #fff; padding: 0.5rem 1rem;
+           border-radius: 6px; text-decoration: none; font-weight: 500; }
+    .btn:hover { background: #5568d3; }
+    footer { text-align: center; color: #fff; padding: 2rem; font-size: 0.85rem; }
+    footer a { color: #fff; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1><span aria-hidden="true">🔐</span> Security reports</h1>
+      <p class="subtitle">Security and quality posture across GitHub organisations</p>
+      <div class="meta">Generated {{ generated_at }} · {{ orgs | length }} organisation(s)</div>
+    </header>
+    <div class="grid">
+      {% for org in orgs %}
+      <div class="card">
+        <h2>{{ org.name }}</h2>
+        <p class="count">{{ org.repo_count }} repositories</p>
+        <a class="btn" href="{{ org.slug }}/report.html">View report →</a>
+      </div>
+      {% endfor %}
+    </div>
+    <footer>
+      Generated by
+      <a href="https://github.com/lfreleng-actions/github-security-report-action">github-security-report</a>
+    </footer>
+  </div>
+</body>
+</html>

github_security_report/templates/report.html.j2

@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Security report: {{ org }}</title>
+  {#- Simple-DataTables: version-pinned with Subresource Integrity, so the
+      browser rejects a tampered/substituted CDN asset. -#}
+  <link rel="stylesheet"
+        href="https://cdn.jsdelivr.net/npm/simple-datatables@{{ datatables_version }}/dist/style.css"
+        integrity="{{ datatables_css_sri }}"
+        crossorigin="anonymous">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif;
+      line-height: 1.6; color: #1a202c; background: #f7fafc; padding: 2rem 1rem;
+    }
+    .container { max-width: 1100px; margin: 0 auto; }
+    header {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: #fff; border-radius: 12px; padding: 2rem; margin-bottom: 2rem;
+    }
+    header h1 { font-size: 2rem; }
+    header .meta { opacity: 0.9; font-size: 0.9rem; margin-top: 0.5rem; }
+    section { background: #fff; border-radius: 12px; padding: 1.5rem 2rem; margin-bottom: 1.5rem;
+              box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    section h2 { color: #2d3748; border-bottom: 2px solid #e2e8f0; padding-bottom: 0.5rem; }
+    section h3 { color: #2d3748; margin-top: 1.5rem; font-size: 1.05rem; }
+    .note { color: #718096; font-size: 0.85rem; margin-top: 0.5rem; font-style: italic; }
+    table { width: 100%; border-collapse: collapse; margin-top: 1rem; }
+    th, td { padding: 0.5rem 0.75rem; text-align: left; border-bottom: 1px solid #edf2f7; }
+    th { background: #f7fafc; }
+    td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+    .clean { color: #2f855a; margin-top: 0.75rem; }
+    .nag-title { margin-top: 1rem; font-weight: 600; color: #b7791f; }
+    .nag { margin: 0.25rem 0 0 1.25rem; }
+    .unknown { color: #718096; font-size: 0.9rem; margin-top: 0.75rem; }
+    .empty { color: #718096; font-style: italic; margin-top: 0.5rem; }
+    .crit { color: #c53030; font-weight: 600; }
+    .partial-banner { background: #fffaf0; border: 1px solid #dd6b20; color: #9c4221;
+                      border-radius: 8px; padding: 0.75rem 1rem; margin-bottom: 1.5rem; }
+    .excluded-banner { background: #ebf8ff; border: 1px solid #4299e1; color: #2c5282;
+                       border-radius: 8px; padding: 0.75rem 1rem; margin-bottom: 1.5rem; }
+    footer { text-align: center; color: #718096; font-size: 0.85rem; padding: 1rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1><span aria-hidden="true">🔐</span> Security report: {{ org }}</h1>
+      <div class="meta">{{ repo_count }} repositories analysed · generated {{ generated_at }}</div>
+    </header>
+
+    {% if partial %}
+    <div class="partial-banner" role="alert">
+      <span aria-hidden="true">⚠️</span> <strong>Incomplete:</strong> the repository
+      listing could not be fully read, so some repositories may be missing from
+      this report.
+    </div>
+    {% endif %}
+
+    {% if excluded %}
+    <div class="excluded-banner">
+      <span aria-hidden="true">⏩</span> <strong>Excluded from analysis ({{ excluded_total }}):</strong>
+      {% for r in excluded %}<a href="{{ r.url }}">{{ r.name }}</a>{% if not loop.last %}, {% endif %}{% endfor %}{% if excluded_hidden %} … and {{ excluded_hidden }} more{% endif %}
+    </div>
+    {% endif %}
+
+    {% for s in sections %}
+    <section>
+      <h2>{{ s.title }}</h2>
+      {% if s.rows %}
+      <table class="dt-enabled">
+        <thead>
+          <tr>{% for col in s.columns %}<th class="{{ 'num' if not loop.first else '' }}">{{ col }}</th>{% endfor %}</tr>
+        </thead>
+        <tbody>
+          {% for row in s.rows %}
+          <tr>
+            <td><a href="{{ row.url }}">{{ row.name }}</a></td>
+            {% for cell in row.cells %}<td class="num">{{ cell }}</td>{% endfor %}
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% if s.hidden %}<p class="note">… and {{ s.hidden }} more</p>{% endif %}
+      {% endif %}
+      {% if s.clean_count %}<p class="clean"><span aria-hidden="true">✅</span> {{ s.clean_count }} repositories clean</p>{% endif %}
+      {% if s.nag %}
+      <p class="nag-title">Not enabled — enable to appear in future reports:</p>
+      <ul class="nag">{% for r in s.nag %}<li><a href="{{ r.url }}">{{ r.name }}</a></li>{% endfor %}{% if s.nag_hidden %}<li>… and {{ s.nag_hidden }} more</li>{% endif %}</ul>
+      {% endif %}
+      {% if s.unknown_count %}<p class="unknown"><span aria-hidden="true">ℹ️</span> {{ s.unknown_count }} repositories with unknown status (insufficient permission or a transient read failure)</p>{% endif %}
+      {% if not (s.rows or s.clean_count or s.nag or s.unknown_count) %}<p class="empty">No data available.</p>{% endif %}
+      {% for t in s.extra_tables or [] %}
+      <h3>{{ t.title }}</h3>
+      {% if t.rows %}
+      <table class="dt-enabled">
+        <thead>
+          <tr>{% for col in t.columns %}<th>{{ col }}</th>{% endfor %}</tr>
+        </thead>
+        <tbody>
+          {% for row in t.rows %}
+          <tr>
+            <td><a href="{{ row.url }}">{{ row.name }}</a></td>
+            {% for cell in row.cells %}<td>{{ cell }}</td>{% endfor %}
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% if t.hidden %}<p class="note">… and {{ t.hidden }} more</p>{% endif %}
+      {% elif t.empty_note %}<p class="clean"><span aria-hidden="true">✅</span> {{ t.empty_note }}</p>{% endif %}
+      {% if t.rows and t.note %}<p class="note">{{ t.note }}</p>{% endif %}
+      {% endfor %}
+    </section>
+    {% endfor %}
+
+    {% if releases %}
+    <section>
+      <h2>{{ releases.title }}</h2>
+      {% if releases.rows %}
+      <table class="dt-enabled">
+        <thead>
+          <tr>{% for col in releases.columns %}<th>{{ col }}</th>{% endfor %}</tr>
+        </thead>
+        <tbody>
+          {% for row in releases.rows %}
+          <tr>
+            <td><a href="{{ row.url }}">{{ row.name }}</a></td>
+            {% for cell in row.cells %}<td>{{ cell }}</td>{% endfor %}
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% if releases.hidden %}<p class="note">… and {{ releases.hidden }} more</p>{% endif %}
+      {% elif releases.empty_note %}<p class="clean"><span aria-hidden="true">✅</span> {{ releases.empty_note }}</p>{% endif %}
+      {% if releases.rows and releases.note %}<p class="note">{{ releases.note }}</p>{% endif %}
+    </section>
+    {% endif %}
+
+    <footer>
+      Generated by
+      <a href="https://github.com/lfreleng-actions/github-security-report-action">github-security-report</a>
+    </footer>
+  </div>
+
+  <script src="https://cdn.jsdelivr.net/npm/simple-datatables@{{ datatables_version }}/dist/umd/simple-datatables.min.js"
+          integrity="{{ datatables_js_sri }}"
+          crossorigin="anonymous"
+          type="text/javascript"></script>
+  <script>
+    document.addEventListener('DOMContentLoaded', function () {
+      document.querySelectorAll('table.dt-enabled').forEach(function (table) {
+        if (table.querySelectorAll('tbody tr').length < 3) { return; }
+        try { new simpleDatatables.DataTable(table, { perPage: 25 }); }
+        catch (e) { console.error('DataTable init failed', e); }
+      });
+    });
+  </script>
+</body>
+</html>