pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/sandbox/network.py

@@ -0,0 +1,205 @@
+"""Network policy and isolation engine for Pulse sandbox execution.
+
+Implements backend-independent network security controls including DNS
+rebinding protection, proxy configuration, and connection allowlisting.
+
+Security architecture:
+    - Default policy is DENY_ALL.
+    - ALLOWLIST dynamically resolves hostnames to prevent DNS rebinding
+      to internal/private IPs.
+    - PROXY mode securely isolates credentials from direct container exposure.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import ipaddress
+import socket
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class NetworkMode(str, Enum):
+    """Execution network isolation modes."""
+    DENY_ALL = "deny_all"
+    LOCALHOST_ONLY = "localhost_only"
+    ALLOWLIST = "allowlist"
+    PROXY = "proxy"
+    ALLOW_ALL = "allow_all"
+
+
+class NetworkEnforcementLevel(str, Enum):
+    """Strength of network enforcement provided by a backend.
+    
+    Security: Only STRONGLY_ENFORCED is accepted by the Sandbox API for strict modes.
+    ADVISORY is rejected to prevent silent downgrades of security policies.
+    """
+    STRONGLY_ENFORCED = "strongly_enforced"
+    PARTIALLY_ENFORCED = "partially_enforced"
+    ADVISORY = "advisory"
+    UNSUPPORTED = "unsupported"
+
+
+class Protocol(str, Enum):
+    """Network protocols."""
+    TCP = "tcp"
+    UDP = "udp"
+    ANY = "any"
+
+
+@dataclass(frozen=True, slots=True)
+class NetworkRule:
+    """A rule defining an allowed network destination."""
+    
+    destination: str  # Can be an IP, a hostname, or a wildcard domain (e.g. *.example.com)
+    port: int | None = None  # None means any port
+    protocol: Protocol = Protocol.ANY
+    
+    def matches(self, host: str, port: int, protocol: Protocol) -> bool:
+        """Check if a specific request matches this rule."""
+        if self.port is not None and self.port != port:
+            return False
+        if self.protocol != Protocol.ANY and self.protocol != protocol:
+            return False
+            
+        # Exact match or IP match
+        if self.destination.lower() == host.lower():
+            return True
+            
+        # Wildcard domain match (e.g. *.example.com)
+        return fnmatch.fnmatch(host.lower(), self.destination.lower())
+
+
+@dataclass(frozen=True, slots=True)
+class NetworkPolicy:
+    """Backend-independent network security policy.
+    
+    Security architecture:
+        - Mode defaults to DENY_ALL.
+        - Rules only apply if mode is ALLOWLIST.
+        - Proxy URL is used if mode is PROXY.
+    """
+    
+    mode: NetworkMode = NetworkMode.DENY_ALL
+    rules: list[NetworkRule] = field(default_factory=list)
+    proxy_url: str | None = None
+    
+    def is_safe_ip(self, ip_str: str) -> bool:
+        """Determine if an IP address is a safe external address.
+        
+        Security: Protects against SSRF and DNS rebinding by explicitly
+        blocking RFC1918 private addresses, loopback, link-local, and multicast
+        from being accessed when a domain resolves to them.
+        """
+        try:
+            ip = ipaddress.ip_address(ip_str)
+        except ValueError:
+            return False
+            
+        # Explicitly block internal/private ranges
+        if ip.is_loopback:
+            return False
+        if ip.is_private:
+            return False
+        if ip.is_link_local:
+            return False
+        return not ip.is_multicast
+
+    def validate_destination(self, host: str, port: int, protocol: Protocol = Protocol.TCP) -> bool:
+        """Validate an outbound connection attempt against the policy.
+        
+        This is primarily used by backends that can intercept connections
+        or by API layers wrapping specific network requests.
+        """
+        if self.mode == NetworkMode.DENY_ALL:
+            return False
+            
+        if self.mode == NetworkMode.LOCALHOST_ONLY:
+            try:
+                ip = ipaddress.ip_address(host)
+                return ip.is_loopback
+            except ValueError:
+                return host.lower() == "localhost"
+                
+        if self.mode == NetworkMode.PROXY:
+            # In proxy mode, direct connections are denied; they must go through the proxy URL.
+            # This validation returns False for direct requests unless it's the proxy itself.
+            return False
+            
+        if self.mode == NetworkMode.ALLOWLIST:
+            rule_matched = False
+            for rule in self.rules:
+                if rule.matches(host, port, protocol):
+                    rule_matched = True
+                    break
+                    
+            if not rule_matched:
+                return False
+                
+            # DNS Rebinding Protection:
+            # If the host is a hostname (not a raw IP), we must resolve it locally
+            # and verify it does not resolve to an internal/private IP.
+            try:
+                ipaddress.ip_address(host)
+                # It's already a raw IP, and it was in the allowlist.
+                return True
+            except ValueError:
+                pass
+                
+            try:
+                # Resolve hostname
+                # Use getaddrinfo to handle both IPv4 and IPv6
+                addr_info = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+                for family, type, proto, canonname, sockaddr in addr_info:
+                    ip_str = sockaddr[0]
+                    if not self.is_safe_ip(ip_str):
+                        return False  # Deny if ANY resolved IP is private/unsafe
+                return True
+            except socket.gaierror:
+                # If we can't resolve it, fail closed.
+                return False
+                
+        return False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> NetworkPolicy:
+        mode_str = str(data.get("mode", "deny_all")).lower()
+        try:
+            mode = NetworkMode(mode_str)
+        except ValueError:
+            mode = NetworkMode.DENY_ALL
+            
+        rules = []
+        for raw_rule in data.get("rules", []):
+            try:
+                protocol_str = str(raw_rule.get("protocol", "any")).lower()
+                rules.append(
+                    NetworkRule(
+                        destination=str(raw_rule.get("destination")),
+                        port=int(raw_rule["port"]) if raw_rule.get("port") is not None else None,
+                        protocol=Protocol(protocol_str),
+                    )
+                )
+            except (ValueError, KeyError):
+                continue
+                
+        return cls(
+            mode=mode,
+            rules=rules,
+            proxy_url=data.get("proxy_url")
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "mode": self.mode.value,
+            "rules": [
+                {
+                    "destination": r.destination,
+                    "port": r.port,
+                    "protocol": r.protocol.value,
+                }
+                for r in self.rules
+            ],
+            "proxy_url": self.proxy_url,
+        }

pulse/sandbox/path_validator.py

@@ -0,0 +1,280 @@
+"""Path validation, TOCTOU-safe file access, and workspace boundary isolation.
+
+Prevents path traversal, symlink loops, symlink escapes, and unauthorized access
+outside configured workspace boundaries.
+
+Security hardening (TOCTOU + Memory Exhaustion):
+    - safe_open() atomically validates and opens file descriptors.
+    - O_NOFOLLOW used on POSIX to prevent symlink following.
+    - Post-open fstat() re-validates the resolved path matches expectations.
+    - MAX_FILE_SIZE enforced before reading to prevent OOM attacks.
+    - safe_read() returns content with enforced size limits.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path, PureWindowsPath
+
+from pulse.sandbox.errors import SandboxResourceError, SandboxSecurityError
+
+# Maximum file size that can be read through the sandbox (50 MB)
+MAX_FILE_SIZE: int = 50 * 1024 * 1024
+
+
+class PathValidationError(ValueError):
+    """Raised when a path violates security boundaries."""
+
+    def __init__(self, message: str, path: str | Path, reason: str) -> None:
+        super().__init__(f"{message}: {path} ({reason})")
+        self.path = str(path)
+        self.reason = reason
+
+
+class PathValidator:
+    """Security boundary validator for workspace filesystem access.
+
+    Provides TOCTOU-safe file operations that atomically validate and open
+    file descriptors, preventing race condition exploits.
+    """
+
+    def __init__(
+        self,
+        workspace_root: Path,
+        allowed_external_reads: list[Path] | None = None,
+        max_file_size: int = MAX_FILE_SIZE,
+    ) -> None:
+        self.workspace_root = workspace_root.resolve()
+        self.allowed_external_reads = [p.resolve() for p in (allowed_external_reads or [])]
+        self.max_file_size = max_file_size
+
+    def validate_path(
+        self,
+        path: str | Path,
+        *,
+        allow_read_only_external: bool = False,
+        must_exist: bool = False,
+    ) -> Path:
+        """Resolve and validate that a path is strictly inside workspace boundaries.
+
+        Args:
+            path: Relative or absolute path to validate.
+            allow_read_only_external: Whether to allow access to configured external read paths.
+            must_exist: If True, raises PathValidationError if target path does not exist.
+
+        Returns:
+            Resolved canonical Path object.
+
+        Raises:
+            PathValidationError: If path escapes workspace or violates symlink rules.
+        """
+        raw_value = os.fspath(path)
+        windows_path = PureWindowsPath(raw_value)
+        if sys.platform != "win32" and (
+            windows_path.is_absolute()
+            or windows_path.drive
+            or ".." in windows_path.parts
+        ):
+            raise PathValidationError(
+                "Path is outside workspace boundary",
+                path,
+                "Windows absolute, UNC, or traversal path is forbidden",
+            )
+        raw_path = Path(raw_value)
+
+        # 1. Resolve path candidate relative to workspace root if relative
+        if not raw_path.is_absolute():
+            candidate = (self.workspace_root / raw_path)
+        else:
+            candidate = raw_path
+
+        # 2. Check symlink loops and resolve target
+        try:
+            resolved = candidate.resolve()
+        except RuntimeError as err:
+            raise PathValidationError("Symlink resolution failed", path, "Possible symlink loop") from err
+
+        if must_exist and not resolved.exists():
+            raise PathValidationError("Path does not exist", path, "Target path missing")
+
+        # 3. Verify workspace root containment
+        if self._is_contained_in(resolved, self.workspace_root):
+            return resolved
+
+        # 4. Check allowed external read paths if permitted
+        if allow_read_only_external:
+            for ext_path in self.allowed_external_reads:
+                if self._is_contained_in(resolved, ext_path):
+                    return resolved
+
+        raise PathValidationError("Path is outside workspace boundary", path, f"Resolved to {resolved}")
+
+    def is_inside_workspace(self, path: str | Path) -> bool:
+        """Return True if path resolves inside workspace_root."""
+        try:
+            self.validate_path(path, allow_read_only_external=False, must_exist=False)
+            return True
+        except PathValidationError:
+            return False
+
+    def assert_inside_workspace(self, path: str | Path) -> Path:
+        """Convenience assertion method returning resolved Path or raising PathValidationError."""
+        return self.validate_path(path, allow_read_only_external=False, must_exist=False)
+
+    def safe_open(self, path: str | Path, *, for_write: bool = False) -> int:
+        """Atomically validate and open a file descriptor, preventing TOCTOU races.
+
+        Security guarantees:
+            1. Path is validated inside workspace BEFORE opening.
+            2. On POSIX, O_NOFOLLOW prevents following symlinks at the final component.
+            3. After open, fstat() verifies the file is a regular file.
+            4. File size is checked against max_file_size before returning.
+
+        Args:
+            path: Relative or absolute path to open.
+            for_write: If True, open for writing (O_WRONLY | O_CREAT).
+
+        Returns:
+            Raw file descriptor (caller is responsible for os.close()).
+
+        Raises:
+            PathValidationError: If path escapes workspace.
+            SandboxSecurityError: If symlink detected at open time, or file is not regular.
+            SandboxResourceError: If file exceeds max_file_size.
+        """
+        resolved = self.assert_inside_workspace(path)
+
+        # Build open flags
+        flags = os.O_RDONLY
+        if for_write:
+            flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+
+        # On POSIX, add O_NOFOLLOW to prevent symlink following at the final path component.
+        # This closes the TOCTOU gap between validate_path() and the actual open().
+        is_windows = sys.platform == "win32"
+        if not is_windows and hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+
+        # Windows TOCTOU mitigation: lstat before open, fstat after open
+        pre_stat = None
+        if is_windows:
+            try:
+                pre_stat = os.lstat(str(resolved))
+                if stat.S_ISLNK(pre_stat.st_mode):
+                    raise SandboxSecurityError(
+                        "Symlink detected during safe_open (pre-stat) — possible TOCTOU attack",
+                        operation="safe_open",
+                        path=str(path),
+                    )
+            except FileNotFoundError:
+                # File doesn't exist yet, which is fine if for_write is True
+                if not for_write:
+                    raise
+
+        try:
+            fd = os.open(str(resolved), flags, 0o644)
+        except OSError as err:
+            if err.errno == 40:  # ELOOP — symlink detected with O_NOFOLLOW
+                raise SandboxSecurityError(
+                    "Symlink detected during safe_open — possible TOCTOU attack",
+                    operation="safe_open",
+                    path=str(path),
+                ) from err
+            raise
+
+        try:
+            # Post-open validation: verify file descriptor points to a regular file
+            file_stat = os.fstat(fd)
+            
+            # Windows TOCTOU mitigation: verify st_ino and st_dev match pre_stat
+            if is_windows and pre_stat is not None:  # noqa: SIM102
+                if pre_stat.st_ino != file_stat.st_ino or pre_stat.st_dev != file_stat.st_dev:
+                    os.close(fd)
+                    raise SandboxSecurityError(
+                        "File identity changed during safe_open (inode mismatch) — TOCTOU race detected",
+                        operation="safe_open",
+                        path=str(path),
+                    )
+            
+            if not stat.S_ISREG(file_stat.st_mode) and not for_write:
+                os.close(fd)
+                raise SandboxSecurityError(
+                    "Opened file is not a regular file (possible device/pipe/socket injection)",
+                    operation="safe_open",
+                    path=str(path),
+                )
+
+            # Check file size against limit (only for reads)
+            if not for_write and file_stat.st_size > self.max_file_size:
+                os.close(fd)
+                raise SandboxResourceError(
+                    f"File size ({file_stat.st_size} bytes) exceeds maximum "
+                    f"({self.max_file_size} bytes): {path}",
+                    limit_name="max_file_size",
+                    limit_value=self.max_file_size,
+                )
+
+            return fd
+
+        except Exception:
+            # Ensure fd is closed on any validation failure
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            raise
+
+    def safe_read(self, path: str | Path) -> str:
+        """TOCTOU-safe file read with size limit enforcement.
+
+        Atomically validates, opens, checks size, and reads the file content
+        through a single file descriptor, closing the race window between
+        validation and use.
+
+        Args:
+            path: Relative or absolute path to read.
+
+        Returns:
+            File content as a UTF-8 string.
+
+        Raises:
+            PathValidationError: If path escapes workspace.
+            SandboxSecurityError: On TOCTOU/symlink detection.
+            SandboxResourceError: If file exceeds max_file_size.
+        """
+        fd = self.safe_open(path, for_write=False)
+        try:
+            # Read in chunks to prevent unbounded memory allocation
+            chunks: list[bytes] = []
+            total_read = 0
+            chunk_size = 1024 * 1024  # 1 MB chunks
+
+            while True:
+                chunk = os.read(fd, chunk_size)
+                if not chunk:
+                    break
+                total_read += len(chunk)
+                if total_read > self.max_file_size:
+                    raise SandboxResourceError(
+                        f"File read exceeded maximum size ({self.max_file_size} bytes): {path}",
+                        limit_name="max_file_size",
+                        limit_value=self.max_file_size,
+                    )
+                chunks.append(chunk)
+
+            return b"".join(chunks).decode("utf-8", errors="replace")
+        finally:
+            os.close(fd)
+
+    @staticmethod
+    def _is_contained_in(target: Path, parent: Path) -> bool:
+        """Return True if target equals parent or is a child of parent."""
+        if target == parent:
+            return True
+        try:
+            target.relative_to(parent)
+            return True
+        except ValueError:
+            return False

pulse/sandbox/policy.py

@@ -0,0 +1,209 @@
+"""Policy-based permission engine for Pulse sandbox execution.
+
+Implements zero-trust fine-grained policy evaluation with inheritance,
+wildcard pattern matching, and action-level overrides.
+
+Security hardening (case bypass fix):
+    - All targets are normalized through _normalize_target() before matching.
+    - Normalization covers case, separators, Unicode NFC, and drive letters.
+    - Rules match against BOTH raw and normalized targets (defense-in-depth).
+    - Default decisions changed to DENY for all actions except READ.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import unicodedata
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class ActionType(str, Enum):
+    READ = "read"
+    WRITE = "write"
+    DELETE = "delete"
+    RENAME = "rename"
+    SHELL = "shell"
+    GIT = "git"
+    PYTHON = "python"
+    NETWORK = "network"
+    SECRETS = "secrets"
+
+
+class PolicyDecision(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyRule:
+    """Individual policy rule matching an action and optional target pattern."""
+
+    action: str
+    target_pattern: str = "*"
+    decision: PolicyDecision = PolicyDecision.ASK
+    reason: str = ""
+
+    def matches(self, action: str, target: str) -> bool:
+        """Check if this rule matches the given action and target.
+
+        Security: matches against BOTH the raw target and the normalized
+        target. If either matches, the rule applies. This prevents
+        case-sensitivity bypass on Linux where filenames are case-sensitive
+        but policy rules may have been written case-insensitively.
+        """
+        if self.action != "*" and self.action.casefold() != action.casefold():
+            return False
+        if self.target_pattern == "*":
+            return True
+
+        normalized_pattern = SandboxPolicy.normalize_target(self.target_pattern)
+
+        # Match against both raw and normalized target
+        raw_normalized = SandboxPolicy.normalize_target(target)
+
+        return (
+            fnmatch.fnmatch(raw_normalized, normalized_pattern)
+            or fnmatch.fnmatch(target.replace("\\", "/").casefold(), normalized_pattern)
+        )
+
+
+class SandboxPolicy:
+    """Production-grade policy manager supporting inheritance and pattern overrides.
+
+    Security hardening:
+        - Default decisions are DENY for all mutating actions.
+        - READ defaults to ALLOW (read-only operations are safe).
+        - GIT and PYTHON default to ASK (require explicit approval).
+        - NETWORK defaults to DENY.
+        - SECRETS defaults to DENY.
+    """
+
+    DEFAULT_DECISIONS: dict[str, PolicyDecision] = {  # noqa: RUF012
+        ActionType.READ.value: PolicyDecision.ALLOW,
+        ActionType.WRITE.value: PolicyDecision.DENY,
+        ActionType.DELETE.value: PolicyDecision.DENY,
+        ActionType.RENAME.value: PolicyDecision.DENY,
+        ActionType.SHELL.value: PolicyDecision.DENY,
+        ActionType.GIT.value: PolicyDecision.ASK,
+        ActionType.PYTHON.value: PolicyDecision.ASK,
+        ActionType.NETWORK.value: PolicyDecision.DENY,
+        ActionType.SECRETS.value: PolicyDecision.DENY,
+    }
+
+    def __init__(
+        self,
+        default_decisions: dict[str, PolicyDecision] | None = None,
+        rules: list[PolicyRule] | None = None,
+        parent_policy: SandboxPolicy | None = None,
+    ) -> None:
+        self.default_decisions = {**self.DEFAULT_DECISIONS, **(default_decisions or {})}
+        self.rules: list[PolicyRule] = list(rules or [])
+        self.parent_policy = parent_policy
+
+    def add_rule(self, rule: PolicyRule) -> None:
+        self.rules.insert(0, rule)  # Higher priority rules first
+
+    def evaluate(self, action: ActionType | str, target: str = "") -> PolicyDecision:
+        action_str = action.value if isinstance(action, ActionType) else str(action).casefold()
+
+        # 1. Check explicit rules (most specific target patterns first)
+        for rule in self.rules:
+            if rule.matches(action_str, target):
+                return rule.decision
+
+        # 2. Consult parent policy if present
+        if self.parent_policy:
+            return self.parent_policy.evaluate(action, target)
+
+        # 3. Fall back to default action decision (DENY if unknown action)
+        return self.default_decisions.get(action_str, PolicyDecision.DENY)
+
+    def is_allowed(self, action: ActionType | str, target: str = "") -> bool:
+        return self.evaluate(action, target) == PolicyDecision.ALLOW
+
+    def requires_approval(self, action: ActionType | str, target: str = "") -> bool:
+        return self.evaluate(action, target) == PolicyDecision.ASK
+
+    @staticmethod
+    def normalize_target(target: str) -> str:
+        """Normalize a path/target string for consistent policy matching.
+
+        Security: prevents bypass via case differences, separator
+        inconsistencies, Unicode confusables, or drive letter prefixes.
+
+        Normalization steps:
+            1. Unicode NFC normalization (canonical decomposition + composition)
+            2. Backslash → forward slash
+            3. Lowercase
+            4. Strip Windows drive letter prefix (e.g., C:/)
+            5. Collapse consecutive slashes
+            6. Strip leading/trailing slashes for relative matching
+        """
+        # 1. Unicode NFC normalization
+        normalized = unicodedata.normalize("NFC", target)
+
+        # 2. Normalize separators
+        normalized = normalized.replace("\\", "/")
+
+        # 3. Casefold (robust lowercasing for Unicode)
+        normalized = normalized.casefold()
+
+        # 4. Strip drive letter prefix (e.g., c:/ or C:/ or C:file.txt)
+        if len(normalized) >= 2 and normalized[0].isalpha() and normalized[1] == ":":
+            if len(normalized) >= 3 and normalized[2] == "/":
+                normalized = normalized[3:]  # Strip "c:/"
+            else:
+                normalized = normalized[2:]  # Strip "c:" (drive-relative)
+
+        # 5. Collapse consecutive slashes
+        while "//" in normalized:
+            normalized = normalized.replace("//", "/")
+
+        # 6. Strip leading slash for relative matching (preserves internal structure)
+        normalized = normalized.strip("/")
+
+        return normalized
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], parent_policy: SandboxPolicy | None = None) -> SandboxPolicy:
+        defaults: dict[str, PolicyDecision] = {}
+        for action_name, decision_val in data.get("defaults", {}).items():
+            defaults[action_name.casefold()] = PolicyDecision(str(decision_val).casefold())
+
+        rules: list[PolicyRule] = []
+        for raw_rule in data.get("rules", []):
+            rules.append(
+                PolicyRule(
+                    action=str(raw_rule.get("action", "*")).casefold(),
+                    target_pattern=str(raw_rule.get("target_pattern", "*")),
+                    decision=PolicyDecision(str(raw_rule.get("decision", "ask")).casefold()),
+                    reason=str(raw_rule.get("reason", "")),
+                )
+            )
+
+        return cls(default_decisions=defaults, rules=rules, parent_policy=parent_policy)
+
+    @classmethod
+    def from_file(cls, path: Path, parent_policy: SandboxPolicy | None = None) -> SandboxPolicy:
+        text = path.read_text(encoding="utf-8")
+        raw = json.loads(text)
+        return cls.from_dict(raw, parent_policy=parent_policy)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "defaults": {k: v.value for k, v in self.default_decisions.items()},
+            "rules": [
+                {
+                    "action": r.action,
+                    "target_pattern": r.target_pattern,
+                    "decision": r.decision.value,
+                    "reason": r.reason,
+                }
+                for r in reversed(self.rules)
+            ],
+        }