interbolt 0.1.0__py3-none-any.whl

interbolt/models/protocols.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Protocol, runtime_checkable
+
+from interbolt.models.core import Decision, Event, Finding
+
+
+@runtime_checkable
+class Reporter(Protocol):
+    """The reporting seam. `enforcement` emits through this, never a concrete type."""
+
+    def export(self, event: Event | Finding) -> None:
+        """Emit a decision event or audit finding.
+
+        Args:
+            event: The record to emit.
+
+        A reporter's `export` must never block or delay a decision; that is the
+        reporter author's responsibility, not a guarantee the engine provides.
+        """
+        ...
+
+
+@runtime_checkable
+class ApprovalResolver(Protocol):
+    """Resolves a `require_approval` decision to allow or deny.
+
+    Invoked synchronously at a sync call site and asynchronously (awaited) at an
+    async call site; a sync call site cannot use a resolver that only returns an
+    awaitable.
+    """
+
+    def __call__(self, decision: Decision) -> bool | Awaitable[bool]:
+        """Decide whether to allow the call that produced `decision`.
+
+        Args:
+            decision: The decision that requires approval.
+
+        Returns:
+            `True` to allow the call, `False` to deny it. May return an
+            awaitable when called from an async call site.
+        """
+        ...
+
+
+def auto_deny(decision: Decision) -> bool:
+    """The default `ApprovalResolver`: deny every approval request.
+
+    Args:
+        decision: The decision that requires approval.
+
+    Returns:
+        Always `False`.
+    """
+    return False

interbolt/policy/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from interbolt.models.core import TrustLevel
+from interbolt.policy.engine import CompiledSink, compile_policy
+from interbolt.policy.schema import (
+    PolicyDocument,
+    load_policy_document,
+    validate_policy,
+)
+
+
+class Policy:
+    """A loaded, compiled policy: the validated document plus its compiled sinks.
+
+    Attributes:
+        document: The validated policy document.
+        compiled_sinks: Every sink's compiled, ready-to-evaluate rule list.
+    """
+
+    def __init__(
+        self, document: PolicyDocument, compiled_sinks: dict[str, CompiledSink]
+    ) -> None:
+        self.document = document
+        self.compiled_sinks = compiled_sinks
+
+    @property
+    def sources_table(self) -> dict[str, TrustLevel]:
+        """The declared source-to-trust mapping, for trust resolution at the sink."""
+        return {
+            declaration.name: declaration.trust for declaration in self.document.sources
+        }
+
+    @classmethod
+    def from_file(cls, path: str) -> Policy:
+        """Load, validate, and compile a policy file in one call.
+
+        Args:
+            path: Filesystem path to the policy YAML file.
+
+        Returns:
+            A `Policy` ready to pass to `configure()`.
+
+        Raises:
+            PolicyEvaluationError: If the file is missing, malformed, or
+                fails schema or CEL compilation.
+        """
+        document = load_policy_document(path)
+        return cls(document=document, compiled_sinks=compile_policy(document))
+
+    @classmethod
+    def validate(cls, path: str) -> list[str]:
+        """Statically analyze a policy file without loading or compiling it for use.
+
+        Args:
+            path: Filesystem path to the policy YAML file.
+
+        Returns:
+            A list of human-readable problem descriptions; empty if valid.
+            Never raises.
+        """
+        return validate_policy(path)

interbolt/policy/engine.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import celpy
+from celpy import celtypes
+from celpy.adapter import json_to_cel
+
+from interbolt.models.core import Action, Label, TrustLevel
+from interbolt.policy.schema import PolicyDocument
+
+_ANY_MACRO_PATTERN = re.compile(r"\.any\(")
+_ENV = celpy.Environment()
+
+
+def _rewrite_any_to_exists(source: str) -> str:
+    """Rewrite the policy DSL's `.any(` to CEL's real `exists` macro.
+
+    CEL's macro set is exactly `{map, filter, all, exists, exists_one, reduce,
+    min}`; there is no `any`. `exists` ("at least one element satisfies the
+    predicate") is semantically identical to Python's `any`, so this is a safe
+    textual rewrite, done once at compile time, never per evaluation.
+    """
+    return _ANY_MACRO_PATTERN.sub(".exists(", source)
+
+
+def compile_cel_expression(source: str) -> celpy.Runner:
+    """Compile one CEL `when` expression into a reusable, evaluate-many program.
+
+    Args:
+        source: The CEL expression text, as written in the policy YAML.
+
+    Returns:
+        A compiled celpy program, ready for repeated `evaluate()` calls.
+
+    Raises:
+        celpy.CELParseError: If the expression is not valid CEL.
+    """
+    return _ENV.program(_ENV.compile(_rewrite_any_to_exists(source)))
+
+
+@dataclass(frozen=True)
+class CompiledRule:
+    """One compiled rule. `program is None` marks the unconditional catch-all."""
+
+    name: str
+    action: Action
+    program: celpy.Runner | None
+
+
+@dataclass(frozen=True)
+class CompiledSink:
+    """A sink's ordered, compiled rule list."""
+
+    rules: tuple[CompiledRule, ...]
+
+
+def compile_policy(document: PolicyDocument) -> dict[str, CompiledSink]:
+    """Compile every sink's rule list once, at policy load time.
+
+    Args:
+        document: The validated policy document.
+
+    Returns:
+        A mapping of dotted sink key to its compiled rule list.
+    """
+    compiled: dict[str, CompiledSink] = {}
+    for sink_key, rules in document.sinks.items():
+        compiled_rules = tuple(
+            CompiledRule(
+                name=rule.name,
+                action=rule.action,
+                program=compile_cel_expression(rule.when)
+                if rule.when is not None
+                else None,
+            )
+            for rule in rules
+        )
+        compiled[sink_key] = CompiledSink(rules=compiled_rules)
+    return compiled
+
+
+def resolve_label_trust(
+    label: Label, sources_table: Mapping[str, TrustLevel]
+) -> TrustLevel:
+    """Resolve a label's trust from every name in its lineage, untrusted-wins.
+
+    Trust is never stored on a `Label`; this is the one place it is computed,
+    at the sink, from the policy's `sources` table. A name not in the table
+    defaults to untrusted (default-deny).
+    """
+    for name in label.lineage:
+        if sources_table.get(name, TrustLevel.UNTRUSTED) is TrustLevel.UNTRUSTED:
+            return TrustLevel.UNTRUSTED
+    return TrustLevel.TRUSTED
+
+
+def _convert_args(args: Mapping[str, Any]) -> celtypes.MapType:
+    converted: dict[celtypes.StringType, Any] = {}
+    for key, value in args.items():
+        try:
+            converted[celtypes.StringType(key)] = json_to_cel(value)
+        except (ValueError, TypeError):
+            # Not representable in CEL (e.g. an arbitrary object); simply
+            # unavailable to `when` predicates, same as a missing key.
+            continue
+    return celtypes.MapType(converted)
+
+
+def build_context(
+    *,
+    tool: str,
+    args: Mapping[str, Any],
+    labels: tuple[Label, ...],
+    trifecta: frozenset[str],
+    sources_table: Mapping[str, TrustLevel],
+) -> dict[str, Any]:
+    """Build the CEL evaluation context for one `check()` call.
+
+    `args` must already be stripped of taint carriers (plain `str`/`bytes`/
+    containers) by the caller; this function has no knowledge of `Tainted`,
+    `TaintedBytes`, or `LabeledValue` (`policy/` never imports `taint/`).
+
+    `taint` stays a plain CEL list so `taint.any(...)`/`taint.all(...)` keep
+    working as macros over it. The two aggregate convenience values move to
+    top-level siblings, `sources` and `max_trust`, rather than `taint.sources`/
+    `taint.max_trust`: CEL cannot make one context variable both a list (for
+    the macros) and a map (for dotted field access) at once.
+
+    Args:
+        tool: The dotted qualified tool name.
+        args: The call's bound arguments, taint carriers already stripped.
+        labels: Every label collected from the call's original arguments.
+        trifecta: The trifecta legs satisfied by this call.
+        sources_table: The policy's declared source-to-trust mapping.
+
+    Returns:
+        A context mapping ready for `celpy.Runner.evaluate(...)`.
+    """
+    taint_list = celtypes.ListType(
+        [
+            celtypes.MapType(
+                {
+                    celtypes.StringType("source"): celtypes.StringType(label.source),
+                    celtypes.StringType("trust"): celtypes.StringType(
+                        resolve_label_trust(label, sources_table).value
+                    ),
+                }
+            )
+            for label in labels
+        ]
+    )
+
+    all_sources: dict[str, None] = {}
+    for label in labels:
+        for name in label.lineage:
+            all_sources.setdefault(name, None)
+
+    max_trust = (
+        TrustLevel.UNTRUSTED
+        if any(
+            resolve_label_trust(label, sources_table) is TrustLevel.UNTRUSTED
+            for label in labels
+        )
+        else TrustLevel.TRUSTED
+    )
+
+    return {
+        "tool": celtypes.StringType(tool),
+        "args": _convert_args(args),
+        "taint": taint_list,
+        "sources": celtypes.ListType(
+            [celtypes.StringType(name) for name in all_sources]
+        ),
+        "max_trust": celtypes.StringType(max_trust.value),
+        "trifecta": celtypes.ListType([celtypes.StringType(leg) for leg in trifecta]),
+    }
+
+
+def evaluate_sink(
+    compiled_sink: CompiledSink, context: Mapping[str, Any], *, default_action: Action
+) -> tuple[str | None, Action]:
+    """Evaluate a sink's compiled rules, first match wins.
+
+    Args:
+        compiled_sink: The sink's compiled rule list.
+        context: The CEL context built by `build_context`.
+        default_action: The action to fall through to if no rule matches.
+
+    Returns:
+        The matched rule's name (or `None` for the default) and its action.
+
+    Raises:
+        celpy.evaluation.CELEvalError: If a rule's `when` references a missing
+            argument, a `None` value, or otherwise fails to evaluate.
+    """
+    for rule in compiled_sink.rules:
+        if rule.program is None:
+            return rule.name, rule.action
+        if bool(rule.program.evaluate(context)):
+            return rule.name, rule.action
+    return None, default_action

interbolt/policy/schema.json

@@ -0,0 +1,131 @@
+{
+  "$defs": {
+    "Action": {
+      "description": "The three possible policy decisions.",
+      "enum": [
+        "allow",
+        "block",
+        "require_approval"
+      ],
+      "title": "Action",
+      "type": "string"
+    },
+    "Defaults": {
+      "description": "Default-deny posture for sources and sinks not otherwise declared.",
+      "properties": {
+        "source_trust": {
+          "$ref": "#/$defs/TrustLevel",
+          "default": "untrusted"
+        },
+        "sink_action": {
+          "$ref": "#/$defs/Action",
+          "default": "require_approval"
+        },
+        "fail_mode": {
+          "default": "enforce",
+          "enum": [
+            "enforce",
+            "monitor",
+            "dry_run"
+          ],
+          "title": "Fail Mode",
+          "type": "string"
+        }
+      },
+      "title": "Defaults",
+      "type": "object"
+    },
+    "SinkRule": {
+      "description": "One ordered rule within a sink's rule list. First match wins.",
+      "properties": {
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "when": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "When"
+        },
+        "action": {
+          "$ref": "#/$defs/Action"
+        }
+      },
+      "required": [
+        "name",
+        "action"
+      ],
+      "title": "SinkRule",
+      "type": "object"
+    },
+    "SourceDeclaration": {
+      "description": "A declared ingress source and the trust level it resolves to.",
+      "properties": {
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "trust": {
+          "$ref": "#/$defs/TrustLevel"
+        }
+      },
+      "required": [
+        "name",
+        "trust"
+      ],
+      "title": "SourceDeclaration",
+      "type": "object"
+    },
+    "TrustLevel": {
+      "description": "The result of resolving a source name against a policy's sources table.",
+      "enum": [
+        "trusted",
+        "untrusted"
+      ],
+      "title": "TrustLevel",
+      "type": "string"
+    }
+  },
+  "description": "The validated shape of a policy YAML file.",
+  "properties": {
+    "version": {
+      "title": "Version",
+      "type": "string"
+    },
+    "defaults": {
+      "$ref": "#/$defs/Defaults"
+    },
+    "sources": {
+      "default": [],
+      "items": {
+        "$ref": "#/$defs/SourceDeclaration"
+      },
+      "title": "Sources",
+      "type": "array"
+    },
+    "sinks": {
+      "additionalProperties": {
+        "items": {
+          "$ref": "#/$defs/SinkRule"
+        },
+        "type": "array"
+      },
+      "title": "Sinks",
+      "type": "object"
+    }
+  },
+  "required": [
+    "version",
+    "defaults",
+    "sinks"
+  ],
+  "title": "PolicyDocument",
+  "type": "object"
+}

interbolt/policy/schema.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import re
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+
+from interbolt.constants import TRIFECTA_COMPUTABLE_LEGS
+from interbolt.errors import InterboltConfigError, PolicyEvaluationError
+from interbolt.models.core import Action, Mode, TrustLevel, validate_qualified_name_part
+
+_TRIFECTA_LEG_PATTERN = re.compile(r"trifecta\.contains\(\s*[\"']([^\"']+)[\"']\s*\)")
+
+
+class SourceDeclaration(BaseModel):
+    """A declared ingress source and the trust level it resolves to."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    trust: TrustLevel
+
+
+class Defaults(BaseModel):
+    """Default-deny posture for sources and sinks not otherwise declared."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_trust: TrustLevel = TrustLevel.UNTRUSTED
+    sink_action: Action = Action.REQUIRE_APPROVAL
+    fail_mode: Mode = Mode.ENFORCE
+
+
+class SinkRule(BaseModel):
+    """One ordered rule within a sink's rule list. First match wins."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    when: str | None = None
+    action: Action
+
+
+def _split_sink_key(key: str) -> tuple[str, str]:
+    namespace, separator, tool = key.rpartition(".")
+    if not separator:
+        raise InterboltConfigError(
+            f"sink key {key!r} must be a dotted 'namespace.tool' name"
+        )
+    validate_qualified_name_part(namespace, part="namespace")
+    validate_qualified_name_part(tool, part="tool")
+    return namespace, tool
+
+
+class PolicyDocument(BaseModel):
+    """The validated shape of a policy YAML file."""
+
+    model_config = ConfigDict(frozen=True)
+
+    version: str
+    defaults: Defaults
+    sources: tuple[SourceDeclaration, ...] = ()
+    sinks: dict[str, tuple[SinkRule, ...]]
+
+    @field_validator("sinks")
+    @classmethod
+    def _validate_sink_keys(
+        cls, value: dict[str, tuple[SinkRule, ...]]
+    ) -> dict[str, tuple[SinkRule, ...]]:
+        for key in value:
+            _split_sink_key(key)
+        return value
+
+
+def load_policy_document(path: str) -> PolicyDocument:
+    """Load and validate a policy YAML file against `PolicyDocument`.
+
+    Args:
+        path: Filesystem path to the policy YAML file.
+
+    Returns:
+        The validated `PolicyDocument`.
+
+    Raises:
+        PolicyEvaluationError: If the file cannot be read, is not valid YAML,
+            or does not conform to the policy schema.
+    """
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = yaml.safe_load(handle)
+    except (OSError, yaml.YAMLError) as exc:
+        raise PolicyEvaluationError(
+            f"failed to read policy file {path!r}: {exc}"
+        ) from exc
+    try:
+        return PolicyDocument.model_validate(data)
+    except ValidationError as exc:
+        raise PolicyEvaluationError(f"policy file {path!r} is invalid: {exc}") from exc
+
+
+def validate_policy(path: str) -> list[str]:
+    """Statically analyze a policy file: schema, CEL compilation, dead rules.
+
+    Never executes an agent and never observes live taint; this is the
+    dynamic counterpart's opposite number (`dry_run` + the audit flag, which
+    are in-process instruments). Does not attempt to resolve whether every
+    source name referenced inside a `when` expression is declared, since that
+    would require walking the CEL AST for string-literal comparisons against
+    `t.source`; out of scope for v1's static check.
+
+    Rejects any `when` expression referencing a trifecta leg outside the
+    v1-computable set (`{"from_untrusted"}`), since
+    `trifecta.contains("reaches_external")` silently evaluates to `false` at
+    runtime rather than failing: a rule built on it never fires, with no
+    signal unless caught here.
+
+    Args:
+        path: Filesystem path to the policy YAML file.
+
+    Returns:
+        A list of human-readable problem descriptions. Empty if the policy is
+        valid. Never raises.
+    """
+    from interbolt.policy.engine import compile_cel_expression
+
+    problems: list[str] = []
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = yaml.safe_load(handle)
+    except (OSError, yaml.YAMLError) as exc:
+        return [f"failed to read policy file {path!r}: {exc}"]
+
+    try:
+        document = PolicyDocument.model_validate(data)
+    except ValidationError as exc:
+        for error in exc.errors():
+            location = ".".join(str(part) for part in error["loc"])
+            problems.append(f"{location}: {error['msg']}")
+        return problems
+
+    for sink_key, rules in document.sinks.items():
+        catch_all_seen = False
+        for rule in rules:
+            if catch_all_seen:
+                problems.append(
+                    f"sink {sink_key!r}: rule {rule.name!r} is unreachable, "
+                    "placed after an unconditional catch-all rule"
+                )
+            if rule.when is None:
+                if catch_all_seen:
+                    problems.append(
+                        f"sink {sink_key!r}: more than one unconditional catch-all rule"
+                    )
+                catch_all_seen = True
+                continue
+            try:
+                compile_cel_expression(rule.when)
+            except Exception as exc:  # noqa: BLE001 -- surfacing any compile failure
+                problems.append(
+                    f"sink {sink_key!r}: rule {rule.name!r} "
+                    f"has an invalid CEL expression: {exc}"
+                )
+            for leg in _TRIFECTA_LEG_PATTERN.findall(rule.when):
+                if leg not in TRIFECTA_COMPUTABLE_LEGS:
+                    problems.append(
+                        f"sink {sink_key!r}: rule {rule.name!r} references "
+                        f"trifecta leg {leg!r}, which is not computed in v1 "
+                        f"(trifecta.contains({leg!r}) always evaluates false); "
+                        f"computable legs are {sorted(TRIFECTA_COMPUTABLE_LEGS)}"
+                    )
+
+    return problems

interbolt/reporting/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from interbolt.models.core import Decision, Event, Finding
+from interbolt.utils import get_logger
+
+_logger = get_logger("reporting")
+
+
+class NullReporter:
+    """The default reporter: a no-op. Keeps the library fully local by default."""
+
+    def export(self, event: Event | Finding) -> None:
+        """Discard the record.
+
+        Args:
+            event: The record to discard.
+        """
+        return None
+
+
+class InMemoryReporter:
+    """Captures every exported record in memory; the testing/audit assertion surface."""
+
+    def __init__(self) -> None:
+        self.events: list[Event] = []
+        self.decisions: list[Decision] = []
+        self.findings: list[Finding] = []
+
+    def export(self, event: Event | Finding) -> None:
+        """Capture the record.
+
+        Args:
+            event: The record to capture.
+        """
+        if isinstance(event, Event):
+            self.events.append(event)
+            self.decisions.append(event.decision)
+        else:
+            self.findings.append(event)
+
+    def clear(self) -> None:
+        """Discard every captured record."""
+        self.events.clear()
+        self.decisions.clear()
+        self.findings.clear()
+
+
+class LoggingReporter:
+    """Emits every record via the library logger, at DEBUG."""
+
+    def export(self, event: Event | Finding) -> None:
+        """Log the record.
+
+        Args:
+            event: The record to log.
+        """
+        _logger.debug("export: %r", event)