velune-cli 0.9.0__py3-none-any.whl

velune/tools/git/operations.py

@@ -0,0 +1,122 @@
+"""Git operation tools — GitCommit, GitCheckout.
+
+Uses gitpython's high-level API instead of raw subprocess.  This eliminates
+two classes of injection risk:
+  - Shell injection (subprocess with a shell argument is not used; gitpython handles this).
+  - Argument injection: branch names are looked up by key in the Repo heads
+    dict rather than spliced into a command string, so ``--detach`` or similar
+    flag-like inputs cannot influence git's option parsing.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from velune.execution.path_guard import PathGuard
+from velune.tools.base.tool import BaseTool
+
+
+def _open_repo(path: Path):  # type: ignore[return]
+    try:
+        import git
+
+        return git.Repo(str(path), search_parent_directories=True)
+    except Exception as exc:
+        raise ValueError(f"Not a git repository: {path}") from exc
+
+
+def _validate_ref_name(name: str, label: str = "name") -> None:
+    """Reject ref names that look like git option flags."""
+    if name.startswith("-"):
+        raise ValueError(f"Invalid git {label} '{name}': names must not start with '-'.")
+
+
+class GitCommit(BaseTool):
+    """Tool for committing changes."""
+
+    def __init__(self, workspace: Path | None = None) -> None:
+        self.workspace = Path(workspace).resolve() if workspace else Path.cwd().resolve()
+
+    def get_name(self) -> str:
+        return "git_commit"
+
+    def get_description(self) -> str:
+        return "Commit changes to git"
+
+    async def execute(
+        self,
+        message: str,
+        directory: str = ".",
+        add_all: bool = True,
+    ) -> str:
+        guard = PathGuard(self.workspace)
+        safe_root = guard.validate(directory)
+        repo = _open_repo(safe_root)
+
+        def _do_commit() -> str:
+            if add_all:
+                repo.git.add(A=True)
+            commit = repo.index.commit(message)
+            return f"Committed: {message} ({commit.hexsha[:8]})"
+
+        return await asyncio.to_thread(_do_commit)
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "message": {"type": "string", "description": "Commit message"},
+                "directory": {"type": "string", "description": "Git repository directory"},
+                "add_all": {"type": "boolean", "description": "Add all changes before committing"},
+            },
+            "required": ["message"],
+        }
+
+
+class GitCheckout(BaseTool):
+    """Tool for checking out branches."""
+
+    def __init__(self, workspace: Path | None = None) -> None:
+        self.workspace = Path(workspace).resolve() if workspace else Path.cwd().resolve()
+
+    def get_name(self) -> str:
+        return "git_checkout"
+
+    def get_description(self) -> str:
+        return "Checkout a git branch"
+
+    async def execute(
+        self,
+        branch: str,
+        directory: str = ".",
+        create: bool = False,
+    ) -> str:
+        _validate_ref_name(branch, label="branch")
+        guard = PathGuard(self.workspace)
+        safe_root = guard.validate(directory)
+        repo = _open_repo(safe_root)
+
+        def _do_checkout() -> str:
+            if create:
+                new_head = repo.create_head(branch)
+                new_head.checkout()
+            else:
+                existing = {h.name: h for h in repo.heads}
+                if branch not in existing:
+                    raise ValueError(f"Branch not found: '{branch}'")
+                existing[branch].checkout()
+            return f"Checked out: {branch}"
+
+        return await asyncio.to_thread(_do_checkout)
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "branch": {"type": "string", "description": "Branch name"},
+                "directory": {"type": "string", "description": "Git repository directory"},
+                "create": {"type": "boolean", "description": "Create branch if it doesn't exist"},
+            },
+            "required": ["branch"],
+        }

velune/tools/git/state.py

@@ -0,0 +1,121 @@
+"""Git state tools — GitStatus, GitBranch.
+
+Uses gitpython instead of raw subprocess calls.  PathGuard validates the
+directory parameter so the tools cannot be pointed outside the workspace.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from velune.execution.path_guard import PathGuard
+from velune.tools.base.tool import BaseTool
+
+
+def _open_repo(path: Path):  # type: ignore[return]
+    try:
+        import git
+
+        return git.Repo(str(path), search_parent_directories=True)
+    except Exception as exc:
+        raise ValueError(f"Not a git repository: {path}") from exc
+
+
+class GitStatus(BaseTool):
+    """Tool for viewing git status."""
+
+    def __init__(self, workspace: Path | None = None) -> None:
+        self.workspace = Path(workspace).resolve() if workspace else Path.cwd().resolve()
+
+    def get_name(self) -> str:
+        return "git_status"
+
+    def get_description(self) -> str:
+        return "View git repository status"
+
+    async def execute(self, directory: str = ".") -> dict:
+        guard = PathGuard(self.workspace)
+        safe_root = guard.validate(directory)
+        repo = _open_repo(safe_root)
+
+        def _fetch() -> dict:
+            status: dict[str, list[str]] = {
+                "modified": [],
+                "added": [],
+                "deleted": [],
+                "untracked": [],
+            }
+            # Staged changes (index vs HEAD)
+            try:
+                for diff in repo.index.diff("HEAD"):
+                    if diff.change_type == "M":
+                        status["modified"].append(diff.b_path or diff.a_path)
+                    elif diff.change_type == "A":
+                        status["added"].append(diff.b_path)
+                    elif diff.change_type == "D":
+                        status["deleted"].append(diff.a_path)
+            except Exception:
+                pass
+            # Unstaged changes (working tree vs index)
+            try:
+                for diff in repo.index.diff(None):
+                    path = diff.a_path
+                    if diff.change_type == "M" and path not in status["modified"]:
+                        status["modified"].append(path)
+                    elif diff.change_type == "D" and path not in status["deleted"]:
+                        status["deleted"].append(path)
+            except Exception:
+                pass
+            status["untracked"] = list(repo.untracked_files)
+            return status
+
+        return await asyncio.to_thread(_fetch)
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "directory": {"type": "string", "description": "Git repository directory"},
+            },
+        }
+
+
+class GitBranch(BaseTool):
+    """Tool for viewing git branches."""
+
+    def __init__(self, workspace: Path | None = None) -> None:
+        self.workspace = Path(workspace).resolve() if workspace else Path.cwd().resolve()
+
+    def get_name(self) -> str:
+        return "git_branch"
+
+    def get_description(self) -> str:
+        return "View git branches"
+
+    async def execute(self, directory: str = ".") -> dict:
+        guard = PathGuard(self.workspace)
+        safe_root = guard.validate(directory)
+        repo = _open_repo(safe_root)
+
+        def _fetch() -> dict:
+            try:
+                current = repo.active_branch.name
+            except TypeError:
+                current = "(detached HEAD)"
+            branches = [h.name for h in repo.heads]
+            remote_branches = [ref.name for ref in repo.remote_refs] if repo.remotes else []
+            return {
+                "current": current,
+                "all": branches + remote_branches,
+            }
+
+        return await asyncio.to_thread(_fetch)
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "directory": {"type": "string", "description": "Git repository directory"},
+            },
+        }

velune/tools/module.py

@@ -0,0 +1,81 @@
+from velune.kernel.bootstrap import RuntimeEnvironment, SubsystemModule
+
+
+def _create_tool_registry(env: RuntimeEnvironment):
+    import logging
+
+    from velune.tools import (
+        CreateFile,
+        DeleteFile,
+        ExecuteCommand,
+        FindFiles,
+        FindReferences,
+        GitBlame,
+        GitBranch,
+        GitCheckout,
+        GitCommit,
+        GitDiff,
+        GitLog,
+        GitStatus,
+        GoToDefinition,
+        GrepFiles,
+        ReadDirectory,
+        ReadFile,
+        SemanticCodeSearch,
+        SymbolSearch,
+        TerminalHistory,
+        WebFetch,
+        WriteFile,
+    )
+    from velune.tools.base.registry import ToolRegistry
+
+    logger = logging.getLogger("velune.tools.module")
+
+    execution_executor = env.container.get("runtime.execution_executor")
+
+    tool_registry = ToolRegistry()
+    execute_cmd_tool = ExecuteCommand(
+        sandbox=execution_executor.sandbox, workspace_path=str(env.workspace)
+    )
+    ws = env.workspace
+    default_tools = [
+        ReadFile(workspace=ws),
+        ReadDirectory(workspace=ws),
+        WriteFile(workspace=ws),
+        CreateFile(workspace=ws),
+        DeleteFile(workspace=ws),
+        GrepFiles(workspace=ws),
+        FindFiles(workspace=ws),
+        GitLog(workspace=ws),
+        GitDiff(workspace=ws),
+        GitBlame(workspace=ws),
+        GitStatus(workspace=ws),
+        GitBranch(workspace=ws),
+        GitCommit(workspace=ws),
+        GitCheckout(workspace=ws),
+        execute_cmd_tool,
+        TerminalHistory(),
+        SemanticCodeSearch(workspace=ws),
+        SymbolSearch(workspace=ws),
+        GoToDefinition(workspace=ws),
+        FindReferences(workspace=ws),
+        WebFetch(),
+    ]
+    for tool in default_tools:
+        tool_registry.register(tool)
+
+    broken = tool_registry.list_broken_tools()
+    if broken:
+        logger.warning("Tools failed validation: %s", broken)
+
+    return tool_registry
+
+
+TOOL_MODULES = [
+    SubsystemModule(
+        name="tool_registry",
+        factory=_create_tool_registry,
+        container_key="runtime.tool_registry",
+        dependencies=["runtime.execution_executor"],
+    )
+]

velune/tools/terminal/execute.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from velune.execution.sandbox import SubprocessSandbox
+
+from velune.tools.base.tool import BaseTool
+
+
+class ExecuteCommand(BaseTool):
+    """Tool for executing terminal commands."""
+
+    def __init__(self, sandbox: SubprocessSandbox | None = None, workspace_path: str | None = None):
+        self._sandbox = sandbox
+        self._workspace_path = workspace_path
+
+    def get_name(self) -> str:
+        return "execute_command"
+
+    def get_description(self) -> str:
+        return "Execute a terminal command"
+
+    async def execute(
+        self,
+        command: str,
+        directory: str | None = None,
+        timeout: int = 30,
+    ) -> dict:
+        """Execute a command."""
+        from pathlib import Path
+
+        from velune.core.errors.execution import SandboxError
+        from velune.execution.command_spec import CommandSpec
+        from velune.execution.sandbox import SubprocessSandbox
+
+        workspace = Path(directory or self._workspace_path or Path.cwd())
+        sandbox = self._sandbox or SubprocessSandbox(workspace)
+
+        try:
+            spec = CommandSpec.from_string(command, cwd=workspace, timeout=float(timeout))
+        except SandboxError as e:
+            sandbox.emit_rejection(command, str(e))
+            raise e
+
+        result = sandbox.execute(spec)
+        return {
+            "exit_code": result.exit_code,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "duration_ms": result.duration_ms,
+        }
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "Command to execute",
+                },
+                "directory": {
+                    "type": "string",
+                    "description": "Working directory",
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Command timeout in seconds",
+                },
+            },
+            "required": ["command"],
+        }

velune/tools/terminal/history.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from velune.tools.base.tool import BaseTool
+
+
+class TerminalHistory(BaseTool):
+    """Tool for viewing terminal history."""
+
+    def get_name(self) -> str:
+        return "terminal_history"
+
+    def get_description(self) -> str:
+        return "View terminal command history"
+
+    async def execute(
+        self,
+        limit: int = 50,
+    ) -> list[str]:
+        """Get terminal history."""
+        history_file = Path.home() / ".bash_history"
+
+        if not history_file.exists():
+            history_file = Path.home() / ".zsh_history"
+
+        if not history_file.exists():
+            return []
+
+        with open(history_file, encoding="utf-8", errors="ignore") as f:
+            lines = f.readlines()
+
+        # Get last N lines
+        history = [line.strip() for line in lines[-limit:]]
+
+        return history
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "limit": {
+                    "type": "integer",
+                    "description": "Number of history entries to return",
+                },
+            },
+        }

velune/tools/web/fetch.py

@@ -0,0 +1,55 @@
+"""Web fetch tools."""
+
+from velune.tools.base.tool import BaseTool
+from velune.tools.web.validator import validate_url
+
+
+class WebFetch(BaseTool):
+    """Tool for fetching web content."""
+
+    def get_name(self) -> str:
+        return "web_fetch"
+
+    def get_description(self) -> str:
+        return "Fetch content from a URL"
+
+    async def execute(
+        self,
+        url: str,
+        timeout: int = 10,
+    ) -> str:
+        """Fetch content from URL."""
+        import httpx
+
+        is_valid, error = validate_url(url)
+        if not is_valid:
+            raise ValueError(f"URL validation failed: {error}")
+
+        async with httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=True,
+            max_redirects=3,  # Prevent redirect chains to internal services
+        ) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            # Limit response size to prevent memory exhaustion
+            content = response.text
+            if len(content) > 500_000:  # 500KB limit
+                content = content[:500_000] + "\n... [TRUNCATED: response exceeded 500KB]"
+            return content
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Fetch content from a URL. HTTPS only. Private/internal IPs blocked.",
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Request timeout in seconds",
+                },
+            },
+            "required": ["url"],
+        }

velune/tools/web/validator.py

@@ -0,0 +1,122 @@
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+BLOCKED_HOSTS = frozenset(
+    {
+        "169.254.169.254",  # AWS IMDS v1
+        "169.254.170.2",  # AWS ECS metadata
+        "metadata.google.internal",
+        "metadata.goog",  # GCP metadata alternate
+        "169.254.0.0",  # link-local broadcast
+        "fd00:ec2::254",  # AWS IPv6 IMDS
+        "100.100.100.200",  # Alibaba Cloud metadata
+    }
+)
+
+BLOCKED_PREFIXES = (
+    "169.254.",  # link-local range (catch-all)
+)
+
+# Explicit additional blocked networks not guaranteed by ip.is_private across all
+# Python versions.  ip.is_private was extended in 3.11; these guards ensure
+# correctness on older runtimes too.
+_BLOCKED_NETWORKS: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = [
+    ipaddress.ip_network("100.64.0.0/10"),  # Carrier-grade NAT (RFC 6598) / Alibaba Cloud
+    ipaddress.ip_network("fc00::/7"),  # IPv6 ULA (includes fd00::/8 — AWS IPv6 metadata)
+]
+
+
+def _is_private_ip(address: str) -> tuple[bool, str]:
+    """Returns (is_blocked, reason). Resolves hostnames.
+
+    CRITICAL: always resolves the hostname to an IP and checks the *resolved* IP
+    so that DNS-rebinding / CNAME tricks (external.attacker.com → 169.254.169.254)
+    are blocked.  Uses socket.getaddrinfo() and checks ALL returned addresses.
+    """
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        # It's a hostname — resolve it via getaddrinfo (all returned addresses checked)
+        try:
+            socket.setdefaulttimeout(3)
+            resolved = socket.getaddrinfo(address, None, proto=socket.IPPROTO_TCP)
+            for _family, _type, _proto, _canonname, sockaddr in resolved:
+                ip_str = sockaddr[0]
+                blocked, reason = _is_private_ip(ip_str)
+                if blocked:
+                    return True, f"hostname {address!r} resolves to blocked IP {ip_str}: {reason}"
+        except socket.gaierror:
+            return False, ""  # Can't resolve — let the request fail naturally
+        return False, ""
+
+    if ip.is_loopback:
+        return True, "loopback address"
+    if ip.is_private:
+        return True, "private network range"
+    if ip.is_link_local:
+        return True, "link-local address (fe80::/10 or 169.254.x.x)"
+    if ip.is_reserved:
+        return True, "reserved address"
+    if ip.is_multicast:
+        return True, "multicast address"
+    # Explicitly check for 0.0.0.0/8 (unspecified)
+    if isinstance(ip, ipaddress.IPv4Address) and ip in ipaddress.ip_network("0.0.0.0/8"):
+        return True, "unspecified address range"
+    # Check additional blocked networks (carrier-grade NAT, IPv6 ULA)
+    for net in _BLOCKED_NETWORKS:
+        try:
+            if ip in net:
+                return True, f"blocked network range {net}"
+        except TypeError:
+            pass  # IPv4 address vs IPv6 network (or vice-versa) — skip
+    return False, ""
+
+
+def validate_url(url: str, allow_http: bool = False) -> tuple[bool, str | None]:
+    """
+    Validate URL for SSRF safety.
+    Returns (is_valid, error_message).
+    """
+    try:
+        parsed = urlparse(url)
+    except Exception:
+        return False, "Unparseable URL"
+
+    # Reject credentials in URL
+    if parsed.username or parsed.password:
+        return False, "URLs with embedded credentials are not allowed"
+
+    if parsed.scheme not in ("https", "http"):
+        return False, f"Scheme '{parsed.scheme}' not allowed"
+    if parsed.scheme == "http" and not allow_http:
+        return False, "HTTP not allowed — use HTTPS"
+
+    hostname = parsed.hostname
+    if not hostname:
+        return False, "No hostname"
+    hostname = hostname.lower().strip(".")
+
+    if hostname in BLOCKED_HOSTS:
+        return False, f"Host '{hostname}' is explicitly blocked"
+    for prefix in BLOCKED_PREFIXES:
+        if hostname.startswith(prefix):
+            return False, f"Host '{hostname}' matches blocked prefix"
+
+    # Reject numeric escape forms (0x7f000001, 0177.0.0.1, decimal integer, etc.)
+    # We use socket.inet_aton which handles hex, octal, decimal, integer, and multi-dot notations
+    # exactly the way the OS/socket libraries parse numeric IPv4 addresses.
+    try:
+        packed = socket.inet_aton(hostname)
+        ip_str = socket.inet_ntoa(packed)
+        blocked, reason = _is_private_ip(ip_str)
+        if blocked:
+            return False, f"Numeric IP {hostname} resolves to blocked: {reason}"
+    except OSError:
+        pass
+
+    blocked, reason = _is_private_ip(hostname)
+    if blocked:
+        return False, reason
+
+    return True, None