commitguardian 0.1.0__py3-none-any.whl

commitguard/security/hashing.py

@@ -0,0 +1,30 @@
+"""Deterministic hashing helpers.
+
+Used to derive stable identifiers (e.g. finding fingerprints) so the same
+violation on the same commit always produces the same ID for audit purposes.
+"""
+
+import hashlib
+from collections.abc import Iterable
+
+_FIELD_SEPARATOR = b"\x1f"  # ASCII unit separator: cannot be confused with text
+
+
+def sha256_hex(data: bytes) -> str:
+    """Return the lowercase hex SHA-256 digest of ``data``."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def fingerprint(parts: Iterable[str]) -> str:
+    """Return a stable SHA-256 fingerprint over an ordered sequence of strings.
+
+    Each part is length-prefixed, so ``["ab", "c"]`` and ``["a", "bc"]`` never
+    collide even if a part contains the separator byte.
+    """
+    digest = hashlib.sha256()
+    for part in parts:
+        encoded = part.encode("utf-8", errors="surrogatepass")
+        digest.update(str(len(encoded)).encode("ascii"))
+        digest.update(_FIELD_SEPARATOR)
+        digest.update(encoded)
+    return digest.hexdigest()

commitguard/security/rate_limit.py

@@ -0,0 +1,33 @@
+"""Fixed-window request rate limiting with bounded memory.
+
+Used by the webhook endpoint (per client address) and the dashboard API (per
+user or client address, per operation category). Limits are per process.
+"""
+
+import threading
+import time
+from collections.abc import Callable
+
+
+class RequestRateLimiter:
+    """Fixed-window request counter per client address (bounded memory)."""
+
+    MAX_TRACKED = 10_000
+
+    def __init__(self, per_minute: int, clock: Callable[[], float] = time.monotonic) -> None:
+        self._limit = per_minute
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._windows: dict[str, tuple[int, int]] = {}
+
+    def allow(self, key: str) -> bool:
+        window = int(self._clock() // 60)
+        with self._lock:
+            if len(self._windows) > self.MAX_TRACKED:
+                self._windows.clear()
+            start, count = self._windows.get(key, (window, 0))
+            if start != window:
+                start, count = window, 0
+            count += 1
+            self._windows[key] = (start, count)
+            return count <= self._limit

commitguard/security/safe_yaml.py

@@ -0,0 +1,69 @@
+"""Hardened YAML loading for configuration and rule files.
+
+* ``yaml.SafeLoader`` only: no Python object construction;
+* duplicate mapping keys are rejected (a later ``action: allow`` must not
+  silently override an earlier ``action: block``);
+* anchors/aliases are rejected, removing "billion laughs" style expansion.
+"""
+
+from typing import Any
+
+import yaml
+
+
+class UnsafeYAMLError(yaml.YAMLError):
+    """Raised for YAML constructs CommitGuard refuses to load."""
+
+
+class _StrictSafeLoader(yaml.SafeLoader):
+    def compose_node(self, parent: yaml.Node | None, index: int) -> yaml.Node | None:
+        if self.check_event(yaml.events.AliasEvent):
+            event = self.peek_event()  # type: ignore[no-untyped-call]
+            raise yaml.composer.ComposerError(
+                None, None, "YAML aliases are not allowed", event.start_mark
+            )
+        return super().compose_node(parent, index)
+
+
+def _construct_unique_mapping(
+    loader: _StrictSafeLoader, node: yaml.MappingNode, deep: bool = False
+) -> dict[Any, Any]:
+    seen: set[Any] = set()
+    for key_node, _ in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        try:
+            duplicate = key in seen
+        except TypeError as exc:  # unhashable key such as a list
+            raise yaml.constructor.ConstructorError(
+                None, None, "mapping keys must be scalars", key_node.start_mark
+            ) from exc
+        if duplicate:
+            raise yaml.constructor.ConstructorError(
+                None, None, f"duplicate key {key!r}", key_node.start_mark
+            )
+        seen.add(key)
+    return loader.construct_mapping(node, deep=deep)
+
+
+_StrictSafeLoader.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _construct_unique_mapping
+)
+
+
+def load_yaml(text: str) -> object:
+    """Parse one YAML document with the strict safe loader.
+
+    Raises :class:`yaml.YAMLError` (including for duplicate keys and aliases).
+    """
+    # SafeLoader subclass: no object construction (see tests for !!python tags).
+    return yaml.load(text, Loader=_StrictSafeLoader)  # noqa: S506  # nosec B506
+
+
+def load_yaml_for_inspection(text: str) -> object:
+    """Parse third-party YAML (e.g. GitHub workflow files) for read-only inspection.
+
+    Uses ``yaml.SafeLoader`` (no object construction) but, unlike
+    :func:`load_yaml`, accepts anchors and duplicate keys, which GitHub accepts
+    in workflows. Never use this for CommitGuard configuration or rules.
+    """
+    return yaml.safe_load(text)

commitguard/security/sanitization.py

@@ -0,0 +1,85 @@
+"""Sanitisation of untrusted text before it reaches a terminal or log.
+
+Commit messages and trailers are attacker-controlled. Printing them verbatim
+allows terminal escape injection, e.g. an ANSI "erase line" sequence that hides
+``Co-authored-by: <AI agent>`` from a reviewer while it still exists in the
+commit. Sanitised output makes every such byte visible instead of executing it.
+"""
+
+DEFAULT_MAX_LENGTH = 500
+_TRUNCATION_MARKER = "...[truncated]"
+
+# Bidirectional overrides can visually reorder text ("Trojan Source").
+_BIDI_CONTROLS = frozenset(
+    chr(code)
+    for code in (
+        0x200E,
+        0x200F,
+        0x202A,
+        0x202B,
+        0x202C,
+        0x202D,
+        0x202E,
+        0x2066,
+        0x2067,
+        0x2068,
+        0x2069,
+    )
+)
+
+
+def _escape_char(char: str) -> str:
+    code = ord(char)
+    if code <= 0xFF:
+        return f"\\x{code:02x}"
+    return f"\\u{code:04x}"
+
+
+def sanitize_for_terminal(
+    text: str,
+    *,
+    max_length: int = DEFAULT_MAX_LENGTH,
+    keep_newlines: bool = False,
+) -> str:
+    """Return ``text`` made safe to print to a terminal or plain-text log.
+
+    * C0/C1 control characters (including ESC, so no ANSI sequence can take
+      effect) and Unicode bidi controls are rendered as visible escapes.
+    * Tabs become spaces; newlines are escaped unless ``keep_newlines`` is set.
+    * The result is truncated to at most ``max_length`` characters.
+    """
+    if max_length < len(_TRUNCATION_MARKER):
+        raise ValueError(f"max_length must be at least {len(_TRUNCATION_MARKER)}")
+
+    out: list[str] = []
+    for char in text:
+        code = ord(char)
+        if char == "\n" and keep_newlines:
+            out.append(char)
+        elif char == "\t":
+            out.append(" ")
+        elif code < 0x20 or 0x7F <= code <= 0x9F or char in _BIDI_CONTROLS:
+            out.append(_escape_char(char))
+        else:
+            out.append(char)
+    result = "".join(out)
+
+    if len(result) > max_length:
+        result = result[: max_length - len(_TRUNCATION_MARKER)] + _TRUNCATION_MARKER
+    return result
+
+
+def sanitize_block(text: str, *, max_length: int = DEFAULT_MAX_LENGTH, indent: str = "  ") -> str:
+    """Sanitise multi-line text for a human-readable report block.
+
+    Newlines are kept - a validation error that lists several fields is
+    unreadable once they become ``\\x0a`` - but every line after the first is
+    indented, so text we did not write cannot produce a line that starts at
+    column 0 and impersonates one of ours (for example a forged ``Result:
+    PASS``). Everything :func:`sanitize_for_terminal` escapes is still escaped.
+    """
+    safe = sanitize_for_terminal(text, max_length=max_length, keep_newlines=True)
+    first, separator, rest = safe.partition("\n")
+    if not separator:
+        return first
+    return first + "\n" + "\n".join(indent + line for line in rest.split("\n"))

commitguard/security/secrets.py

@@ -0,0 +1,169 @@
+"""Secret values and redaction.
+
+Credentials (the GitHub App private key, the webhook secret, JWTs, installation
+tokens) are wrapped in :class:`Secret` as soon as they are read, so an
+accidental ``repr()``, f-string or log call prints ``**********`` instead of
+the value. Only code that must send the value calls :meth:`Secret.reveal`.
+
+:class:`SecretRedactor` is the second line of defence: every secret CommitGuard
+mints or loads is registered with it, and structured logs, error messages and
+HTTP responses are passed through :func:`redact`, which also removes
+credential-shaped strings (GitHub tokens, JWTs, PEM keys, ``Authorization``
+header values) that were never registered.
+"""
+
+import hmac
+import re
+import threading
+from typing import NoReturn
+
+REDACTED = "[REDACTED]"
+MIN_REGISTERED_SECRET_LENGTH = 8
+
+_PATTERNS = (
+    # PEM blocks (private keys), even if truncated.
+    re.compile(
+        r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|\Z)", re.S
+    ),
+    # GitHub token formats: ghs_ (installation), ghp_, gho_, ghu_, ghr_, github_pat_.
+    re.compile(r"\b(?:gh[posur]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})"),
+    # Authorization header values and bearer/basic credentials.
+    re.compile(r"(?i)(authorization\s*[:=]\s*)\S+(?:\s+\S+)?"),
+    re.compile(r"(?i)\b((?:bearer|basic)\s+)[A-Za-z0-9._~+/=-]{8,}"),
+    # Webhook signatures are not secrets, but they are credential-derived noise.
+    re.compile(r"sha256=[0-9a-fA-F]{64}"),
+)
+
+# JWTs (header.payload.signature, base64url, the header starting "eyJ") are found in two
+# linear steps instead of one regular expression. The expression
+# ``\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}`` backtracks quadratically
+# on text such as "eyJ-eyJ-eyJ-..." (80 KB took 4.6 s; found by the ReDoS tests), and
+# redaction runs on untrusted text. First, maximal dotted runs of base64url characters are
+# matched (the look-behind means a run is only ever scanned from its first character);
+# then each run is split on dots and checked without backtracking.
+_DOTTED_RUN = re.compile(r"(?<![A-Za-z0-9_-])[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+){2,}")
+_JWT_MIN_SEGMENT = 5
+
+
+def _jwt_start(segment: str) -> int:
+    """Index of the first "eyJ" at a word boundary with a long enough header, else -1."""
+    index = segment.find("eyJ")
+    while index != -1:
+        if index == 0 or segment[index - 1] == "-":
+            return index if len(segment) - index - 3 >= _JWT_MIN_SEGMENT else -1
+        index = segment.find("eyJ", index + 1)
+    return -1
+
+
+def _redact_dotted_run(match: re.Match[str]) -> str:
+    segments = match.group(0).split(".")
+    out: list[str] = []
+    i = 0
+    while i < len(segments):
+        start = -1
+        if (
+            i + 2 < len(segments)
+            and len(segments[i + 1]) >= _JWT_MIN_SEGMENT
+            and len(segments[i + 2]) >= _JWT_MIN_SEGMENT
+        ):
+            start = _jwt_start(segments[i])
+        if start < 0:
+            out.append(segments[i])
+            i += 1
+        else:
+            out.append(segments[i][:start] + REDACTED)
+            i += 3
+    return ".".join(out)
+
+
+class Secret:
+    """A string that never shows its value unless explicitly revealed."""
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("Secret value must be a string")
+        self._value = value
+
+    def reveal(self) -> str:
+        return self._value
+
+    def __repr__(self) -> str:
+        return "Secret('**********')"
+
+    __str__ = __repr__
+
+    def __format__(self, format_spec: str) -> str:
+        return repr(self)
+
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __len__(self) -> int:
+        return len(self._value)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Secret):
+            return NotImplemented
+        return hmac.compare_digest(self._value.encode(), other._value.encode())
+
+    def __hash__(self) -> int:
+        return id(self)
+
+    def __reduce__(self) -> NoReturn:
+        raise TypeError("Secret values cannot be pickled")
+
+
+class SecretRedactor:
+    """Thread-safe registry of secret strings that must never be emitted."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._values: set[str] = set()
+
+    def register(self, value: "str | Secret") -> None:
+        raw = value.reveal() if isinstance(value, Secret) else value
+        if len(raw) < MIN_REGISTERED_SECRET_LENGTH:
+            return  # too short to redact without mangling ordinary text
+        with self._lock:
+            self._values.add(raw)
+            # PEM keys may appear line by line or with escaped newlines.
+            for line in raw.splitlines():
+                if len(line) >= 16 and "-----" not in line:
+                    self._values.add(line)
+
+    def forget(self, value: "str | Secret") -> None:
+        raw = value.reveal() if isinstance(value, Secret) else value
+        with self._lock:
+            self._values.discard(raw)
+
+    def redact(self, text: str) -> str:
+        with self._lock:
+            values = sorted(self._values, key=len, reverse=True)
+        for value in values:
+            if value in text:
+                text = text.replace(value, REDACTED)
+        text = _DOTTED_RUN.sub(_redact_dotted_run, text)
+        for pattern in _PATTERNS:
+            if pattern.groups:
+                text = pattern.sub(lambda m: f"{m.group(1)}{REDACTED}", text)
+            else:
+                text = pattern.sub(REDACTED, text)
+        return text
+
+
+_default_redactor = SecretRedactor()
+
+
+def default_redactor() -> SecretRedactor:
+    return _default_redactor
+
+
+def register_secret(value: "str | Secret") -> None:
+    _default_redactor.register(value)
+
+
+def redact(text: str) -> str:
+    """Remove registered secrets and credential-shaped strings from ``text``."""
+    return _default_redactor.redact(text)

commitguard/security/validation.py

@@ -0,0 +1,89 @@
+"""Validation of untrusted identifiers before they are used.
+
+The most important rule here: a user- or metadata-supplied Git revision must
+never be interpreted as a command-line option (``--output=/etc/passwd``).
+"""
+
+import re
+
+from commitguard.exceptions.base import UnsafeInputError
+
+MAX_REVISION_LENGTH = 256
+
+_SHA_RE = re.compile(r"\A(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
+_IDENTIFIER_RE = re.compile(r"\A[a-z][a-z0-9_]{0,63}\Z")
+# section[.subsection].key - subsections are restricted here to keep it simple.
+_GIT_CONFIG_KEY_RE = re.compile(
+    r"\A[A-Za-z][A-Za-z0-9-]*(?:\.[A-Za-z0-9_./-]+)?\.[A-Za-z][A-Za-z0-9-]*\Z"
+)
+
+
+def validate_revision(revision: str) -> str:
+    """Validate a Git revision expression supplied by a user or hook.
+
+    Rejects empty values, option-like values, control characters and overly
+    long input. This is defence in depth: the Git wrapper additionally passes
+    ``--end-of-options`` before revisions.
+    """
+    if not revision:
+        raise UnsafeInputError("revision must not be empty")
+    if len(revision) > MAX_REVISION_LENGTH:
+        raise UnsafeInputError("revision is too long")
+    if revision.startswith("-"):
+        raise UnsafeInputError("revision must not start with '-'")
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in revision):
+        raise UnsafeInputError("revision must not contain control characters")
+    return revision
+
+
+def is_git_sha(value: str) -> bool:
+    """Return True if ``value`` is a full lowercase SHA-1 or SHA-256 object ID."""
+    return bool(_SHA_RE.match(value))
+
+
+def validate_git_sha(value: str) -> str:
+    """Validate a full Git object ID (SHA-1 or SHA-256)."""
+    if not is_git_sha(value):
+        raise UnsafeInputError("value is not a full Git object id")
+    return value
+
+
+def validate_identifier(value: str, *, kind: str = "identifier") -> str:
+    """Validate an internal identifier (detector name, rule ID, policy ID).
+
+    Identifiers are lowercase snake_case, start with a letter, and are at most
+    64 characters, so they are safe to use as YAML keys, log fields and IDs.
+    """
+    if not _IDENTIFIER_RE.match(value):
+        raise UnsafeInputError(
+            f"invalid {kind} {value!r}: expected lowercase snake_case (max 64 chars)"
+        )
+    return value
+
+
+def validate_git_config_key(key: str) -> str:
+    """Validate a Git configuration key such as ``core.hooksPath``."""
+    if len(key) > MAX_REVISION_LENGTH or not _GIT_CONFIG_KEY_RE.match(key):
+        raise UnsafeInputError(f"invalid git config key {key!r}")
+    return key
+
+
+MAX_REPOSITORY_PATH_LENGTH = 1024
+
+
+def validate_repository_path(path: str) -> str:
+    """Validate a repository-relative POSIX path such as ``.commitguard.yaml``.
+
+    Rejects absolute paths, ``..`` or empty components, backslashes, leading
+    ``-`` and control characters, so the path can only name a file inside the
+    repository tree.
+    """
+    if not path or len(path) > MAX_REPOSITORY_PATH_LENGTH:
+        raise UnsafeInputError("repository path must be non-empty and reasonably short")
+    if path.startswith(("/", "-")) or "\\" in path or ":" in path.split("/", 1)[0]:
+        raise UnsafeInputError(f"invalid repository path {path!r}")
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in path):
+        raise UnsafeInputError("repository path must not contain control characters")
+    if any(part in ("", ".", "..") for part in path.split("/")):
+        raise UnsafeInputError(f"invalid repository path {path!r}")
+    return path

commitguard/services/__init__.py

@@ -0,0 +1,15 @@
+"""Application services shared by every entry point.
+
+* ``analysis``    - the Analyzer pipeline used by scan, check and hooks;
+* ``ci``          - commit range and trusted policy planning for server-side checks;
+* ``scan``        - ScanService: ScanRequest -> ScanResult (Action and GitHub App);
+* ``enforcement`` - maps results to exit codes and check conclusions;
+* ``audit``       - creates audit events with correlation IDs.
+
+``commitguard scan``, ``commitguard check``, the Git hooks, ``ci github`` and the GitHub App all
+run the same pipeline through this package, so no entry point re-implements
+detection or policy logic::
+
+    Repository --> Commit --> Analyzer(DetectionEngine + PolicyEvaluator)
+               --> CommitReport --> ScanReport (text / JSON / future audit log)
+"""

commitguard/services/analysis.py

@@ -0,0 +1,119 @@
+"""The analysis pipeline shared by ``scan``, ``check`` and future hooks/CI."""
+
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+
+from commitguard import __version__
+from commitguard.config.loader import LoadedConfig, load_effective_config
+from commitguard.core.context import CommitContext, ScanTrigger
+from commitguard.core.decision import Action
+from commitguard.core.engine import DetectionEngine
+from commitguard.detectors.registry import builtin_registry
+from commitguard.git.commit import Commit
+from commitguard.git.repository import Repository
+from commitguard.policies.evaluator import PolicyEvaluator
+from commitguard.policies.loader import build_policy_set
+from commitguard.policies.model import PolicySet
+from commitguard.provenance.author import Identity
+from commitguard.rules.loader import load_builtin_rules
+from commitguard.rules.matcher import CompiledRules
+from commitguard.services.reports import CIReport, CommitReport, ScanReport
+from commitguard.utils.filesystem import read_bytes_limited
+
+DEFAULT_MAX_COMMITS = 1000
+MAX_MESSAGE_FILE_BYTES = 1024 * 1024
+
+
+class Analyzer:
+    """Detection engine + policy evaluator for a fixed rule set and policy set."""
+
+    def __init__(self, engine: DetectionEngine, policies: PolicySet) -> None:
+        self._engine = engine
+        self._policies = policies
+        self._evaluator = PolicyEvaluator(policies)
+        self._enabled_rules = frozenset(p.id for p in policies.values() if p.enabled)
+
+    @classmethod
+    def create(cls, policies: PolicySet, rules: CompiledRules | None = None) -> "Analyzer":
+        rules = rules if rules is not None else load_builtin_rules()
+        return cls(DetectionEngine(builtin_registry(rules)), policies)
+
+    @property
+    def policies(self) -> PolicySet:
+        return self._policies
+
+    def analyze(self, commit: Commit, trigger: ScanTrigger = ScanTrigger.MANUAL) -> CommitReport:
+        context = CommitContext(commit=commit, trigger=trigger)
+        detection = self._engine.run(context, enabled_rules=self._enabled_rules)
+        decision = self._evaluator.evaluate(detection)
+        return CommitReport.build(commit.short_sha, detection, decision, subject=commit.subject)
+
+
+def load_analyzer(
+    repository: Repository | None, *, config_path: Path | None = None
+) -> tuple[Analyzer, LoadedConfig]:
+    """Load configuration layers and rules, and build an :class:`Analyzer`."""
+    config = load_effective_config(
+        repository.root if repository else None, explicit_path=config_path
+    )
+    return Analyzer.create(build_policy_set(*config.configs)), config
+
+
+def build_report(
+    reports: Sequence[CommitReport],
+    *,
+    repository: Repository | None,
+    target: str,
+    trigger: ScanTrigger,
+    config: LoadedConfig,
+    ci: CIReport | None = None,
+    extra_config_sources: Sequence[str] = (),
+) -> ScanReport:
+    return ScanReport(
+        tool_version=__version__,
+        generated_at=datetime.now(UTC),
+        repository=str(repository.root) if repository else None,
+        target=target,
+        trigger=trigger.value,
+        config_sources=(*(str(source) for source in config.sources), *extra_config_sources),
+        action=Action.most_restrictive([report.action for report in reports]),
+        commits=tuple(reports),
+        ci=ci,
+    )
+
+
+def analyze_revisions(
+    repository: Repository,
+    analyzer: Analyzer,
+    revision_range: str,
+    *,
+    max_commits: int = DEFAULT_MAX_COMMITS,
+    trigger: ScanTrigger = ScanTrigger.MANUAL,
+) -> list[CommitReport]:
+    """Analyse every commit selected by ``revision_range``."""
+    shas = repository.list_commits(revision_range, max_count=max_commits)
+    return [analyzer.analyze(commit, trigger) for commit in repository.read_commits(shas)]
+
+
+def analyze_message_file(
+    repository: Repository,
+    analyzer: Analyzer,
+    message_file: Path,
+    *,
+    trigger: ScanTrigger = ScanTrigger.CHECK,
+) -> CommitReport:
+    """Analyse a commit that does not exist yet (message file + configured identity).
+
+    TODO(phase-3): apply Git's message cleanup (comment stripping) the way
+    ``git commit`` does before the commit-msg hook result is used.
+    """
+    data = read_bytes_limited(message_file, max_bytes=MAX_MESSAGE_FILE_BYTES)
+    author, committer = repository.pending_identities()
+    return analyzer.analyze(
+        pending_commit(data.decode("utf-8", "replace"), author, committer), trigger
+    )
+
+
+def pending_commit(message: str, author: Identity, committer: Identity) -> Commit:
+    return Commit(author=author, committer=committer, message=message)