iflow-mcp_developermode-korea_reversecore-mcp 1.0.0__py3-none-any.whl

reversecore_mcp/core/security.py

@@ -0,0 +1,213 @@
+"""
+Security utilities for input validation and sanitization.
+
+This module provides functions to validate and sanitize user inputs before
+they are used in subprocess calls, preventing command injection and
+unauthorized file access.
+
+Note: For radare2 command validation, use the improved regex-based validation
+in command_spec.py which provides stronger security guarantees.
+"""
+
+import threading
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+from reversecore_mcp.core.config import get_config
+from reversecore_mcp.core.exceptions import ValidationError
+
+# Configuration constants
+PATH_VALIDATION_CACHE_SIZE = 256  # Number of path resolutions to cache
+
+
+@dataclass(frozen=True)
+class WorkspaceConfig:
+    """Immutable configuration for workspace-aware file validation."""
+
+    workspace: Path
+    read_only_dirs: tuple[Path, ...]
+
+    @classmethod
+    def from_env(cls) -> "WorkspaceConfig":
+        """Create a workspace configuration from the cached Config instance."""
+        config = get_config()
+        return cls(workspace=config.workspace, read_only_dirs=config.read_only_dirs)
+
+
+# Lazy-initialized workspace configuration with thread safety
+# This avoids initialization errors when the module is imported before
+# environment variables are set (common in test fixtures)
+_WORKSPACE_CONFIG: WorkspaceConfig | None = None
+_WORKSPACE_CONFIG_LOCK = threading.Lock()
+
+
+def get_workspace_config() -> WorkspaceConfig:
+    """
+    Get the workspace configuration, initializing it lazily on first access.
+
+    This lazy initialization pattern allows tests to set up environment
+    variables or mock configurations before the first access.
+    Thread-safe via double-checked locking pattern.
+
+    Returns:
+        WorkspaceConfig instance
+    """
+    global _WORKSPACE_CONFIG
+    if _WORKSPACE_CONFIG is None:
+        with _WORKSPACE_CONFIG_LOCK:
+            if _WORKSPACE_CONFIG is None:
+                _WORKSPACE_CONFIG = WorkspaceConfig.from_env()
+    return _WORKSPACE_CONFIG
+
+
+def refresh_workspace_config() -> WorkspaceConfig:
+    """Recompute the default workspace configuration (mainly for tests)."""
+    global _WORKSPACE_CONFIG
+    with _WORKSPACE_CONFIG_LOCK:
+        _WORKSPACE_CONFIG = WorkspaceConfig.from_env()
+        # Clear the path resolution cache when config changes
+        _resolve_path_cached.cache_clear()
+    return _WORKSPACE_CONFIG
+
+
+def reset_workspace_config() -> None:
+    """
+    Reset the workspace configuration to uninitialized state.
+
+    This is useful for tests that need to change environment variables
+    and have the configuration re-read on next access.
+    """
+    global _WORKSPACE_CONFIG
+    with _WORKSPACE_CONFIG_LOCK:
+        _WORKSPACE_CONFIG = None
+        _resolve_path_cached.cache_clear()
+
+
+@lru_cache(maxsize=PATH_VALIDATION_CACHE_SIZE)
+def _resolve_path_cached(path_str: str) -> tuple[Path, bool, str]:
+    """
+    Cached path resolution to avoid repeated filesystem calls.
+
+    Returns:
+        Tuple of (resolved_path, is_file, error_message)
+        If resolution fails, returns (original_path, False, error_message)
+    """
+    try:
+        file_path = Path(path_str)
+        abs_path = file_path.resolve(strict=True)
+        is_file = abs_path.is_file()
+        return (abs_path, is_file, "")
+    except (OSError, RuntimeError) as e:
+        return (Path(path_str), False, str(e))
+
+
+def validate_file_path(
+    path: str,
+    read_only: bool = False,
+    config: WorkspaceConfig | None = None,
+) -> Path:
+    """
+    Validate and normalize a file path.
+
+    This function ensures that:
+    1. The path exists and points to a file (not a directory)
+    2. The path is within the allowed workspace directory (REVERSECORE_WORKSPACE)
+       or within allowed read-only directories (if read_only=True)
+    3. The path is resolved to an absolute path
+
+    The workspace directory is determined by an immutable WorkspaceConfig that
+    is loaded once from environment variables (REVERSECORE_WORKSPACE and
+    REVERSECORE_READ_DIRS).
+
+    Performance: Uses LRU cache for path resolution to avoid repeated
+    filesystem calls for frequently accessed files.
+
+    Args:
+        path: The file path to validate
+        read_only: If True, also allow files from configured read-only directories
+        config: Optional WorkspaceConfig override (useful for tests)
+
+    Returns:
+        The normalized absolute file path as a Path instance
+
+    Raises:
+        ValueError: If the path is invalid, doesn't exist, or is outside
+                   the allowed directories
+    """
+    active_config = config or get_workspace_config()
+
+    # Handle relative paths: resolve them relative to workspace directory
+    # This allows users to specify just the filename (e.g., "sample.exe")
+    # instead of the full path ("/app/workspace/sample.exe")
+    file_path = Path(path)
+
+    # Defense against AI mistakes: if a host-side absolute path is passed
+    # (e.g., "/Users/john/Reversecore_Workspace/sample.exe"), extract just
+    # the filename and try to find it in the workspace directory.
+    # This handles cases where AI ignores the prompt instructions.
+    if file_path.is_absolute() and not str(file_path).startswith(str(active_config.workspace)):
+        # Path is absolute but not in workspace - likely a host path
+        # Extract filename and try workspace
+        filename_only = file_path.name
+        workspace_path = active_config.workspace / filename_only
+        if workspace_path.exists():
+            path = str(workspace_path)
+        # If not found, continue with original path (will error with helpful message)
+
+    if not file_path.is_absolute():
+        # Try workspace-relative path first
+        workspace_path = active_config.workspace / path
+        if workspace_path.exists():
+            path = str(workspace_path)
+
+    # Use cached path resolution to avoid repeated filesystem calls
+    abs_path, is_file, error = _resolve_path_cached(path)
+
+    if error:
+        raise ValidationError(
+            f"Invalid file path: {path}. Error: {error}",
+            details={
+                "path": path,
+                "error": error,
+                "hint": "Ensure the file is in the workspace directory",
+            },
+        )
+
+    # Check that it's a file, not a directory
+    if not is_file:
+        raise ValidationError(
+            f"Path does not point to a file: {abs_path}",
+            details={"path": str(abs_path)},
+        )
+
+    def _is_relative_to(base: Path) -> bool:
+        try:
+            abs_path.relative_to(base)
+            return True
+        except ValueError:
+            return False
+
+    is_in_workspace = _is_relative_to(active_config.workspace)
+    if is_in_workspace and not read_only:
+        return abs_path
+
+    is_in_read_dir = False
+    if read_only and not is_in_workspace:
+        for read_dir in active_config.read_only_dirs:
+            if _is_relative_to(read_dir):
+                is_in_read_dir = True
+                break
+
+    if not (is_in_workspace or is_in_read_dir):
+        allowed_dirs = [str(active_config.workspace)]
+        if read_only:
+            allowed_dirs.extend(str(d) for d in active_config.read_only_dirs)
+        raise ValidationError(
+            f"File path is outside allowed directories: {abs_path}. "
+            f"Allowed directories: {allowed_dirs}. "
+            f"Set REVERSECORE_WORKSPACE or REVERSECORE_READ_DIRS environment variables to change allowed paths.",
+            details={"path": str(abs_path), "allowed_directories": allowed_dirs},
+        )
+
+    return abs_path

reversecore_mcp/core/validators.py

@@ -0,0 +1,238 @@
+"""
+Input validators for tool-specific parameters.
+"""
+
+import re
+from typing import Any
+
+from reversecore_mcp.core.config import get_config
+from reversecore_mcp.core.exceptions import ValidationError
+
+# Pre-compile address validation pattern for performance
+# Allow alphanumeric, dots, underscores, and C++ symbol chars (:, <, >, ~, *, &, [, ], (, ), -, ,, @)
+_ADDRESS_PATTERN = re.compile(r"^[a-zA-Z0-9_:.<>~*&\[\]()\-,@]+$")
+
+# OPTIMIZATION: Pre-compile pattern for hex prefix removal
+_HEX_PREFIX_PATTERN = re.compile(r"^0[xX]")
+
+
+def validate_address_format(address: str, param_name: str = "address") -> None:
+    """
+    Validate address format to prevent shell injection.
+
+    Ensures the address contains only safe characters: alphanumeric, dots,
+    underscores, and optional '0x' prefix.
+
+    Args:
+        address: The address string to validate (e.g., 'main', '0x401000', 'sym.decrypt')
+        param_name: Name of the parameter for error messages (default: 'address')
+
+    Raises:
+        ValidationError: If address format is invalid
+    """
+    # OPTIMIZATION: Use pre-compiled regex pattern instead of replace
+    clean_address = _HEX_PREFIX_PATTERN.sub("", address)
+
+    if not _ADDRESS_PATTERN.match(clean_address):
+        raise ValidationError(
+            f"{param_name} must contain only safe characters (alphanumeric, dots, underscores, "
+            "and C++ symbol characters like :, <, >)"
+        )
+
+
+def validate_tool_parameters(tool_name: str, params: dict[str, Any]) -> None:
+    """
+    Validate tool-specific parameters.
+
+    Args:
+        tool_name: Name of the tool
+        params: Parameters to validate
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    validators = {
+        "run_strings": _validate_strings_params,
+        "run_radare2": _validate_radare2_params,
+        "disassemble_with_capstone": _validate_capstone_params,
+        "run_yara": _validate_yara_params,
+        "generate_function_graph": _validate_cfg_params,
+        "emulate_machine_code": _validate_emulation_params,
+        "get_pseudo_code": _validate_pseudo_code_params,
+        "generate_signature": _validate_signature_params,
+        "extract_rtti_info": _validate_rtti_params,
+        "smart_decompile": _validate_decompile_params,
+        "generate_yara_rule": _validate_yara_generation_params,
+        "diff_binaries": _validate_diff_binaries_params,
+        "match_libraries": _validate_match_libraries_params,
+    }
+
+    if tool_name in validators:
+        validators[tool_name](params)
+
+
+def _validate_strings_params(params: dict[str, Any]) -> None:
+    """Validate run_strings parameters."""
+    min_length = params.get("min_length", 4)
+    if not isinstance(min_length, int) or min_length < 1:
+        raise ValidationError("min_length must be a positive integer")
+
+    max_output_size = params.get("max_output_size", get_config().max_output_size)
+    if not isinstance(max_output_size, int) or max_output_size < 1:
+        raise ValidationError("max_output_size must be a positive integer")
+
+
+def _validate_radare2_params(params: dict[str, Any]) -> None:
+    """Validate run_radare2 parameters."""
+    if "r2_command" not in params:
+        raise ValidationError("r2_command is required")
+
+    if not isinstance(params["r2_command"], str):
+        raise ValidationError("r2_command must be a string")
+
+
+def _validate_capstone_params(params: dict[str, Any]) -> None:
+    """Validate disassemble_with_capstone parameters."""
+    offset = params.get("offset", 0)
+    if not isinstance(offset, int) or offset < 0:
+        raise ValidationError("offset must be a non-negative integer")
+
+    size = params.get("size", 1024)
+    if not isinstance(size, int) or size < 1:
+        raise ValidationError("size must be a positive integer")
+
+    # Note: Architecture validation is done by the tool function itself
+    # to provide more detailed error messages
+
+
+def _validate_yara_params(params: dict[str, Any]) -> None:
+    """Validate run_yara parameters."""
+    if "rule_file" not in params:
+        raise ValidationError("rule_file is required")
+
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")
+
+
+def _validate_cfg_params(params: dict[str, Any]) -> None:
+    """Validate generate_function_graph parameters."""
+    if "function_address" in params:
+        if not isinstance(params["function_address"], str):
+            raise ValidationError("function_address must be a string")
+
+    output_format = params.get("format", "mermaid")
+    allowed_formats = ["json", "mermaid", "dot"]
+    if output_format not in allowed_formats:
+        raise ValidationError(
+            f"Invalid format '{output_format}'. Allowed: {', '.join(allowed_formats)}"
+        )
+
+
+def _validate_emulation_params(params: dict[str, Any]) -> None:
+    """Validate emulate_machine_code parameters."""
+    if "start_address" in params:
+        if not isinstance(params["start_address"], str):
+            raise ValidationError("start_address must be a string")
+
+    instructions = params.get("instructions", 50)
+    if not isinstance(instructions, int):
+        raise ValidationError("instructions must be an integer")
+
+    # Critical: Prevent infinite loops and CPU exhaustion
+    if instructions < 1:
+        raise ValidationError("instructions must be at least 1")
+
+    max_instructions = get_config().max_emulation_instructions
+    if instructions > max_instructions:
+        raise ValidationError(
+            f"instructions cannot exceed {max_instructions} (safety limit to prevent CPU exhaustion)"
+        )
+
+
+def _validate_pseudo_code_params(params: dict[str, Any]) -> None:
+    """Validate get_pseudo_code parameters."""
+    if "address" in params:
+        if not isinstance(params["address"], str):
+            raise ValidationError("address must be a string")
+
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")
+
+
+def _validate_signature_params(params: dict[str, Any]) -> None:
+    """Validate generate_signature parameters."""
+    if "address" not in params:
+        raise ValidationError("address is required")
+
+    if not isinstance(params["address"], str):
+        raise ValidationError("address must be a string")
+
+    length = params.get("length", 32)
+    if not isinstance(length, int) or length < 1 or length > 1024:
+        raise ValidationError("length must be between 1 and 1024 bytes")
+
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")
+
+
+def _validate_rtti_params(params: dict[str, Any]) -> None:
+    """Validate extract_rtti_info parameters."""
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")
+
+
+def _validate_decompile_params(params: dict[str, Any]) -> None:
+    """Validate smart_decompile parameters."""
+    if "function_address" in params:
+        if not isinstance(params["function_address"], str):
+            raise ValidationError("function_address must be a string")
+
+
+def _validate_yara_generation_params(params: dict[str, Any]) -> None:
+    """Validate generate_yara_rule parameters."""
+    if "function_address" in params:
+        if not isinstance(params["function_address"], str):
+            raise ValidationError("function_address must be a string")
+
+    if "byte_length" in params:
+        byte_length = params["byte_length"]
+        if not isinstance(byte_length, int):
+            raise ValidationError("byte_length must be a positive integer")
+        if byte_length < 1:
+            raise ValidationError("byte_length must be a positive integer")
+        if byte_length > 1024:
+            raise ValidationError("byte_length cannot exceed 1024")
+
+    if "rule_name" in params:
+        if not isinstance(params["rule_name"], str):
+            raise ValidationError("rule_name must be a string")
+
+
+def _validate_diff_binaries_params(params: dict[str, Any]) -> None:
+    """Validate diff_binaries parameters."""
+    if "function_name" in params and params["function_name"] is not None:
+        if not isinstance(params["function_name"], str):
+            raise ValidationError("function_name must be a string")
+
+    max_output_size = params.get("max_output_size", 10_000_000)
+    if not isinstance(max_output_size, int) or max_output_size < 1:
+        raise ValidationError("max_output_size must be a positive integer")
+
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")
+
+
+def _validate_match_libraries_params(params: dict[str, Any]) -> None:
+    """Validate match_libraries parameters."""
+    max_output_size = params.get("max_output_size", 10_000_000)
+    if not isinstance(max_output_size, int) or max_output_size < 1:
+        raise ValidationError("max_output_size must be a positive integer")
+
+    timeout = params.get("timeout", 300)
+    if not isinstance(timeout, int) or timeout < 1:
+        raise ValidationError("timeout must be a positive integer")

reversecore_mcp/dashboard/__init__.py

@@ -0,0 +1,221 @@
+"""
+Web Dashboard for Reversecore MCP.
+
+Provides a visual interface for binary analysis using FastAPI + Jinja2.
+
+SECURITY NOTES:
+- All user-provided data (filenames, binary strings) is auto-escaped by Jinja2
+- Path traversal protection via validate_file_path()
+- CSRF tokens required for state-changing operations
+"""
+
+import html
+import secrets
+from pathlib import Path
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+# Setup paths
+DASHBOARD_DIR = Path(__file__).parent
+TEMPLATES_DIR = DASHBOARD_DIR / "templates"
+STATIC_DIR = DASHBOARD_DIR / "static"
+
+# Create router
+router = APIRouter(prefix="/dashboard", tags=["dashboard"])
+
+# Setup templates with auto-escaping enabled (default)
+templates = Jinja2Templates(directory=str(TEMPLATES_DIR))
+
+# CSRF token storage (in production, use Redis or database)
+_csrf_tokens: dict[str, str] = {}
+
+
+def _generate_csrf_token(session_id: str) -> str:
+    """Generate a CSRF token for a session."""
+    token = secrets.token_urlsafe(32)
+    _csrf_tokens[session_id] = token
+    return token
+
+
+def _verify_csrf_token(session_id: str, token: str) -> bool:
+    """Verify a CSRF token."""
+    expected = _csrf_tokens.get(session_id)
+    return expected is not None and secrets.compare_digest(expected, token)
+
+
+def _sanitize_for_display(text: str, max_length: int = 1000) -> str:
+    """
+    Sanitize binary-extracted text for safe display.
+
+    This is a defense-in-depth measure on top of Jinja2's auto-escaping.
+    """
+    if not isinstance(text, str):
+        text = str(text)
+    # Truncate long strings
+    if len(text) > max_length:
+        text = text[:max_length] + "... [truncated]"
+    # HTML escape (Jinja2 does this, but we double-check for safety)
+    return html.escape(text)
+
+
+def get_router() -> APIRouter:
+    """Get the dashboard router."""
+    return router
+
+
+def get_static_files() -> StaticFiles:
+    """Get static files mount."""
+    return StaticFiles(directory=str(STATIC_DIR))
+
+
+@router.get("/", response_class=HTMLResponse)
+async def dashboard_index(request: Request):
+    """Dashboard overview page."""
+    from reversecore_mcp.core.config import get_config
+
+    settings = get_config()
+    workspace = settings.workspace
+
+    # Get list of files in workspace
+    files = []
+    if workspace.exists():
+        for f in workspace.iterdir():
+            if f.is_file() and not f.name.startswith("."):
+                stat = f.stat()
+                # Sanitize filename for display (defense in depth)
+                files.append(
+                    {
+                        "name": _sanitize_for_display(f.name, 255),
+                        "name_raw": f.name,  # For URL construction
+                        "size": stat.st_size,
+                        "modified": stat.st_mtime,
+                    }
+                )
+
+    # Sort by modified time (newest first)
+    files.sort(key=lambda x: x["modified"], reverse=True)
+
+    return templates.TemplateResponse(
+        "index.html",
+        {
+            "request": request,
+            "files": files,
+            "workspace": str(workspace),
+            "file_count": len(files),
+        },
+    )
+
+
+@router.get("/analysis/{filename}", response_class=HTMLResponse)
+async def dashboard_analysis(request: Request, filename: str):
+    """Analysis page for a specific file."""
+    from reversecore_mcp.core.config import get_config
+    from reversecore_mcp.core.security import validate_file_path
+
+    settings = get_config()
+    file_path = settings.workspace / filename
+
+    try:
+        validated_path = validate_file_path(str(file_path))
+    except Exception as e:
+        return templates.TemplateResponse(
+            "error.html",
+            {"request": request, "error": _sanitize_for_display(str(e))},
+        )
+
+    # Get basic file info
+    file_info = {
+        "name": _sanitize_for_display(validated_path.name, 255),
+        "path": str(validated_path),
+        "size": validated_path.stat().st_size,
+    }
+
+    # Try to get functions list
+    functions = []
+    disasm = ""
+
+    try:
+        from reversecore_mcp.tools.radare2.r2_session import R2Session
+
+        session = R2Session(str(validated_path))
+        session.analyze(level=1)
+
+        # Get functions
+        funcs_json = session.cmdj("aflj") or []
+        for func in funcs_json[:50]:  # Limit to 50
+            # SECURITY: Sanitize function names from binary
+            functions.append(
+                {
+                    "name": _sanitize_for_display(func.get("name", "unknown"), 100),
+                    "offset": hex(func.get("offset", 0)),
+                    "size": func.get("size", 0),
+                }
+            )
+
+        # Get entry point disassembly
+        raw_disasm = session.cmd("pdf @ entry0") or "No disassembly available"
+        # SECURITY: Sanitize disassembly output
+        disasm = _sanitize_for_display(raw_disasm, 50000)
+
+    except Exception as e:
+        disasm = f"Error: {_sanitize_for_display(str(e))}"
+
+    return templates.TemplateResponse(
+        "analysis.html",
+        {
+            "request": request,
+            "file": file_info,
+            "functions": functions,
+            "disasm": disasm,
+        },
+    )
+
+
+@router.get("/iocs/{filename}", response_class=HTMLResponse)
+async def dashboard_iocs(request: Request, filename: str):
+    """IOC extraction page."""
+    from reversecore_mcp.core.config import get_config
+    from reversecore_mcp.core.security import validate_file_path
+
+    settings = get_config()
+    file_path = settings.workspace / filename
+
+    try:
+        validated_path = validate_file_path(str(file_path))
+    except Exception as e:
+        return templates.TemplateResponse(
+            "error.html",
+            {"request": request, "error": _sanitize_for_display(str(e))},
+        )
+
+    # Extract IOCs
+    iocs: dict = {"urls": [], "ips": [], "emails": [], "strings": []}
+
+    try:
+        from reversecore_mcp.tools.malware.ioc_tools import extract_iocs
+
+        result = await extract_iocs(str(validated_path))
+        if result.status == "success" and isinstance(result.data, dict):
+            raw_iocs = result.data
+            # SECURITY: Sanitize all IOC values extracted from binary
+            iocs["urls"] = [_sanitize_for_display(u, 500) for u in raw_iocs.get("urls", [])]
+            iocs["ips"] = [_sanitize_for_display(ip, 50) for ip in raw_iocs.get("ips", [])]
+            iocs["emails"] = [_sanitize_for_display(e, 100) for e in raw_iocs.get("emails", [])]
+            iocs["strings"] = [
+                _sanitize_for_display(s, 200) for s in raw_iocs.get("strings", [])[:100]
+            ]
+
+    except Exception as e:
+        iocs["error"] = _sanitize_for_display(str(e))
+
+    return templates.TemplateResponse(
+        "iocs.html",
+        {
+            "request": request,
+            "filename": _sanitize_for_display(filename, 255),
+            "iocs": iocs,
+        },
+    )