aetherruntime-arch 2.0.0__py3-none-any.whl

aetherruntime/containment/isolation.py

@@ -0,0 +1,253 @@
+"""
+AetherRuntime v2.0.0 — Containment: Isolation (Layer 3)
+
+This module implements the isolation mechanisms for containment.
+While `policy.py` defines the containment policy (what to restrict),
+this module enforces it (how to restrict).
+
+Key properties:
+    - Isolation is reversible (X5).
+    - Isolation preserves forensic evidence (no data destruction).
+    - Isolation applies resource limits per level.
+
+Invariants enforced:
+    - X5: containment is reversible
+    - I13: restrictions are applied correctly
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..models import (
+    Agent,
+    AgentStatus,
+    ContainmentLevel,
+    ContainmentPolicy,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Isolation state
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+@dataclass
+class IsolationState:
+    """
+    The current isolation state of an agent.
+
+    Fields:
+        - agent_id: The isolated agent.
+        - level: The current containment level.
+        - restrictions: The active restrictions.
+        - applied_at: When isolation was applied.
+        - released_at: When isolation was released (None if active).
+    """
+    agent_id: str
+    level: ContainmentLevel
+    restrictions: dict
+    applied_at: str
+    released_at: Optional[str] = None
+
+    @property
+    def is_active(self) -> bool:
+        """Check if isolation is currently active."""
+        return self.released_at is None
+
+    def to_dict(self) -> dict:
+        """Serialize to dict."""
+        return {
+            "agent_id": self.agent_id,
+            "level": self.level.value,
+            "restrictions": self.restrictions,
+            "applied_at": self.applied_at,
+            "released_at": self.released_at,
+            "is_active": self.is_active,
+        }
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Isolation manager
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class IsolationManager:
+    """
+    Manages the isolation state of agents.
+
+    Applies containment policies by:
+        1. Recording the isolation state.
+        2. Enforcing resource restrictions (in simulation: tracked only).
+        3. Providing query methods for the current state.
+    """
+
+    def __init__(self) -> None:
+        self._states: dict[str, IsolationState] = {}
+        self._history: list[IsolationState] = []
+
+    def apply(self, policy: ContainmentPolicy) -> IsolationState:
+        """
+        Apply a containment policy (enforce isolation).
+
+        Args:
+            policy: The ContainmentPolicy to apply.
+
+        Returns:
+            The IsolationState after application.
+        """
+        if policy.agent_id in self._states and self._states[policy.agent_id].is_active:
+            raise ValueError(
+                f"Agent {policy.agent_id} already isolated at "
+                f"{self._states[policy.agent_id].level.value}"
+            )
+
+        state = IsolationState(
+            agent_id=policy.agent_id,
+            level=policy.level,
+            restrictions=dict(policy.restrictions),
+            applied_at=datetime.now(timezone.utc).isoformat(),
+        )
+        self._states[policy.agent_id] = state
+        self._history.append(state)
+        return state
+
+    def release(self, agent_id: str) -> Optional[IsolationState]:
+        """
+        Release an agent from isolation.
+
+        Args:
+            agent_id: The agent to release.
+
+        Returns:
+            The IsolationState after release, or None if not isolated.
+        """
+        state = self._states.get(agent_id)
+        if state is None or not state.is_active:
+            return None
+        state.released_at = datetime.now(timezone.utc).isoformat()
+        self._history.append(state)
+        return state
+
+    def get(self, agent_id: str) -> Optional[IsolationState]:
+        """Get the current isolation state for an agent."""
+        return self._states.get(agent_id)
+
+    def is_isolated(self, agent_id: str) -> bool:
+        """Check if an agent is currently isolated."""
+        state = self._states.get(agent_id)
+        return state is not None and state.is_active
+
+    def active_agents(self) -> list[str]:
+        """Get all currently isolated agent IDs."""
+        return [aid for aid, st in self._states.items() if st.is_active]
+
+    def history(self) -> list[IsolationState]:
+        """Get the full history of isolation states."""
+        return list(self._history)
+
+    def count_active(self) -> int:
+        """Count currently isolated agents."""
+        return len(self.active_agents())
+
+    def clear(self) -> None:
+        """Clear all isolation states."""
+        self._states.clear()
+        self._history.clear()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Resource enforcement (simulated)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+@dataclass
+class ResourceSnapshot:
+    """A snapshot of an agent's resource usage (for enforcement)."""
+    cpu_percent: float
+    memory_mb: float
+    network_requests: int = 0
+    filesystem_writes: int = 0
+
+
+def enforce_restrictions(
+    usage: ResourceSnapshot,
+    restrictions: dict,
+) -> tuple[ResourceSnapshot, list[str]]:
+    """
+    Enforce resource restrictions on a snapshot.
+
+    Args:
+        usage: The agent's current resource usage.
+        restrictions: The containment restrictions.
+
+    Returns:
+        (adjusted_usage, violations):
+            - adjusted_usage: The usage after applying restrictions.
+            - violations: List of violations (empty if none).
+    """
+    adjusted = ResourceSnapshot(
+        cpu_percent=usage.cpu_percent,
+        memory_mb=usage.memory_mb,
+        network_requests=usage.network_requests,
+        filesystem_writes=usage.filesystem_writes,
+    )
+    violations: list[str] = []
+
+    # CPU limit
+    cpu_limit = restrictions.get("cpu_percent")
+    if cpu_limit is not None and adjusted.cpu_percent > cpu_limit:
+        violations.append(
+            f"CPU {adjusted.cpu_percent:.1f}% > {cpu_limit}%"
+        )
+        adjusted.cpu_percent = cpu_limit
+
+    # Memory limit
+    mem_limit = restrictions.get("memory_mb")
+    if mem_limit is not None and adjusted.memory_mb > mem_limit:
+        violations.append(
+            f"Memory {adjusted.memory_mb:.0f}MB > {mem_limit}MB"
+        )
+        adjusted.memory_mb = mem_limit
+
+    # Network restriction
+    net_policy = restrictions.get("network")
+    if net_policy == "deny" and adjusted.network_requests > 0:
+        violations.append(
+            f"Network denied, {adjusted.network_requests} requests blocked"
+        )
+        adjusted.network_requests = 0
+
+    # Filesystem restriction
+    fs_policy = restrictions.get("filesystem")
+    if fs_policy in ("read-only", "sandboxed", "frozen"):
+        if adjusted.filesystem_writes > 0:
+            violations.append(
+                f"Filesystem {fs_policy}, {adjusted.filesystem_writes} writes blocked"
+            )
+            adjusted.filesystem_writes = 0
+
+    return adjusted, violations
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Convenience functions
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def apply_isolation(
+    manager: IsolationManager,
+    policy: ContainmentPolicy,
+) -> IsolationState:
+    """Convenience wrapper: apply isolation via manager."""
+    return manager.apply(policy)
+
+
+def release_isolation(
+    manager: IsolationManager,
+    agent_id: str,
+) -> Optional[IsolationState]:
+    """Convenience wrapper: release isolation via manager."""
+    return manager.release(agent_id)

aetherruntime/containment/policy.py

@@ -0,0 +1,273 @@
+"""
+AetherRuntime v2.0.0 — Containment: Policy (Layer 3)
+
+This module implements Operation 4 (`contain`) from
+docs/specification/02_operations.md.
+
+The `contain` operation applies a containment policy to an anomalous agent,
+restricting its resources without destroying forensic evidence.
+
+Invariants enforced:
+    - I11: level is one of four defined levels
+    - I12: expiry > created_at
+    - I13: restrictions contains all required keys for level
+    - I31: policy references existing AnomalyAlert
+
+Errors:
+    - E11: AlertNotFound
+    - E12: InvalidLevel
+    - E13: ExpiryInPast
+    - E14: AlreadyContained
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from ..models import (
+    Agent,
+    AgentStatus,
+    AnomalyAlert,
+    ContainmentLevel,
+    ContainmentPolicy,
+    _now_iso,
+    _random_hex,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Errors
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class AlertNotFound(Exception):
+    """E11: Alert does not exist."""
+    pass
+
+
+class InvalidLevel(Exception):
+    """E12: level not in {L1, L2, L3, L4}."""
+    pass
+
+
+class ExpiryInPast(Exception):
+    """E13: expiry <= created_at."""
+    pass
+
+
+class AlreadyContained(Exception):
+    """E14: Agent already contained at higher level."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Default restrictions for each level (I13)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+DEFAULT_RESTRICTIONS: dict[ContainmentLevel, dict] = {
+    ContainmentLevel.L1_THROTTLE: {
+        "cpu_percent": 10.0,
+        "memory_mb": 512,
+        "network": "allow",
+        "filesystem": "read-write",
+    },
+    ContainmentLevel.L2_ISOLATE: {
+        "cpu_percent": 10.0,
+        "memory_mb": 256,
+        "network": "deny",
+        "filesystem": "read-only",
+    },
+    ContainmentLevel.L3_QUARANTINE: {
+        "cpu_percent": 5.0,
+        "memory_mb": 128,
+        "network": "deny",
+        "filesystem": "sandboxed",
+    },
+    ContainmentLevel.L4_FREEZE: {
+        "cpu_percent": 0.0,
+        "memory_mb": 0,
+        "network": "deny",
+        "filesystem": "frozen",
+    },
+}
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Operation 4 — contain
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def contain(
+    agent: Agent,
+    alert: AnomalyAlert,
+    level: ContainmentLevel,
+    expiry_seconds: int = 300,
+    restrictions: Optional[dict] = None,
+    existing_policy: Optional[ContainmentPolicy] = None,
+) -> ContainmentPolicy:
+    """
+    Apply a containment policy to an anomalous agent (Operation 4).
+
+    Args:
+        agent: The agent to contain.
+        alert: The AnomalyAlert that triggered containment.
+        level: Containment level (L1, L2, L3, L4).
+        expiry_seconds: How long containment lasts (default 300 = 5 min).
+        restrictions: Optional custom restrictions. Defaults to DEFAULT_RESTRICTIONS[level].
+        existing_policy: Optional existing policy (for re-containment).
+
+    Returns:
+        A new ContainmentPolicy.
+
+    Raises:
+        AlertNotFound: If alert is None.
+        InvalidLevel: If level is not a valid ContainmentLevel.
+        ExpiryInPast: If expiry <= created_at.
+        AlreadyContained: If agent is already contained at same/higher level.
+
+    Invariants:
+        I11: level is valid.
+        I12: expiry > created_at.
+        I13: restrictions contains all required keys.
+        I31: policy references existing alert.
+
+    Example:
+        >>> policy = contain(agent, alert, ContainmentLevel.L2_ISOLATE)
+        >>> policy.level
+        <ContainmentLevel.L2_ISOLATE: 'L2_isolate'>
+    """
+    # ─── E11: Alert must exist ───
+    if alert is None:
+        raise AlertNotFound("alert must not be None")
+
+    # ─── E12: Level must be valid (I11) ───
+    if not isinstance(level, ContainmentLevel):
+        raise InvalidLevel(f"level must be ContainmentLevel, got {type(level)}")
+
+    # ─── E14: Agent not already contained at higher level ───
+    if agent.status == AgentStatus.CONTAINED and existing_policy is not None:
+        if _level_rank(level) <= _level_rank(existing_policy.level):
+            raise AlreadyContained(
+                f"Agent {agent.agent_id} already contained at "
+                f"{existing_policy.level.value} (>= {level.value})"
+            )
+
+    # ─── I12: expiry > created_at ───
+    now = datetime.now(timezone.utc)
+    created_at = now.isoformat()
+    expiry_dt = now + timedelta(seconds=expiry_seconds)
+    expiry = expiry_dt.isoformat()
+
+    if expiry_dt <= now:
+        raise ExpiryInPast(f"expiry must be > created_at")
+
+    # ─── I13: restrictions contains required keys ───
+    if restrictions is None:
+        restrictions = dict(DEFAULT_RESTRICTIONS[level])
+    required = {"cpu_percent", "memory_mb", "network", "filesystem"}
+    missing = required - set(restrictions.keys())
+    if missing:
+        raise ValueError(f"restrictions missing keys: {missing}")
+
+    # ─── Q1: Create ContainmentPolicy ───
+    policy = ContainmentPolicy(
+        policy_id=_random_hex(),
+        agent_id=agent.agent_id,
+        alert_id=alert.alert_id,
+        level=level,
+        restrictions=restrictions,
+        expiry=expiry,
+        created_at=created_at,
+    )
+
+    # ─── Q3: Update agent status ───
+    agent.status = AgentStatus.CONTAINED
+
+    return policy
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def _level_rank(level: ContainmentLevel) -> int:
+    """Return a numeric rank for a containment level (higher = stricter)."""
+    ranks = {
+        ContainmentLevel.L1_THROTTLE: 1,
+        ContainmentLevel.L2_ISOLATE: 2,
+        ContainmentLevel.L3_QUARANTINE: 3,
+        ContainmentLevel.L4_FREEZE: 4,
+    }
+    return ranks[level]
+
+
+def release(
+    agent: Agent,
+    policy: ContainmentPolicy,
+) -> None:
+    """
+    Release an agent from containment (reversal).
+
+    Args:
+        agent: The agent to release.
+        policy: The policy to release.
+
+    Invariants:
+        - X5: Containment policy is reversible.
+    """
+    if agent.agent_id != policy.agent_id:
+        raise ValueError(
+            f"agent {agent.agent_id} does not match policy agent {policy.agent_id}"
+        )
+    agent.status = AgentStatus.RUNNING
+
+
+def is_expired(policy: ContainmentPolicy) -> bool:
+    """Check if a containment policy has expired."""
+    now = datetime.now(timezone.utc)
+    expiry_dt = datetime.fromisoformat(policy.expiry.replace("Z", "+00:00"))
+    return now >= expiry_dt
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Containment registry
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class ContainmentRegistry:
+    """An in-memory registry of containment policies."""
+
+    def __init__(self) -> None:
+        self._policies: dict[str, ContainmentPolicy] = {}
+        self._by_agent: dict[str, list[ContainmentPolicy]] = {}
+
+    def put(self, policy: ContainmentPolicy) -> None:
+        """Register a containment policy."""
+        if policy.policy_id in self._policies:
+            raise ValueError(f"policy_id {policy.policy_id} already registered")
+        self._policies[policy.policy_id] = policy
+        self._by_agent.setdefault(policy.agent_id, []).append(policy)
+
+    def get(self, policy_id: str) -> Optional[ContainmentPolicy]:
+        """Get a policy by ID."""
+        return self._policies.get(policy_id)
+
+    def get_by_agent(self, agent_id: str) -> list[ContainmentPolicy]:
+        """Get all policies for an agent."""
+        return list(self._by_agent.get(agent_id, []))
+
+    def active_for_agent(self, agent_id: str) -> list[ContainmentPolicy]:
+        """Get all active (non-expired) policies for an agent."""
+        return [p for p in self.get_by_agent(agent_id) if not is_expired(p)]
+
+    def count(self) -> int:
+        """Count all policies."""
+        return len(self._policies)
+
+    def clear(self) -> None:
+        """Clear all policies."""
+        self._policies.clear()
+        self._by_agent.clear()

aetherruntime/detection/__init__.py

@@ -0,0 +1,35 @@
+"""AetherRuntime — Detection layer (Layer 2)."""
+
+from .classifier import (
+    detect,
+    detect_batch,
+    summarize_detection,
+    DetectionSummary,
+    TelemetryNotFound,
+    BaselineNotFound,
+    NonDeterministic,
+)
+from .alert import (
+    AlertRegistry,
+    AlertStats,
+    validate_alert_against_telemetry,
+    filter_alerts_by_confidence,
+    group_alerts_by_agent,
+    latest_alert_for_agent,
+)
+
+__all__ = [
+    "detect",
+    "detect_batch",
+    "summarize_detection",
+    "DetectionSummary",
+    "TelemetryNotFound",
+    "BaselineNotFound",
+    "NonDeterministic",
+    "AlertRegistry",
+    "AlertStats",
+    "validate_alert_against_telemetry",
+    "filter_alerts_by_confidence",
+    "group_alerts_by_agent",
+    "latest_alert_for_agent",
+]