agentcontainment 0.1.0__py3-none-any.whl

agent_containment/__init__.py

@@ -0,0 +1,31 @@
+from .bootstrap import BootstrapAdmissionError, require_controller_available
+from .control import ContainmentService, ManagedAgent, RecoveryAuthorization
+from .cgroup_enforcer import CgroupV2Enforcer
+from .cilium_enforcer import CiliumNetworkPolicyEnforcer
+from .egress import EgressController, EgressLease, hard_close_socket
+from .governance_event import GovernanceEvent
+from .enforcer import Enforcer, EnforcementResult, EnforcementStatus, NoopEnforcer
+from .gateway import ActionGateway
+from .incident_state import IncidentRecord, IncidentRegistry, IncidentState
+from .linux_supervisor import LinuxCgroupSupervisor
+from .models import Action, Decision, DecisionType
+from .policy import PolicyEngine
+from .provenance import InMemoryProvenanceSink, ProvenanceEmitter, ProvenanceRecord, ProvenanceSink, provenance_record
+from .regression import RegressionFixture, RegressionFixtureBuilder, assert_regression
+from .regression_replay import RegressionReplayResult, assert_fixture_replays, replay_fixture
+from .runtime_fence import FenceRecord, RuntimeFenceRegistry
+from .warden_observation import WardenObservation
+
+__all__ = [
+    "Action", "ActionGateway", "Decision", "DecisionType",
+    "BootstrapAdmissionError", "require_controller_available",
+    "ContainmentService", "ManagedAgent", "RecoveryAuthorization",
+    "IncidentRecord", "IncidentRegistry", "IncidentState", "GovernanceEvent",
+    "ProvenanceRecord", "ProvenanceSink", "ProvenanceEmitter", "InMemoryProvenanceSink", "provenance_record",
+    "RegressionFixture", "RegressionFixtureBuilder", "assert_regression",
+    "RegressionReplayResult", "replay_fixture", "assert_fixture_replays",
+    "EgressController", "EgressLease", "PolicyEngine", "hard_close_socket",
+    "LinuxCgroupSupervisor", "FenceRecord", "RuntimeFenceRegistry",
+    "Enforcer", "EnforcementResult", "EnforcementStatus", "NoopEnforcer",
+    "CgroupV2Enforcer", "CiliumNetworkPolicyEnforcer", "WardenObservation",
+]

agent_containment/agent_tree.py

@@ -0,0 +1,102 @@
+from dataclasses import dataclass, field
+from threading import RLock
+
+from .containment import CapabilitySet, ContainmentController
+from .runtime import Runtime
+
+
+@dataclass
+class AgentNode:
+    agent_id: str
+    parent_id: str | None
+    runtime: Runtime
+    containment: ContainmentController
+    children: set[str] = field(default_factory=set)
+
+
+class AgentTree:
+    """Tracks parent/child relationships with controller-owned spawn/containment serialization."""
+
+    def __init__(self):
+        self.nodes: dict[str, AgentNode] = {}
+        self._lock = RLock()
+
+    def register_root(
+        self,
+        agent_id: str,
+        capabilities: set[str] | None = None,
+    ) -> AgentNode:
+        with self._lock:
+            if agent_id in self.nodes:
+                raise ValueError(f"agent already registered: {agent_id}")
+            runtime = Runtime(agent_id)
+            controller = ContainmentController(
+                runtime,
+                CapabilitySet(set(capabilities or set())),
+            )
+            node = AgentNode(agent_id, None, runtime, controller)
+            self.nodes[agent_id] = node
+            return node
+
+    def spawn(
+        self,
+        parent_id: str,
+        child_id: str,
+        capabilities: set[str] | None = None,
+    ) -> AgentNode:
+        with self._lock:
+            if child_id in self.nodes:
+                raise ValueError(f"agent already registered: {child_id}")
+            parent = self._require(parent_id)
+
+            if not parent.runtime.can_execute or parent.containment.contained:
+                raise RuntimeError(f"parent agent cannot spawn children: {parent_id}")
+
+            inherited = set(parent.containment.capabilities.capabilities)
+            if capabilities is not None:
+                inherited &= set(capabilities)
+
+            runtime = Runtime(child_id)
+            controller = ContainmentController(
+                runtime,
+                CapabilitySet(inherited),
+            )
+            node = AgentNode(child_id, parent_id, runtime, controller)
+            self.nodes[child_id] = node
+            parent.children.add(child_id)
+            return node
+
+    def contain(self, agent_id: str) -> list[str]:
+        """Contain an agent and every descendant known at the containment fence."""
+        with self._lock:
+            root = self._require(agent_id)
+            contained: list[str] = []
+            stack = [root.agent_id]
+
+            while stack:
+                current_id = stack.pop()
+                current = self._require(current_id)
+                current.containment.contain()
+                contained.append(current_id)
+                stack.extend(sorted(current.children, reverse=True))
+
+            return contained
+
+    def descendants(self, agent_id: str) -> list[str]:
+        with self._lock:
+            self._require(agent_id)
+            result: list[str] = []
+            stack = list(self.nodes[agent_id].children)
+
+            while stack:
+                child_id = stack.pop()
+                result.append(child_id)
+                stack.extend(self.nodes[child_id].children)
+
+            return result
+
+    def _require(self, agent_id: str) -> AgentNode:
+        try:
+            return self.nodes[agent_id]
+        except KeyError as exc:
+            raise KeyError(f"unknown agent: {agent_id}") from exc

agent_containment/attack_harness.py

@@ -0,0 +1,44 @@
+"""Controlled adversarial harness for testing containment invariants.
+
+This module never executes real external commands, network calls, or destructive
+operations. It models an agent attempting to bypass the control plane.
+"""
+from dataclasses import dataclass, field
+from .models import Action, DecisionType
+from .gateway import ActionGateway
+from .containment import ContainmentController
+
+@dataclass
+class AttackAttempt:
+    name: str
+    action: Action
+
+@dataclass
+class AttackResult:
+    name: str
+    decision: DecisionType
+    blocked: bool
+    reason: str
+
+@dataclass
+class AttackHarness:
+    gateway: ActionGateway
+    containment: ContainmentController
+    results: list[AttackResult] = field(default_factory=list)
+
+    def attempt(self, attack: AttackAttempt) -> AttackResult:
+        decision = self.gateway.authorize(attack.action)
+        result = AttackResult(
+            name=attack.name,
+            decision=decision.decision,
+            blocked=decision.decision is not DecisionType.ALLOW,
+            reason=decision.reason,
+        )
+        self.results.append(result)
+        return result
+
+    def assert_contained(self) -> None:
+        failures = [r for r in self.results if not r.blocked]
+        if failures:
+            names = ", ".join(r.name for r in failures)
+            raise AssertionError(f"containment bypasses detected: {names}")

agent_containment/audit.py

@@ -0,0 +1,94 @@
+"""Controller-owned tamper-evident JSONL audit chain."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from threading import RLock
+from time import time
+from typing import Any
+
+GENESIS = "0" * 64
+
+
+def _canonical(value: dict[str, Any]) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+class AuditLog:
+    """Append-only hash chain.
+
+    The chain is tamper-evident, not externally immutable: an attacker who can
+    delete the file can remove history. Verification therefore fails closed
+    before appending to an already-corrupt chain.
+    """
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self._lock = RLock()
+
+    def record(self, event_type: str, *, agent_id: str, action_id: str | None = None,
+               decision: str | None = None, reason: str | None = None,
+               timestamp: float | None = None, **fields: Any) -> dict[str, Any]:
+        if not isinstance(event_type, str) or not event_type:
+            raise ValueError("event_type must be non-empty")
+        if not isinstance(agent_id, str) or not agent_id:
+            raise ValueError("agent_id must be non-empty")
+        with self._lock:
+            if self.path.exists():
+                ok, verification_reason = self.verify()
+                if not ok:
+                    raise RuntimeError(
+                        f"refusing to append to invalid audit chain: {verification_reason}"
+                    )
+                lines = [line for line in self.path.read_text(encoding="utf-8").splitlines() if line.strip()]
+            else:
+                lines = []
+
+            previous_hash = GENESIS
+            if lines:
+                previous_hash = json.loads(lines[-1])["hash"]
+
+            event: dict[str, Any] = {
+                "version": 1,
+                "sequence": 1 if not lines else len(lines) + 1,
+                "timestamp": time() if timestamp is None else timestamp,
+                "event_type": event_type,
+                "agent_id": agent_id,
+                "action_id": action_id,
+                "decision": decision,
+                "reason": reason,
+                "previous_hash": previous_hash,
+                **fields,
+            }
+            event["hash"] = hashlib.sha256(_canonical(event)).hexdigest()
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(event, sort_keys=True, separators=(",", ":"), ensure_ascii=False) + "\n")
+        return event
+
+    def verify(self) -> tuple[bool, str]:
+        with self._lock:
+            if not self.path.exists():
+                return True, "empty audit log"
+            expected_previous = GENESIS
+            expected_sequence = 1
+            try:
+                lines = self.path.read_text(encoding="utf-8").splitlines()
+                for line in lines:
+                    if not line.strip():
+                        continue
+                    event = json.loads(line)
+                    stored = event.pop("hash")
+                    if event.get("sequence") != expected_sequence:
+                        return False, f"sequence mismatch at {expected_sequence}"
+                    if event.get("previous_hash") != expected_previous:
+                        return False, f"previous hash mismatch at sequence {expected_sequence}"
+                    actual = hashlib.sha256(_canonical(event)).hexdigest()
+                    if stored != actual:
+                        return False, f"hash mismatch at sequence {expected_sequence}"
+                    expected_previous = stored
+                    expected_sequence += 1
+            except (OSError, json.JSONDecodeError, KeyError, TypeError):
+                return False, "malformed audit log"
+            return True, "audit chain valid"

agent_containment/blast_radius.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+
+@dataclass
+class ResourceGraph:
+    touched: set[str] = field(default_factory=set)
+    modified: set[str] = field(default_factory=set)
+    external: set[str] = field(default_factory=set)
+
+    def record(self, resource: str, *, modified: bool = False, external: bool = False) -> None:
+        self.touched.add(resource)
+        if modified:
+            self.modified.add(resource)
+        if external:
+            self.external.add(resource)
+
+    def summary(self) -> dict[str, int]:
+        return {"touched": len(self.touched), "modified": len(self.modified), "external": len(self.external)}

agent_containment/bootstrap.py

@@ -0,0 +1,33 @@
+"""Controller-owned bootstrap admission checks.
+
+This module is a pre-admission guard for trusted launchers. It is intentionally
+not an authorization API: the agent must not be able to choose or bypass the
+launcher that invokes it. Production admission should be enforced by the host
+service manager or container runtime before the agent workload is started.
+"""
+from __future__ import annotations
+
+import socket
+from pathlib import Path
+
+
+class BootstrapAdmissionError(RuntimeError):
+    """Raised when controller availability cannot be established."""
+
+
+def require_controller_available(
+    socket_path: str | Path, *, timeout: float = 1.0
+) -> None:
+    """Require a live controller IPC endpoint before admitting a workload."""
+    path = Path(socket_path)
+    if not path.exists():
+        raise BootstrapAdmissionError("controller socket is unavailable")
+
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.settimeout(timeout)
+            client.connect(str(path))
+    except OSError as exc:
+        raise BootstrapAdmissionError(
+            "controller endpoint is unavailable"
+        ) from exc

agent_containment/cgroup_enforcer.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from .enforcer import EnforcementResult, EnforcementStatus
+from .linux_supervisor import LinuxCgroupSupervisor
+
+
+@dataclass(frozen=True)
+class _CgroupIdentity:
+    device: int
+    inode: int
+    ctime_ns: int
+
+
+class CgroupV2Enforcer:
+    """Adapt a dedicated, identity-bound cgroup v2 workload boundary to Enforcer."""
+
+    name = "cgroup-v2"
+
+    def __init__(self, cgroup_paths: Mapping[str, str | os.PathLike[str]]):
+        self._cgroup_paths = {
+            agent_id: Path(path) for agent_id, path in cgroup_paths.items()
+        }
+        self._identities = {
+            agent_id: self._identity(path)
+            for agent_id, path in self._cgroup_paths.items()
+        }
+
+    @staticmethod
+    def _identity(path: Path) -> _CgroupIdentity:
+        stat = path.stat()
+        if not path.is_dir():
+            raise ValueError(f"cgroup path is not a directory: {path}")
+        return _CgroupIdentity(stat.st_dev, stat.st_ino, stat.st_ctime_ns)
+
+    def _path(self, agent_id: str) -> Path | None:
+        return self._cgroup_paths.get(agent_id)
+
+    def _missing(self, agent_id: str) -> EnforcementResult:
+        return EnforcementResult(
+            self.name,
+            EnforcementStatus.NOT_CONFIGURED,
+            f"no cgroup configured for agent {agent_id}",
+        )
+
+    def _verify_identity(self, agent_id: str, path: Path) -> EnforcementResult | None:
+        expected = self._identities[agent_id]
+        try:
+            actual = self._identity(path)
+        except (OSError, ValueError) as exc:
+            return EnforcementResult(
+                self.name,
+                EnforcementStatus.VERIFICATION_FAILED,
+                f"cgroup identity unavailable: {type(exc).__name__}: {exc}",
+            )
+        if actual != expected:
+            return EnforcementResult(
+                self.name,
+                EnforcementStatus.VERIFICATION_FAILED,
+                f"cgroup identity changed for {agent_id}",
+            )
+        # A directory with the right filesystem identity is not sufficient:
+        # require the kernel cgroup v2 control files before trusting its state.
+        for control in ("cgroup.events", "cgroup.kill"):
+            if not (path / control).is_file():
+                return EnforcementResult(
+                    self.name,
+                    EnforcementStatus.VERIFICATION_FAILED,
+                    f"required cgroup control file is missing: {control}",
+                )
+        return None
+
+    def contain(self, agent_id: str) -> EnforcementResult:
+        path = self._path(agent_id)
+        if path is None:
+            return self._missing(agent_id)
+        try:
+            identity_failure = self._verify_identity(agent_id, path)
+            if identity_failure:
+                return identity_failure
+            LinuxCgroupSupervisor.contain(path)
+            return EnforcementResult(self.name, EnforcementStatus.ENFORCED)
+        except Exception as exc:
+            return EnforcementResult(
+                self.name, EnforcementStatus.DEGRADED, f"{type(exc).__name__}: {exc}"
+            )
+
+    def verify_contained(self, agent_id: str) -> EnforcementResult:
+        path = self._path(agent_id)
+        if path is None:
+            return self._missing(agent_id)
+        try:
+            identity_failure = self._verify_identity(agent_id, path)
+            if identity_failure:
+                return identity_failure
+            if LinuxCgroupSupervisor.is_populated(path):
+                return EnforcementResult(
+                    self.name,
+                    EnforcementStatus.VERIFICATION_FAILED,
+                    f"cgroup remains populated for {agent_id}",
+                )
+            return EnforcementResult(self.name, EnforcementStatus.ENFORCED)
+        except Exception as exc:
+            return EnforcementResult(
+                self.name,
+                EnforcementStatus.VERIFICATION_FAILED,
+                f"{type(exc).__name__}: {exc}",
+            )
+
+    def release(self, agent_id: str) -> EnforcementResult:
+        path = self._path(agent_id)
+        if path is None:
+            return self._missing(agent_id)
+        try:
+            identity_failure = self._verify_identity(agent_id, path)
+            if identity_failure:
+                return identity_failure
+            if LinuxCgroupSupervisor.is_populated(path):
+                return EnforcementResult(
+                    self.name,
+                    EnforcementStatus.DEGRADED,
+                    f"cgroup remains populated for {agent_id}",
+                )
+            return EnforcementResult(self.name, EnforcementStatus.RELEASED)
+        except Exception as exc:
+            return EnforcementResult(
+                self.name, EnforcementStatus.DEGRADED, f"{type(exc).__name__}: {exc}"
+            )
+
+    def verify_released(self, agent_id: str) -> EnforcementResult:
+        path = self._path(agent_id)
+        if path is None:
+            return self._missing(agent_id)
+        try:
+            identity_failure = self._verify_identity(agent_id, path)
+            if identity_failure:
+                return identity_failure
+            if LinuxCgroupSupervisor.is_populated(path):
+                return EnforcementResult(
+                    self.name,
+                    EnforcementStatus.VERIFICATION_FAILED,
+                    f"cgroup is unexpectedly populated for {agent_id}",
+                )
+            return EnforcementResult(self.name, EnforcementStatus.RELEASED)
+        except Exception as exc:
+            return EnforcementResult(
+                self.name,
+                EnforcementStatus.VERIFICATION_FAILED,
+                f"{type(exc).__name__}: {exc}",
+            )