commitguardian 0.1.0__py3-none-any.whl

commitguard/audit/models.py

@@ -0,0 +1,222 @@
+"""Audit event model.
+
+Audit events record security-relevant actions; they are not application logs.
+Each has a stable ``type``, an **actor** (CommitGuard itself, GitHub, or a
+signed-in dashboard user), tenant keys (``account_id`` - the GitHub
+organisation or user account - ``installation_id``, ``repository_id``),
+correlation IDs and a small, validated ``data`` mapping. Values are bounded
+and sanitised on creation, and events are never updated after they are stored.
+
+Notifications are a separate, typed stream (:mod:`commitguard.notifications`);
+each notification records the audit correlation IDs of the change that caused it.
+"""
+
+import re
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from commitguard.core.decision import Action
+from commitguard.security.sanitization import sanitize_for_terminal
+from commitguard.security.secrets import redact
+
+MAX_DATA_ITEMS = 32
+MAX_DATA_STRING = 512
+_KEY_RE = re.compile(r"\A[a-z][a-z0-9_]{0,63}\Z")
+
+type AuditValue = str | int | bool | None
+
+
+class ActorType(StrEnum):
+    SYSTEM = "system"  # CommitGuard acting on its own (scans, lifecycle updates)
+    GITHUB = "github"  # a verified GitHub webhook
+    USER = "user"  # a signed-in dashboard user
+
+
+class Actor(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    type: ActorType
+    id: int | None = None
+    login: str | None = Field(default=None, max_length=64)
+
+    @classmethod
+    def user(cls, user_id: int, login: str) -> "Actor":
+        return cls(type=ActorType.USER, id=user_id, login=login)
+
+
+SYSTEM_ACTOR = Actor(type=ActorType.SYSTEM)
+GITHUB_ACTOR = Actor(type=ActorType.GITHUB)
+
+
+class AuditEventType(StrEnum):
+    INSTALLATION_CREATED = "installation_created"
+    INSTALLATION_REMOVED = "installation_removed"
+    INSTALLATION_SUSPENDED = "installation_suspended"
+    INSTALLATION_UNSUSPENDED = "installation_unsuspended"
+    INSTALLATION_PERMISSIONS_UPDATED = "installation_permissions_updated"
+    REPOSITORIES_ADDED = "repositories_added"
+    REPOSITORIES_REMOVED = "repositories_removed"
+    WEBHOOK_REJECTED = "webhook_rejected"
+    SCAN_QUEUED = "scan_queued"
+    REPOSITORY_SCANNED = "repository_scanned"
+    SCAN_PASSED = "scan_passed"
+    SCAN_FAILED = "scan_failed"
+    POLICY_VIOLATION = "policy_violation"
+    POLICY_MODIFICATION = "policy_modification"
+    CONFIGURATION_ERROR = "configuration_error"
+    SCAN_ERROR = "scan_error"
+    SCAN_CANCELLED = "scan_cancelled"
+    AUTHORIZATION_DENIED = "authorization_denied"
+    PULL_REQUEST_MERGED = "pull_request_merged"
+    # Control plane (dashboard) events.
+    USER_SIGNED_IN = "user_signed_in"
+    USER_SIGNED_OUT = "user_signed_out"
+    SESSION_REVOKED = "session_revoked"
+    MEMBER_ROLE_GRANTED = "member_role_granted"
+    MEMBER_ROLE_CHANGED = "member_role_changed"
+    MEMBER_REMOVED = "member_removed"
+    ORGANIZATION_POLICY_CHANGED = "organization_policy_changed"
+    VIOLATION_OPENED = "violation_opened"
+    VIOLATION_REOPENED = "violation_reopened"
+    VIOLATION_RESOLVED = "violation_resolved"
+    VIOLATION_ACKNOWLEDGED = "violation_acknowledged"
+    VIOLATION_ACKNOWLEDGEMENT_REMOVED = "violation_acknowledgement_removed"
+    REPOSITORY_MONITORING_DISABLED = "repository_monitoring_disabled"
+    REPOSITORY_MONITORING_ENABLED = "repository_monitoring_enabled"
+    REPOSITORIES_SYNCED = "repositories_synced"
+    ENFORCEMENT_STATUS_CHECKED = "enforcement_status_checked"
+    SCAN_REQUESTED = "scan_requested"
+    # Phase 7: executions, re-runs, merge queue, policy recovery, notifications.
+    SCAN_STARTED = "scan_started"
+    SCAN_RETRY_SCHEDULED = "scan_retry_scheduled"
+    CHECK_RERUN_REQUESTED = "check_rerun_requested"
+    CHECK_RERUN_REJECTED = "check_rerun_rejected"
+    MERGE_GROUP_CREATED = "merge_group_created"
+    MERGE_GROUP_PASSED = "merge_group_passed"
+    MERGE_GROUP_BLOCKED = "merge_group_blocked"
+    MERGE_GROUP_SCAN_FAILED = "merge_group_scan_failed"
+    MERGE_GROUP_DESTROYED = "merge_group_destroyed"
+    ORGANIZATION_POLICY_ROLLED_BACK = "organization_policy_rolled_back"
+    NOTIFICATION_CREATED = "notification_created"
+    NOTIFICATION_DELIVERED = "notification_delivered"
+    NOTIFICATION_DELIVERY_FAILED = "notification_delivery_failed"
+    NOTIFICATION_READ = "notification_read"
+    NOTIFICATION_SETTINGS_CHANGED = "notification_settings_changed"
+    NOTIFICATION_PREFERENCES_CHANGED = "notification_preferences_changed"
+    NOTIFICATION_WEBHOOK_ADDED = "notification_webhook_added"
+    NOTIFICATION_WEBHOOK_REMOVED = "notification_webhook_removed"
+    # Phase 8: organization governance.
+    ORGANIZATION_SETTINGS_CHANGED = "organization_settings_changed"
+    REPOSITORY_DISCOVERED = "repository_discovered"
+    REPOSITORY_ONBOARDED = "repository_onboarded"
+    REPOSITORY_EXCLUDED = "repository_excluded"
+    REPOSITORY_MODE_CHANGED = "repository_mode_changed"
+    REPOSITORY_ARCHIVED = "repository_archived"
+    REPOSITORY_SYNC_FAILED = "repository_sync_failed"
+    REPOSITORY_GROUP_CREATED = "repository_group_created"
+    REPOSITORY_GROUP_UPDATED = "repository_group_updated"
+    REPOSITORY_GROUP_ARCHIVED = "repository_group_archived"
+    REPOSITORY_GROUP_MEMBERS_ADDED = "repository_group_members_added"
+    REPOSITORY_GROUP_MEMBERS_REMOVED = "repository_group_members_removed"
+    POLICY_DRAFT_CREATED = "policy_draft_created"
+    POLICY_DRAFT_UPDATED = "policy_draft_updated"
+    POLICY_DRAFT_CANCELLED = "policy_draft_cancelled"
+    POLICY_APPROVAL_REQUESTED = "policy_approval_requested"
+    POLICY_APPROVED = "policy_approved"
+    POLICY_REJECTED = "policy_rejected"
+    POLICY_PUBLISHED = "policy_published"
+    POLICY_EMERGENCY_PUBLISHED = "policy_emergency_published"
+    POLICY_ROLLED_BACK = "policy_rolled_back"
+    POLICY_SIMULATED = "policy_simulated"
+    POLICY_ROLLOUT_STARTED = "policy_rollout_started"
+    POLICY_ROLLOUT_ADVANCED = "policy_rollout_advanced"
+    POLICY_ROLLOUT_PAUSED = "policy_rollout_paused"
+    POLICY_ROLLOUT_RESUMED = "policy_rollout_resumed"
+    POLICY_ROLLOUT_COMPLETED = "policy_rollout_completed"
+    POLICY_ROLLOUT_ROLLED_BACK = "policy_rollout_rolled_back"
+    POLICY_PROPAGATION_FAILED = "policy_propagation_failed"
+    EXCEPTION_REQUESTED = "exception_requested"
+    EXCEPTION_APPROVED = "exception_approved"
+    EXCEPTION_REJECTED = "exception_rejected"
+    EXCEPTION_CANCELLED = "exception_cancelled"
+    EXCEPTION_REVOKED = "exception_revoked"
+    EXCEPTION_EXPIRED = "exception_expired"
+    ORGANIZATION_RULES_CHANGED = "organization_rules_changed"
+    SCAN_SCHEDULE_CREATED = "scan_schedule_created"
+    SCAN_SCHEDULE_CHANGED = "scan_schedule_changed"
+    SCAN_SCHEDULE_DISABLED = "scan_schedule_disabled"
+    SCHEDULED_SCANS_QUEUED = "scheduled_scans_queued"
+    BULK_OPERATION_REQUESTED = "bulk_operation_requested"
+    BULK_OPERATION_FINISHED = "bulk_operation_finished"
+    BULK_OPERATION_CANCELLED = "bulk_operation_cancelled"
+    SECURITY_EVENT_ACKNOWLEDGED = "security_event_acknowledged"
+    REPORT_EXPORTED = "report_exported"
+
+
+#: Security-relevant events. Notifications are not generated from this list: the
+#: domain services emit typed notification events (:mod:`commitguard.notifications`)
+#: in the same transaction as the state change.
+SECURITY_ALERT_TYPES = frozenset(
+    {
+        AuditEventType.POLICY_VIOLATION,
+        AuditEventType.POLICY_MODIFICATION,
+        AuditEventType.ORGANIZATION_POLICY_CHANGED,
+        AuditEventType.ORGANIZATION_POLICY_ROLLED_BACK,
+        AuditEventType.INSTALLATION_REMOVED,
+        AuditEventType.INSTALLATION_SUSPENDED,
+        AuditEventType.REPOSITORY_MONITORING_DISABLED,
+        AuditEventType.MEMBER_ROLE_GRANTED,
+        AuditEventType.MEMBER_ROLE_CHANGED,
+        AuditEventType.MERGE_GROUP_BLOCKED,
+        AuditEventType.NOTIFICATION_SETTINGS_CHANGED,
+        AuditEventType.ORGANIZATION_SETTINGS_CHANGED,
+        AuditEventType.REPOSITORY_MODE_CHANGED,
+        AuditEventType.POLICY_PUBLISHED,
+        AuditEventType.POLICY_EMERGENCY_PUBLISHED,
+        AuditEventType.POLICY_ROLLED_BACK,
+        AuditEventType.POLICY_ROLLOUT_PAUSED,
+        AuditEventType.POLICY_PROPAGATION_FAILED,
+        AuditEventType.EXCEPTION_APPROVED,
+        AuditEventType.EXCEPTION_REVOKED,
+        AuditEventType.ORGANIZATION_RULES_CHANGED,
+    }
+)
+
+
+class AuditEvent(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    event_id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    type: AuditEventType
+    occurred_at: datetime
+    delivery_id: str | None = None
+    request_id: str | None = None  # dashboard API request
+    job_id: str | None = None
+    scan_id: str | None = None
+    actor_type: ActorType = ActorType.SYSTEM
+    actor_id: int | None = None  # GitHub user ID for ActorType.USER
+    actor_login: str | None = None
+    account_id: int | None = None  # filled from the installation when stored
+    installation_id: int | None = None
+    repository_id: int | None = None
+    repository: str | None = None
+    head_sha: str | None = None
+    action: Action | None = None
+    data: dict[str, AuditValue] = {}
+
+    @field_validator("data")
+    @classmethod
+    def _bounded(cls, value: dict[str, AuditValue]) -> dict[str, AuditValue]:
+        if len(value) > MAX_DATA_ITEMS:
+            raise ValueError(f"audit data has more than {MAX_DATA_ITEMS} items")
+        clean: dict[str, AuditValue] = {}
+        for key, item in value.items():
+            if not _KEY_RE.match(key):
+                raise ValueError(f"invalid audit data key {key!r}")
+            if isinstance(item, str):
+                item = sanitize_for_terminal(redact(item), max_length=MAX_DATA_STRING)
+            clean[key] = item
+        return clean

commitguard/audit/storage.py

@@ -0,0 +1,59 @@
+"""Audit storage interface.
+
+Storage is append-only for callers; the only deletion is retention purging.
+Reads are always scoped to a tenant (installation, optionally repository), so a
+future dashboard or API cannot list another organisation's events by mistake.
+The GitHub App's SQLite state store implements this interface; a PostgreSQL
+implementation can replace it without touching the services.
+"""
+
+import threading
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+from commitguard.audit.models import AuditEvent
+
+
+class AuditStorage(ABC):
+    @abstractmethod
+    def append_audit_event(self, event: AuditEvent) -> None:
+        """Persist ``event``. Existing events are never updated."""
+
+    @abstractmethod
+    def list_audit_events(
+        self, *, installation_id: int, repository_id: int | None = None, limit: int = 100
+    ) -> list[AuditEvent]:
+        """Most recent events for one tenant, newest first."""
+
+    @abstractmethod
+    def purge_audit_events(self, before: datetime) -> int:
+        """Delete events older than ``before`` (retention). Returns the count removed."""
+
+
+class InMemoryAuditStorage(AuditStorage):
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._events: list[AuditEvent] = []
+
+    def append_audit_event(self, event: AuditEvent) -> None:
+        with self._lock:
+            self._events.append(event)
+
+    def list_audit_events(
+        self, *, installation_id: int, repository_id: int | None = None, limit: int = 100
+    ) -> list[AuditEvent]:
+        with self._lock:
+            matching = [
+                e
+                for e in self._events
+                if e.installation_id == installation_id
+                and (repository_id is None or e.repository_id == repository_id)
+            ]
+        return list(reversed(matching))[:limit]
+
+    def purge_audit_events(self, before: datetime) -> int:
+        with self._lock:
+            kept = [e for e in self._events if e.occurred_at >= before]
+            removed = len(self._events) - len(kept)
+            self._events = kept
+        return removed

commitguard/ci/__init__.py

@@ -0,0 +1,7 @@
+"""Provider-neutral CI enforcement.
+
+CI providers (GitHub Actions today; GitLab, Bitbucket, Azure DevOps later)
+translate their event data into a :class:`~commitguard.ci.context.CIContext`.
+Everything after that - commit range, trusted policy source, detection, policy
+evaluation - is shared and lives in :mod:`commitguard.services.ci`.
+"""

commitguard/ci/context.py

@@ -0,0 +1,60 @@
+"""Normalised CI event context. Contains only what CommitGuard needs."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from commitguard.security.validation import validate_git_sha
+
+
+class CIProvider(StrEnum):
+    GITHUB = "github"
+
+
+class CIEventKind(StrEnum):
+    PULL_REQUEST = "pull_request"  # changes proposed for a base branch
+    PUSH = "push"  # commits that already reached the server
+    MERGE_GROUP = "merge_group"  # merge queue candidate
+
+
+def _oid(value: str | None) -> str | None:
+    return None if value is None else validate_git_sha(value)
+
+
+class CIContext(BaseModel):
+    """What changed, according to the CI provider.
+
+    SHAs are full object IDs. For pushes, ``before_sha``/``after_sha`` are None
+    when Git reports the all-zero ID (new ref / deleted ref).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    provider: CIProvider
+    event: CIEventKind
+    event_name: str = Field(description="Provider's own event name, for display")
+    repository: str | None = None  # e.g. "owner/name"
+    ref: str | None = None  # fully qualified ref that changed / PR base ref
+    default_branch: str | None = None
+    base_sha: str | None = None
+    head_sha: str | None = None
+    before_sha: str | None = None
+    after_sha: str | None = None
+    pull_request_number: int | None = Field(default=None, ge=1)
+    from_fork: bool = False
+    ref_deleted: bool = False
+
+    @field_validator("base_sha", "head_sha", "before_sha", "after_sha")
+    @classmethod
+    def _valid_oids(cls, value: str | None) -> str | None:
+        return _oid(value)
+
+    @model_validator(mode="after")
+    def _consistent(self) -> "CIContext":
+        needs_both = self.event in (CIEventKind.PULL_REQUEST, CIEventKind.MERGE_GROUP)
+        if needs_both and (self.base_sha is None or self.head_sha is None):
+            raise ValueError(f"{self.event.value} requires base and head commits")
+        push_mismatch = self.ref_deleted != (self.after_sha is None)
+        if self.event is CIEventKind.PUSH and push_mismatch:
+            raise ValueError("push: after commit must be absent exactly when the ref is deleted")
+        return self

commitguard/cli/__init__.py

@@ -0,0 +1,6 @@
+"""Command-line interface.
+
+The CLI is the only layer that reads process state (CWD, argv) and writes to
+the terminal. It composes the lower layers; it contains no detection or policy
+logic of its own.
+"""

commitguard/cli/app.py

@@ -0,0 +1,74 @@
+"""Typer application and console entry point."""
+
+from typing import Annotated
+
+import typer
+
+from commitguard import __version__
+from commitguard.cli.commands import (
+    benchmark,
+    check,
+    ci,
+    dashboard,
+    doctor,
+    github,
+    hook,
+    init,
+    install,
+    policy,
+    report,
+    reproduce,
+    scan,
+)
+
+app = typer.Typer(
+    name="commitguard",
+    help="Git commit provenance and contribution policy enforcement.",
+    no_args_is_help=True,
+    add_completion=False,
+    # Never render local variables in tracebacks: they may hold secrets.
+    pretty_exceptions_enable=False,
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"commitguard {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show the version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """CommitGuard analyses commits and enforces repository contribution policies."""
+
+
+app.command("init")(init.init_command)
+app.command("install")(install.install_command)
+app.command("uninstall")(install.uninstall_command)
+app.command("scan")(scan.scan_command)
+app.command("check")(check.check_command)
+app.command("doctor")(doctor.doctor_command)
+app.add_typer(policy.policy_app, name="policy")
+app.add_typer(hook.hook_app, name="hook")
+app.add_typer(ci.ci_app, name="ci")
+app.add_typer(github.github_app, name="github")
+app.add_typer(dashboard.dashboard_app, name="dashboard")
+app.add_typer(benchmark.benchmark_app, name="benchmark")
+app.add_typer(reproduce.reproduce_app, name="reproduce")
+app.add_typer(report.report_app, name="report")
+
+
+def main() -> None:
+    """Console script entry point (``commitguard``)."""
+    app()

commitguard/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations, one module per top-level command."""