interbolt 0.1.0__py3-none-any.whl

interbolt/__init__.py

@@ -0,0 +1,55 @@
+"""Provenance-gated tool calls for AI agents.
+
+Mark untrusted data where it enters an agent. interbolt records its provenance,
+carries that provenance through your code, and evaluates a YAML+CEL policy at
+the tool-call boundary to allow, block, or require approval. Decisions are
+deterministic and local: no model in the loop, no network calls.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from interbolt.errors import (
+    ApprovalDenied,
+    InterboltConfigError,
+    InterboltError,
+    InterboltUsageError,
+    PolicyEvaluationError,
+    PolicyViolation,
+)
+from interbolt.models.core import Action, Decision, Label, Mode, TrustLevel
+from interbolt.models.protocols import ApprovalResolver, Reporter
+from interbolt.policy import Policy
+from interbolt.reporting import InMemoryReporter, LoggingReporter, NullReporter
+from interbolt.runtime import Runtime, check, configure, guard
+from interbolt.taint import LabeledValue, Tainted, TaintedBytes, taint
+
+__all__ = [
+    "taint",
+    "guard",
+    "check",
+    "configure",
+    "Runtime",
+    "Policy",
+    "Decision",
+    "Action",
+    "Mode",
+    "Label",
+    "TrustLevel",
+    "Reporter",
+    "ApprovalResolver",
+    "NullReporter",
+    "InMemoryReporter",
+    "LoggingReporter",
+    "InterboltError",
+    "PolicyViolation",
+    "PolicyEvaluationError",
+    "ApprovalDenied",
+    "InterboltConfigError",
+    "InterboltUsageError",
+    "Tainted",
+    "LabeledValue",
+    "TaintedBytes",
+    "__version__",
+]

interbolt/cli/__init__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import argparse
+
+from rich.console import Console
+
+from interbolt import Policy
+
+_console = Console()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """The `interbolt` console script entrypoint.
+
+    Args:
+        argv: Command-line arguments, or `None` to use `sys.argv[1:]`.
+
+    Returns:
+        The process exit code: 0 on success, 1 on failure.
+    """
+    parser = argparse.ArgumentParser(prog="interbolt")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate_parser = subparsers.add_parser(
+        "validate", help="Static policy analysis only. Never executes an agent."
+    )
+    validate_parser.add_argument("policy_path")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "validate":
+        return _validate(args.policy_path)
+    return 1
+
+
+def _validate(policy_path: str) -> int:
+    problems = Policy.validate(policy_path)
+    if problems:
+        for problem in problems:
+            _console.print(f"[red]✗[/red] {problem}")
+        return 1
+    _console.print(f"[green]✓[/green] {policy_path} is valid")
+    return 0

interbolt/constants.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import os
+
+from interbolt.errors import InterboltConfigError
+
+DEFAULT_NAMESPACE: str = "default"
+DEFAULT_AGENT_ID: str = "default"
+
+ENV_MODE: str = "INTERBOLT_MODE"
+ENV_AUDIT: str = "INTERBOLT_AUDIT"
+ENV_RECURSION_DEPTH: str = "INTERBOLT_RECURSION_DEPTH"
+ENV_CACHE_DIR: str = "INTERBOLT_CACHE_DIR"
+
+DEFAULT_RECURSION_DEPTH: int = 4
+RECURSION_DEPTH_MAX: int = 10
+EVENT_SCHEMA_VERSION: int = 1
+AUDIT_MIN_MATCH_LENGTH: int = 12
+
+TRIFECTA_FROM_UNTRUSTED: str = "from_untrusted"
+TRIFECTA_COMPUTABLE_LEGS: frozenset[str] = frozenset({TRIFECTA_FROM_UNTRUSTED})
+
+
+def _resolve_recursion_depth() -> int:
+    """Resolve the container-recursion depth once, at import time.
+
+    Reads `INTERBOLT_RECURSION_DEPTH`, falling back to `DEFAULT_RECURSION_DEPTH`.
+    Both `taint()` and `check()`/`guard` read the resulting constant, so
+    ingress labeling and sink collection are bounded identically (§6.6).
+
+    Raises:
+        InterboltConfigError: If the env var is set but is not an integer in
+            `[1, RECURSION_DEPTH_MAX]`.
+    """
+    raw = os.environ.get(ENV_RECURSION_DEPTH)
+    if raw is None:
+        return DEFAULT_RECURSION_DEPTH
+    try:
+        depth = int(raw)
+    except ValueError as exc:
+        raise InterboltConfigError(
+            f"{ENV_RECURSION_DEPTH}={raw!r} is not an integer"
+        ) from exc
+    if not (1 <= depth <= RECURSION_DEPTH_MAX):
+        raise InterboltConfigError(
+            f"{ENV_RECURSION_DEPTH}={raw!r} must be in [1, {RECURSION_DEPTH_MAX}]"
+        )
+    return depth
+
+
+RECURSION_DEPTH: int = _resolve_recursion_depth()

interbolt/enforcement/__init__.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import uuid
+from collections.abc import Generator, Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+from celpy.evaluation import CELEvalError
+
+from interbolt.constants import (
+    AUDIT_MIN_MATCH_LENGTH,
+    EVENT_SCHEMA_VERSION,
+    RECURSION_DEPTH,
+    TRIFECTA_FROM_UNTRUSTED,
+)
+from interbolt.errors import PolicyEvaluationError
+from interbolt.models.core import (
+    Action,
+    Decision,
+    Event,
+    Finding,
+    Label,
+    Mode,
+    TrustLevel,
+)
+from interbolt.models.protocols import Reporter
+from interbolt.policy import Policy
+from interbolt.policy.engine import build_context, evaluate_sink, resolve_label_trust
+from interbolt.taint import Tainted, TaintedBytes, collect_labels, unwrap
+from interbolt.utils import get_logger
+
+_logger = get_logger("enforcement")
+_CONTAINER_TYPES = (list, tuple, set, frozenset)
+
+
+def check(
+    *,
+    tool: str,
+    args: Mapping[str, Any],
+    agent_id: str,
+    run_id: str | None,
+    session_id: str | None,
+    policy: Policy,
+    reporter: Reporter,
+    mode: Mode,
+    audit_registry: AuditRegistry | None = None,
+) -> Decision:
+    """Evaluate policy for one guarded call. The single decision entrypoint.
+
+    Pure with respect to the decision itself; the only side effects are the
+    fire-and-forget reporter emission and, when an audit registry is given,
+    the laundering scan. `guard` is sugar over this function and never
+    duplicates this sequence.
+
+    Note: this function never raises `PolicyViolation` or `ApprovalDenied`
+    for a normally-computed `block`/`require_approval` decision; it returns
+    the `Decision` and leaves enforcing it (raising, invoking the approval
+    resolver) to the caller, exactly as `guard` does. It only raises
+    directly for a genuine policy *evaluation* failure under `enforce` mode.
+
+    Args:
+        tool: The dotted qualified tool name.
+        args: The call's bound arguments.
+        agent_id: The durable agent identity.
+        run_id: The per-run identity, or `None` to mint a fresh one.
+        session_id: The optional session identity.
+        policy: The compiled policy to evaluate against.
+        reporter: Where to emit the resulting `Event`.
+        mode: The enforcement mode in effect.
+        audit_registry: The laundering-audit registry, or `None` if the
+            audit instrument is disabled.
+
+    Returns:
+        The computed `Decision`.
+
+    Raises:
+        PolicyEvaluationError: Under `enforce` mode, if policy evaluation
+            itself fails (a missing argument, a `None` value, or another CEL
+            evaluation error).
+    """
+    labels = collect_labels(args, max_depth=RECURSION_DEPTH)
+    plain_args = unwrap(args)
+    sources_table = policy.sources_table
+    trifecta = _compute_trifecta(labels, sources_table)
+    compiled_sink = policy.compiled_sinks.get(tool)
+    resolved_run_id = run_id or str(uuid.uuid4())
+
+    matched_rule: str | None = None
+    action: Action = policy.document.defaults.sink_action
+    evaluation_error: CELEvalError | None = None
+    try:
+        context = build_context(
+            tool=tool,
+            args=plain_args,
+            labels=labels,
+            trifecta=trifecta,
+            sources_table=sources_table,
+        )
+        if compiled_sink is not None:
+            matched_rule, action = evaluate_sink(
+                compiled_sink,
+                context,
+                default_action=policy.document.defaults.sink_action,
+            )
+    except CELEvalError as exc:
+        evaluation_error = exc
+
+    raw_action = action
+    outcome = action.value
+    if evaluation_error is not None:
+        outcome = "evaluation_error"
+        matched_rule = None
+        raw_action = Action.BLOCK if mode == Mode.ENFORCE else Action.ALLOW
+
+    final_action = Action.ALLOW if mode == Mode.DRY_RUN else raw_action
+
+    decision = Decision(
+        action=final_action,
+        matched_rule=matched_rule,
+        tool=tool,
+        contributing_labels=labels,
+        trifecta=trifecta,
+        mode=mode,
+        decision_id=str(uuid.uuid4()),
+        agent_id=agent_id,
+        run_id=resolved_run_id,
+        session_id=session_id,
+    )
+
+    all_sources = frozenset(name for label in labels for name in label.lineage)
+    event = Event(
+        schema_version=EVENT_SCHEMA_VERSION,
+        decision=decision,
+        agent_id=agent_id,
+        run_id=resolved_run_id,
+        session_id=session_id,
+        sources=all_sources,
+        lineage=tuple(sorted(all_sources)),
+        matched_rule=matched_rule,
+        trifecta=trifecta,
+        mode=mode,
+        outcome=outcome,
+        timestamp=datetime.now(UTC),
+    )
+    _emit(reporter, event)
+
+    if audit_registry is not None:
+        audit_registry.register_from_args(
+            args,
+            sources_table=sources_table,
+            run_id=resolved_run_id,
+            depth=RECURSION_DEPTH,
+        )
+        findings = audit_registry.scan(
+            args,
+            tool=tool,
+            run_id=resolved_run_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            depth=RECURSION_DEPTH,
+        )
+        for finding in findings:
+            _emit(reporter, finding)
+
+    if evaluation_error is not None and mode == Mode.ENFORCE:
+        raise PolicyEvaluationError(str(evaluation_error), decision=decision)
+
+    return decision
+
+
+def _emit(reporter: Reporter, event: Event | Finding) -> None:
+    try:
+        reporter.export(event)
+    except Exception:  # noqa: BLE001 -- a reporter failure must never affect a decision
+        _logger.warning(
+            "reporter %r failed to export %r", reporter, type(event).__name__
+        )
+
+
+def _compute_trifecta(
+    labels: tuple[Label, ...], sources_table: Mapping[str, TrustLevel]
+) -> frozenset[str]:
+    """Compute the lethal-trifecta legs satisfied by this call.
+
+    v1 computes `from_untrusted` only. The `reaches_external` and
+    `reads_private` legs are not computed in v1 (the latter requires the
+    deferred capabilities declaration); `trifecta.contains("reaches_external")`
+    always evaluates false. Do not rely on a v1 trifecta size as a backstop.
+    """
+    if any(
+        resolve_label_trust(label, sources_table) is TrustLevel.UNTRUSTED
+        for label in labels
+    ):
+        return frozenset({TRIFECTA_FROM_UNTRUSTED})
+    return frozenset()
+
+
+def _walk_strings(
+    value: Any,
+    *,
+    depth: int,  # noqa: ANN401 -- arbitrary bound-argument value
+) -> Generator[tuple[str, Label | None], None, None]:
+    """Yield every string leaf in `value`: `(content, label)`.
+
+    `label` is `None` for a plain `str` (a potential laundering point) and
+    set for a `Tainted`/`TaintedBytes` leaf (already labeled, not a
+    laundering point). Recurses into builtin containers to `depth`.
+    """
+    if isinstance(value, (Tainted, TaintedBytes)):
+        content = (
+            value if isinstance(value, str) else value.decode("utf-8", errors="ignore")
+        )
+        yield str(content), value.label
+        return
+    if isinstance(value, str):
+        yield value, None
+        return
+    if depth <= 0:
+        return
+    if isinstance(value, Mapping):
+        for v in value.values():
+            yield from _walk_strings(v, depth=depth - 1)
+        return
+    if isinstance(value, _CONTAINER_TYPES):
+        for item in value:
+            yield from _walk_strings(item, depth=depth - 1)
+
+
+class AuditRegistry:
+    """The laundering audit's per-run registry of untrusted-resolving content.
+
+    Advisory only: findings never change a decision. Off the latency budget;
+    only ever invoked when audit is enabled. Catches mechanical laundering
+    (the bytes survive into a sink argument unlabeled); cannot catch semantic
+    laundering (a model paraphrasing the untrusted text first).
+    """
+
+    def __init__(self, *, min_match_length: int = AUDIT_MIN_MATCH_LENGTH) -> None:
+        self._min_match_length = min_match_length
+        self._by_run: dict[str, list[tuple[str, str]]] = {}
+        self._findings: list[Finding] = []
+
+    def register_from_args(
+        self,
+        args: Mapping[str, Any],
+        *,
+        sources_table: Mapping[str, TrustLevel],
+        run_id: str,
+        depth: int,
+    ) -> None:
+        """Register every untrusted-resolving string found in `args` for this run."""
+        for value in args.values():
+            for content, label in _walk_strings(value, depth=depth):
+                if label is None or len(content) < self._min_match_length:
+                    continue
+                if resolve_label_trust(label, sources_table) is TrustLevel.UNTRUSTED:
+                    self._by_run.setdefault(run_id, []).append((content, label.source))
+
+    def scan(
+        self,
+        args: Mapping[str, Any],
+        *,
+        tool: str,
+        run_id: str,
+        agent_id: str,
+        session_id: str | None,
+        depth: int,
+    ) -> list[Finding]:
+        """Scan `args` for previously-registered untrusted content with no label."""
+        registered = self._by_run.get(run_id, [])
+        if not registered:
+            return []
+        findings: list[Finding] = []
+        for argument, value in args.items():
+            for content, label in _walk_strings(value, depth=depth):
+                if label is not None:
+                    continue
+                for registered_content, source in registered:
+                    if registered_content in content:
+                        findings.append(
+                            Finding(
+                                schema_version=EVENT_SCHEMA_VERSION,
+                                source=source,
+                                tool=tool,
+                                argument=argument,
+                                agent_id=agent_id,
+                                run_id=run_id,
+                                session_id=session_id,
+                                timestamp=datetime.now(UTC),
+                            )
+                        )
+        self._findings.extend(findings)
+        return findings
+
+    def clear_run(self, run_id: str) -> None:
+        """Drop the registered content for a finished run."""
+        self._by_run.pop(run_id, None)
+
+    @property
+    def findings(self) -> list[Finding]:
+        """Every finding recorded so far, across all runs."""
+        return list(self._findings)

interbolt/errors.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from interbolt.models.core import Decision
+
+
+class InterboltError(Exception):
+    """Base class for every exception interbolt raises as part of a policy decision."""
+
+
+class PolicyViolation(InterboltError):
+    """Raised when a guarded call is blocked by policy.
+
+    Attributes:
+        decision: The `Decision` that produced the block.
+    """
+
+    def __init__(self, message: str, *, decision: Decision) -> None:
+        super().__init__(message)
+        self.decision = decision
+
+
+class PolicyEvaluationError(InterboltError):
+    """Raised when policy evaluation itself fails.
+
+    Covers a malformed policy file at load time, and a CEL evaluation error
+    (missing argument, `None` value, non-marshalable value) under `enforce` mode
+    at call time.
+
+    Attributes:
+        decision: The partial `Decision`, if one was assembled before the error.
+            `None` for load-time failures, where no call context exists yet.
+    """
+
+    def __init__(self, message: str, *, decision: Decision | None = None) -> None:
+        super().__init__(message)
+        self.decision = decision
+
+
+class ApprovalDenied(InterboltError):
+    """Raised when a `require_approval` decision is denied by the approval resolver.
+
+    Attributes:
+        decision: The `Decision` that required approval.
+    """
+
+    def __init__(self, message: str, *, decision: Decision) -> None:
+        super().__init__(message)
+        self.decision = decision
+
+
+class InterboltConfigError(InterboltError, ValueError):
+    """Raised for an invalid configuration value.
+
+    Examples: an unrecognized `mode`, an out-of-range
+    `INTERBOLT_RECURSION_DEPTH`, a tool or namespace name containing a dot.
+    Subclasses `ValueError` as well as `InterboltError`, so callers can catch it
+    either as interbolt's own type or by its builtin semantics.
+    """
+
+
+class InterboltUsageError(InterboltError, RuntimeError):
+    """Raised when the public API is used out of sequence.
+
+    Example: calling `check()`/`guard` before `configure()` has run.
+    Subclasses `RuntimeError` as well as `InterboltError`, so callers can catch
+    it either as interbolt's own type or by its builtin semantics.
+    """

interbolt/models/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

interbolt/models/core.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from interbolt.errors import InterboltConfigError
+
+
+def validate_qualified_name_part(value: str, *, part: str) -> None:
+    """Reject a namespace or tool name that contains a dot.
+
+    The dotted `namespace.tool` form is the policy-key surface, so neither half
+    may itself contain a dot or the two forms become ambiguous to parse back apart.
+
+    Args:
+        value: The candidate namespace or tool name.
+        part: Which part this is, for the error message ("namespace" or "tool").
+
+    Raises:
+        InterboltConfigError: If `value` contains a dot.
+    """
+    if "." in value:
+        raise InterboltConfigError(f"{part} {value!r} may not contain a dot")
+
+
+class Mode(StrEnum):
+    """The enforcement mode: governs behavior on evaluation error.
+
+    Does not change a correct `block`/`require_approval` decision, except
+    under `DRY_RUN` where every decision is downgraded to allow.
+    """
+
+    ENFORCE = "enforce"
+    MONITOR = "monitor"
+    DRY_RUN = "dry_run"
+
+
+class TrustLevel(StrEnum):
+    """The result of resolving a source name against a policy's sources table."""
+
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+
+
+class Label(BaseModel):
+    """Provenance attached to a value: where it came from, never a resolved trust bit.
+
+    Attributes:
+        source: The originating source name. For a merged value, the first
+            contributing source (lineage carries the full set).
+        value_id: A unique id minted when this label was created or last
+            transformed, for the flow graph and audit trail.
+        lineage: The de-duplicated set of source names that contributed to this
+            value, in first-contributed order.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source: str
+    value_id: str
+    lineage: tuple[str, ...]
+
+
+class Action(StrEnum):
+    """The three possible policy decisions."""
+
+    ALLOW = "allow"
+    BLOCK = "block"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+class Decision(BaseModel):
+    """The outcome of evaluating a policy against a guarded call.
+
+    Attributes:
+        action: The decision taken.
+        matched_rule: The name of the first matching rule, or `None` if the
+            sink's default action was used.
+        tool: The qualified tool name the decision was made for.
+        contributing_labels: Every label collected from the call's arguments.
+        trifecta: The lethal-trifecta legs satisfied by this call. In v1 this
+            only ever contains `"from_untrusted"` or is empty; the
+            `reaches_external` and `reads_private` legs are not computed.
+        mode: The enforcement mode in effect when this decision was made.
+        decision_id: A unique id for this decision, for the audit trail.
+        agent_id: The durable, integrator-supplied agent identity.
+        run_id: The per-run identity.
+        session_id: The optional, integrator-supplied session identity.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    action: Action
+    matched_rule: str | None
+    tool: str
+    contributing_labels: tuple[Label, ...]
+    trifecta: frozenset[str]
+    mode: Mode
+    decision_id: str
+    agent_id: str
+    run_id: str
+    session_id: str | None
+
+
+class QualifiedName(BaseModel):
+    """A structured `(namespace, tool)` pair; `namespace.tool` is the surface form."""
+
+    model_config = ConfigDict(frozen=True)
+
+    namespace: str
+    tool: str
+
+    @field_validator("namespace")
+    @classmethod
+    def _validate_namespace(cls, value: str) -> str:
+        validate_qualified_name_part(value, part="namespace")
+        return value
+
+    @field_validator("tool")
+    @classmethod
+    def _validate_tool(cls, value: str) -> str:
+        validate_qualified_name_part(value, part="tool")
+        return value
+
+    def __str__(self) -> str:
+        return f"{self.namespace}.{self.tool}"
+
+
+class Event(BaseModel):
+    """The versioned, emitted record of a `Decision`."""
+
+    model_config = ConfigDict(frozen=True)
+
+    schema_version: int
+    decision: Decision
+    agent_id: str
+    run_id: str
+    session_id: str | None
+    sources: frozenset[str]
+    lineage: tuple[str, ...]
+    matched_rule: str | None
+    trifecta: frozenset[str]
+    mode: Mode
+    outcome: str
+    timestamp: datetime
+
+
+class Finding(BaseModel):
+    """A laundering-audit record: untrusted content reached a sink without a label."""
+
+    model_config = ConfigDict(frozen=True)
+
+    schema_version: int
+    source: str
+    tool: str
+    argument: str
+    agent_id: str
+    run_id: str
+    session_id: str | None
+    timestamp: datetime