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

github_security_report/config.py

@@ -0,0 +1,343 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Configuration: schema, loading, token resolution, and Slack-day gating.
+
+The tool's configuration is JSON, supplied either as a CLI file, a plain
+GitHub ``vars.`` entry, or base64 inside a ``secrets.`` entry (base64 only to
+stop raw JSON braces tripping GitHub's log redaction -- it is encoding, not
+encryption). Tokens are referenced by environment-variable name, never embedded
+literally. See ``docs/BRIEF.md`` sections 8-9.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import datetime as dt
+import json
+import logging
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from types import MappingProxyType
+
+import jsonschema
+
+log = logging.getLogger(__name__)
+
+WEEKDAYS = (
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+)
+
+# Heuristic to warn when a token value, rather than an env-var name, is given.
+_TOKEN_PREFIXES = ("ghp_", "gho_", "ghu_", "ghs_", "ghr_", "github_pat_")
+
+
+class ConfigError(ValueError):
+    """Raised when configuration is malformed or fails validation."""
+
+
+CONFIG_SCHEMA: dict = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "slack": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "channel": {"type": "string"},
+                "report_day": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ]
+                },
+            },
+        },
+        "report": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "top_n": {"type": "integer", "minimum": 1},
+                "top_n_report": {"type": "integer", "minimum": 1},
+                "top_n_cli": {"type": "integer", "minimum": 1},
+                "top_n_slack": {"type": "integer", "minimum": 1},
+                "include_archived": {"type": "boolean"},
+                "include_test": {"type": "boolean"},
+                "release_min_age_days": {"type": "integer", "minimum": 0},
+                "ruleset_workflows": {
+                    "type": "object",
+                    "additionalProperties": {"type": "string"},
+                },
+            },
+        },
+        "organizations": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["name"],
+                "properties": {
+                    "name": {"type": "string", "minLength": 1},
+                    "token_env": {"type": "string"},
+                    "exclude": {"type": "array", "items": {"type": "string"}},
+                    "releases_exclude": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "slack": {"$ref": "#/properties/slack"},
+                    "report": {"$ref": "#/properties/report"},
+                },
+            },
+        },
+    },
+    "required": ["organizations"],
+}
+
+
+@dataclass(frozen=True)
+class ReportDay:
+    """When to post the Slack digest. Owned and evaluated by the tool."""
+
+    always: bool = False
+    never: bool = False
+    days: frozenset[str] = field(default_factory=frozenset)
+
+    def should_notify(
+        self, *, now: dt.date | None = None, force: bool = False
+    ) -> bool:
+        if force or self.always:
+            return True
+        if self.never:
+            return False
+        today = (now or dt.date.today()).strftime("%A").lower()
+        return today in self.days
+
+
+@dataclass(frozen=True)
+class SlackConfig:
+    channel: str = ""
+    report_day: ReportDay = field(default_factory=lambda: ReportDay(days=frozenset({"tuesday"})))
+
+
+# Default mapping of signal value -> required-workflow path keyword. A repo
+# covered by an active org ruleset whose required workflow path contains the
+# keyword is treated as having that tool enabled (see :mod:`rulesets`).
+DEFAULT_RULESET_WORKFLOWS = {"zizmor": "zizmor"}
+
+
+@dataclass(frozen=True)
+class ReportConfig:
+    # Shared default number of offenders shown per signal; per-output overrides
+    # below take precedence when set. report = GitHub Pages (Markdown + HTML),
+    # cli = terminal, slack = the Slack digest.
+    top_n: int = 10
+    top_n_report: int | None = None
+    top_n_cli: int | None = None
+    top_n_slack: int | None = None
+    include_archived: bool = False
+    include_test: bool = False
+    # Repositories created within this many days are excluded from the
+    # Releases/Tagging requirement (0 = include all repositories).
+    release_min_age_days: int = 28
+    # Read-only mapping (frozen dataclasses do not deep-freeze a plain dict, so a
+    # MappingProxyType prevents in-place mutation of a shared config).
+    ruleset_workflows: Mapping[str, str] = field(
+        default_factory=lambda: MappingProxyType(dict(DEFAULT_RULESET_WORKFLOWS))
+    )
+
+    @property
+    def report_top_n(self) -> int:
+        """Offenders shown per signal in the GitHub Pages output."""
+        return self.top_n_report if self.top_n_report is not None else self.top_n
+
+    @property
+    def cli_top_n(self) -> int:
+        """Offenders shown per signal in the terminal output."""
+        return self.top_n_cli if self.top_n_cli is not None else self.top_n
+
+    @property
+    def slack_top_n(self) -> int:
+        """Offenders shown per signal in the Slack digest."""
+        return self.top_n_slack if self.top_n_slack is not None else self.top_n
+
+
+@dataclass(frozen=True)
+class OrgConfig:
+    name: str
+    token_env: str = "GITHUB_TOKEN"
+    exclude: tuple[str, ...] = ()
+    # Repositories excluded from the Releases/Tagging table only (e.g. repos
+    # that are never released/consumed externally).
+    releases_exclude: tuple[str, ...] = ()
+    slack: SlackConfig = field(default_factory=SlackConfig)
+    report: ReportConfig = field(default_factory=ReportConfig)
+
+
+@dataclass(frozen=True)
+class Config:
+    organizations: tuple[OrgConfig, ...]
+    slack: SlackConfig = field(default_factory=SlackConfig)
+    report: ReportConfig = field(default_factory=ReportConfig)
+
+
+def parse_report_day(value: str | list[str] | None) -> ReportDay:
+    """Parse ``report_day`` into a :class:`ReportDay`.
+
+    Accepts a single weekday, a list of weekdays, ``"never"`` or ``"always"``
+    (case-insensitive). Defaults to Tuesday when unset.
+    """
+    if value is None:
+        return ReportDay(days=frozenset({"tuesday"}))
+    items = [value] if isinstance(value, str) else list(value)
+    normalised = [item.strip().lower() for item in items if item.strip()]
+    if normalised == ["always"]:
+        return ReportDay(always=True)
+    if normalised == ["never"]:
+        return ReportDay(never=True)
+    for day in normalised:
+        if day in {"always", "never"}:
+            raise ConfigError(
+                f"'{day}' cannot be combined with weekdays in report_day"
+            )
+        if day not in WEEKDAYS:
+            raise ConfigError(f"invalid report_day value: {day!r}")
+    if not normalised:
+        return ReportDay(days=frozenset({"tuesday"}))
+    return ReportDay(days=frozenset(normalised))
+
+
+def _slack_from(data: dict, base: SlackConfig) -> SlackConfig:
+    return SlackConfig(
+        channel=data.get("channel", base.channel),
+        report_day=(
+            parse_report_day(data["report_day"])
+            if "report_day" in data
+            else base.report_day
+        ),
+    )
+
+
+def _report_from(data: dict, base: ReportConfig) -> ReportConfig:
+    result = replace(
+        base,
+        **{
+            k: v
+            for k, v in data.items()
+            if k in {
+                "top_n",
+                "top_n_report",
+                "top_n_cli",
+                "top_n_slack",
+                "include_archived",
+                "include_test",
+                "release_min_age_days",
+            }
+        },
+    )
+    if "ruleset_workflows" in data:
+        # Merge so the built-in defaults (e.g. zizmor) survive unless overridden.
+        merged = {**base.ruleset_workflows, **data["ruleset_workflows"]}
+        result = replace(result, ruleset_workflows=MappingProxyType(merged))
+    return result
+
+
+def build_config(data: dict) -> Config:
+    """Validate a config mapping and build the typed :class:`Config`."""
+    try:
+        jsonschema.validate(data, CONFIG_SCHEMA)
+    except jsonschema.ValidationError as exc:
+        raise ConfigError(f"configuration is invalid: {exc.message}") from exc
+
+    global_slack = _slack_from(data.get("slack", {}), SlackConfig())
+    global_report = _report_from(data.get("report", {}), ReportConfig())
+
+    orgs: list[OrgConfig] = []
+    for raw in data["organizations"]:
+        token_env = raw.get("token_env", "GITHUB_TOKEN")
+        if token_env.startswith(_TOKEN_PREFIXES):
+            log.warning(
+                "organization %r token_env looks like a literal token; it must "
+                "be an environment-variable NAME, not a token value",
+                raw["name"],
+            )
+        orgs.append(
+            OrgConfig(
+                name=raw["name"],
+                token_env=token_env,
+                exclude=tuple(raw.get("exclude", ())),
+                releases_exclude=tuple(raw.get("releases_exclude", ())),
+                slack=_slack_from(raw.get("slack", {}), global_slack),
+                report=_report_from(raw.get("report", {}), global_report),
+            )
+        )
+    return Config(
+        organizations=tuple(orgs), slack=global_slack, report=global_report
+    )
+
+
+def loads(raw: str) -> Config:
+    """Load config from a string that is either raw JSON or base64-of-JSON.
+
+    Tries JSON first; if that fails, tries base64-decoding then JSON. This lets
+    the same loader read a plain ``vars.`` entry or a base64 ``secrets.`` entry
+    without the caller knowing which it is.
+    """
+    text = raw.strip()
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        try:
+            decoded = base64.b64decode(text, validate=True).decode("utf-8")
+            data = json.loads(decoded)
+        except (binascii.Error, UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ConfigError(
+                "configuration is neither valid JSON nor base64-encoded JSON"
+            ) from exc
+    if not isinstance(data, dict):
+        raise ConfigError("configuration must be a JSON object")
+    return build_config(data)
+
+
+def load_file(path: str) -> Config:
+    with open(path, encoding="utf-8") as handle:
+        return loads(handle.read())
+
+
+# Conventional per-user config location, so a local run with no flags picks up
+# a central config instead of erroring. Honours $XDG_CONFIG_HOME, falling back
+# to ~/.config (the XDG Base Directory default).
+DEFAULT_CONFIG_DIR = "github-security-report"
+DEFAULT_CONFIG_FILE = "config.json"
+
+
+def default_config_path() -> Path:
+    """The conventional per-user config path (whether or not it exists).
+
+    ``$XDG_CONFIG_HOME/github-security-report/config.json`` when the variable is
+    set, otherwise ``~/.config/github-security-report/config.json``.
+    """
+    base = os.environ.get("XDG_CONFIG_HOME", "").strip() or str(Path.home() / ".config")
+    return Path(base) / DEFAULT_CONFIG_DIR / DEFAULT_CONFIG_FILE
+
+
+def find_default_config() -> Path | None:
+    """The per-user config path if a readable file exists there, else None."""
+    path = default_config_path()
+    return path if path.is_file() else None
+
+
+def resolve_token(org: OrgConfig, env: dict[str, str] | None = None) -> str | None:
+    """Resolve an organisation's token from the environment by name."""
+    environ = env if env is not None else os.environ
+    token = environ.get(org.token_env, "").strip()
+    return token or None

github_security_report/gitctx.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Git context detection for local repo-mode.
+
+When run inside a Git checkout with no org config, the tool defaults to repo
+mode for the repository the checkout points at. The remote is resolved in
+preference order ``upstream`` then ``origin``, and only ``github.com`` remotes
+qualify. See ``docs/BRIEF.md`` section 10.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+from collections.abc import Callable
+
+log = logging.getLogger(__name__)
+
+REMOTE_PREFERENCE = ("upstream", "origin")
+
+# git@github.com:owner/repo(.git) or https://github.com/owner/repo(.git)
+_SSH = re.compile(r"^git@github\.com:(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?$")
+_HTTPS = re.compile(
+    r"^https://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+
+def parse_remote_url(url: str) -> tuple[str, str] | None:
+    """Parse a github.com remote URL into ``(owner, repo)``; None otherwise."""
+    url = url.strip()
+    match = _SSH.match(url) or _HTTPS.match(url)
+    if not match:
+        return None
+    return match.group("owner"), match.group("repo")
+
+
+def _git_remote_url(name: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", name],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (OSError, FileNotFoundError):  # git not installed / not a repo
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def detect_repo(
+    remote_reader: Callable[[str], str | None] = _git_remote_url,
+) -> tuple[str, str] | None:
+    """Resolve ``(owner, repo)`` from git remotes (upstream, then origin)."""
+    for name in REMOTE_PREFERENCE:
+        url = remote_reader(name)
+        if not url:
+            continue
+        parsed = parse_remote_url(url)
+        if parsed:
+            log.info("detected %s/%s from the %s remote", parsed[0], parsed[1], name)
+            return parsed
+        log.debug("remote %s (%s) is not a github.com remote", name, url)
+    return None

github_security_report/models.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 The Linux Foundation
+"""Domain models for the security report.
+
+Encodes the Phase 0 design (see ``docs/BRIEF.md`` and
+``docs/phase0-findings.md``): the five v1 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).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from enum import Enum
+
+from github_security_report.severity import Severity
+
+
+class SignalType(str, Enum):
+    """The five v1 ranked signals."""
+
+    CODEQL = "codeql"
+    SCORECARD = "scorecard"
+    ZIZMOR = "zizmor"
+    DEPENDABOT = "dependabot"
+    SECRET_SCANNING = "secret_scanning"
+
+    @property
+    def heading(self) -> str:
+        return {
+            SignalType.CODEQL: "CodeQL",
+            SignalType.SCORECARD: "OpenSSF Scorecard",
+            SignalType.ZIZMOR: "Zizmor Static Analysis",
+            SignalType.DEPENDABOT: "Dependabot: Security Alerts",
+            SignalType.SECRET_SCANNING: "Secret scanning",
+        }[self]
+
+    @property
+    def uses_severity_columns(self) -> bool:
+        """Secret scanning is a flat open-count; the rest use severity columns.
+
+        Scorecard's primary metric is its aggregate score, but its
+        code-scanning findings still carry severities, so it keeps the columns.
+        """
+        return self is not SignalType.SECRET_SCANNING
+
+    @property
+    def sort_ascending(self) -> bool:
+        """Scorecard ranks by score ascending (lower == worse); others descend."""
+        return self is SignalType.SCORECARD
+
+
+class RepoState(str, Enum):
+    """The four-state per-report classification (BRIEF section 6)."""
+
+    OFFENDER = "offender"  # enabled + has open findings -> table row
+    CLEAN = "clean"  # enabled + zero findings -> counted beneath table
+    NAG = "nag"  # supported but not enabled -> bulleted nag list
+    UNKNOWN = "unknown"  # indeterminate (403 / insufficient permission)
+
+
+@dataclass(frozen=True)
+class Repo:
+    """Minimal repository identity carried through the report."""
+
+    name: str
+    full_name: str
+    html_url: str
+    archived: bool = False
+    fork: bool = False
+    is_template: bool = False
+    private: bool = False
+    default_branch: str = "main"
+    # Repository creation time (UTC); used to exclude freshly-created repos from
+    # the release/tag age requirement. None when the API did not provide it.
+    created_at: dt.datetime | None = None
+
+
+@dataclass
+class SeverityCounts:
+    """Open-finding counts by severity, with worst-first ordering."""
+
+    critical: int = 0
+    high: int = 0
+    medium: int = 0
+    low: int = 0
+
+    def add(self, severity: Severity, count: int = 1) -> None:
+        if severity is Severity.CRITICAL:
+            self.critical += count
+        elif severity is Severity.HIGH:
+            self.high += count
+        elif severity is Severity.MEDIUM:
+            self.medium += count
+        else:
+            self.low += count
+
+    @property
+    def total(self) -> int:
+        return self.critical + self.high + self.medium + self.low
+
+    @property
+    def weighted(self) -> int:
+        """Severity-weighted score, so 1 critical outranks many low findings."""
+        return (
+            self.critical * 1000
+            + self.high * 100
+            + self.medium * 10
+            + self.low
+        )
+
+    @property
+    def sort_key(self) -> tuple[int, int, int, int]:
+        """Hierarchical key: critical, then high, then medium, then low.
+
+        Use with ``reverse=True`` for worst-first ordering.
+        """
+        return (self.critical, self.high, self.medium, self.low)
+
+
+@dataclass
+class RepoSignal:
+    """One repository's result for one signal."""
+
+    repo: Repo
+    signal: SignalType
+    state: RepoState
+    counts: SeverityCounts = field(default_factory=SeverityCounts)
+    score: float | None = None  # Scorecard aggregate (0-10), lower == worse
+    detail: str = ""  # short human note (e.g. "secret scanning disabled")
+
+    @property
+    def is_offender(self) -> bool:
+        return self.state is RepoState.OFFENDER
+
+
+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.
+
+    Numeric components are negated so the whole sort runs ascending (no
+    ``reverse=True``); that keeps the name tiebreaker correctly ascending even
+    when one name is a prefix of another.
+    """
+    offenders = [s for s in signals if s.is_offender]
+    if not offenders:
+        return []
+    signal = offenders[0].signal
+    if signal.sort_ascending:
+        return sorted(
+            offenders,
+            key=lambda s: (
+                s.score if s.score is not None else float("inf"),
+                s.repo.name,
+            ),
+        )
+    return sorted(
+        offenders,
+        key=lambda s: (
+            -s.counts.critical,
+            -s.counts.high,
+            -s.counts.medium,
+            -s.counts.low,
+            -s.counts.total,
+            s.repo.name,
+        ),
+    )