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

reversecore_mcp/core/__init__.py

@@ -0,0 +1,78 @@
+"""
+Core utilities for Reversecore_MCP.
+
+This package contains security, execution, and exception handling utilities
+used across all tool modules.
+"""
+
+# Import decorators and helpers for public API
+# Import dependency injection container
+from reversecore_mcp.core.container import (
+    ServiceContainer,
+    container,
+    get_ghidra_service,
+    get_r2_pool,
+    get_resource_manager,
+)
+from reversecore_mcp.core.decorators import log_execution
+from reversecore_mcp.core.error_formatting import format_error, get_validation_hint
+from reversecore_mcp.core.exceptions import (
+    ExecutionTimeoutError,
+    OutputLimitExceededError,
+    ReversecoreError,
+    ToolNotFoundError,
+    ValidationError,
+)
+from reversecore_mcp.core.execution import (
+    execute_subprocess_async,
+    execute_subprocess_streaming,
+)
+from reversecore_mcp.core.logging_config import get_logger, setup_logging
+
+# Import shared R2 helper functions
+from reversecore_mcp.core.r2_helpers import (
+    build_r2_cmd,
+    calculate_dynamic_timeout,
+    escape_mermaid_chars,
+    execute_r2_command,
+    parse_json_output,
+    strip_address_prefixes,
+)
+
+# Import performance optimization modules
+from reversecore_mcp.core.r2_pool import R2ConnectionPool, r2_pool
+from reversecore_mcp.core.resource_manager import ResourceManager, resource_manager
+from reversecore_mcp.core.security import validate_file_path
+
+__all__ = [
+    "ReversecoreError",
+    "ToolNotFoundError",
+    "ExecutionTimeoutError",
+    "OutputLimitExceededError",
+    "ValidationError",
+    "execute_subprocess_streaming",
+    "execute_subprocess_async",
+    "validate_file_path",
+    "format_error",
+    "get_validation_hint",
+    "get_logger",
+    "setup_logging",
+    "log_execution",
+    "R2ConnectionPool",
+    "r2_pool",
+    "ResourceManager",
+    "resource_manager",
+    # R2 helper functions
+    "strip_address_prefixes",
+    "escape_mermaid_chars",
+    "build_r2_cmd",
+    "execute_r2_command",
+    "parse_json_output",
+    "calculate_dynamic_timeout",
+    # Dependency injection
+    "ServiceContainer",
+    "container",
+    "get_r2_pool",
+    "get_resource_manager",
+    "get_ghidra_service",
+]

reversecore_mcp/core/audit.py

@@ -0,0 +1,101 @@
+"""
+Audit Logging Module
+
+Provides a tamper-evident record of security-critical actions (uploads, patches, etc.).
+Logs are written to a separate file (audit.json) to distinguish from operational logs.
+"""
+
+import json
+import logging
+import time
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Optional
+
+from reversecore_mcp.core.config import get_config
+
+
+class AuditAction(str, Enum):
+    """Types of actions that require auditing."""
+    
+    FILE_UPLOAD = "FILE_UPLOAD"
+    BINARY_PATCH = "BINARY_PATCH"
+    FILE_DELETE = "FILE_DELETE"
+    CONFIG_CHANGE = "CONFIG_CHANGE"
+    AUTH_FAILURE = "AUTH_FAILURE"
+
+
+class AuditLogger:
+    """Specialized logger for security audit trails."""
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(AuditLogger, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self._initialized:
+            return
+            
+        settings = get_config()
+        self.log_file = settings.workspace.parent / "audit.json"  # Store outside workspace if possible, or root
+        # If workspace is root, maybe put in /var/log/reversecore if possible?
+        # For Docker, settings.workspace is /app/workspace. Parent is /app.
+        # Let's verify permission. If not, fallback to workspace.
+        
+        # Prepare file handler
+        self._logger = logging.getLogger("reversecore_audit")
+        self._logger.setLevel(logging.INFO)
+        self._logger.propagate = False
+        
+        try:
+            handler = logging.FileHandler(str(self.log_file), encoding="utf-8")
+            formatter = logging.Formatter("%(message)s")
+            handler.setFormatter(formatter)
+            self._logger.addHandler(handler)
+        except Exception:
+            # Fallback to standard log if separate file fails
+            self._logger = logging.getLogger("reversecore_mcp")
+            self._logger.warning("Failed to initialize separate audit log. Merging with app log.")
+        
+        self._initialized = True
+
+    def log_event(
+        self,
+        action: AuditAction | str,
+        resource: str,
+        status: str,
+        user: str = "system",
+        ip: str = "local",
+        details: Optional[dict[str, Any]] = None
+    ) -> None:
+        """
+        Record a security event.
+        
+        Args:
+            action: Type of action (e.g., FILE_UPLOAD)
+            resource: Target resource (filename, path)
+            status: SUCCESS or FAILURE
+            user: Username or ID
+            ip: Source IP
+            details: Additional context
+        """
+        event = {
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "action": str(action),
+            "resource": resource,
+            "status": status,
+            "user": user,
+            "ip": ip,
+            "details": details or {}
+        }
+        
+        self._logger.info(json.dumps(event))
+
+
+# Global instance
+audit_logger = AuditLogger()

reversecore_mcp/core/binary_cache.py

@@ -0,0 +1,138 @@
+"""
+Binary Metadata Cache
+
+This module provides caching for binary analysis results.
+It prevents redundant analysis of the same files.
+"""
+
+import time
+from pathlib import Path
+from typing import Any
+
+from reversecore_mcp.core.logging_config import get_logger
+from reversecore_mcp.core.metrics import metrics_collector
+
+logger = get_logger(__name__)
+
+# Configuration constants
+DEFAULT_CACHE_TTL_SECONDS = 60  # Default time-to-live for cache validation
+
+
+class BinaryMetadataCache:
+    """
+    Caches metadata for analyzed binaries.
+
+    Keyed by file path and modification time (or hash).
+
+    Performance optimizations:
+    - TTL-based validation to reduce stat() calls
+    - Cached mtime stored with last check time
+    - Configurable cache lifetime (default: 60 seconds)
+    """
+
+    def __init__(self, ttl_seconds: int = DEFAULT_CACHE_TTL_SECONDS):
+        self._cache: dict[str, Any] = {}
+        # Store (mtime, last_check_time) tuple to reduce stat() calls
+        self._file_timestamps: dict[str, tuple[float, float]] = {}
+        self._ttl_seconds = ttl_seconds
+
+    def _get_cache_key(self, file_path: str) -> str:
+        """Generate a cache key based on file path."""
+        return str(Path(file_path).absolute())
+
+    def _is_valid(self, file_path: str) -> bool:
+        """
+        Check if cache entry is valid (file hasn't changed).
+
+        Uses TTL-based checking to avoid excessive stat() calls:
+        - If checked within TTL window, assume valid (fast path)
+        - Otherwise, verify mtime hasn't changed (slow path)
+        """
+        key = self._get_cache_key(file_path)
+        if key not in self._cache:
+            return False
+
+        if key not in self._file_timestamps:
+            return False
+
+        cached_mtime, last_check_time = self._file_timestamps[key]
+        current_time = time.time()
+
+        # Fast path: If within TTL window, trust the cache without stat()
+        # Using < instead of <= for strict TTL boundary to avoid edge case stat() calls
+        if current_time - last_check_time < self._ttl_seconds:
+            return True
+
+        # Slow path: TTL expired, need to check file modification time
+        try:
+            actual_mtime = Path(file_path).stat().st_mtime
+            is_valid = cached_mtime == actual_mtime
+
+            if is_valid:
+                # Update last check time to reset TTL window
+                self._file_timestamps[key] = (cached_mtime, current_time)
+            else:
+                # File changed, invalidate cache
+                if key in self._cache:
+                    del self._cache[key]
+                if key in self._file_timestamps:
+                    del self._file_timestamps[key]
+
+            return is_valid
+        except FileNotFoundError:
+            # File deleted, invalidate cache
+            if key in self._cache:
+                del self._cache[key]
+            if key in self._file_timestamps:
+                del self._file_timestamps[key]
+            return False
+
+    def get(self, file_path: str, key: str) -> Any | None:
+        """Get a specific metadata item for a file."""
+        cache_key = self._get_cache_key(file_path)
+        if self._is_valid(file_path):
+            val = self._cache[cache_key].get(key)
+            if val is not None:
+                metrics_collector.record_cache_hit("binary_cache")
+                return val
+
+        metrics_collector.record_cache_miss("binary_cache")
+        return None
+
+    def set(self, file_path: str, key: str, value: Any):
+        """Set a specific metadata item for a file."""
+        cache_key = self._get_cache_key(file_path)
+
+        # Initialize if needed
+        if cache_key not in self._cache:
+            self._cache[cache_key] = {}
+
+        # Update timestamp with current time as last check
+        try:
+            mtime = Path(file_path).stat().st_mtime
+            self._file_timestamps[cache_key] = (mtime, time.time())
+        except FileNotFoundError:
+            # For memory/stream analysis or temp files that no longer exist,
+            # use current time as mtime to enable caching
+            # Without this, cache always misses because _is_valid returns False
+            current_time = time.time()
+            self._file_timestamps[cache_key] = (current_time, current_time)
+
+        self._cache[cache_key][key] = value
+        logger.debug(f"Cached {key} for {file_path}")
+
+    def clear(self, file_path: str = None):
+        """Clear cache for a specific file or all files."""
+        if file_path:
+            key = self._get_cache_key(file_path)
+            if key in self._cache:
+                del self._cache[key]
+            if key in self._file_timestamps:
+                del self._file_timestamps[key]
+        else:
+            self._cache.clear()
+            self._file_timestamps.clear()
+
+
+# Global instance with default TTL
+binary_cache = BinaryMetadataCache(ttl_seconds=DEFAULT_CACHE_TTL_SECONDS)

reversecore_mcp/core/command_spec.py

@@ -0,0 +1,357 @@
+"""
+Command specification and validation with regex patterns.
+
+This module provides strict command validation using regular expressions
+to prevent command injection attacks. It addresses the vulnerability where
+commands like "pdf @ main; w hello" could bypass simple prefix matching.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Literal, NewType
+
+from reversecore_mcp.core.exceptions import ValidationError
+
+CommandType = Literal["read", "write", "analyze", "system"]
+ValidatedR2Command = NewType("ValidatedR2Command", str)
+
+
+@dataclass
+class CommandSpec:
+    """
+    Specification for a command with strict regex validation.
+
+    Attributes:
+        name: Human-readable command name
+        type: Command type (read, write, analyze, system)
+        regex: Compiled regex pattern for strict validation
+        description: Optional description of what the command does
+    """
+
+    name: str
+    type: CommandType
+    regex: re.Pattern
+    description: str = ""
+
+    def validate(self, cmd: str) -> bool:
+        """
+        Validate a command string against this spec's regex.
+
+        Args:
+            cmd: Command string to validate
+
+        Returns:
+            True if command matches, False otherwise
+        """
+        return self.regex.match(cmd.strip()) is not None
+
+
+# Radare2 command specifications with strict regex patterns
+R2_COMMAND_SPECS: list[CommandSpec] = [
+    # Disassembly commands
+    CommandSpec(
+        name="pdf",
+        type="read",
+        regex=re.compile(r"^pdf(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print disassembly function",
+    ),
+    CommandSpec(
+        name="pd",
+        type="read",
+        regex=re.compile(r"^pd(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print disassembly",
+    ),
+    CommandSpec(
+        name="pdfj",
+        type="read",
+        regex=re.compile(r"^pdfj(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print disassembly function (JSON)",
+    ),
+    CommandSpec(
+        name="pdj",
+        type="read",
+        regex=re.compile(r"^pdj(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print disassembly (JSON)",
+    ),
+    CommandSpec(
+        name="pdc",
+        type="read",
+        regex=re.compile(r"^pdc(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print C-like pseudo code",
+    ),
+    # Analysis commands
+    CommandSpec(
+        name="aaa",
+        type="analyze",
+        regex=re.compile(r"^aaa$"),
+        description="Analyze all referenced code",
+    ),
+    CommandSpec(
+        name="aa",
+        type="analyze",
+        regex=re.compile(r"^aa[a]?$"),
+        description="Analyze all",
+    ),
+    CommandSpec(
+        name="afl",
+        type="read",
+        regex=re.compile(r"^afl[j]?(\s*~.+)?$"),
+        description="Analyze functions list",
+    ),
+    CommandSpec(
+        name="aflj",
+        type="read",
+        regex=re.compile(r"^aflj(\s*~.+)?$"),
+        description="Analyze functions list (JSON)",
+    ),
+    CommandSpec(
+        name="af",
+        type="analyze",
+        regex=re.compile(r"^af(\s+@\s+[a-zA-Z0-9_.]+)?$"),
+        description="Analyze function",
+    ),
+    CommandSpec(
+        name="afi",
+        type="read",
+        regex=re.compile(r"^afi(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Analyze function info",
+    ),
+    CommandSpec(
+        name="afv",
+        type="read",
+        regex=re.compile(r"^afv[j]?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Analyze function variables",
+    ),
+    # Graph commands
+    CommandSpec(
+        name="agfj",
+        type="read",
+        regex=re.compile(r"^agfj(\s+@\s+[a-zA-Z0-9_.]+)?$"),
+        description="Print function graph in JSON format",
+    ),
+    # ESIL emulation commands
+    CommandSpec(
+        name="aei",
+        type="analyze",
+        regex=re.compile(r"^aei$"),
+        description="Initialize ESIL VM",
+    ),
+    CommandSpec(
+        name="aeim",
+        type="analyze",
+        regex=re.compile(r"^aeim$"),
+        description="Initialize ESIL VM memory (stack)",
+    ),
+    CommandSpec(
+        name="aeip",
+        type="analyze",
+        regex=re.compile(r"^aeip$"),
+        description="Initialize ESIL VM program counter",
+    ),
+    CommandSpec(
+        name="aes",
+        type="analyze",
+        regex=re.compile(r"^aes(\s+\d+)?$"),
+        description="ESIL step execution",
+    ),
+    CommandSpec(
+        name="ar",
+        type="read",
+        regex=re.compile(r"^ar[j]?$"),
+        description="Show all register values",
+    ),
+    CommandSpec(
+        name="s",
+        type="analyze",
+        regex=re.compile(r"^s(\s+[a-zA-Z0-9_.]+)?$"),
+        description="Seek to address",
+    ),
+    # Information commands
+    CommandSpec(
+        name="i",
+        type="read",
+        regex=re.compile(r"^i[IiSszeEhj]?(\s*~.+)?$"),
+        description="File information",
+    ),
+    CommandSpec(
+        name="iI",
+        type="read",
+        regex=re.compile(r"^iI(\s*~.+)?$"),
+        description="Binary info",
+    ),
+    CommandSpec(
+        name="ii",
+        type="read",
+        regex=re.compile(r"^ii[j]?(\s*~.+)?$"),
+        description="Imports",
+    ),
+    CommandSpec(
+        name="iS",
+        type="read",
+        regex=re.compile(r"^iS[j]?(\s*~.+)?$"),
+        description="Sections",
+    ),
+    CommandSpec(
+        name="iz",
+        type="read",
+        regex=re.compile(r"^iz[j]?(\s*~.+)?$"),
+        description="Strings in data sections",
+    ),
+    CommandSpec(
+        name="izz",
+        type="read",
+        regex=re.compile(r"^izz[j]?(\s*~.+)?$"),
+        description="All strings",
+    ),
+    CommandSpec(
+        name="ie",
+        type="read",
+        regex=re.compile(r"^ie[j]?(\s*~.+)?$"),
+        description="Entry points",
+    ),
+    CommandSpec(
+        name="iE",
+        type="read",
+        regex=re.compile(r"^iE[j]?(\s*~.+)?$"),
+        description="Exports",
+    ),
+    # Hexdump commands
+    CommandSpec(
+        name="px",
+        type="read",
+        regex=re.compile(r"^px[wqd]?(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print hexdump",
+    ),
+    CommandSpec(
+        name="pxw",
+        type="read",
+        regex=re.compile(r"^pxw(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print hexdump (words)",
+    ),
+    CommandSpec(
+        name="pxq",
+        type="read",
+        regex=re.compile(r"^pxq(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print hexdump (qwords)",
+    ),
+    CommandSpec(
+        name="p8",
+        type="read",
+        regex=re.compile(r"^p8(\s+\d+)?(\s+@\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Print raw bytes in hexadecimal",
+    ),
+    # Seek commands (read-only navigation)
+    CommandSpec(
+        name="s",
+        type="read",
+        regex=re.compile(r"^s(\s+[a-zA-Z0-9_.+\-]+)?(\s*~.+)?$"),
+        description="Seek to address",
+    ),
+    # Flag commands (read-only)
+    CommandSpec(
+        name="f",
+        type="read",
+        regex=re.compile(r"^f[sj]?(\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Flags",
+    ),
+    CommandSpec(
+        name="fs",
+        type="read",
+        regex=re.compile(r"^fs(\s+[a-zA-Z0-9_.]+)?(\s*~.+)?$"),
+        description="Flag spaces",
+    ),
+]
+
+
+# Dangerous patterns that should always be blocked
+DANGEROUS_PATTERNS = [
+    re.compile(r";"),  # SECURITY: Block ALL semicolons (prevents `pdf ~;!id` bypass)
+    re.compile(r"\|(?!})"),  # Pipe to another command (but allow JSON `|` in output)
+    re.compile(r"`.*`"),  # Backticks (command substitution)
+    re.compile(r"\$\(.*\)"),  # Command substitution
+    re.compile(r"&&"),  # Logical AND (command chaining)
+    re.compile(r"\|\|"),  # Logical OR (command chaining)
+    re.compile(r"^w[oxa]?\s"),  # Write commands
+    re.compile(r"^!"),  # System commands
+    re.compile(r"^#!"),  # Scripts
+    re.compile(r"~.*;"),  # Tilde filter followed by semicolon (extra protection)
+]
+
+
+def validate_r2_command(cmd: str, allow_write: bool = False) -> ValidatedR2Command:
+    """
+    Validate a radare2 command using strict regex patterns.
+
+    This function provides comprehensive validation to prevent command injection:
+    1. Checks for dangerous patterns (semicolons, pipes, command substitution)
+    2. Validates against known safe command patterns
+    3. Blocks write commands unless explicitly allowed
+
+    Args:
+        cmd: Radare2 command string to validate
+        allow_write: If True, allow write commands (default: False)
+
+    Returns:
+        ValidatedR2Command: Command string marked as validated
+
+    Raises:
+        ValidationError: If command is invalid, dangerous, or not in allowlist
+
+    Example:
+        >>> validate_r2_command("pdf @ main")
+        ValidatedR2Command('pdf @ main')
+
+        >>> validate_r2_command("pdf @ main; w hello")
+        ValidationError: Dangerous command pattern detected
+    """
+    if not cmd or not cmd.strip():
+        raise ValidationError("Command string cannot be empty", details={"command": cmd})
+
+    cmd_stripped = cmd.strip()
+
+    # Check for dangerous patterns first
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(cmd_stripped):
+            raise ValidationError(
+                f"Dangerous command pattern detected: {pattern.pattern}. "
+                "Command chaining, pipes, and command substitution are not allowed.",
+                details={"command": cmd_stripped, "pattern": pattern.pattern},
+            )
+
+    # Try to match against command specifications
+    for spec in R2_COMMAND_SPECS:
+        if spec.validate(cmd_stripped):
+            # Check if write command when not allowed
+            if spec.type == "write" and not allow_write:
+                raise ValidationError(
+                    f"Write commands are not allowed: {spec.name}",
+                    details={"command": cmd_stripped, "command_type": spec.type},
+                )
+            return ValidatedR2Command(cmd_stripped)
+
+    # No match found
+    raise ValidationError(
+        f"Command not in allowlist: {cmd_stripped}. "
+        "Only read-only and analysis commands are allowed.",
+        details={
+            "command": cmd_stripped,
+            "allowed_commands": [spec.name for spec in R2_COMMAND_SPECS],
+        },
+    )
+
+
+def is_safe_r2_command(cmd: str) -> bool:
+    """
+    Check if a radare2 command is safe (non-blocking validation).
+
+    Args:
+        cmd: Command string to check
+
+    Returns:
+        True if command is safe, False otherwise
+    """
+    try:
+        validate_r2_command(cmd, allow_write=False)
+        return True
+    except ValidationError:
+        return False