commitguardian 0.1.0__py3-none-any.whl

commitguard/github/auth.py

@@ -0,0 +1,217 @@
+"""GitHub App authentication.
+
+::
+
+    App ID + private key --(RS256 JWT, 9 min)--> POST /app/installations/{id}/access_tokens
+                                                  (repository_ids=[one repo], least-privilege
+                                                   permissions)
+                          <-- installation token (expires after ~1 hour)
+
+* The private key is parsed once at start-up; a malformed, encrypted, non-RSA
+  or short key fails closed with a message that never contains key material.
+* JWTs and installation tokens are :class:`~commitguard.security.secrets.Secret`
+  values registered for redaction; they are kept in memory only, never
+  persisted, and dropped when they are near expiry, when GitHub rejects them,
+  or when the installation or repository is removed.
+* Every installation token is down-scoped to the single repository being
+  scanned and to :data:`~commitguard.github.permissions.REQUIRED_PERMISSIONS`;
+  GitHub refuses to mint it if the installation cannot access that repository,
+  which makes the token request itself an authorization check.
+"""
+
+import base64
+import json
+import threading
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import NoReturn
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+from commitguard.github.client import GitHubClient, InstallationTokenGrant
+from commitguard.github.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    GitHubForbiddenError,
+    GitHubNotFoundError,
+    GitHubUnauthorizedError,
+    GitHubValidationError,
+    InsufficientPermissionsError,
+)
+from commitguard.github.permissions import REQUIRED_PERMISSIONS, missing_permissions
+from commitguard.security.secrets import Secret, default_redactor, register_secret
+
+MIN_RSA_KEY_BITS = 2048
+JWT_BACKDATE_SECONDS = 60  # tolerate clock drift between this host and GitHub
+JWT_LIFETIME_SECONDS = 540  # GitHub allows at most 10 minutes
+JWT_REUSE_MARGIN_SECONDS = 60
+TOKEN_EXPIRY_MARGIN = timedelta(minutes=5)
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+class AppCredentials:
+    """The App ID and parsed private key. Creates short-lived JWTs."""
+
+    def __init__(
+        self, app_id: int, private_key_pem: Secret, *, clock: Callable[[], float] = time.time
+    ) -> None:
+        if not isinstance(app_id, int) or app_id <= 0:
+            raise AuthenticationError("GitHub App ID must be a positive integer")
+        try:
+            key = serialization.load_pem_private_key(
+                private_key_pem.reveal().encode("utf-8"), password=None
+            )
+        except Exception:  # noqa: BLE001 - never chain: parser errors could echo input
+            raise AuthenticationError(
+                "GitHub App private key is malformed or encrypted "
+                "(expected an unencrypted PEM RSA private key)"
+            ) from None
+        if not isinstance(key, rsa.RSAPrivateKey):
+            raise AuthenticationError("GitHub App private key must be an RSA key")
+        if key.key_size < MIN_RSA_KEY_BITS:
+            raise AuthenticationError(
+                f"GitHub App private key must be at least {MIN_RSA_KEY_BITS} bits"
+            )
+        self.app_id = app_id
+        self._key = key
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._jwt: Secret | None = None
+        self._jwt_expires = 0.0
+
+    def __repr__(self) -> str:
+        return f"AppCredentials(app_id={self.app_id})"
+
+    def __reduce__(self) -> NoReturn:
+        raise TypeError("AppCredentials cannot be pickled")
+
+    def create_jwt(self) -> Secret:
+        """A JWT for App-level API calls, reused until shortly before it expires."""
+        now = self._clock()
+        with self._lock:
+            if self._jwt is not None and now < self._jwt_expires - JWT_REUSE_MARGIN_SECONDS:
+                return self._jwt
+            issued = int(now) - JWT_BACKDATE_SECONDS
+            expires = int(now) + JWT_LIFETIME_SECONDS
+            header = _b64url(
+                json.dumps({"alg": "RS256", "typ": "JWT"}, separators=(",", ":")).encode()
+            )
+            claims = {"iat": issued, "exp": expires, "iss": str(self.app_id)}
+            payload = _b64url(json.dumps(claims, separators=(",", ":")).encode())
+            signing_input = f"{header}.{payload}".encode("ascii")
+            signature = self._key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+            token = Secret(f"{header}.{payload}.{_b64url(signature)}")
+            register_secret(token)
+            if self._jwt is not None:
+                default_redactor().forget(self._jwt)
+            self._jwt, self._jwt_expires = token, float(expires)
+            return token
+
+
+@dataclass(frozen=True, slots=True)
+class InstallationToken:
+    installation_id: int
+    repository_id: int | None
+    token: Secret
+    expires_at: datetime
+    permissions: Mapping[str, str]
+
+    def usable_at(self, now: datetime) -> bool:
+        return now < self.expires_at - TOKEN_EXPIRY_MARGIN
+
+
+class InstallationTokenProvider:
+    """Mints and caches down-scoped installation tokens (memory only)."""
+
+    def __init__(
+        self,
+        credentials: AppCredentials,
+        client: GitHubClient,
+        *,
+        permissions: Mapping[str, str] = REQUIRED_PERMISSIONS,
+        now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._credentials = credentials
+        self._client = client
+        self._permissions = dict(permissions)
+        self._now = now
+        self._lock = threading.Lock()
+        self._cache: dict[tuple[int, int | None], InstallationToken] = {}
+
+    def app_jwt(self) -> Secret:
+        """A short-lived App JWT for App-level API calls (e.g. installation details)."""
+        return self._credentials.create_jwt()
+
+    def token(self, installation_id: int, repository_id: int | None) -> InstallationToken:
+        """A token for one repository (or, with ``None``, the whole installation)."""
+        key = (int(installation_id), None if repository_id is None else int(repository_id))
+        with self._lock:
+            cached = self._cache.get(key)
+            if cached is not None and cached.usable_at(self._now()):
+                return cached
+        grant = self._mint(*key)
+        token = InstallationToken(
+            installation_id=key[0],
+            repository_id=key[1],
+            token=grant.token,
+            expires_at=grant.expires_at,
+            permissions=dict(grant.permissions),
+        )
+        with self._lock:
+            previous = self._cache.get(key)
+            self._cache[key] = token
+        if previous is not None:
+            default_redactor().forget(previous.token)
+        return token
+
+    def _mint(self, installation_id: int, repository_id: int | None) -> InstallationTokenGrant:
+        jwt = self._credentials.create_jwt()
+        try:
+            grant = self._client.create_installation_token(
+                jwt,
+                installation_id,
+                repository_ids=None if repository_id is None else [repository_id],
+                permissions=self._permissions,
+            )
+        except GitHubUnauthorizedError:
+            raise AuthenticationError(
+                "GitHub rejected the App credentials (check the App ID and private key)"
+            ) from None
+        except GitHubNotFoundError:
+            raise AuthorizationError(
+                "GitHub App installation not found (the App may have been uninstalled)"
+            ) from None
+        except GitHubValidationError:
+            raise AuthorizationError(
+                "the installation cannot access this repository with the required permissions"
+            ) from None
+        except GitHubForbiddenError:
+            raise AuthorizationError(
+                "GitHub refused an installation token (installation suspended?)"
+            ) from None
+        if grant.expires_at.tzinfo is None or grant.expires_at <= self._now():
+            raise AuthenticationError("GitHub returned an already expired installation token")
+        if repository_id is not None and grant.repository_ids not in ((), (repository_id,)):
+            raise AuthorizationError("installation token is not scoped to the requested repository")
+        missing = missing_permissions(grant.permissions, self._permissions)
+        if missing:
+            raise InsufficientPermissionsError(missing)
+        return grant
+
+    def invalidate(self, installation_id: int, repository_id: int | None = None) -> None:
+        """Forget cached tokens for an installation (or one of its repositories)."""
+        with self._lock:
+            keys = [
+                k
+                for k in self._cache
+                if k[0] == installation_id and (repository_id is None or k[1] == repository_id)
+            ]
+            dropped = [self._cache.pop(k) for k in keys]
+        for token in dropped:
+            default_redactor().forget(token.token)

commitguard/github/check_runs.py

@@ -0,0 +1,172 @@
+"""Check Run content for the GitHub App, rendered from a :class:`ScanResult`.
+
+The conclusion comes from :class:`~commitguard.services.enforcement.EnforcementDecision`
+(BLOCK -> ``failure``; WARN -> ``success`` with warnings listed; could not
+verify -> ``failure``/``timed_out``). Security violations are never reported
+as successful checks. All untrusted values (identities, subjects, policy
+descriptions) are Markdown-escaped and truncated; output is capped at
+:data:`~commitguard.github.checks.MAX_CHECK_FINDINGS` findings with counts for
+the rest, and never includes secrets or infrastructure details.
+"""
+
+from commitguard.core.decision import Action
+from commitguard.github.checks import MAX_CHECK_FINDINGS, CheckRunConclusion, CheckRunOutput
+from commitguard.github.markdown import escape_markdown as md
+from commitguard.services.enforcement import EnforcementState, FailureKind
+from commitguard.services.reports import CommitReport, EvaluatedFinding
+from commitguard.services.scan import ScanResult
+
+_REMEDIATION = (
+    "Remove the prohibited attribution from the listed commits (for example by "
+    "rewording them locally) and push the corrected commits. CommitGuard never "
+    "rewrites history or modifies the repository."
+)
+
+
+def queued_output(description: str) -> CheckRunOutput:
+    return CheckRunOutput(
+        title="Queued",
+        summary=f"CommitGuard will scan {md(description, 120)}.",
+    )
+
+
+def in_progress_output(commits: int, policy_source: str) -> CheckRunOutput:
+    return CheckRunOutput(
+        title=f"Scanning {commits} commit(s)",
+        summary=(
+            f"CommitGuard is scanning **{commits}** commit(s).\n\nPolicy: {md(policy_source, 200)}"
+        ),
+    )
+
+
+def error_output(kind: FailureKind, reason: str) -> tuple[CheckRunConclusion, CheckRunOutput]:
+    conclusion = (
+        CheckRunConclusion.TIMED_OUT if kind is FailureKind.TIMEOUT else CheckRunConclusion.FAILURE
+    )
+    title = {
+        FailureKind.CONFIGURATION: "Configuration error",
+        FailureKind.AUTHORIZATION: "Not authorized",
+        FailureKind.INFRASTRUCTURE: "Scan could not be completed",
+        FailureKind.TIMEOUT: "Scan timed out",
+        FailureKind.INTERNAL: "Scan could not be completed",
+    }[kind]
+    summary = (
+        "## CommitGuard could not verify repository policy\n\n"
+        f"Reason: {md(reason, 500)}\n\n"
+        "Security validation could not be completed, so this check fails (fail closed). "
+        "Push a new commit or reopen the pull request to scan again."
+    )
+    return conclusion, CheckRunOutput(title=title, summary=summary)
+
+
+def _finding_lines(index: int, commit: CommitReport, item: EvaluatedFinding) -> list[str]:
+    finding = item.finding
+    return [
+        f"#### {index}. {md(finding.title, 120)}",
+        "",
+        f"- **Rule:** {finding.rule_id}",
+        f"- **Commit:** {md(commit.short_sha, 40)} {md(commit.subject, 120)}",
+        f"- **Identity:** {md(finding.evidence[0].value, 200)}",
+        f"- **Source:** {md(finding.evidence[0].source.label, 60)}",
+        f"- **Severity:** {finding.severity.value}",
+        f"- **Action:** {item.action.value}",
+        f"- **Remediation:** {md(finding.remediation, 300)}",
+        "",
+    ]
+
+
+def completed_output(result: ScanResult) -> tuple[CheckRunConclusion, CheckRunOutput]:
+    report, stats, meta = result.report, result.statistics, result.metadata
+    decision = result.enforcement
+    conclusion = CheckRunConclusion(decision.check_conclusion)
+    blocked = decision.state is EnforcementState.BLOCKED
+    with_warnings = decision.state is EnforcementState.PASSED_WITH_WARNINGS
+
+    if blocked:
+        heading, title = "CommitGuard: BLOCKED", f"Blocked: {stats.violations} violation(s)"
+    elif with_warnings:
+        heading, title = (
+            "CommitGuard: PASS (with warnings)",
+            f"Passed with {stats.warnings} warning(s)",
+        )
+    else:
+        heading, title = (
+            "CommitGuard: PASS",
+            f"Passed: {stats.commits_scanned} commit(s) scanned",
+        )
+
+    ci = report.ci
+    rows = [
+        "| | |",
+        "|---|---|",
+        f"| Commits scanned | {stats.commits_scanned} |",
+        f"| Violations | {stats.violations} |",
+        f"| Warnings | {stats.warnings} |",
+        f"| Detector failures | {stats.detector_failures} |",
+    ]
+    if ci is not None:
+        rows.append(f"| Policy | {md(ci.policy_source, 200)} |")
+        if ci.base_sha and ci.head_sha:
+            rows.append(f"| Range | {ci.base_sha[:12]}..{ci.head_sha[:12]} |")
+        elif ci.head_sha:
+            rows.append(f"| Commit | {ci.head_sha[:12]} |")
+    rows.append(f"| Scan ID | {meta.scan_id} |")
+    summary = [f"## {heading}", "", *rows, ""]
+    if not blocked and not with_warnings:
+        summary += ["All configured CommitGuard policies passed.", ""]
+    if ci is not None and ci.policy_weakenings:
+        summary += [
+            "### Security policy modification detected",
+            "",
+            "The evaluated commits attempt to weaken an existing CommitGuard policy. "
+            "They were evaluated with the trusted policy; additional authorization may be "
+            "required.",
+            "",
+            *[f"- {md(change, 200)}" for change in ci.policy_weakenings],
+            "",
+        ]
+    if ci is not None and ci.notices:
+        summary += ["### Notices", "", *[f"- {md(n, 400)}" for n in ci.notices], ""]
+
+    ordered = sorted(report.commits, key=lambda c: -c.action.rank)
+    failures = [(c, f) for c in ordered for f in c.failures]
+    violations = [(c, f) for c in ordered for f in c.findings if f.action is Action.BLOCK]
+    warnings = [(c, f) for c in ordered for f in c.findings if f.action is Action.WARN]
+
+    text: list[str] = []
+    if failures:
+        text += ["### Detector failures", ""]
+        for commit, failure in failures[:MAX_CHECK_FINDINGS]:
+            text.append(
+                f"- {md(commit.short_sha, 40)}: {md(failure.failure.detector, 60)} did not "
+                f"complete ({md(failure.failure.message, 200)}); action {failure.action.value}"
+            )
+        text.append("")
+    shown = 0
+    for label, items in (("Violations", violations), ("Warnings", warnings)):
+        if not items:
+            continue
+        text += [f"### {label}", ""]
+        budget = max(0, MAX_CHECK_FINDINGS - shown)
+        for index, (commit, item) in enumerate(items[:budget], start=1):
+            text += _finding_lines(index, commit, item)
+        shown += min(len(items), budget)
+        if len(items) > budget:
+            text += [f"{label}: {len(items)}. Showing first {budget}.", ""]
+    total = len(violations) + len(warnings)
+    if total > MAX_CHECK_FINDINGS:
+        target = (
+            f"{ci.base_sha}..{ci.head_sha}"
+            if ci is not None and ci.base_sha and ci.head_sha
+            else "<range>"
+        )
+        text += [
+            f"Showing {MAX_CHECK_FINDINGS} of {total} findings. Use the CommitGuard CLI for the "
+            f"complete machine-readable report: `commitguard scan {target} --format json`",
+            "",
+        ]
+    if blocked:
+        text += ["### Remediation", "", _REMEDIATION, ""]
+    return conclusion, CheckRunOutput(
+        title=title, summary="\n".join(summary), text="\n".join(text) or None
+    )

commitguard/github/checks.py

@@ -0,0 +1,210 @@
+"""Check output built from a report, for both GitHub integrations.
+
+* ``build_check_output`` feeds the Actions job summary and workflow annotations.
+* The Check Run types at the end of this module are what the GitHub App sends
+  to the Checks API (content rendered by :mod:`commitguard.github.check_runs`).
+
+Nothing here talks to GitHub. Findings already carry rule ID, severity,
+message, evidence and commit, so a SARIF exporter can be built from the same
+report later.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.core.decision import Action
+from commitguard.services.reports import ScanReport
+
+MAX_ANNOTATIONS_PER_LEVEL = 10  # GitHub shows at most 10 errors and 10 warnings per step
+
+
+class AnnotationLevel(StrEnum):
+    FAILURE = "failure"
+    WARNING = "warning"
+    NOTICE = "notice"
+
+
+class Annotation(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    level: AnnotationLevel
+    title: str
+    message: str
+    rule_id: str | None = None
+    commit_sha: str | None = None
+
+
+class CheckOutput(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    conclusion: str  # "success" | "failure"
+    title: str
+    counts: dict[str, int]
+    annotations: tuple[Annotation, ...]
+    omitted_annotations: int = 0
+
+
+def check_conclusion(action: Action, fail_on: Action = Action.BLOCK) -> str:
+    return "failure" if action.rank >= fail_on.rank else "success"
+
+
+def build_check_output(report: ScanReport, *, fail_on: Action = Action.BLOCK) -> CheckOutput:
+    commits = report.commits
+    counts = {
+        "commits": len(commits),
+        "block": sum(1 for c in commits if c.action is Action.BLOCK),
+        "warn": sum(1 for c in commits if c.action is Action.WARN),
+        "allow": sum(1 for c in commits if c.action is Action.ALLOW),
+        "findings": sum(len(c.findings) for c in commits),
+        "failures": sum(len(c.failures) for c in commits),
+    }
+    annotations: list[Annotation] = []
+    per_level: dict[AnnotationLevel, int] = {}
+    omitted = 0
+
+    def add(annotation: Annotation) -> None:
+        nonlocal omitted
+        used = per_level.get(annotation.level, 0)
+        if used >= MAX_ANNOTATIONS_PER_LEVEL:
+            omitted += 1
+            return
+        per_level[annotation.level] = used + 1
+        annotations.append(annotation)
+
+    for commit in sorted(commits, key=lambda c: -c.action.rank):
+        for failure in commit.failures:
+            add(
+                Annotation(
+                    level=AnnotationLevel.FAILURE,
+                    title="CommitGuard: detector failure",
+                    message=f"{commit.short_sha}: {failure.failure.detector} did not complete "
+                    f"({failure.failure.message}); analysis incomplete",
+                    commit_sha=commit.commit_sha,
+                )
+            )
+        for item in commit.findings:
+            if item.action is Action.ALLOW:
+                continue
+            finding = item.finding
+            level = (
+                AnnotationLevel.FAILURE
+                if item.action.rank >= fail_on.rank
+                else AnnotationLevel.WARNING
+            )
+            add(
+                Annotation(
+                    level=level,
+                    title=f"CommitGuard: {finding.title}",
+                    message=(
+                        f"{commit.short_sha} {commit.subject}: {finding.evidence[0].value} "
+                        f"[{finding.rule_id}, {finding.severity.value}, action {item.action.value}]"
+                    ),
+                    rule_id=finding.rule_id,
+                    commit_sha=commit.commit_sha,
+                )
+            )
+    if report.ci is not None:
+        for notice in report.ci.notices:
+            add(Annotation(level=AnnotationLevel.NOTICE, title="CommitGuard", message=notice))
+
+    conclusion = check_conclusion(report.action, fail_on)
+    if conclusion == "failure":
+        title = f"CommitGuard: {counts['block']} of {counts['commits']} commit(s) blocked"
+        if counts["block"] == 0:
+            title = f"CommitGuard: failed on warnings ({counts['warn']} commit(s))"
+    elif counts["warn"]:
+        title = f"CommitGuard: passed with warnings ({counts['warn']} commit(s))"
+    else:
+        title = f"CommitGuard: passed ({counts['commits']} commit(s) checked)"
+    return CheckOutput(
+        conclusion=conclusion,
+        title=title,
+        counts=counts,
+        annotations=tuple(annotations),
+        omitted_annotations=omitted,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# GitHub App Check Runs (Checks API)
+# --------------------------------------------------------------------------- #
+# The App publishes its own check, separate from the Action's "commitguard" job:
+#
+# * "commitguard-app"       - pull requests: the check to require in branch protection;
+# * "commitguard-app/push"  - pushes: informational (the commits are already on GitHub).
+#
+# Separate names keep a push scan (only the newly pushed commits) from ever
+# replacing a pull request scan (all commits of the PR) on the same SHA.
+#
+# Commit metadata has no file or line, so no annotations are sent: findings are
+# listed in the summary and text instead of being attached to invented locations.
+
+APP_CHECK_NAME = "commitguard-app"
+APP_PUSH_CHECK_NAME = "commitguard-app/push"
+MAX_CHECK_FINDINGS = 20
+MAX_CHECK_TITLE_CHARS = 200
+MAX_CHECK_TEXT_CHARS = 60_000  # GitHub limit: 65535 characters for summary and text
+
+
+class CheckRunStatus(StrEnum):
+    QUEUED = "queued"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+class CheckRunConclusion(StrEnum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    NEUTRAL = "neutral"
+    CANCELLED = "cancelled"
+    TIMED_OUT = "timed_out"
+    ACTION_REQUIRED = "action_required"
+
+
+class CheckRunOutput(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    title: str
+    summary: str
+    text: str | None = None
+
+    def to_api(self) -> dict[str, str]:
+        output = {
+            "title": self.title[:MAX_CHECK_TITLE_CHARS],
+            "summary": _clip(self.summary),
+        }
+        if self.text:
+            output["text"] = _clip(self.text)
+        return output
+
+
+def _clip(text: str) -> str:
+    if len(text) <= MAX_CHECK_TEXT_CHARS:
+        return text
+    return text[: MAX_CHECK_TEXT_CHARS - 40] + "\n\n_Output truncated by CommitGuard._\n"
+
+
+def check_run_create_payload(
+    *, name: str, head_sha: str, external_id: str, output: CheckRunOutput
+) -> dict[str, object]:
+    return {
+        "name": name,
+        "head_sha": head_sha,
+        "status": CheckRunStatus.QUEUED.value,
+        "external_id": external_id,
+        "output": output.to_api(),
+    }
+
+
+def check_run_update_payload(
+    status: CheckRunStatus,
+    output: CheckRunOutput,
+    conclusion: CheckRunConclusion | None = None,
+) -> dict[str, object]:
+    if (status is CheckRunStatus.COMPLETED) != (conclusion is not None):
+        raise ValueError("a conclusion is required exactly when the check run is completed")
+    payload: dict[str, object] = {"status": status.value, "output": output.to_api()}
+    if conclusion is not None:
+        payload["conclusion"] = conclusion.value
+    return payload