commitguardian 0.1.0__py3-none-any.whl

commitguard/services/audit.py

@@ -0,0 +1,95 @@
+"""AuditService: create audit events with correlation IDs and record them."""
+
+from collections.abc import Callable, Mapping, Sequence
+from datetime import UTC, datetime
+
+from commitguard.audit.logger import AuditLogger
+from commitguard.audit.models import SYSTEM_ACTOR, Actor, AuditEvent, AuditEventType, AuditValue
+from commitguard.audit.storage import AuditStorage
+from commitguard.core.decision import Action
+from commitguard.observability.logging import current_correlation
+
+
+class AuditService:
+    def __init__(
+        self,
+        storages: Sequence[AuditStorage] = (),
+        *,
+        now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._logger = AuditLogger(storages)
+        self._now = now
+
+    def record(
+        self,
+        event_type: AuditEventType,
+        *,
+        actor: Actor = SYSTEM_ACTOR,
+        account_id: int | None = None,
+        installation_id: int | None = None,
+        repository_id: int | None = None,
+        repository: str | None = None,
+        head_sha: str | None = None,
+        action: Action | None = None,
+        extra: Mapping[str, AuditValue] | None = None,
+        **data: AuditValue,
+    ) -> AuditEvent:
+        """Record an event. ``extra`` carries data built elsewhere (merged with ``data``)."""
+        event = self.build(
+            event_type,
+            actor=actor,
+            account_id=account_id,
+            installation_id=installation_id,
+            repository_id=repository_id,
+            repository=repository,
+            head_sha=head_sha,
+            action=action,
+            extra={**(extra or {}), **data},
+        )
+        self._logger.record(event)
+        return event
+
+    def build(
+        self,
+        event_type: AuditEventType,
+        *,
+        actor: Actor = SYSTEM_ACTOR,
+        account_id: int | None = None,
+        installation_id: int | None = None,
+        repository_id: int | None = None,
+        repository: str | None = None,
+        head_sha: str | None = None,
+        action: Action | None = None,
+        extra: Mapping[str, AuditValue] | None = None,
+        **data: AuditValue,
+    ) -> AuditEvent:
+        """Create an event without storing it (for writes inside a larger transaction)."""
+        data = {**(extra or {}), **data}
+        correlation = current_correlation()
+
+        def _str(key: str) -> str | None:
+            value = correlation.get(key)
+            return str(value) if value is not None else None
+
+        return AuditEvent(
+            type=event_type,
+            occurred_at=self._now(),
+            delivery_id=_str("delivery_id"),
+            request_id=_str("request_id"),
+            job_id=_str("job_id"),
+            scan_id=_str("scan_id"),
+            actor_type=actor.type,
+            actor_id=actor.id,
+            actor_login=actor.login,
+            account_id=account_id,
+            installation_id=installation_id,
+            repository_id=repository_id,
+            repository=repository,
+            head_sha=head_sha,
+            action=action,
+            data=data,
+        )
+
+    def log_stored(self, event: AuditEvent) -> None:
+        """Emit the log line for an event another component stored transactionally."""
+        self._logger.log(event)

commitguard/services/ci.py

@@ -0,0 +1,383 @@
+"""CI enforcement service: the server-side counterpart of the pre-push hook.
+
+Given a provider-neutral :class:`~commitguard.ci.context.CIContext` it decides
+
+1. **which commits** the event introduces (a :class:`CommitRange`), and
+2. **which policy** evaluates them (a trusted :class:`PolicySource`),
+
+then runs the same :class:`~commitguard.services.analysis.Analyzer` as
+``commitguard scan`` and the Git hooks. There is no CI-specific detection.
+
+Trust model (see docs/github-enforcement.md):
+
+==============================  ==========================  =========================
+Event                           Commits analysed            Policy read from
+==============================  ==========================  =========================
+pull request / merge group      ``head ^base``              base commit's tree
+push, ``before`` known          ``after ^before``           ``before`` commit's tree
+push, new ref (not default)     ``after ^<default branch>`` default branch tip's tree
+push, new default branch / no   ``after`` (bounded)         built-in defaults
+trusted commit available
+push, ref deleted               nothing                     -
+==============================  ==========================  =========================
+
+The evaluated commits' own ``.commitguard.yaml`` is never applied; a change to
+it is reported as a notice and takes effect once it is on the trusted branch.
+A change that would *weaken* a policy (disable it or lower its action) is
+reported as a security policy modification. Detection rules always come from
+the installed CommitGuard package. A central service may add a mandatory
+policy (:mod:`commitguard.policies.mandatory`) that no repository can weaken,
+or - for the GitHub App - the complete organization governance inputs
+(:mod:`commitguard.policies.governance`): policy layers, approved exceptions and
+monitor mode, resolved together with the trusted repository configuration.
+
+Planning (:func:`plan_ci`) and execution (:func:`execute_ci_plan`) are separate
+so a service can report the commit count before analysis starts.
+"""
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.ci.context import CIContext, CIEventKind
+from commitguard.config.schema import CommitGuardConfig
+from commitguard.config.sources import (
+    MandatoryPolicy,
+    PolicySource,
+    PolicySourceKind,
+    config_differs,
+    load_config_at_revision,
+    load_policy_source,
+)
+from commitguard.core.context import ScanTrigger
+from commitguard.exceptions.configuration import ConfigurationError
+from commitguard.git.ranges import CommitRange, require_commit, resolve_commit_range
+from commitguard.git.repository import Repository
+from commitguard.policies.governance import EffectivePolicy, GovernanceInputs, resolve_policy
+from commitguard.policies.loader import build_policy_set
+from commitguard.policies.mandatory import apply_mandatory_policies
+from commitguard.policies.model import Policy, PolicySet
+from commitguard.rules.matcher import CompiledRules
+from commitguard.security.hashing import fingerprint
+from commitguard.services.analysis import Analyzer, build_report
+from commitguard.services.reports import CIReport, ScanReport
+
+DEFAULT_CI_MAX_COMMITS = 10_000
+
+
+class CIPlan(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    range: CommitRange
+    policy_source: PolicySource
+    config_changes: tuple[str, ...] = ()
+    policy_weakenings: tuple[str, ...] = ()
+    notices: tuple[str, ...] = ()
+
+
+class CIRun(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    context: CIContext
+    plan: CIPlan
+    report: ScanReport
+    policy_fingerprint: str  # effective policies (trusted config + mandatory floor)
+    policies: tuple[Policy, ...] = ()  # the effective policies that evaluated the commits
+    #: The repository configuration's own overrides (rule -> fields it set), kept so a
+    #: policy simulation can re-resolve historical scans under a draft policy.
+    repository_overrides: dict[str, dict[str, str | bool]] = {}
+    effective: EffectivePolicy | None = None  # provenance, when governance applied
+
+
+def repository_overrides(
+    configs: Sequence[CommitGuardConfig],
+) -> dict[str, dict[str, str | bool]]:
+    """The merged per-rule fields the configuration layers set (later layers win)."""
+    merged: dict[str, dict[str, str | bool]] = {}
+    for config in configs:
+        for rule, override in config.policies.items():
+            for key, value in override.model_dump(mode="json", exclude_unset=True).items():
+                merged.setdefault(rule, {})[key] = value
+    return dict(sorted(merged.items()))
+
+
+def policy_set_fingerprint(policies: PolicySet) -> str:
+    parts: list[str] = []
+    for policy in policies.values():
+        parts += [policy.id, str(policy.enabled), policy.action.value]
+    return fingerprint(parts)
+
+
+def policy_weakenings(
+    repository: Repository, trusted: str, head: str, *, config_path: str | None = None
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Policies the evaluated commits' configuration would weaken, plus notices.
+
+    Only used for reporting: the evaluated commits' configuration is never applied.
+    """
+    try:
+        before = build_policy_set(
+            *load_config_at_revision(repository, trusted, config_path=config_path).configs
+        )
+    except ConfigurationError:
+        return (), ()  # the trusted configuration itself is invalid: the scan fails later
+    try:
+        after = build_policy_set(
+            *load_config_at_revision(repository, head, config_path=config_path).configs
+        )
+    except ConfigurationError:
+        return (), (
+            "the evaluated commits contain an invalid or missing CommitGuard configuration; "
+            "it was not applied",
+        )
+    weakened = []
+    for policy_id, old in before.items():
+        new = after[policy_id]
+        if old.enabled and not new.enabled:
+            weakened.append(f"{policy_id}: {old.action.value} -> disabled")
+        elif old.enabled and new.action.rank < old.action.rank:
+            weakened.append(f"{policy_id}: {old.action.value} -> {new.action.value}")
+    return tuple(weakened), ()
+
+
+def _config_notices(
+    repository: Repository,
+    trusted: str,
+    head: str,
+    changes: tuple[str, ...],
+    label: str,
+    config_path: str | None,
+) -> tuple[tuple[str, ...], list[str]]:
+    if not changes:
+        return (), []
+    notices = [
+        f"{', '.join(changes)} is changed by the evaluated commits; the policy from the "
+        f"{label} was used. Policy changes take effect after they reach the trusted branch."
+    ]
+    weakened, extra = policy_weakenings(repository, trusted, head, config_path=config_path)
+    notices.extend(extra)
+    if weakened:
+        notices.append(
+            "Security policy modification detected: the evaluated commits attempt to weaken "
+            f"an existing CommitGuard policy ({'; '.join(weakened)}). The trusted policy was "
+            "used; additional authorization may be required."
+        )
+    return weakened, notices
+
+
+def _default_branch_tip(repository: Repository, context: CIContext) -> str | None:
+    if not context.default_branch:
+        return None
+    for ref in (
+        f"refs/remotes/origin/{context.default_branch}",
+        f"refs/heads/{context.default_branch}",
+    ):
+        tip = repository.ref_commit(ref)
+        if tip is not None:
+            return tip
+    return None
+
+
+def plan_ci(
+    repository: Repository,
+    context: CIContext,
+    *,
+    config_path: str | None = None,
+    max_commits: int = DEFAULT_CI_MAX_COMMITS,
+) -> CIPlan:
+    notices: list[str] = []
+
+    if context.event in (CIEventKind.PULL_REQUEST, CIEventKind.MERGE_GROUP):
+        if context.base_sha is None or context.head_sha is None:  # guaranteed by CIContext
+            raise ValueError("pull request context without base and head commits")
+        base = require_commit(repository, context.base_sha, role="base")
+        head = require_commit(repository, context.head_sha, role="head")
+        commit_range = resolve_commit_range(
+            repository, head, [base], base=base, max_count=max_commits
+        )
+        label = (
+            "pull request base" if context.event is CIEventKind.PULL_REQUEST else "merge queue base"
+        )
+        source = PolicySource(
+            kind=PolicySourceKind.REVISION,
+            revision=base,
+            description=label,
+            config_path=config_path,
+        )
+        changes = tuple(config_differs(repository, base, head))
+        weakened, config_notices = _config_notices(
+            repository, base, head, changes, label, config_path
+        )
+        notices.extend(config_notices)
+        return CIPlan(
+            range=commit_range,
+            policy_source=source,
+            config_changes=changes,
+            policy_weakenings=weakened,
+            notices=tuple(notices),
+        )
+
+    # push
+    if context.ref_deleted or context.after_sha is None:
+        return CIPlan(
+            range=CommitRange(),
+            policy_source=PolicySource(kind=PolicySourceKind.BUILTIN, description="not needed"),
+            notices=("ref deleted: no commits to analyse",),
+        )
+    if not repository.object_exists(context.after_sha):
+        require_commit(repository, context.after_sha, role="pushed")  # raises a clear error
+    pushed = repository.peel_to_commit(context.after_sha)
+    if pushed is None:
+        return CIPlan(
+            range=CommitRange(),
+            policy_source=PolicySource(kind=PolicySourceKind.BUILTIN, description="not needed"),
+            notices=("pushed object is not a commit (e.g. a tag of a tree): nothing to analyse",),
+        )
+
+    before = repository.peel_to_commit(context.before_sha) if context.before_sha else None
+    if context.before_sha and before is None:
+        notices.append(
+            f"previous commit {context.before_sha[:12]} is not in this clone (force push?); "
+            "falling back to the default branch"
+        )
+    if before is not None:
+        exclude = [before]
+        source = PolicySource(
+            kind=PolicySourceKind.REVISION,
+            revision=before,
+            description="commit before the push",
+            config_path=config_path,
+        )
+        changes = tuple(config_differs(repository, before, pushed))
+    else:
+        is_default = bool(context.default_branch) and context.ref == (
+            f"refs/heads/{context.default_branch}"
+        )
+        tip = None if is_default else _default_branch_tip(repository, context)
+        if tip is not None:
+            exclude = [tip]
+            source = PolicySource(
+                kind=PolicySourceKind.REVISION,
+                revision=tip,
+                description="default branch",
+                config_path=config_path,
+            )
+            changes = tuple(config_differs(repository, tip, pushed))
+        else:
+            exclude = []
+            source = PolicySource(
+                kind=PolicySourceKind.BUILTIN,
+                description="built-in defaults (no trusted commit available)",
+                config_path=config_path,
+            )
+            changes = ()
+            notices.append(
+                "no trusted commit to read policy from or to limit the range; analysing all "
+                "commits reachable from the pushed commit with built-in default policies"
+            )
+    push_weakened: tuple[str, ...] = ()
+    if changes and source.revision is not None:
+        push_weakened, push_notices = _config_notices(
+            repository, source.revision, pushed, changes, source.description, config_path
+        )
+        notices.extend(push_notices)
+    commit_range = resolve_commit_range(
+        repository, pushed, exclude, base=exclude[0] if exclude else None, max_count=max_commits
+    )
+    return CIPlan(
+        range=commit_range,
+        policy_source=source,
+        config_changes=changes,
+        policy_weakenings=push_weakened,
+        notices=tuple(notices),
+    )
+
+
+def execute_ci_plan(
+    repository: Repository,
+    context: CIContext,
+    plan: CIPlan,
+    *,
+    rules: CompiledRules | None = None,
+    mandatory: MandatoryPolicy | None = None,
+    governance: GovernanceInputs | None = None,
+) -> CIRun:
+    """Analyse the planned commits with the planned (trusted) policy.
+
+    ``governance`` replaces ``mandatory`` when given (its service layer carries
+    the same floor): the effective policy is resolved from the governance inputs
+    and the trusted repository configuration.
+    """
+    loaded = load_policy_source(repository, plan.policy_source)
+    repository_policies = build_policy_set(*loaded.configs)
+    policies = repository_policies
+    extra_sources: tuple[str, ...] = ()
+    effective: EffectivePolicy | None = None
+    if governance is not None:
+        effective = resolve_policy(governance, loaded.configs)
+        policies = effective.policy_set()
+        extra_sources = (f"organization governance: {governance.describe()}",)
+    elif mandatory is not None:
+        policies = apply_mandatory_policies(policies, mandatory.config)
+        extra_sources = (f"mandatory: {mandatory.description}",)
+    analyzer = Analyzer.create(policies, rules)
+    # Commits are read and analysed in batches; only the compact reports are kept.
+    reports = [
+        analyzer.analyze(commit, ScanTrigger.CI)
+        for commit in repository.iter_commits(plan.range.commits)
+    ]
+    policy_source = str(plan.policy_source)
+    if governance is not None and not governance.empty:
+        policy_source += f" + {governance.describe()}"
+    elif mandatory is not None and governance is None:
+        policy_source += f" + mandatory policy ({mandatory.description})"
+    ci_report = CIReport(
+        provider=context.provider.value,
+        event=context.event_name,
+        repository=context.repository,
+        ref=context.ref,
+        pull_request_number=context.pull_request_number,
+        from_fork=context.from_fork,
+        base_sha=plan.range.base,
+        head_sha=plan.range.head,
+        policy_source=policy_source,
+        config_changes=plan.config_changes,
+        policy_weakenings=plan.policy_weakenings,
+        notices=plan.notices,
+    )
+    target = (
+        f"{plan.range.base[:12]}..{plan.range.head[:12]}"
+        if plan.range.base and plan.range.head
+        else (plan.range.head[:12] if plan.range.head else "nothing")
+    )
+    report = build_report(
+        reports,
+        repository=None,
+        target=target,
+        trigger=ScanTrigger.CI,
+        config=loaded,
+        ci=ci_report,
+        extra_config_sources=extra_sources,
+    )
+    return CIRun(
+        context=context,
+        plan=plan,
+        report=report,
+        policy_fingerprint=policy_set_fingerprint(policies),
+        policies=tuple(policies.values()),
+        repository_overrides=repository_overrides(loaded.configs),
+        effective=effective,
+    )
+
+
+def run_ci(
+    repository: Repository,
+    context: CIContext,
+    *,
+    config_path: str | None = None,
+    max_commits: int = DEFAULT_CI_MAX_COMMITS,
+    rules: CompiledRules | None = None,
+    mandatory: MandatoryPolicy | None = None,
+) -> CIRun:
+    plan = plan_ci(repository, context, config_path=config_path, max_commits=max_commits)
+    return execute_ci_plan(repository, context, plan, rules=rules, mandatory=mandatory)

commitguard/services/enforcement.py

@@ -0,0 +1,102 @@
+"""Enforcement: translate a policy result into what an entry point does.
+
+The policy engine decides ALLOW / WARN / BLOCK. This service turns that
+decision - or the failure to reach one - into an :class:`EnforcementDecision`.
+``commitguard ci github`` and the GitHub App use it directly; the Git hooks
+(:mod:`commitguard.services.hooks`) follow the same exit-code contract:
+
+=====================  ==============  ==================  ================
+State                  CLI / Action    Git hook            GitHub Check
+=====================  ==============  ==================  ================
+passed                 exit 0          commit/push allowed ``success``
+passed_with_warnings   exit 0          allowed             ``success`` (+ warnings)
+blocked                exit 1          rejected            ``failure``
+error                  exit 2          rejected            ``failure`` / ``timed_out``
+=====================  ==============  ==================  ================
+
+``blocked`` (the scan worked and found a violation) and ``error`` (the scan
+could not be completed) are kept apart for audit and reporting even though
+both fail closed.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.core.decision import Action
+from commitguard.services.reports import ScanReport
+
+
+class EnforcementState(StrEnum):
+    PASSED = "passed"
+    PASSED_WITH_WARNINGS = "passed_with_warnings"
+    BLOCKED = "blocked"
+    ERROR = "error"
+
+
+class FailureKind(StrEnum):
+    CONFIGURATION = "configuration"  # invalid trusted/mandatory policy or rules
+    AUTHORIZATION = "authorization"  # the integration may not access the repository
+    INFRASTRUCTURE = "infrastructure"  # Git, storage, GitHub API unavailable
+    TIMEOUT = "timeout"
+    INTERNAL = "internal"  # unexpected error
+
+
+class EnforcementDecision(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    state: EnforcementState
+    action: Action | None = None
+    failure: FailureKind | None = None
+    reason: str
+
+    @property
+    def allowed(self) -> bool:
+        return self.state in (EnforcementState.PASSED, EnforcementState.PASSED_WITH_WARNINGS)
+
+    @property
+    def exit_code(self) -> int:
+        """0 allowed, 1 blocked by policy, 2 could not be verified (stable CLI contract)."""
+        return {
+            EnforcementState.PASSED: 0,
+            EnforcementState.PASSED_WITH_WARNINGS: 0,
+            EnforcementState.BLOCKED: 1,
+            EnforcementState.ERROR: 2,
+        }[self.state]
+
+    @property
+    def check_conclusion(self) -> str:
+        if self.allowed:
+            return "success"
+        if self.failure is FailureKind.TIMEOUT:
+            return "timed_out"
+        return "failure"
+
+
+class EnforcementService:
+    def __init__(self, fail_on: Action = Action.BLOCK) -> None:
+        if fail_on is Action.ALLOW:
+            raise ValueError("fail_on must be block or warn")
+        self.fail_on = fail_on
+
+    def decide(self, report: ScanReport) -> EnforcementDecision:
+        action = report.action
+        if action.rank >= self.fail_on.rank:
+            return EnforcementDecision(
+                state=EnforcementState.BLOCKED,
+                action=action,
+                reason=f"policy result {action.value} is at or above fail-on {self.fail_on.value}",
+            )
+        if action is Action.WARN:
+            return EnforcementDecision(
+                state=EnforcementState.PASSED_WITH_WARNINGS,
+                action=action,
+                reason="warnings only",
+            )
+        return EnforcementDecision(
+            state=EnforcementState.PASSED, action=action, reason="all policies passed"
+        )
+
+    @staticmethod
+    def failed(kind: FailureKind, reason: str) -> EnforcementDecision:
+        return EnforcementDecision(state=EnforcementState.ERROR, failure=kind, reason=reason)