commitguardian 0.1.0__py3-none-any.whl

commitguard/config/schema.py

@@ -0,0 +1,105 @@
+"""Configuration schema.
+
+Every model forbids extra keys and uses strict scalar types, so that e.g.
+``enabled: "no"`` or a misspelled ``acton: allow`` is an error instead of a
+silent change in security behaviour.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt, field_validator
+
+from commitguard.core.decision import Action
+from commitguard.policies.defaults import KNOWN_POLICY_IDS
+
+
+class PolicyOverride(BaseModel):
+    """Repository override for one built-in policy. Unset fields keep defaults."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    enabled: StrictBool | None = None
+    action: Action | None = None
+
+    @field_validator("enabled", "action", mode="before")
+    @classmethod
+    def _reject_explicit_null(cls, value: object) -> object:
+        # ``action:`` with no value in YAML is null; treat it as a mistake.
+        if value is None:
+            raise ValueError("must not be null; remove the key to use the default")
+        return value
+
+
+class EnforcementOverride(BaseModel):
+    """Which Git hooks enforce policy. Unset fields keep the value from lower layers.
+
+    Disabling a hook never changes *policies*; it only stops that hook from
+    running the analysis, and ``commitguard doctor`` reports enforcement as
+    incomplete.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    pre_commit: StrictBool | None = None
+    commit_msg: StrictBool | None = None
+    pre_push: StrictBool | None = None
+    max_push_commits: StrictInt | None = Field(default=None, ge=1, le=1_000_000)
+
+    @field_validator("pre_commit", "commit_msg", "pre_push", "max_push_commits", mode="before")
+    @classmethod
+    def _reject_explicit_null(cls, value: object) -> object:
+        if value is None:
+            raise ValueError("must not be null; remove the key to use the default")
+        return value
+
+
+class RemediationOverride(BaseModel):
+    """What CommitGuard may do about a violation, beyond reporting it.
+
+    ``auto_remove`` lets the ``commit-msg`` hook delete the offending lines from
+    the pending message instead of refusing the commit. It only ever applies
+    when *every* blocking finding is a message line: attribution carried by the
+    author or committer identity cannot be fixed by editing text, and still
+    blocks. The stripped message is re-analysed, and the commit proceeds only if
+    it is then clean.
+
+    It is off by default, because it edits what the developer wrote.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    auto_remove: StrictBool | None = None
+
+    @field_validator("auto_remove", mode="before")
+    @classmethod
+    def _reject_explicit_null(cls, value: object) -> object:
+        if value is None:
+            raise ValueError("must not be null; remove the key to use the default")
+        return value
+
+
+class CommitGuardConfig(BaseModel):
+    """Top-level ``.commitguard.yaml`` document."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: Literal[1]
+    policies: dict[str, PolicyOverride] = {}
+    enforcement: EnforcementOverride = EnforcementOverride()
+    remediation: RemediationOverride = RemediationOverride()
+
+    @field_validator("version", mode="before")
+    @classmethod
+    def _strict_version(cls, value: object) -> object:
+        if type(value) is not int:
+            raise ValueError("version must be the integer 1")
+        return value
+
+    @field_validator("policies")
+    @classmethod
+    def _known_policies(cls, value: dict[str, PolicyOverride]) -> dict[str, PolicyOverride]:
+        unknown = sorted(set(value) - KNOWN_POLICY_IDS)
+        if unknown:
+            known = ", ".join(sorted(KNOWN_POLICY_IDS))
+            raise ValueError(f"unknown policy id(s): {', '.join(unknown)} (known: {known})")
+        return value

commitguard/config/sources.py

@@ -0,0 +1,183 @@
+"""Policy sources: where the policy that evaluates a change comes from.
+
+The source of a policy is a security decision. A pull request that edits
+``.commitguard.yaml`` to ``action: allow`` must not be evaluated with the policy
+it introduces, otherwise it could approve itself.
+
+=================  =======================================  ======================
+Kind               Configuration read from                  Used by
+=================  =======================================  ======================
+``working_tree``   global config + work tree + ``--config``  local scan/check/hooks
+``revision``       the tree of a *trusted* commit (never     CI (PR base, push
+                   the work tree); no global config          ``before``, default
+                                                             branch)
+``builtin``        built-in secure defaults only             CI when no trusted
+                                                             commit exists
+=================  =======================================  ======================
+
+On top of any source, a central service can apply a :class:`MandatoryPolicy`
+(e.g. the operator of the GitHub App, later an organisation). It is a floor,
+not a layer: repository configuration cannot weaken it (see
+:mod:`commitguard.policies.mandatory`). The intended future hierarchy is::
+
+    global mandatory policy -> organisation mandatory policy
+        -> trusted repository configuration -> (local developer configuration)
+
+where every mandatory level can only tighten what the levels below produce.
+"""
+
+from enum import StrEnum
+from pathlib import Path, PurePosixPath
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from commitguard.config.defaults import CONFIG_FILENAMES, MAX_CONFIG_BYTES
+from commitguard.config.loader import (
+    ConfigLayer,
+    ConfigSource,
+    LoadedConfig,
+    load_config,
+    load_effective_config,
+    parse_config,
+)
+from commitguard.config.schema import CommitGuardConfig
+from commitguard.exceptions.base import UnsafeInputError
+from commitguard.exceptions.configuration import ConfigurationError
+from commitguard.git.repository import Repository
+from commitguard.policies.mandatory import validate_mandatory_config
+from commitguard.security.hashing import sha256_hex
+from commitguard.security.validation import validate_git_sha, validate_repository_path
+
+
+class PolicySourceKind(StrEnum):
+    WORKING_TREE = "working_tree"
+    REVISION = "revision"
+    BUILTIN = "builtin"
+
+
+class PolicySource(BaseModel):
+    """A description of where policy is loaded from, shown in every report."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: PolicySourceKind
+    revision: str | None = None
+    description: str
+    config_path: str | None = None  # repository-relative; None = .commitguard.yaml/.yml
+
+    @field_validator("revision")
+    @classmethod
+    def _valid_revision(cls, value: str | None) -> str | None:
+        return None if value is None else validate_git_sha(value)
+
+    @field_validator("config_path")
+    @classmethod
+    def _valid_path(cls, value: str | None) -> str | None:
+        return None if value is None else validate_repository_path(value)
+
+    def __str__(self) -> str:
+        if self.kind is PolicySourceKind.REVISION and self.revision:
+            return f"{self.description} ({self.revision[:12]})"
+        return self.description
+
+
+class MandatoryPolicy(BaseModel):
+    """A policy floor applied after all configuration layers."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    config: CommitGuardConfig
+    description: str
+    fingerprint: str
+
+
+def load_mandatory_policy(path: Path, *, description: str | None = None) -> MandatoryPolicy:
+    """Load and validate a mandatory policy file (same schema as ``.commitguard.yaml``)."""
+    config = load_config(path)
+    try:
+        validate_mandatory_config(config)
+    except ValueError as exc:
+        raise ConfigurationError(str(exc), path=path) from None
+    canonical = config.model_dump_json(exclude_unset=True)
+    return MandatoryPolicy(
+        config=config,
+        description=description or path.name,
+        fingerprint=sha256_hex(canonical.encode("utf-8")),
+    )
+
+
+def load_config_at_revision(
+    repository: Repository, revision: str, *, config_path: str | None = None
+) -> LoadedConfig:
+    """Built-in defaults + the repository configuration stored in ``revision``.
+
+    Nothing is read from the work tree or the user's global configuration. With
+    ``config_path`` the file must exist at that revision; otherwise the usual
+    names are looked up and a missing file means built-in defaults.
+    """
+    layers: list[tuple[ConfigSource, CommitGuardConfig]] = [
+        (ConfigSource(layer=ConfigLayer.BUILTIN), CommitGuardConfig(version=1))
+    ]
+    candidates = [config_path] if config_path else list(CONFIG_FILENAMES)
+    found: list[tuple[str, bytes]] = []
+    for name in candidates:
+        try:
+            data = repository.read_blob_at(revision, name, max_bytes=MAX_CONFIG_BYTES)
+        except UnsafeInputError as exc:
+            raise ConfigurationError(f"{exc} (trusted revision {revision[:12]})") from exc
+        if data is not None:
+            found.append((name, data))
+    if config_path and not found:
+        raise ConfigurationError(
+            f"configuration file {config_path} does not exist at trusted revision {revision[:12]}"
+        )
+    if len(found) > 1:
+        raise ConfigurationError(
+            f"multiple configuration files at {revision[:12]}: "
+            + ", ".join(name for name, _ in found)
+        )
+    if found:
+        name, data = found[0]
+        display = Path(PurePosixPath(name))
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ConfigurationError(
+                f"not valid UTF-8 text (trusted revision {revision[:12]})", path=display
+            ) from exc
+        config = parse_config(text, path=display)
+        source = ConfigSource(layer=ConfigLayer.REPOSITORY, path=display, revision=revision)
+        layers.append((source, config))
+    return LoadedConfig(layers=tuple(layers))
+
+
+def load_policy_source(repository: Repository, source: PolicySource) -> LoadedConfig:
+    if source.kind is PolicySourceKind.REVISION:
+        if source.revision is None:
+            raise ConfigurationError("revision policy source without a revision")
+        return load_config_at_revision(repository, source.revision, config_path=source.config_path)
+    if source.kind is PolicySourceKind.BUILTIN:
+        if source.config_path:
+            raise ConfigurationError(
+                f"configuration file {source.config_path} requested but no trusted revision exists"
+            )
+        return LoadedConfig(
+            layers=((ConfigSource(layer=ConfigLayer.BUILTIN), CommitGuardConfig(version=1)),)
+        )
+    explicit = repository.root / source.config_path if source.config_path else None
+    return load_effective_config(repository.root, explicit_path=explicit)
+
+
+def config_differs(repository: Repository, trusted: str, head: str) -> list[str]:
+    """Configuration file names whose content differs between two commits."""
+    changed = []
+    for name in CONFIG_FILENAMES:
+        try:
+            before = repository.read_blob_at(trusted, name, max_bytes=MAX_CONFIG_BYTES)
+            after = repository.read_blob_at(head, name, max_bytes=MAX_CONFIG_BYTES)
+        except UnsafeInputError:
+            changed.append(name)  # e.g. replaced by a symlink or oversized: report it
+            continue
+        if before != after:
+            changed.append(name)
+    return changed

commitguard/controlplane/__init__.py

@@ -0,0 +1,24 @@
+"""The CommitGuard control plane: what the dashboard API exposes.
+
+::
+
+    CommitGuard core (detection, policy)  ->  ScanService -> ScanResult
+            |                                                   |
+            |                        ScanResultRecorder (findings, violation lifecycle)
+            v                                                   v
+    OrganizationPolicyService  ---- mandatory floor ---->  state database
+            ^                                                   ^
+            |                                                   |
+    dashboard API routes -> authentication -> authorization -> query/command services
+
+Nothing here detects attribution or evaluates policy. Scans are produced by
+the same :class:`~commitguard.services.scan.ScanService` the GitHub Action and
+the GitHub App use; this package stores their results, tracks whether each
+violation is still present, versions organisation policy, and answers
+questions about that data for one authorised principal at a time.
+
+Tenant isolation is structural: every read takes an
+:class:`~commitguard.controlplane.access.AccessScope` built from the signed-in
+session, and every query filters by the installations and repositories in that
+scope.
+"""

commitguard/controlplane/access.py

@@ -0,0 +1,231 @@
+"""Roles, permissions and the access scope of a signed-in user.
+
+Tenant model
+============
+
+* A **tenant** (organisation) is a GitHub account - an organisation or a user -
+  identified by its immutable numeric account ID. It owns one GitHub App
+  installation (GitHub allows one per account), whose repositories, scans,
+  violations and audit events belong to it.
+* A **member** is a GitHub user with a CommitGuard role in that tenant. Roles
+  are granted in CommitGuard (``commitguard dashboard members grant`` or by an
+  owner in the dashboard); GitHub does not grant them.
+* Access needs both: a role in CommitGuard *and* access in GitHub. At sign-in
+  GitHub reports which installations and repositories the user can see
+  (``GET /user/installations``, ``GET /user/installations/{id}/repositories``);
+  CommitGuard stores that list with the session and never shows a repository
+  the user could not open on GitHub, whatever their CommitGuard role.
+
+Roles
+=====
+
+==================  =========================================================
+Role                Adds
+==================  =========================================================
+``viewer``          read repositories, scans, violations, policies, rules,
+                    exceptions, the organization and its security posture;
+                    receive in-app notifications about them
+``security_manager`` acknowledge violations, request re-scans, read the audit log,
+                    request policy exceptions
+``admin``           change, publish, approve and roll back policy, manage
+                    repository groups, onboarding, rollouts, scan schedules,
+                    organization rules and settings, approve and revoke
+                    exceptions, stop/resume monitoring a repository, refresh
+                    enforcement status, sync installation repositories, list
+                    members, manage organisation notification settings and webhooks
+``owner``           grant, change and remove member roles; emergency policy
+                    publication (bypassing approval, always audited)
+==================  =========================================================
+
+Each role includes every permission of the roles above it. The owner of a
+personal (user-account) installation is always its ``owner``.
+
+Authorization is by permission, never by role name: routes and services check
+a :class:`Permission`, and the role table below is the only place that maps
+roles to permissions. There is no separate ``member`` role: ``viewer`` is the
+least-privileged member. Separation of duties (a policy change approved by
+someone other than its author) is enforced by the policy workflow, not by roles.
+"""
+
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+
+
+class Permission(StrEnum):
+    REPOSITORIES_READ = "repositories:read"
+    REPOSITORIES_MANAGE = "repositories:manage"
+    SCANS_READ = "scans:read"
+    SCANS_TRIGGER = "scans:trigger"
+    VIOLATIONS_READ = "violations:read"
+    VIOLATIONS_MANAGE = "violations:manage"
+    POLICIES_READ = "policies:read"
+    POLICIES_WRITE = "policies:write"
+    POLICIES_ROLLBACK = "policies:rollback"
+    RULES_READ = "rules:read"
+    AUDIT_READ = "audit:read"
+    GITHUB_MANAGE = "github:manage"
+    MEMBERS_READ = "members:read"
+    MEMBERS_MANAGE = "members:manage"
+    NOTIFICATIONS_READ = "notifications:read"
+    NOTIFICATIONS_MANAGE = "notifications:manage"
+    # Phase 8: organization governance.
+    ORGANIZATION_READ = "organization:read"
+    ORGANIZATION_MANAGE = "organization:manage"
+    POLICIES_PUBLISH = "policies:publish"
+    POLICIES_APPROVE = "policies:approve"
+    POLICIES_EMERGENCY = "policies:emergency"
+    RULES_MANAGE = "rules:manage"
+    EXCEPTIONS_READ = "exceptions:read"
+    EXCEPTIONS_CREATE = "exceptions:create"
+    EXCEPTIONS_APPROVE = "exceptions:approve"
+    EXCEPTIONS_REVOKE = "exceptions:revoke"
+    SECURITY_READ = "security:read"
+    SECURITY_MANAGE = "security:manage"
+
+
+class Role(StrEnum):
+    VIEWER = "viewer"
+    SECURITY_MANAGER = "security_manager"
+    ADMIN = "admin"
+    OWNER = "owner"
+
+    @property
+    def rank(self) -> int:
+        return list(Role).index(self)
+
+    @property
+    def permissions(self) -> frozenset[Permission]:
+        return ROLE_PERMISSIONS[self]
+
+
+_VIEWER = frozenset(
+    {
+        Permission.REPOSITORIES_READ,
+        Permission.SCANS_READ,
+        Permission.VIOLATIONS_READ,
+        Permission.POLICIES_READ,
+        Permission.RULES_READ,
+        Permission.NOTIFICATIONS_READ,
+        Permission.ORGANIZATION_READ,
+        Permission.EXCEPTIONS_READ,
+        Permission.SECURITY_READ,
+    }
+)
+_SECURITY_MANAGER = _VIEWER | {
+    Permission.VIOLATIONS_MANAGE,
+    Permission.SCANS_TRIGGER,
+    Permission.AUDIT_READ,
+    Permission.EXCEPTIONS_CREATE,
+}
+_ADMIN = _SECURITY_MANAGER | {
+    Permission.POLICIES_WRITE,
+    Permission.POLICIES_ROLLBACK,
+    Permission.POLICIES_PUBLISH,
+    Permission.POLICIES_APPROVE,
+    Permission.NOTIFICATIONS_MANAGE,
+    Permission.REPOSITORIES_MANAGE,
+    Permission.GITHUB_MANAGE,
+    Permission.MEMBERS_READ,
+    Permission.ORGANIZATION_MANAGE,
+    Permission.RULES_MANAGE,
+    Permission.EXCEPTIONS_APPROVE,
+    Permission.EXCEPTIONS_REVOKE,
+    Permission.SECURITY_MANAGE,
+}
+_OWNER = _ADMIN | {Permission.MEMBERS_MANAGE, Permission.POLICIES_EMERGENCY}
+
+ROLE_PERMISSIONS: Mapping[Role, frozenset[Permission]] = {
+    Role.VIEWER: _VIEWER,
+    Role.SECURITY_MANAGER: frozenset(_SECURITY_MANAGER),
+    Role.ADMIN: frozenset(_ADMIN),
+    Role.OWNER: frozenset(_OWNER),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AccessScope:
+    """What one session may see for one permission.
+
+    ``installation_ids`` are installations whose account grants the permission
+    to the user *and* that GitHub reported as accessible at sign-in.
+    ``session_hash`` keys the per-session list of repositories GitHub reported;
+    repository-level rows are only visible when listed there.
+    """
+
+    session_hash: str
+    installation_ids: tuple[int, ...]
+    account_ids: tuple[int, ...]
+
+    @property
+    def empty(self) -> bool:
+        return not self.installation_ids and not self.account_ids
+
+    @property
+    def installations_json(self) -> str:
+        """The installation IDs as a JSON array, bound to ``json_each(?)`` in queries."""
+        return json.dumps(list(self.installation_ids))
+
+    @property
+    def accounts_json(self) -> str:
+        return json.dumps(list(self.account_ids))
+
+
+@dataclass(frozen=True, slots=True)
+class Membership:
+    account_id: int
+    account_login: str
+    account_type: str
+    role: Role
+    implicit: bool = False  # owner of a personal installation
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """A signed-in user, as established by the session for one request."""
+
+    user_id: int
+    login: str
+    session_hash: str
+    session_public_id: str
+    authenticated_at: datetime
+    expires_at: datetime
+    memberships: Mapping[int, Membership] = field(default_factory=dict)
+    # installation_id -> account_id, for installations GitHub reported at sign-in
+    installations: Mapping[int, int] = field(default_factory=dict)
+
+    def role_in(self, account_id: int) -> Role | None:
+        membership = self.memberships.get(account_id)
+        return membership.role if membership else None
+
+    def can(self, permission: Permission, account_id: int) -> bool:
+        role = self.role_in(account_id)
+        return role is not None and permission in role.permissions
+
+    def accounts_with(self, permission: Permission) -> tuple[int, ...]:
+        return tuple(
+            sorted(a for a, m in self.memberships.items() if permission in m.role.permissions)
+        )
+
+    def scope(self, permission: Permission, *, account_id: int | None = None) -> AccessScope:
+        accounts = set(self.accounts_with(permission))
+        if account_id is not None:
+            accounts &= {account_id}
+        installations = tuple(
+            sorted(i for i, account in self.installations.items() if account in accounts)
+        )
+        return AccessScope(
+            session_hash=self.session_hash,
+            installation_ids=installations,
+            account_ids=tuple(sorted(accounts)),
+        )
+
+    def permissions_for(self, account_id: int) -> frozenset[Permission]:
+        role = self.role_in(account_id)
+        return role.permissions if role else frozenset()
+
+
+def highest_role(roles: Iterable[Role]) -> Role | None:
+    return max(roles, key=lambda role: role.rank, default=None)