flowly-code 1.0.0__py3-none-any.whl

flowly_code/exec/executor.py

@@ -0,0 +1,184 @@
+"""Command executor with security checks."""
+
+import asyncio
+import subprocess
+import sys
+from pathlib import Path
+
+from loguru import logger
+
+from flowly_code.exec.types import (
+    ExecRequest,
+    ExecResult,
+    ExecConfig,
+)
+from flowly_code.exec.safety import analyze_command
+from flowly_code.exec.approvals import (
+    ExecApprovalStore,
+    check_allowlist,
+    requires_approval,
+)
+
+
+async def execute_command(
+    request: ExecRequest,
+    config: ExecConfig,
+    store: ExecApprovalStore,
+) -> ExecResult:
+    """
+    Execute a command with full security checks.
+
+    Security flow:
+    1. Check if exec is enabled
+    2. Analyze command for safety
+    3. Check security mode (deny/allowlist/full)
+    4. Check allowlist if in allowlist mode
+    5. Request approval if needed
+    6. Execute command with timeout
+    """
+    # Check if enabled
+    if not config.enabled:
+        return ExecResult(
+            success=False,
+            denied=True,
+            error="Command execution is disabled"
+        )
+
+    # Analyze command
+    analysis = analyze_command(request.command)
+
+    # Check for dangerous patterns
+    if analysis.has_dangerous_chars:
+        return ExecResult(
+            success=False,
+            denied=True,
+            error=f"Command rejected: {analysis.reason}"
+        )
+
+    # Get store config
+    store_config = store.config
+
+    # Security mode check
+    if store_config.security == "deny":
+        return ExecResult(
+            success=False,
+            denied=True,
+            error="Command execution denied by security policy"
+        )
+
+    # Allowlist mode
+    if store_config.security == "allowlist":
+        allowlist_ok = check_allowlist(store, analysis.resolved_path, analysis.executable)
+
+        # Check if approval is required
+        if requires_approval(store_config, analysis.ok, allowlist_ok):
+            # Create pending approval
+            pending = store.create_pending(request, config.approval_timeout_seconds)
+
+            # Request approval via callback (Telegram)
+            decision = await store.request_approval(pending)
+
+            if decision is None:
+                # Timeout or no callback
+                return ExecResult(
+                    success=False,
+                    denied=True,
+                    error="Approval timed out or not available"
+                )
+
+            if decision == "deny":
+                store.resolve_pending(pending.id, decision)
+                return ExecResult(
+                    success=False,
+                    denied=True,
+                    error="Command denied by user"
+                )
+
+            # Allow-once or allow-always
+            store.resolve_pending(pending.id, decision)
+
+        elif not allowlist_ok and not analysis.is_safe_bin:
+            # Not in allowlist and not a safe bin
+            return ExecResult(
+                success=False,
+                denied=True,
+                error=f"Command not in allowlist: {analysis.executable}"
+            )
+
+    # Execute the command
+    timeout = request.timeout or config.timeout_seconds
+    cwd = request.cwd or str(Path.home())
+
+    try:
+        # Build environment
+        env = None
+        if request.env:
+            import os
+            env = os.environ.copy()
+            env.update(request.env)
+
+        # Background mode: start process and return immediately with PID
+        if request.background:
+            process = await asyncio.create_subprocess_shell(
+                request.command,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+                cwd=cwd,
+                env=env,
+                start_new_session=True,
+            )
+            logger.info(f"Background process started: PID={process.pid}, cmd={request.command[:80]}")
+            return ExecResult(
+                success=True,
+                pid=process.pid,
+                stdout=f"Process started in background (PID: {process.pid})",
+            )
+
+        # Foreground mode: run and wait for completion
+        process = await asyncio.create_subprocess_shell(
+            request.command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=env,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            return ExecResult(
+                success=False,
+                exit_code=-1,
+                error=f"Command timed out after {timeout} seconds",
+                timed_out=True
+            )
+
+        # Decode output
+        stdout_str = stdout.decode('utf-8', errors='replace')
+        stderr_str = stderr.decode('utf-8', errors='replace')
+
+        # Truncate if too long
+        max_output = config.max_output_chars
+        if len(stdout_str) > max_output:
+            stdout_str = stdout_str[:max_output] + f"\n... (truncated, {len(stdout_str)} total chars)"
+        if len(stderr_str) > max_output:
+            stderr_str = stderr_str[:max_output] + f"\n... (truncated, {len(stderr_str)} total chars)"
+
+        return ExecResult(
+            success=process.returncode == 0,
+            exit_code=process.returncode,
+            stdout=stdout_str,
+            stderr=stderr_str,
+        )
+
+    except Exception as e:
+        logger.error(f"Command execution error: {e}")
+        return ExecResult(
+            success=False,
+            error=str(e)
+        )

flowly_code/exec/safety.py

@@ -0,0 +1,247 @@
+"""Command safety analysis and validation."""
+
+import platform
+import re
+import shlex
+import shutil
+from pathlib import Path
+
+from flowly_code.exec.types import CommandAnalysis
+
+# Safe binaries that only operate on stdin (no file args)
+DEFAULT_SAFE_BINS = frozenset([
+    "jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc",
+    "cat", "echo", "date", "whoami", "pwd", "hostname", "uname",
+])
+
+# Dangerous shell metacharacters
+SHELL_METACHARS = re.compile(r'[;&|`$<>]')
+CONTROL_CHARS = re.compile(r'[\r\n\x00]')
+QUOTE_CHARS = re.compile(r'["\']')
+
+# Patterns for dangerous commands (Unix)
+_UNIX_DANGEROUS_PATTERNS = [
+    re.compile(r'\brm\s+(-[rf]+\s+)*/', re.IGNORECASE),  # rm -rf /
+    re.compile(r'\bsudo\b', re.IGNORECASE),
+    re.compile(r'\bchmod\s+777', re.IGNORECASE),
+    re.compile(r'\bchown\b.*root', re.IGNORECASE),
+    re.compile(r'\bmkfs\b', re.IGNORECASE),
+    re.compile(r'\bdd\b.*of=/', re.IGNORECASE),
+    re.compile(r'>\s*/dev/', re.IGNORECASE),
+    re.compile(r'\bcurl\b.*\|\s*(ba)?sh', re.IGNORECASE),  # curl | sh
+    re.compile(r'\bwget\b.*\|\s*(ba)?sh', re.IGNORECASE),  # wget | sh
+    re.compile(r':(){.*};:', re.IGNORECASE),  # Fork bomb
+]
+
+# Patterns for dangerous commands (Windows)
+_WINDOWS_DANGEROUS_PATTERNS = [
+    re.compile(r'\bformat\b\s+[a-z]:', re.IGNORECASE),  # format C:
+    re.compile(r'\bdiskpart\b', re.IGNORECASE),
+    re.compile(r'\breg\b\s+delete', re.IGNORECASE),  # reg delete
+    re.compile(r'\bcipher\b\s+/w', re.IGNORECASE),  # cipher /w (wipe)
+    re.compile(r'\bdel\b\s+/[sfq]', re.IGNORECASE),  # del /s /f /q
+    re.compile(r'\brd\b\s+/s', re.IGNORECASE),  # rd /s (recursive delete)
+    re.compile(r'\brmdir\b\s+/s', re.IGNORECASE),  # rmdir /s
+    re.compile(r'\bnet\b\s+user\b.*\b/delete\b', re.IGNORECASE),  # net user /delete
+    re.compile(r'\bbcdedit\b', re.IGNORECASE),  # boot config
+    re.compile(r'\brunas\b\s+/user:administrator', re.IGNORECASE),
+]
+
+DANGEROUS_PATTERNS = (
+    _UNIX_DANGEROUS_PATTERNS + _WINDOWS_DANGEROUS_PATTERNS
+    if platform.system() == "Windows"
+    else _UNIX_DANGEROUS_PATTERNS
+)
+
+# Pipeline operators that are not allowed in allowlist mode
+DISALLOWED_PIPELINE_OPS = {'||', '|&', '`', '$(', '\n', '\r', '(', ')'}
+
+
+def is_safe_executable(value: str | None) -> bool:
+    """Check if a string is safe to use as an executable name."""
+    if not value:
+        return False
+
+    trimmed = value.strip()
+    if not trimmed:
+        return False
+
+    # Check for dangerous characters
+    if '\0' in trimmed:
+        return False
+    if CONTROL_CHARS.search(trimmed):
+        return False
+    if SHELL_METACHARS.search(trimmed):
+        return False
+
+    return True
+
+
+def resolve_executable(name: str) -> str | None:
+    """Resolve an executable name to its full path."""
+    import os
+
+    # If it's already a path (check both Unix and Windows separators)
+    if '/' in name or '\\' in name or os.sep in name:
+        path = Path(name).expanduser().resolve()
+        if path.exists() and path.is_file():
+            return str(path)
+        return None
+
+    # Use shutil.which to find in PATH
+    return shutil.which(name)
+
+
+def is_safe_bin(executable: str, args: list[str]) -> bool:
+    """Check if command is a safe stdin-only binary with safe args."""
+    import os
+
+    # Get basename (handle both Unix and Windows paths)
+    name = Path(executable).name if ('/' in executable or '\\' in executable or os.sep in executable) else executable
+
+    if name not in DEFAULT_SAFE_BINS:
+        return False
+
+    # Check args don't reference files
+    for arg in args:
+        # Skip flags
+        if arg.startswith('-'):
+            continue
+        # Check if arg looks like a path
+        if '/' in arg or '\\' in arg or arg.startswith('~'):
+            return False
+        # Check if arg is an existing file
+        if Path(arg).exists():
+            return False
+
+    return True
+
+
+def has_dangerous_pattern(command: str) -> bool:
+    """Check if command matches any dangerous patterns."""
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(command):
+            return True
+    return False
+
+
+def split_pipeline(command: str) -> tuple[bool, str | None, list[str]]:
+    """
+    Split a command into pipeline segments.
+
+    Returns (ok, reason, segments).
+    """
+    # Check for disallowed operators
+    for op in DISALLOWED_PIPELINE_OPS:
+        if op in command:
+            return False, f"Disallowed operator: {op}", []
+
+    # Check for command substitution
+    if '$(' in command or '`' in command:
+        return False, "Command substitution not allowed", []
+
+    # Check for redirection
+    if re.search(r'[<>]', command):
+        return False, "Redirection not allowed in allowlist mode", []
+
+    # Split by pipe
+    segments = [s.strip() for s in command.split('|')]
+
+    # Validate each segment
+    for seg in segments:
+        if not seg:
+            return False, "Empty pipeline segment", []
+
+    return True, None, segments
+
+
+def parse_command(command: str) -> tuple[str | None, list[str]]:
+    """Parse a command into executable and arguments."""
+    try:
+        parts = shlex.split(command)
+        if not parts:
+            return None, []
+        return parts[0], parts[1:]
+    except ValueError:
+        return None, []
+
+
+def analyze_command(command: str) -> CommandAnalysis:
+    """
+    Analyze a shell command for safety.
+
+    Returns a CommandAnalysis with details about the command.
+    """
+    command = command.strip()
+
+    if not command:
+        return CommandAnalysis(ok=False, reason="Empty command")
+
+    # Check for control characters
+    if CONTROL_CHARS.search(command):
+        return CommandAnalysis(
+            ok=False,
+            reason="Control characters not allowed",
+            has_dangerous_chars=True
+        )
+
+    # Check for dangerous patterns
+    if has_dangerous_pattern(command):
+        return CommandAnalysis(
+            ok=False,
+            reason="Command matches dangerous pattern",
+            has_dangerous_chars=True
+        )
+
+    # Check if it's a pipeline
+    is_pipeline = '|' in command and '||' not in command
+
+    if is_pipeline:
+        ok, reason, segments = split_pipeline(command)
+        if not ok:
+            return CommandAnalysis(
+                ok=False,
+                reason=reason,
+                is_pipeline=True,
+                has_dangerous_chars=True
+            )
+
+        # For pipelines, analyze the first segment
+        executable, args = parse_command(segments[0])
+        resolved = resolve_executable(executable) if executable else None
+
+        return CommandAnalysis(
+            ok=True,
+            executable=executable,
+            resolved_path=resolved,
+            args=args,
+            is_pipeline=True,
+            segments=segments,
+            is_safe_bin=is_safe_bin(executable, args) if executable else False
+        )
+
+    # Single command
+    executable, args = parse_command(command)
+
+    if not executable:
+        return CommandAnalysis(ok=False, reason="Could not parse command")
+
+    # Check for shell metachars in the executable
+    if SHELL_METACHARS.search(executable):
+        return CommandAnalysis(
+            ok=False,
+            reason="Shell metacharacters in executable",
+            has_dangerous_chars=True
+        )
+
+    # Resolve the executable path
+    resolved = resolve_executable(executable)
+
+    return CommandAnalysis(
+        ok=True,
+        executable=executable,
+        resolved_path=resolved,
+        args=args,
+        is_pipeline=False,
+        is_safe_bin=is_safe_bin(executable, args)
+    )

flowly_code/exec/types.py

@@ -0,0 +1,88 @@
+"""Type definitions for secure command execution."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+# Security modes
+ExecSecurity = Literal["deny", "allowlist", "full"]
+
+# Ask modes for approval
+ExecAsk = Literal["off", "on-miss", "always"]
+
+# Execution host
+ExecHost = Literal["local", "sandbox"]
+
+# Approval decisions
+ExecApprovalDecision = Literal["allow-once", "allow-always", "deny"]
+
+
+@dataclass
+class ExecConfig:
+    """Configuration for command execution."""
+    enabled: bool = False
+    security: ExecSecurity = "deny"
+    ask: ExecAsk = "on-miss"
+    ask_fallback: ExecSecurity = "deny"
+    host: ExecHost = "local"
+    timeout_seconds: int = 300  # 5 minutes default
+    max_output_chars: int = 200_000  # 200KB
+    approval_timeout_seconds: int = 120  # 2 minutes to approve
+
+
+@dataclass
+class AllowlistEntry:
+    """An entry in the exec allowlist."""
+    pattern: str
+    last_used_at: int | None = None
+    last_used_command: str | None = None
+    last_resolved_path: str | None = None
+
+
+@dataclass
+class ExecRequest:
+    """A request to execute a command."""
+    command: str
+    cwd: str | None = None
+    timeout: int | None = None
+    env: dict[str, str] | None = None
+    session_key: str | None = None
+    background: bool = False
+
+
+@dataclass
+class ExecResult:
+    """Result of command execution."""
+    success: bool
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""
+    error: str | None = None
+    timed_out: bool = False
+    denied: bool = False
+    approval_required: bool = False
+    pid: int | None = None
+
+
+@dataclass
+class CommandAnalysis:
+    """Analysis of a shell command for safety."""
+    ok: bool
+    reason: str | None = None
+    executable: str | None = None
+    resolved_path: str | None = None
+    args: list[str] = field(default_factory=list)
+    is_pipeline: bool = False
+    segments: list[str] = field(default_factory=list)
+    has_dangerous_chars: bool = False
+    is_safe_bin: bool = False
+
+
+@dataclass
+class PendingApproval:
+    """A pending approval request."""
+    id: str
+    request: ExecRequest
+    created_at: float
+    expires_at: float
+    session_key: str | None = None
+    resolved_path: str | None = None

flowly_code/gateway/__init__.py

@@ -0,0 +1,5 @@
+"""Gateway API for external integrations."""
+
+from flowly_code.gateway.server import GatewayServer
+
+__all__ = ["GatewayServer"]

flowly_code/gateway/server.py

@@ -0,0 +1,103 @@
+"""HTTP API server for gateway integrations."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from aiohttp import web
+from loguru import logger
+
+from flowly_code.activity.bus import ActivityBus
+
+# Maximum allowed request body size (1MB)
+_MAX_BODY_SIZE = 1024 * 1024
+
+
+class GatewayServer:
+    """
+    HTTP API server for health check and integrations.
+
+    Provides endpoints for:
+    - Health check (GET /health)
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 18790,
+        activity_bus: ActivityBus | None = None,
+    ):
+        """
+        Initialize the gateway server.
+
+        Args:
+            host: Host to bind to.
+            port: Port to listen on.
+            activity_bus: Optional activity bus for real-time event streaming.
+        """
+        self.host = host
+        self.port = port
+        self.activity_bus = activity_bus
+        self._app: web.Application | None = None
+        self._runner: web.AppRunner | None = None
+        self._site: web.TCPSite | None = None
+
+    def _create_app(self) -> web.Application:
+        """Create the aiohttp application."""
+        app = web.Application(client_max_size=_MAX_BODY_SIZE)
+        app.router.add_get("/health", self._handle_health)
+        if self.activity_bus is not None:
+            app.router.add_get(
+                "/api/activity/stream", self._handle_activity_stream
+            )
+        return app
+
+    async def _handle_health(self, request: web.Request) -> web.Response:
+        """Health check endpoint."""
+        return web.json_response({"status": "ok"})
+
+    async def _handle_activity_stream(
+        self, request: web.Request
+    ) -> web.StreamResponse:
+        """SSE endpoint for real-time agent activity events."""
+        response = web.StreamResponse(
+            status=200,
+            reason="OK",
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Access-Control-Allow-Origin": "http://127.0.0.1:7777",
+            },
+        )
+        await response.prepare(request)
+
+        sub_id, events = await self.activity_bus.subscribe()
+        try:
+            async for event in events:
+                data = json.dumps(event.to_dict())
+                await response.write(f"data: {data}\n\n".encode("utf-8"))
+        except (ConnectionResetError, asyncio.CancelledError):
+            pass
+        finally:
+            await self.activity_bus.unsubscribe(sub_id)
+
+        return response
+
+    async def start(self) -> None:
+        """Start the HTTP server."""
+        self._app = self._create_app()
+        self._runner = web.AppRunner(self._app)
+        await self._runner.setup()
+        self._site = web.TCPSite(self._runner, self.host, self.port)
+        await self._site.start()
+        logger.info(f"Gateway API listening on http://{self.host}:{self.port}")
+
+    async def stop(self) -> None:
+        """Stop the HTTP server."""
+        if self._site:
+            await self._site.stop()
+        if self._runner:
+            await self._runner.cleanup()
+        logger.info("Gateway API stopped")

flowly_code/heartbeat/__init__.py

@@ -0,0 +1,5 @@
+"""Heartbeat service for periodic agent wake-ups."""
+
+from flowly_code.heartbeat.service import HeartbeatService
+
+__all__ = ["HeartbeatService"]