agent-os-kernel 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

modules/atr/atr/tools/safe/file_reader.py

@@ -0,0 +1,400 @@
+"""
+Safe File Reader Tool.
+
+Provides read-only file access with security controls:
+- Path sandboxing (only read from allowed directories)
+- No directory traversal (../ blocked)
+- File size limits
+- Extension filtering
+- No symbolic link following outside sandbox
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+from atr.decorator import tool
+
+
+class FileReaderTool:
+    """
+    Safe file reader with path sandboxing.
+    
+    Features:
+    - Read-only operations only
+    - Sandbox path enforcement (can't read outside allowed dirs)
+    - Directory traversal prevention
+    - File size limits
+    - Extension whitelisting
+    - Symlink safety
+    
+    Example:
+        ```python
+        reader = FileReaderTool(
+            sandbox_paths=["/data/docs", "/data/configs"],
+            allowed_extensions=[".txt", ".json", ".yaml", ".md"],
+            max_file_size=1_000_000  # 1MB
+        )
+        
+        # Register with ATR
+        registry.register(reader.read_file)
+        registry.register(reader.list_directory)
+        
+        # Use from agent
+        content = reader.read_file("/data/docs/readme.txt")
+        ```
+    """
+    
+    def __init__(
+        self,
+        sandbox_paths: Optional[List[str]] = None,
+        allowed_extensions: Optional[List[str]] = None,
+        blocked_extensions: Optional[List[str]] = None,
+        max_file_size: int = 10_000_000,  # 10MB
+        follow_symlinks: bool = False,
+        encoding: str = "utf-8"
+    ):
+        """
+        Initialize file reader tool.
+        
+        Args:
+            sandbox_paths: List of allowed directory paths
+            allowed_extensions: Whitelist of file extensions (e.g., [".txt", ".json"])
+            blocked_extensions: Blacklist of extensions (e.g., [".exe", ".sh"])
+            max_file_size: Maximum file size to read in bytes
+            follow_symlinks: Whether to follow symbolic links
+            encoding: Default file encoding
+        """
+        self.sandbox_paths: List[Path] = [
+            Path(p).resolve() for p in (sandbox_paths or [os.getcwd()])
+        ]
+        self.allowed_extensions: Optional[Set[str]] = (
+            set(ext.lower() for ext in allowed_extensions) if allowed_extensions else None
+        )
+        self.blocked_extensions: Set[str] = set(
+            ext.lower() for ext in (blocked_extensions or [
+                ".exe", ".dll", ".so", ".dylib",
+                ".sh", ".bash", ".zsh", ".fish",
+                ".bat", ".cmd", ".ps1",
+                ".py", ".pyc", ".pyo",
+                ".class", ".jar",
+            ])
+        )
+        self.max_file_size = max_file_size
+        self.follow_symlinks = follow_symlinks
+        self.encoding = encoding
+    
+    def _validate_path(self, path: str) -> Path:
+        """Validate path is within sandbox and safe to access."""
+        # Convert to Path and resolve
+        file_path = Path(path)
+        
+        # Don't resolve symlinks if not allowed
+        if self.follow_symlinks:
+            resolved = file_path.resolve()
+        else:
+            # Resolve parent but not the file itself if it's a symlink
+            resolved = file_path.parent.resolve() / file_path.name
+            if file_path.is_symlink():
+                raise ValueError(f"Symbolic links not allowed: {path}")
+        
+        # Check for directory traversal attempts
+        path_str = str(path)
+        if ".." in path_str:
+            raise ValueError(f"Directory traversal not allowed: {path}")
+        
+        # Check if within sandbox
+        in_sandbox = False
+        for sandbox in self.sandbox_paths:
+            try:
+                resolved.relative_to(sandbox)
+                in_sandbox = True
+                break
+            except ValueError:
+                continue
+        
+        if not in_sandbox:
+            raise ValueError(
+                f"Path '{path}' is outside allowed directories. "
+                f"Allowed: {[str(p) for p in self.sandbox_paths]}"
+            )
+        
+        return resolved
+    
+    def _validate_extension(self, path: Path):
+        """Validate file extension."""
+        ext = path.suffix.lower()
+        
+        # Check blocked extensions
+        if ext in self.blocked_extensions:
+            raise ValueError(f"File extension '{ext}' is blocked")
+        
+        # Check allowed extensions (if whitelist set)
+        if self.allowed_extensions and ext not in self.allowed_extensions:
+            raise ValueError(
+                f"File extension '{ext}' not allowed. "
+                f"Allowed: {', '.join(sorted(self.allowed_extensions))}"
+            )
+    
+    @tool(
+        name="read_file",
+        description="Read the contents of a text file",
+        tags=["file", "read", "safe"]
+    )
+    def read_file(
+        self,
+        path: str,
+        encoding: Optional[str] = None,
+        max_lines: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Read a file's contents.
+        
+        Args:
+            path: Path to file (must be within sandbox)
+            encoding: File encoding (default: utf-8)
+            max_lines: Maximum number of lines to read
+        
+        Returns:
+            Dict with content, size, and metadata
+        """
+        # Validate path
+        file_path = self._validate_path(path)
+        self._validate_extension(file_path)
+        
+        # Check file exists
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        
+        if not file_path.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+        
+        # Check file size
+        file_size = file_path.stat().st_size
+        if file_size > self.max_file_size:
+            raise ValueError(
+                f"File too large: {file_size} bytes. "
+                f"Maximum: {self.max_file_size} bytes"
+            )
+        
+        # Read file
+        enc = encoding or self.encoding
+        try:
+            content = file_path.read_text(encoding=enc)
+        except UnicodeDecodeError:
+            raise ValueError(f"Unable to decode file with encoding '{enc}'")
+        
+        # Apply line limit
+        if max_lines:
+            lines = content.splitlines(keepends=True)
+            if len(lines) > max_lines:
+                content = "".join(lines[:max_lines])
+                content += f"\n... [truncated, showing {max_lines} of {len(lines)} lines]"
+        
+        return {
+            "content": content,
+            "size": file_size,
+            "path": str(file_path),
+            "encoding": enc,
+            "lines": content.count("\n") + 1
+        }
+    
+    @tool(
+        name="read_file_lines",
+        description="Read specific lines from a file",
+        tags=["file", "read", "safe"]
+    )
+    def read_lines(
+        self,
+        path: str,
+        start_line: int = 1,
+        end_line: Optional[int] = None,
+        encoding: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Read specific lines from a file.
+        
+        Args:
+            path: Path to file
+            start_line: First line to read (1-indexed)
+            end_line: Last line to read (inclusive, None for end of file)
+            encoding: File encoding
+        
+        Returns:
+            Dict with lines, content, and metadata
+        """
+        file_path = self._validate_path(path)
+        self._validate_extension(file_path)
+        
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        
+        if start_line < 1:
+            raise ValueError("start_line must be >= 1")
+        
+        enc = encoding or self.encoding
+        lines = file_path.read_text(encoding=enc).splitlines()
+        
+        # Adjust for 0-indexing
+        start_idx = start_line - 1
+        end_idx = end_line if end_line else len(lines)
+        
+        selected = lines[start_idx:end_idx]
+        
+        return {
+            "lines": selected,
+            "content": "\n".join(selected),
+            "start_line": start_line,
+            "end_line": min(end_idx, len(lines)),
+            "total_lines": len(lines),
+            "path": str(file_path)
+        }
+    
+    @tool(
+        name="list_directory",
+        description="List files and directories in a path",
+        tags=["file", "directory", "safe"]
+    )
+    def list_directory(
+        self,
+        path: str,
+        pattern: str = "*",
+        recursive: bool = False,
+        include_hidden: bool = False
+    ) -> Dict[str, Any]:
+        """
+        List directory contents.
+        
+        Args:
+            path: Directory path
+            pattern: Glob pattern (e.g., "*.txt")
+            recursive: Whether to search recursively
+            include_hidden: Include hidden files (starting with .)
+        
+        Returns:
+            Dict with files, directories, and counts
+        """
+        dir_path = self._validate_path(path)
+        
+        if not dir_path.exists():
+            raise FileNotFoundError(f"Directory not found: {path}")
+        
+        if not dir_path.is_dir():
+            raise ValueError(f"Path is not a directory: {path}")
+        
+        # List contents
+        if recursive:
+            matches = list(dir_path.rglob(pattern))
+        else:
+            matches = list(dir_path.glob(pattern))
+        
+        files = []
+        directories = []
+        
+        for item in matches:
+            # Skip hidden files unless requested
+            if not include_hidden and item.name.startswith("."):
+                continue
+            
+            # Skip symlinks if not following
+            if item.is_symlink() and not self.follow_symlinks:
+                continue
+            
+            rel_path = str(item.relative_to(dir_path))
+            
+            if item.is_file():
+                files.append({
+                    "name": item.name,
+                    "path": rel_path,
+                    "size": item.stat().st_size,
+                    "extension": item.suffix
+                })
+            elif item.is_dir():
+                directories.append({
+                    "name": item.name,
+                    "path": rel_path
+                })
+        
+        return {
+            "path": str(dir_path),
+            "files": files,
+            "directories": directories,
+            "file_count": len(files),
+            "directory_count": len(directories)
+        }
+    
+    @tool(
+        name="file_exists",
+        description="Check if a file or directory exists",
+        tags=["file", "check", "safe"]
+    )
+    def exists(self, path: str) -> Dict[str, Any]:
+        """
+        Check if path exists.
+        
+        Args:
+            path: Path to check
+        
+        Returns:
+            Dict with exists, is_file, is_dir
+        """
+        try:
+            file_path = self._validate_path(path)
+            return {
+                "exists": file_path.exists(),
+                "is_file": file_path.is_file(),
+                "is_directory": file_path.is_dir(),
+                "path": str(file_path)
+            }
+        except ValueError:
+            # Path outside sandbox
+            return {
+                "exists": False,
+                "is_file": False,
+                "is_directory": False,
+                "path": path,
+                "error": "Path outside allowed directories"
+            }
+    
+    @tool(
+        name="file_info",
+        description="Get metadata about a file",
+        tags=["file", "metadata", "safe"]
+    )
+    def file_info(self, path: str) -> Dict[str, Any]:
+        """
+        Get file metadata.
+        
+        Args:
+            path: Path to file
+        
+        Returns:
+            Dict with size, modified time, etc.
+        """
+        file_path = self._validate_path(path)
+        
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        
+        stat = file_path.stat()
+        
+        return {
+            "path": str(file_path),
+            "name": file_path.name,
+            "extension": file_path.suffix,
+            "size": stat.st_size,
+            "size_human": self._human_size(stat.st_size),
+            "modified": stat.st_mtime,
+            "created": stat.st_ctime,
+            "is_file": file_path.is_file(),
+            "is_directory": file_path.is_dir(),
+            "is_symlink": file_path.is_symlink()
+        }
+    
+    def _human_size(self, size: int) -> str:
+        """Convert bytes to human readable string."""
+        for unit in ["B", "KB", "MB", "GB"]:
+            if size < 1024:
+                return f"{size:.1f} {unit}"
+            size /= 1024
+        return f"{size:.1f} TB"

modules/atr/atr/tools/safe/http_client.py

@@ -0,0 +1,314 @@
+"""
+Safe HTTP Client Tool.
+
+Provides HTTP request capabilities with security controls:
+- URL whitelisting
+- Rate limiting
+- Request timeout enforcement
+- Response size limits
+- No redirect following to external domains
+"""
+
+import asyncio
+import time
+from collections import deque
+from typing import Any, Dict, List, Optional, Set
+from urllib.parse import urlparse
+
+from atr.decorator import tool
+
+
+class RateLimiter:
+    """Simple rate limiter using sliding window."""
+    
+    def __init__(self, max_requests: int, window_seconds: float = 60.0):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._requests: deque = deque()
+    
+    def check(self) -> bool:
+        """Check if request is allowed."""
+        now = time.monotonic()
+        
+        # Remove old requests
+        while self._requests and self._requests[0] < now - self.window_seconds:
+            self._requests.popleft()
+        
+        return len(self._requests) < self.max_requests
+    
+    def record(self):
+        """Record a request."""
+        self._requests.append(time.monotonic())
+
+
+class HttpClientTool:
+    """
+    Safe HTTP client with security controls.
+    
+    Features:
+    - Domain whitelisting (only specified domains allowed)
+    - Rate limiting (prevent abuse)
+    - Timeout enforcement (prevent hanging)
+    - Response size limits (prevent memory exhaustion)
+    - Safe redirect handling (no external redirects)
+    
+    Example:
+        ```python
+        http = HttpClientTool(
+            allowed_domains=["api.github.com", "httpbin.org"],
+            rate_limit=30,  # 30 requests per minute
+            timeout=10.0,
+            max_response_size=1_000_000  # 1MB
+        )
+        
+        # Register with ATR
+        registry.register(http.get)
+        registry.register(http.post)
+        
+        # Use from agent
+        response = await http.get("https://api.github.com/users/octocat")
+        ```
+    """
+    
+    def __init__(
+        self,
+        allowed_domains: Optional[List[str]] = None,
+        blocked_domains: Optional[List[str]] = None,
+        rate_limit: int = 60,
+        timeout: float = 30.0,
+        max_response_size: int = 10_000_000,  # 10MB
+        allow_redirects: bool = True,
+        max_redirects: int = 5
+    ):
+        """
+        Initialize HTTP client tool.
+        
+        Args:
+            allowed_domains: Whitelist of allowed domains (if set, only these allowed)
+            blocked_domains: Blacklist of blocked domains
+            rate_limit: Maximum requests per minute
+            timeout: Request timeout in seconds
+            max_response_size: Maximum response size in bytes
+            allow_redirects: Whether to follow redirects
+            max_redirects: Maximum number of redirects to follow
+        """
+        self.allowed_domains: Set[str] = set(allowed_domains or [])
+        self.blocked_domains: Set[str] = set(blocked_domains or [
+            "localhost",
+            "127.0.0.1",
+            "0.0.0.0",
+            "169.254.169.254",  # AWS metadata
+            "metadata.google.internal",  # GCP metadata
+        ])
+        self.timeout = timeout
+        self.max_response_size = max_response_size
+        self.allow_redirects = allow_redirects
+        self.max_redirects = max_redirects
+        self._rate_limiter = RateLimiter(rate_limit)
+    
+    def _validate_url(self, url: str) -> str:
+        """Validate and normalize URL."""
+        parsed = urlparse(url)
+        
+        # Must have scheme
+        if not parsed.scheme:
+            raise ValueError("URL must include scheme (http:// or https://)")
+        
+        # Only allow http/https
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(f"Scheme '{parsed.scheme}' not allowed. Use http or https.")
+        
+        # Extract domain
+        domain = parsed.netloc.lower()
+        if ":" in domain:
+            domain = domain.split(":")[0]  # Remove port
+        
+        # Check blocked domains
+        if domain in self.blocked_domains:
+            raise ValueError(f"Domain '{domain}' is blocked")
+        
+        # Check for private IP ranges (basic check)
+        if self._is_private_domain(domain):
+            raise ValueError(f"Private/internal domains not allowed: {domain}")
+        
+        # Check allowed domains (if whitelist set)
+        if self.allowed_domains:
+            if not any(domain.endswith(allowed) for allowed in self.allowed_domains):
+                raise ValueError(
+                    f"Domain '{domain}' not in allowed list. "
+                    f"Allowed: {', '.join(self.allowed_domains)}"
+                )
+        
+        return url
+    
+    def _is_private_domain(self, domain: str) -> bool:
+        """Check if domain resolves to private IP (basic check)."""
+        # Check common private patterns
+        private_patterns = [
+            "10.",
+            "192.168.",
+            "172.16.", "172.17.", "172.18.", "172.19.",
+            "172.20.", "172.21.", "172.22.", "172.23.",
+            "172.24.", "172.25.", "172.26.", "172.27.",
+            "172.28.", "172.29.", "172.30.", "172.31.",
+            "internal",
+            ".local",
+        ]
+        return any(domain.startswith(p) or domain.endswith(p) for p in private_patterns)
+    
+    def _check_rate_limit(self):
+        """Check and enforce rate limit."""
+        if not self._rate_limiter.check():
+            raise RuntimeError("Rate limit exceeded. Please wait before making more requests.")
+        self._rate_limiter.record()
+    
+    @tool(
+        name="http_get",
+        description="Make a safe HTTP GET request to retrieve data from a URL",
+        tags=["http", "network", "safe"]
+    )
+    async def get(
+        self,
+        url: str,
+        headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Make a GET request.
+        
+        Args:
+            url: URL to request (must be in allowed domains)
+            headers: Optional request headers
+        
+        Returns:
+            Dict with status_code, headers, and body
+        """
+        try:
+            import aiohttp
+        except ImportError:
+            raise ImportError("aiohttp required. Install with: pip install aiohttp")
+        
+        # Validate
+        url = self._validate_url(url)
+        self._check_rate_limit()
+        
+        # Make request
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.get(
+                url,
+                headers=headers,
+                allow_redirects=self.allow_redirects,
+                max_redirects=self.max_redirects
+            ) as response:
+                # Check response size
+                content_length = response.headers.get("Content-Length")
+                if content_length and int(content_length) > self.max_response_size:
+                    raise ValueError(f"Response too large: {content_length} bytes")
+                
+                # Read response (with size limit)
+                body = await response.text()
+                if len(body) > self.max_response_size:
+                    body = body[:self.max_response_size] + "... [truncated]"
+                
+                return {
+                    "status_code": response.status,
+                    "headers": dict(response.headers),
+                    "body": body,
+                    "url": str(response.url)
+                }
+    
+    @tool(
+        name="http_post",
+        description="Make a safe HTTP POST request to send data to a URL",
+        tags=["http", "network", "safe"]
+    )
+    async def post(
+        self,
+        url: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Make a POST request.
+        
+        Args:
+            url: URL to request (must be in allowed domains)
+            data: Form data to send
+            json_body: JSON body to send
+            headers: Optional request headers
+        
+        Returns:
+            Dict with status_code, headers, and body
+        """
+        try:
+            import aiohttp
+        except ImportError:
+            raise ImportError("aiohttp required. Install with: pip install aiohttp")
+        
+        # Validate
+        url = self._validate_url(url)
+        self._check_rate_limit()
+        
+        # Make request
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(
+                url,
+                data=data,
+                json=json_body,
+                headers=headers,
+                allow_redirects=self.allow_redirects,
+                max_redirects=self.max_redirects
+            ) as response:
+                # Check response size
+                content_length = response.headers.get("Content-Length")
+                if content_length and int(content_length) > self.max_response_size:
+                    raise ValueError(f"Response too large: {content_length} bytes")
+                
+                # Read response
+                body = await response.text()
+                if len(body) > self.max_response_size:
+                    body = body[:self.max_response_size] + "... [truncated]"
+                
+                return {
+                    "status_code": response.status,
+                    "headers": dict(response.headers),
+                    "body": body,
+                    "url": str(response.url)
+                }
+    
+    @tool(
+        name="http_head",
+        description="Make a safe HTTP HEAD request to check if a URL exists",
+        tags=["http", "network", "safe"]
+    )
+    async def head(self, url: str) -> Dict[str, Any]:
+        """
+        Make a HEAD request (useful for checking if resource exists).
+        
+        Args:
+            url: URL to check
+        
+        Returns:
+            Dict with status_code and headers
+        """
+        try:
+            import aiohttp
+        except ImportError:
+            raise ImportError("aiohttp required. Install with: pip install aiohttp")
+        
+        url = self._validate_url(url)
+        self._check_rate_limit()
+        
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.head(url, allow_redirects=self.allow_redirects) as response:
+                return {
+                    "status_code": response.status,
+                    "headers": dict(response.headers),
+                    "url": str(response.url)
+                }