commitguardian 0.1.0__py3-none-any.whl

commitguard/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core domain: scan context, findings, decisions and the detection engine.
+
+The core knows nothing about the CLI, hooks, or how commits were obtained. It
+receives a :class:`~commitguard.core.context.CommitContext`, runs registered
+detectors, and returns a :class:`~commitguard.core.result.DetectionResult`.
+"""

commitguard/core/context.py

@@ -0,0 +1,31 @@
+"""Commit context: everything a detector is allowed to see.
+
+Detectors receive a context rather than a repository handle. This keeps them
+pure (no I/O, cannot modify the repository) and trivially unit-testable.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.git.commit import Commit
+
+
+class ScanTrigger(StrEnum):
+    """Why an analysis is running."""
+
+    MANUAL = "manual"
+    CHECK = "check"
+    PRE_COMMIT = "pre-commit"
+    COMMIT_MSG = "commit-msg"
+    PRE_PUSH = "pre-push"
+    CI = "ci"
+
+
+class CommitContext(BaseModel):
+    """Immutable input to a single detection run over one commit."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    commit: Commit
+    trigger: ScanTrigger = ScanTrigger.MANUAL

commitguard/core/decision.py

@@ -0,0 +1,58 @@
+"""Security decisions.
+
+A :class:`Decision` is the policy engine's verdict over a :class:`DetectionResult`,
+with an explanation for every finding and failure that contributed to it.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.core.result import DetectorFailure, Finding
+
+
+class Action(StrEnum):
+    """What to do about a finding. Ordered from least to most restrictive."""
+
+    ALLOW = "allow"
+    WARN = "warn"
+    BLOCK = "block"
+
+    @property
+    def rank(self) -> int:
+        return _ACTION_RANK[self]
+
+    @classmethod
+    def most_restrictive(cls, actions: "list[Action]") -> "Action":
+        return max(actions, key=lambda action: action.rank, default=cls.ALLOW)
+
+
+_ACTION_RANK = {action: index for index, action in enumerate(Action)}
+
+
+class Explanation(BaseModel):
+    """Why a particular action was taken for one finding or failure."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    action: Action
+    reason: str
+    policy_id: str | None = None
+    finding: Finding | None = None
+    failure: DetectorFailure | None = None
+
+
+class Decision(BaseModel):
+    """Final verdict for one scan, with full explanations."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    action: Action
+    explanations: tuple[Explanation, ...] = ()
+
+    @property
+    def blocked(self) -> bool:
+        return self.action is Action.BLOCK
+
+    def explanations_for(self, action: Action) -> tuple[Explanation, ...]:
+        return tuple(e for e in self.explanations if e.action is action)

commitguard/core/engine.py

@@ -0,0 +1,82 @@
+"""Detection engine: runs registered detectors over a commit context.
+
+The engine is deliberately small and policy-agnostic:
+
+* detectors run in a deterministic order (sorted by name);
+* callers may pass the set of *enabled rule IDs*; a detector none of whose
+  rules are enabled is skipped (recorded in ``detectors_skipped``). The engine
+  never looks at actions - that remains the policy evaluator's job;
+* a detector that raises is recorded as a :class:`DetectorFailure` rather than
+  crashing the scan - the policy evaluator then fails closed;
+* output is validated: detectors must return :class:`Finding` objects for
+  rules they declared, attributed to themselves and to the scanned commit.
+"""
+
+from collections.abc import Collection
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import DetectionResult, DetectorFailure, Finding
+from commitguard.detectors.base import Detector
+from commitguard.detectors.registry import DetectorRegistry
+from commitguard.exceptions.detection import DetectionError
+from commitguard.security.sanitization import sanitize_for_terminal
+
+
+class DetectionEngine:
+    """Execute detectors from a registry against a :class:`CommitContext`."""
+
+    def __init__(self, registry: DetectorRegistry) -> None:
+        self._registry = registry
+
+    @property
+    def registry(self) -> DetectorRegistry:
+        return self._registry
+
+    def run(
+        self,
+        context: CommitContext,
+        *,
+        enabled_rules: Collection[str] | None = None,
+    ) -> DetectionResult:
+        findings: list[Finding] = []
+        failures: list[DetectorFailure] = []
+        ran: list[str] = []
+        skipped: list[str] = []
+
+        for detector in self._registry.all():
+            if enabled_rules is not None and not detector.rules & set(enabled_rules):
+                skipped.append(detector.name)
+                continue
+            ran.append(detector.name)
+            try:
+                findings.extend(self._run_detector(detector, context))
+            except Exception as exc:  # noqa: BLE001 - any detector failure must fail closed
+                failures.append(
+                    DetectorFailure(
+                        detector=detector.name,
+                        error_type=type(exc).__name__,
+                        message=sanitize_for_terminal(str(exc) or type(exc).__name__),
+                    )
+                )
+
+        return DetectionResult(
+            commit_sha=context.commit.sha,
+            detectors_run=tuple(ran),
+            detectors_skipped=tuple(skipped),
+            findings=tuple(findings),
+            failures=tuple(failures),
+        )
+
+    @staticmethod
+    def _run_detector(detector: Detector, context: CommitContext) -> list[Finding]:
+        produced = list(detector.detect(context))
+        for finding in produced:
+            if not isinstance(finding, Finding):
+                raise DetectionError(f"detector returned {type(finding).__name__}, not Finding")
+            if finding.detector != detector.name:
+                raise DetectionError(f"finding attributed to {finding.detector!r}")
+            if finding.rule_id not in detector.rules:
+                raise DetectionError(f"finding uses undeclared rule {finding.rule_id!r}")
+            if finding.commit_sha != context.commit.sha:
+                raise DetectionError("finding refers to a different commit")
+        return produced

commitguard/core/result.py

@@ -0,0 +1,177 @@
+"""Findings and detection results.
+
+A :class:`Finding` is a detector's structured, explainable claim that commit
+*metadata* matched a rule. It never contains a decision (that is the policy's
+job) and never claims that code was written by an AI - only that the commit
+contains an identity or attribution associated with one.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from commitguard.security.hashing import fingerprint
+from commitguard.security.validation import validate_git_sha, validate_identifier
+
+MAX_EVIDENCE_CHARS = 512
+_TRUNCATION_MARKER = "...[truncated]"
+
+
+class Severity(StrEnum):
+    """How serious a finding is, independent of the action a policy takes."""
+
+    INFO = "info"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def rank(self) -> int:
+        return list(Severity).index(self)
+
+
+class Confidence(StrEnum):
+    """How strong the evidence behind a finding is."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+    @property
+    def rank(self) -> int:
+        return list(Confidence).index(self)
+
+
+class MatchKind(StrEnum):
+    """Which piece of an identity matched a rule."""
+
+    NAME = "name"  # full name equals a configured alias
+    NAME_PREFIX = "name_prefix"  # name starts with a configured distinctive prefix
+    AMBIGUOUS_NAME = "ambiguous_name"  # alias that is also a common human name
+    EMAIL = "email"  # exact configured address
+    GITHUB_LOGIN = "github_login"  # login from a GitHub noreply address or name
+    AUTOMATION_EMAIL = "automation_email"  # automation local part at a vendor domain
+    VENDOR_DOMAIN = "vendor_domain"  # vendor domain with a non-automation local part
+    TRAILER_KEY = "trailer_key"  # trailer key configured as attribution
+    MESSAGE_MARKER = "message_marker"  # exact attribution line inserted by a tool
+
+
+class MatchReason(BaseModel):
+    """One reason a rule matched, with a reference to the rule that matched."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: MatchKind
+    value: str = Field(description="The normalised value that matched")
+    rule: str = Field(description="Rule reference, e.g. 'ai-identities.yaml#claude'")
+
+
+class EvidenceSource(StrEnum):
+    COAUTHOR_TRAILER = "coauthor_trailer"
+    TRAILER = "trailer"
+    AUTHOR = "author"
+    COMMITTER = "committer"
+    MESSAGE = "message"
+
+    @property
+    def label(self) -> str:
+        return _SOURCE_LABELS[self]
+
+
+_SOURCE_LABELS = {
+    EvidenceSource.COAUTHOR_TRAILER: "Co-authored-by trailer",
+    EvidenceSource.TRAILER: "commit trailer",
+    EvidenceSource.AUTHOR: "commit author",
+    EvidenceSource.COMMITTER: "commit committer",
+    EvidenceSource.MESSAGE: "commit message line",
+}
+
+
+class Evidence(BaseModel):
+    """The concise metadata that triggered a finding (never file contents).
+
+    ``value`` is untrusted raw data, truncated to :data:`MAX_EVIDENCE_CHARS`;
+    it must be sanitised before display.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    source: EvidenceSource
+    value: str
+    line_number: int | None = Field(default=None, ge=1)
+    matched: tuple[MatchReason, ...] = ()
+    notes: tuple[str, ...] = Field(default=(), description="e.g. malformed-trailer issues")
+
+    @field_validator("value")
+    @classmethod
+    def _truncate(cls, value: str) -> str:
+        if len(value) > MAX_EVIDENCE_CHARS:
+            return value[: MAX_EVIDENCE_CHARS - len(_TRUNCATION_MARKER)] + _TRUNCATION_MARKER
+        return value
+
+
+class Finding(BaseModel):
+    """A structured security finding produced by a detector."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    detector: str
+    rule_id: str
+    severity: Severity
+    confidence: Confidence
+    title: str = Field(min_length=1)
+    message: str = Field(min_length=1)
+    evidence: tuple[Evidence, ...] = Field(min_length=1)
+    commit_sha: str | None = None
+    remediation: str = Field(min_length=1)
+
+    @field_validator("detector")
+    @classmethod
+    def _validate_detector(cls, value: str) -> str:
+        return validate_identifier(value, kind="detector name")
+
+    @field_validator("rule_id")
+    @classmethod
+    def _validate_rule(cls, value: str) -> str:
+        return validate_identifier(value, kind="rule id")
+
+    @field_validator("commit_sha")
+    @classmethod
+    def _validate_commit_sha(cls, value: str | None) -> str | None:
+        return None if value is None else validate_git_sha(value)
+
+    @property
+    def fingerprint(self) -> str:
+        """Stable ID: same detector, rule, commit and evidence => same fingerprint."""
+        parts = [self.detector, self.rule_id, self.commit_sha or ""]
+        for item in self.evidence:
+            parts.extend([item.source.value, item.value, str(item.line_number or "")])
+        return fingerprint(parts)
+
+
+class DetectorFailure(BaseModel):
+    """A detector that raised or misbehaved. Evaluated fail-closed by policy."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    detector: str
+    error_type: str
+    message: str
+
+
+class DetectionResult(BaseModel):
+    """Everything the engine produced for one commit."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    commit_sha: str | None
+    detectors_run: tuple[str, ...]
+    detectors_skipped: tuple[str, ...] = ()
+    findings: tuple[Finding, ...] = ()
+    failures: tuple[DetectorFailure, ...] = ()
+
+    @property
+    def complete(self) -> bool:
+        """True if every detector that ran completed successfully."""
+        return not self.failures

commitguard/detectors/__init__.py

@@ -0,0 +1,6 @@
+"""Detectors: independent, pure analyses that turn a commit into findings.
+
+A detector answers "does this commit match rule X, and what is the evidence?".
+It never decides whether that is acceptable (see :mod:`commitguard.policies`)
+and never performs I/O or modifies the repository.
+"""

commitguard/detectors/base.py

@@ -0,0 +1,58 @@
+"""Detector interface.
+
+Contract every detector must honour:
+
+1. **Pure.** Output depends only on the :class:`CommitContext` and the rule
+   data given at construction. No network, subprocesses, files or Git.
+2. **Deterministic.** The same context always yields the same findings in the
+   same order.
+3. **Declared rules.** Every finding's ``rule_id`` is listed in :attr:`rules`;
+   the engine rejects anything else.
+4. **Evidence.** Every finding carries the concise metadata that triggered it.
+5. **No decisions.** Detectors report; policies decide allow/warn/block.
+6. **Hostile input.** Commit data may be crafted to crash or evade a detector.
+   Raising is acceptable (the scan fails closed); silently skipping is not.
+7. **Honest wording.** Findings describe attribution/identity *evidence*;
+   they never claim that code was written by an AI.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import ClassVar
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import Finding
+from commitguard.exceptions.detection import DetectionError
+from commitguard.git.commit import Commit
+
+
+class Detector(ABC):
+    """Base class for all detectors."""
+
+    #: Unique, snake_case detector name (used in findings and output).
+    name: ClassVar[str]
+    #: Rule IDs this detector may emit. Each must have a policy.
+    rules: ClassVar[frozenset[str]]
+    #: One-line human description.
+    description: ClassVar[str]
+
+    @abstractmethod
+    def detect(self, context: CommitContext) -> Sequence[Finding]:
+        """Analyse ``context`` and return zero or more findings."""
+
+
+def require_complete_trailers(commit: Commit) -> None:
+    """Fail closed if the commit has more trailers than can be analysed.
+
+    Otherwise an attacker could hide attribution behind a flood of trailers.
+    """
+    if commit.trailers_truncated:
+        raise DetectionError("commit has too many trailers to analyse completely")
+
+
+def group_by_rule[T](items: list[tuple[str, T]]) -> dict[str, list[T]]:
+    """Group ``(rule_id, item)`` pairs preserving first-seen order (deterministic)."""
+    grouped: dict[str, list[T]] = {}
+    for key, item in items:
+        grouped.setdefault(key, []).append(item)
+    return grouped

commitguard/detectors/bot.py

@@ -0,0 +1,87 @@
+"""Bot detector: explicitly configured automation identities.
+
+Bots are not AI agents. Dependabot or a release bot produce ``bot_identity``
+findings - never ``ai_*`` findings - so a repository can allow bots while
+blocking AI attribution. Only identities listed in ``rules/bot-identities.yaml``
+match; there is no generic ``[bot]`` heuristic.
+"""
+
+from collections.abc import Sequence
+from typing import ClassVar
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import Evidence, EvidenceSource, Finding, Severity
+from commitguard.detectors.base import Detector, group_by_rule, require_complete_trailers
+from commitguard.rules.matcher import CompiledRules, IdentityMatch
+
+RULE_BOT_IDENTITY = "bot_identity"
+
+
+class BotDetector(Detector):
+    name: ClassVar[str] = "bot"
+    rules: ClassVar[frozenset[str]] = frozenset({RULE_BOT_IDENTITY})
+    description: ClassVar[str] = (
+        "Configured automation/bot account as author, committer or co-author."
+    )
+
+    def __init__(self, rules: CompiledRules) -> None:
+        self._matcher = rules.bot_matcher
+        self._coauthor_keys = frozenset(rules.rules.patterns.coauthor_trailer_keys)
+
+    def detect(self, context: CommitContext) -> Sequence[Finding]:
+        commit = context.commit
+        require_complete_trailers(commit)
+        candidates: list[tuple[EvidenceSource, str, str | None, str | None, int | None]] = [
+            (
+                EvidenceSource.AUTHOR,
+                str(commit.author),
+                commit.author.name,
+                commit.author.email,
+                None,
+            ),
+            (
+                EvidenceSource.COMMITTER,
+                str(commit.committer),
+                commit.committer.name,
+                commit.committer.email,
+                None,
+            ),
+        ]
+        candidates.extend(
+            (EvidenceSource.COAUTHOR_TRAILER, t.value, t.name, t.email, t.line_number)
+            for t in commit.trailers
+            if t.normalized_key in self._coauthor_keys
+        )
+
+        matches: list[tuple[str, tuple[Evidence, IdentityMatch]]] = []
+        for source, value, name, email, line_number in candidates:
+            match = self._matcher.match(name, email)
+            if match is not None:
+                evidence = Evidence(
+                    source=source, value=value, line_number=line_number, matched=match.reasons
+                )
+                matches.append((match.rule_id, (evidence, match)))
+
+        findings = []
+        for items in group_by_rule(matches).values():
+            match = max((m for _, m in items), key=lambda m: m.confidence.rank)
+            findings.append(
+                Finding(
+                    detector=self.name,
+                    rule_id=RULE_BOT_IDENTITY,
+                    severity=Severity.LOW,
+                    confidence=match.confidence,
+                    title="Bot identity detected",
+                    message=(
+                        f"The commit involves the configured automation identity "
+                        f"{match.display_name}. This is a bot finding, not an AI attribution."
+                    ),
+                    evidence=tuple(evidence for evidence, _ in items),
+                    commit_sha=commit.sha,
+                    remediation=(
+                        "If this automation is expected, set `bot_identity` to `allow` in "
+                        ".commitguard.yaml; otherwise investigate where the commit came from."
+                    ),
+                )
+            )
+        return findings

commitguard/detectors/coauthor.py

@@ -0,0 +1,86 @@
+"""Co-author detector: AI agents listed in ``Co-authored-by`` style trailers.
+
+Example that produces an ``ai_coauthor`` finding::
+
+    feat: implement authentication
+
+    Co-authored-by: Claude <noreply@anthropic.com>
+
+Every co-author trailer is matched *independently* against the AI identity
+rules, so human co-authors in the same commit never produce findings.
+Trailers are considered even when malformed or outside Git's trailer block,
+because hiding attribution that way is still attribution.
+"""
+
+from collections.abc import Sequence
+from typing import ClassVar
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import Evidence, EvidenceSource, Finding, Severity
+from commitguard.detectors.base import Detector, require_complete_trailers
+from commitguard.provenance.normalization import uses_disguising_characters
+from commitguard.provenance.trailers import Trailer
+from commitguard.rules.matcher import CompiledRules
+
+RULE_AI_COAUTHOR = "ai_coauthor"
+
+
+class CoauthorDetector(Detector):
+    name: ClassVar[str] = "coauthor"
+    rules: ClassVar[frozenset[str]] = frozenset({RULE_AI_COAUTHOR})
+    description: ClassVar[str] = "AI agent identity listed as a co-author in commit trailers."
+
+    def __init__(self, rules: CompiledRules) -> None:
+        self._matcher = rules.ai_matcher
+        self._keys = frozenset(rules.rules.patterns.coauthor_trailer_keys)
+
+    def detect(self, context: CommitContext) -> Sequence[Finding]:
+        commit = context.commit
+        require_complete_trailers(commit)
+        findings: list[Finding] = []
+        for trailer in commit.trailers:
+            if trailer.normalized_key not in self._keys:
+                continue
+            match = self._matcher.match(trailer.name, trailer.email)
+            if match is None:
+                continue
+            findings.append(
+                Finding(
+                    detector=self.name,
+                    rule_id=RULE_AI_COAUTHOR,
+                    severity=Severity.HIGH,
+                    confidence=match.confidence,
+                    title="AI coauthor detected",
+                    message=(
+                        f"A co-author trailer names an identity associated with the AI agent "
+                        f"{match.display_name}."
+                    ),
+                    evidence=(
+                        Evidence(
+                            source=EvidenceSource.COAUTHOR_TRAILER,
+                            value=trailer.value or trailer.raw,
+                            line_number=trailer.line_number,
+                            matched=match.reasons,
+                            notes=_notes(trailer),
+                        ),
+                    ),
+                    commit_sha=commit.sha,
+                    remediation=(
+                        "Remove the AI co-author attribution from the commit message before "
+                        "pushing (for example with `git commit --amend`). CommitGuard never "
+                        "rewrites commits itself."
+                    ),
+                )
+            )
+        return findings
+
+
+def _notes(trailer: Trailer) -> tuple[str, ...]:
+    notes: list[str] = []
+    if uses_disguising_characters(trailer.raw):
+        notes.append("contains look-alike or invisible Unicode characters")
+    if not trailer.in_trailer_block:
+        notes.append("outside the commit's trailer block")
+    notes.extend(f"trailer: {issue.value}" for issue in trailer.issues)
+    notes.extend(f"identity: {issue.value}" for issue in trailer.identity.issues)
+    return tuple(notes)

commitguard/detectors/identity.py

@@ -0,0 +1,76 @@
+"""Identity detector: AI agents recorded as the commit author or committer.
+
+Some agents commit under their own identity instead of adding a trailer, e.g.
+``Copilot <175728472+Copilot@users.noreply.github.com>`` as author.
+
+Only identities configured as AI agents match. Automation accounts that are
+not AI agents (Dependabot, CI) are the bot detector's concern.
+"""
+
+from collections.abc import Sequence
+from typing import ClassVar
+
+from commitguard.core.context import CommitContext
+from commitguard.core.result import Evidence, EvidenceSource, Finding, Severity
+from commitguard.detectors.base import Detector, group_by_rule
+from commitguard.provenance.normalization import uses_disguising_characters
+from commitguard.rules.matcher import CompiledRules, IdentityMatch
+
+RULE_AI_IDENTITY = "ai_identity"
+
+
+class IdentityDetector(Detector):
+    name: ClassVar[str] = "identity"
+    rules: ClassVar[frozenset[str]] = frozenset({RULE_AI_IDENTITY})
+    description: ClassVar[str] = "AI agent identity recorded as the commit author or committer."
+
+    def __init__(self, rules: CompiledRules) -> None:
+        self._matcher = rules.ai_matcher
+
+    def detect(self, context: CommitContext) -> Sequence[Finding]:
+        commit = context.commit
+        matches: list[tuple[str, tuple[EvidenceSource, str, IdentityMatch]]] = []
+        for source, identity in (
+            (EvidenceSource.AUTHOR, commit.author),
+            (EvidenceSource.COMMITTER, commit.committer),
+        ):
+            match = self._matcher.match(identity.name, identity.email)
+            if match is not None:
+                matches.append((match.rule_id, (source, str(identity), match)))
+
+        findings = []
+        for items in group_by_rule(matches).values():
+            match = max((m for _, _, m in items), key=lambda m: m.confidence.rank)
+            roles = " and ".join(source.label for source, _, _ in items)
+            findings.append(
+                Finding(
+                    detector=self.name,
+                    rule_id=RULE_AI_IDENTITY,
+                    severity=Severity.HIGH,
+                    confidence=match.confidence,
+                    title="AI agent identity detected",
+                    message=(
+                        f"The {roles} identity is associated with the AI agent "
+                        f"{match.display_name}."
+                    ),
+                    evidence=tuple(
+                        Evidence(
+                            source=source,
+                            value=value,
+                            matched=m.reasons,
+                            notes=(
+                                ("contains look-alike or invisible Unicode characters",)
+                                if uses_disguising_characters(value)
+                                else ()
+                            ),
+                        )
+                        for source, value, m in items
+                    ),
+                    commit_sha=commit.sha,
+                    remediation=(
+                        "Recreate the commit under the responsible human contributor's identity "
+                        "before pushing. CommitGuard never rewrites commits itself."
+                    ),
+                )
+            )
+        return findings