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

reversecore_mcp/core/evidence.py

@@ -0,0 +1,229 @@
+"""
+Evidence-based analysis types and confidence levels.
+
+This module provides data structures for tracking the evidence level
+and confidence of analysis findings, preventing hallucination and
+over-inference in automated reports.
+"""
+
+from enum import Enum
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+
+class EvidenceLevel(str, Enum):
+    """Evidence level classification for analysis findings.
+    
+    Based on professional SOC/IR standards:
+    - OBSERVED: Directly observed through dynamic analysis or tracing
+    - INFERRED: Logically inferred from static analysis (high confidence)
+    - POSSIBLE: Hypothesized based on patterns (requires verification)
+    """
+    OBSERVED = "observed"   # Directly observed (dynamic analysis, logs, traces)
+    INFERRED = "inferred"   # Logically inferred from static analysis
+    POSSIBLE = "possible"   # Possible but needs verification
+    
+    @property
+    def symbol(self) -> str:
+        """Return a symbol for display."""
+        return {
+            "observed": "🔍",
+            "inferred": "🔎",
+            "possible": "❓",
+        }[self.value]
+    
+    @property
+    def confidence_score(self) -> float:
+        """Return a confidence score (0.0-1.0)."""
+        return {
+            "observed": 1.0,
+            "inferred": 0.7,
+            "possible": 0.4,
+        }[self.value]
+
+
+class MITREConfidence(str, Enum):
+    """MITRE ATT&CK mapping confidence levels."""
+    CONFIRMED = "confirmed"     # Multiple evidence sources
+    HIGH = "high"               # Strong single evidence
+    MEDIUM = "medium"           # Inferred from API/patterns
+    LOW = "low"                 # Possible based on behavior
+
+
+@dataclass
+class Evidence:
+    """Evidence record for a finding."""
+    source: str                 # e.g., "strings", "imports", "decompile", "sandbox"
+    location: str               # e.g., "0x401000", "section:.rsrc", "log:procmon"
+    description: str            # What was found
+    raw_data: Optional[str] = None  # Raw evidence (hex, string, etc.)
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "location": self.location,
+            "description": self.description,
+            "raw_data": self.raw_data,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+
+@dataclass
+class Finding:
+    """An analysis finding with evidence tracking."""
+    title: str
+    description: str
+    level: EvidenceLevel
+    category: str               # e.g., "persistence", "encryption", "network"
+    evidence: list[Evidence] = field(default_factory=list)
+    mitre_techniques: list[str] = field(default_factory=list)
+    
+    def add_evidence(self, source: str, location: str, description: str, 
+                     raw_data: Optional[str] = None) -> None:
+        """Add evidence to this finding."""
+        self.evidence.append(Evidence(
+            source=source,
+            location=location,
+            description=description,
+            raw_data=raw_data,
+        ))
+    
+    @property
+    def confidence(self) -> float:
+        """Calculate overall confidence based on evidence level and count."""
+        base = self.level.confidence_score
+        # More evidence = higher confidence (up to 20% boost)
+        evidence_boost = min(len(self.evidence) * 0.05, 0.2)
+        return min(base + evidence_boost, 1.0)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "description": self.description,
+            "level": self.level.value,
+            "level_symbol": self.level.symbol,
+            "category": self.category,
+            "confidence": round(self.confidence, 2),
+            "evidence_count": len(self.evidence),
+            "evidence": [e.to_dict() for e in self.evidence],
+            "mitre_techniques": self.mitre_techniques,
+        }
+    
+    def format_markdown(self) -> str:
+        """Format finding as markdown with evidence."""
+        lines = [
+            f"### {self.level.symbol} [{self.level.value.upper()}] {self.title}",
+            f"",
+            f"**Confidence**: {self.confidence:.0%}",
+            f"**Category**: {self.category}",
+            f"",
+            self.description,
+            f"",
+        ]
+        
+        if self.evidence:
+            lines.append("**Evidence:**")
+            for i, ev in enumerate(self.evidence, 1):
+                lines.append(f"  {i}. `{ev.source}` @ `{ev.location}`: {ev.description}")
+                if ev.raw_data:
+                    lines.append(f"     ```")
+                    lines.append(f"     {ev.raw_data[:200]}{'...' if len(ev.raw_data) > 200 else ''}")
+                    lines.append(f"     ```")
+        
+        if self.mitre_techniques:
+            lines.append(f"")
+            lines.append(f"**MITRE ATT&CK**: {', '.join(self.mitre_techniques)}")
+        
+        return "\n".join(lines)
+
+
+@dataclass
+class MITRETechnique:
+    """MITRE ATT&CK technique with confidence tracking."""
+    technique_id: str           # e.g., "T1055"
+    technique_name: str
+    tactic: str
+    confidence: MITREConfidence
+    evidence: list[Evidence] = field(default_factory=list)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "technique_id": self.technique_id,
+            "technique_name": self.technique_name,
+            "tactic": self.tactic,
+            "confidence": self.confidence.value,
+            "evidence_count": len(self.evidence),
+        }
+    
+    def format_markdown_row(self) -> str:
+        """Format as markdown table row."""
+        conf_symbol = {
+            "confirmed": "✅",
+            "high": "🟢",
+            "medium": "🟡",
+            "low": "🔴",
+        }[self.confidence.value]
+        
+        return f"| {self.technique_id} | {self.technique_name} | {self.tactic} | {conf_symbol} {self.confidence.value} |"
+
+
+@dataclass
+class AnalysisMetadata:
+    """Unified metadata for analysis session (single source of truth)."""
+    session_id: str
+    sample_name: str
+    sample_hash: str            # SHA256
+    start_time: datetime
+    end_time: Optional[datetime] = None
+    analyst: str = "Reversecore MCP"
+    tools_used: list[str] = field(default_factory=list)
+    
+    @property
+    def duration_seconds(self) -> float:
+        """Calculate analysis duration in seconds."""
+        if self.end_time:
+            return (self.end_time - self.start_time).total_seconds()
+        return (datetime.now() - self.start_time).total_seconds()
+    
+    @property
+    def duration_formatted(self) -> str:
+        """Return human-readable duration."""
+        seconds = self.duration_seconds
+        if seconds < 60:
+            return f"{seconds:.1f} seconds"
+        elif seconds < 3600:
+            return f"{seconds / 60:.1f} minutes"
+        else:
+            return f"{seconds / 3600:.1f} hours"
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "sample_name": self.sample_name,
+            "sample_hash": self.sample_hash,
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "duration": self.duration_formatted,
+            "duration_seconds": round(self.duration_seconds, 2),
+            "analyst": self.analyst,
+            "tools_used": self.tools_used,
+        }
+
+
+# Helper functions for quick finding creation
+def observed_finding(title: str, description: str, category: str, **kwargs) -> Finding:
+    """Create an OBSERVED level finding."""
+    return Finding(title=title, description=description, 
+                   level=EvidenceLevel.OBSERVED, category=category, **kwargs)
+
+def inferred_finding(title: str, description: str, category: str, **kwargs) -> Finding:
+    """Create an INFERRED level finding."""
+    return Finding(title=title, description=description,
+                   level=EvidenceLevel.INFERRED, category=category, **kwargs)
+
+def possible_finding(title: str, description: str, category: str, **kwargs) -> Finding:
+    """Create a POSSIBLE level finding."""
+    return Finding(title=title, description=description,
+                   level=EvidenceLevel.POSSIBLE, category=category, **kwargs)

reversecore_mcp/core/exceptions.py

@@ -0,0 +1,296 @@
+"""
+Custom exception classes for Reversecore_MCP.
+
+All exceptions inherit from ReversecoreError to allow for centralized
+exception handling at the MCP server level.
+"""
+
+
+class ReversecoreError(Exception):
+    """Base exception for all Reversecore_MCP errors."""
+
+    error_code: str = "RCMCP-E000"
+    error_type: str = "UNKNOWN_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str | None = None,
+        error_type: str | None = None,
+    ):
+        self.message = message
+        if error_code:
+            self.error_code = error_code
+        if error_type:
+            self.error_type = error_type
+        super().__init__(message)
+
+
+class ToolNotFoundError(ReversecoreError):
+    """Raised when a required CLI tool is not found in the system."""
+
+    error_code = "RCMCP-E003"
+    error_type = "TOOL_ERROR"
+
+    def __init__(self, tool_name: str):
+        self.tool_name = tool_name
+        message = f"Tool '{tool_name}' not found. Please install it."
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class ExecutionTimeoutError(ReversecoreError):
+    """Raised when a subprocess execution exceeds the timeout limit."""
+
+    error_code = "RCMCP-E002"
+    error_type = "TIMEOUT_ERROR"
+
+    def __init__(self, timeout_seconds: int):
+        self.timeout_seconds = timeout_seconds
+        message = f"Operation timed out after {timeout_seconds} seconds."
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class OutputLimitExceededError(ReversecoreError):
+    """Raised when subprocess output exceeds the maximum allowed size."""
+
+    error_code = "RCMCP-E004"
+    error_type = "OUTPUT_ERROR"
+
+    def __init__(self, max_size: int, actual_size: int):
+        self.max_size = max_size
+        self.actual_size = actual_size
+        message = (
+            f"Output limit exceeded: {actual_size} bytes (max: {max_size} bytes). "
+            "Output has been truncated."
+        )
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class ValidationError(ReversecoreError):
+    """Raised when input validation fails."""
+
+    error_code = "RCMCP-E001"
+    error_type = "VALIDATION_ERROR"
+
+    def __init__(self, message: str, details: dict | None = None):
+        self.details = details or {}
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class ToolExecutionError(ReversecoreError):
+    """Raised when a tool execution fails."""
+
+    error_code = "RCMCP-E005"
+    error_type = "EXECUTION_ERROR"
+
+    def __init__(self, message: str):
+        super().__init__(message, self.error_code, self.error_type)
+
+
+# ============================================================================
+# Binary Analysis Exceptions
+# ============================================================================
+
+
+class BinaryAnalysisError(ReversecoreError):
+    """Base exception for binary analysis operations."""
+
+    error_code = "RCMCP-E100"
+    error_type = "BINARY_ANALYSIS_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        binary_path: str | None = None,
+        tool_name: str | None = None,
+    ):
+        self.binary_path = binary_path
+        self.tool_name = tool_name
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class DecompilationError(BinaryAnalysisError):
+    """Raised when decompilation of a function fails."""
+
+    error_code = "RCMCP-E101"
+    error_type = "DECOMPILATION_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        function_address: str | None = None,
+        binary_path: str | None = None,
+        tool_name: str = "ghidra",
+    ):
+        self.function_address = function_address
+        detailed_message = message
+        if function_address:
+            detailed_message = f"Failed to decompile function at {function_address}: {message}"
+        super().__init__(detailed_message, binary_path, tool_name)
+
+
+class DisassemblyError(BinaryAnalysisError):
+    """Raised when disassembly of code fails."""
+
+    error_code = "RCMCP-E102"
+    error_type = "DISASSEMBLY_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        address: str | None = None,
+        binary_path: str | None = None,
+    ):
+        self.address = address
+        detailed_message = message
+        if address:
+            detailed_message = f"Failed to disassemble at {address}: {message}"
+        super().__init__(detailed_message, binary_path, tool_name="radare2")
+
+
+class StructureRecoveryError(BinaryAnalysisError):
+    """Raised when structure recovery fails."""
+
+    error_code = "RCMCP-E103"
+    error_type = "STRUCTURE_RECOVERY_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        function_address: str | None = None,
+        binary_path: str | None = None,
+    ):
+        self.function_address = function_address
+        super().__init__(message, binary_path, tool_name="ghidra")
+
+
+class SignatureGenerationError(BinaryAnalysisError):
+    """Raised when YARA signature generation fails."""
+
+    error_code = "RCMCP-E104"
+    error_type = "SIGNATURE_GENERATION_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        address: str | None = None,
+        binary_path: str | None = None,
+    ):
+        self.address = address
+        super().__init__(message, binary_path, tool_name="radare2")
+
+
+class EmulationError(BinaryAnalysisError):
+    """Raised when code emulation fails."""
+
+    error_code = "RCMCP-E105"
+    error_type = "EMULATION_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        start_address: str | None = None,
+        binary_path: str | None = None,
+    ):
+        self.start_address = start_address
+        super().__init__(message, binary_path, tool_name="radare2")
+
+
+# ============================================================================
+# Tool-Specific Exceptions
+# ============================================================================
+
+
+class ToolTimeoutError(ReversecoreError):
+    """Raised when a specific tool exceeds its timeout."""
+
+    error_code = "RCMCP-E200"
+    error_type = "TOOL_TIMEOUT_ERROR"
+
+    def __init__(
+        self,
+        tool_name: str,
+        timeout_seconds: int,
+        operation: str | None = None,
+    ):
+        self.tool_name = tool_name
+        self.timeout_seconds = timeout_seconds
+        self.operation = operation
+        if operation:
+            message = f"{tool_name} timed out after {timeout_seconds}s during {operation}"
+        else:
+            message = f"{tool_name} timed out after {timeout_seconds} seconds"
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class GhidraConnectionError(ReversecoreError):
+    """Raised when connection to Ghidra server fails."""
+
+    error_code = "RCMCP-E201"
+    error_type = "GHIDRA_CONNECTION_ERROR"
+
+    def __init__(self, message: str, host: str | None = None, port: int | None = None):
+        self.host = host
+        self.port = port
+        detailed_message = message
+        if host and port:
+            detailed_message = f"Failed to connect to Ghidra at {host}:{port}: {message}"
+        super().__init__(detailed_message, self.error_code, self.error_type)
+
+
+class Radare2Error(ReversecoreError):
+    """Raised when radare2 operation fails."""
+
+    error_code = "RCMCP-E202"
+    error_type = "RADARE2_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        command: str | None = None,
+        binary_path: str | None = None,
+    ):
+        self.command = command
+        self.binary_path = binary_path
+        detailed_message = message
+        if command:
+            detailed_message = f"radare2 command '{command}' failed: {message}"
+        super().__init__(detailed_message, self.error_code, self.error_type)
+
+
+# ============================================================================
+# Workspace & Security Exceptions
+# ============================================================================
+
+
+class WorkspaceError(ReversecoreError):
+    """Raised when workspace operation fails."""
+
+    error_code = "RCMCP-E300"
+    error_type = "WORKSPACE_ERROR"
+
+    def __init__(self, message: str, path: str | None = None):
+        self.path = path
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class SecurityViolationError(ReversecoreError):
+    """Raised when a security policy is violated."""
+
+    error_code = "RCMCP-E301"
+    error_type = "SECURITY_VIOLATION"
+
+    def __init__(self, message: str, attempted_path: str | None = None):
+        self.attempted_path = attempted_path
+        super().__init__(message, self.error_code, self.error_type)
+
+
+class PathTraversalError(SecurityViolationError):
+    """Raised when path traversal attack is detected."""
+
+    error_code = "RCMCP-E302"
+    error_type = "PATH_TRAVERSAL"
+
+    def __init__(self, attempted_path: str):
+        message = f"Path traversal detected: {attempted_path}"
+        super().__init__(message, attempted_path)