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

reversecore_mcp/prompts/report.py

@@ -0,0 +1,150 @@
+"""Prompts for report generation."""
+
+from reversecore_mcp.prompts.common import DOCKER_PATH_RULE, LANGUAGE_RULE
+
+
+def report_generation_mode(filename: str) -> str:
+    """Generate professional malware analysis reports with accurate timestamps and IOC tracking."""
+    return f"""
+    You are a Security Report Specialist generating professional malware analysis documentation.
+    Your task is to analyze '{filename}' and create a comprehensive, shareable report.
+
+    {LANGUAGE_RULE}
+
+    {DOCKER_PATH_RULE}
+
+    ═══════════════════════════════════════════════════════════════════════════
+    ██ REPORT GENERATION WORKFLOW ██
+    ═══════════════════════════════════════════════════════════════════════════
+
+    [STEP 1] Initialize Analysis Session
+    First, get accurate system time and start a tracking session:
+
+    ```
+    get_system_time()                    # Get server timestamp (prevents date hallucination)
+    start_analysis_session(
+        sample_path="{filename}",
+        analyst="Your Name",
+        severity="medium"                # low, medium, high, critical
+    )
+    ```
+
+    [STEP 2] Perform Analysis
+    Conduct your analysis using appropriate tools:
+
+    # 1. Start session
+    create_analysis_session(file_path="{filename}")
+
+    # 2. Extract metadata
+    parse_binary_with_lief(file_path="{filename}")
+    
+    # 3. Analyze code
+    # ...dormant_detector("{filename}")
+    ```
+
+    [STEP 3] Collect IOCs During Analysis
+    As you find indicators, add them to the session:
+
+    ```
+    add_session_ioc("hashes", "SHA256: abc123...")
+    add_session_ioc("ips", "192.168.1.100")
+    add_session_ioc("domains", "malware-c2.com")
+    add_session_ioc("urls", "http://evil.com/payload.exe")
+    ```
+
+    Valid IOC types: hashes, ips, domains, urls, files, registry, mutexes, emails
+
+    [STEP 4] Document MITRE ATT&CK Techniques
+    Map behaviors to MITRE framework:
+
+    ```
+    add_session_mitre("T1059.001", "PowerShell", "Execution")
+    add_session_mitre("T1547.001", "Registry Run Keys", "Persistence")
+    add_session_mitre("T1071.001", "Web Protocols", "Command and Control")
+    ```
+
+    [STEP 5] Add Analysis Notes
+    Document important findings:
+
+    ```
+    add_session_note("Found encrypted config at 0x401000", category="finding")
+    add_session_note("Sample connects to C2 on port 443", category="behavior")
+    add_session_note("Anti-VM checks detected", category="warning")
+    ```
+
+    Note categories: general, finding, warning, important, behavior
+    
+    **Tip: Label each note with evidence level!**
+    ```
+    add_session_note("[🔍 OBSERVED] Procmon captured registry write to Run key", category="finding")
+    add_session_note("[🔎 INFERRED] CryptEncrypt import suggests encryption capability", category="finding")
+    add_session_note("[❓ POSSIBLE] SMB functions may enable lateral movement", category="warning")
+    ```
+
+    [STEP 6] Set Severity and Tags
+    ```
+    set_session_severity("high")
+    add_session_tag("ransomware")
+    add_session_tag("APT")
+    ```
+
+    [STEP 7] End Session and Generate Report
+    ```
+    end_analysis_session(summary="Brief summary of findings...")
+
+    create_analysis_report(
+        template_type="full_analysis",     # full_analysis, quick_triage, ioc_summary, executive_brief
+        classification="TLP:AMBER"
+    )
+    ```
+    
+    [CRITICAL: Evidence Summary in Report]
+    The final report MUST include an evidence summary:
+    
+    ## Confidence Assessment
+    | Evidence Level | Count | Key Findings |
+    |----------------|-------|---------------|
+    | 🔍 OBSERVED | X | (sandbox, logs, traces) |
+    | 🔎 INFERRED | Y | (static analysis) |
+    | ❓ POSSIBLE | Z | (needs verification) |
+    
+    **Overall Confidence**: [✅ CONFIRMED / 🟢 HIGH / 🟡 MEDIUM / 🔴 LOW]
+
+    [STEP 8] Optional: Email Report
+    ```
+    get_email_status()                    # Check if email is configured
+    send_report_email(
+        report_id="MAR-20251205-...",
+        recipients=["security-team@company.com"]
+    )
+    ```
+
+    ═══════════════════════════════════════════════════════════════════════════
+    ██ AVAILABLE REPORT TEMPLATES ██
+    ═══════════════════════════════════════════════════════════════════════════
+
+    | Template | Purpose |
+    |----------|---------|
+    | `full_analysis` | Complete technical report with all details |
+    | `quick_triage` | Rapid assessment summary |
+    | `ioc_summary` | IOC-focused export (YAML/CSV included) |
+    | `executive_brief` | Non-technical summary for management |
+
+    ═══════════════════════════════════════════════════════════════════════════
+    ██ TIMESTAMP FORMATS AVAILABLE ██
+    ═══════════════════════════════════════════════════════════════════════════
+
+    The system provides multiple date/time formats:
+    - `date`: 2025-12-05 (ISO format)
+    - `date_long`: December 05, 2025
+    - `date_short`: 05 Dec 2025
+    - `date_eu`: 05/12/2025
+    - `date_us`: 12/05/2025
+    - `weekday`: Friday
+    - `weekday_short`: Fri
+    - `time_12h`: 02:30:45 PM
+    - `datetime_full`: 2025-12-05 14:30:52 (KST)
+    - `datetime_utc`: 2025-12-05 05:30:52 UTC
+
+    Begin report generation workflow now.
+    """

reversecore_mcp/prompts/security.py

@@ -0,0 +1,136 @@
+"""Prompts for security research, specialized analysis, and patching."""
+
+from reversecore_mcp.prompts.common import DOCKER_PATH_RULE, LANGUAGE_RULE
+
+
+def vulnerability_research_mode(filename: str) -> str:
+    """Specialized mode for Bug Hunting and Vulnerability Research."""
+    return f"""
+    You are a Vulnerability Researcher.
+    Analyze the binary '{filename}' to find exploitable bugs (Buffer Overflow, UAF, Command Injection).
+
+    {LANGUAGE_RULE}
+
+    {DOCKER_PATH_RULE}
+
+    [CRITICAL: Evidence-Based Vulnerability Reporting]
+    ==========================================
+    Vulnerability claims require STRONG evidence. False positives damage credibility.
+    
+    🔍 [CONFIRMED] - Verified through PoC, fuzzing, or dynamic testing
+       Example: "Crash at strcpy with controlled input (PoC attached)"
+    
+    🔎 [LIKELY] - Strong static evidence (dangerous pattern + reachable sink)
+       Example: "User input reaches sprintf without bounds check"
+    
+    ❓ [POSSIBLE] - Pattern present but exploitability unclear
+       Example: "strcpy used but input source not confirmed"
+
+    [Analysis SOP]
+    1. Dangerous API Search:
+       - Identify usage of dangerous functions (strcpy, system, sprintf, gets) using `run_radare2` imports.
+       - Use `analyze_xrefs` to check if user input reaches these sinks.
+       → API present only = [❓ POSSIBLE]
+       → API + reachable input = [🔎 LIKELY]
+       → PoC crash = [🔍 CONFIRMED]
+
+    2. Mitigation Check:
+       - Check for exploit mitigations (ASLR, DEP/NX, Canary, PIE) using `parse_binary_with_lief`.
+       → Mitigations affect exploitability, not vulnerability existence
+
+    3. Fuzzing Candidate Identification:
+       - Identify parsing functions or network handlers suitable for fuzzing.
+
+    4. Reporting Format:
+       | Vulnerability | CWE | Confidence | Evidence |
+       |---------------|-----|------------|----------|
+       | Stack Buffer Overflow | CWE-121 | 🔍 CONFIRMED | PoC crash at 0x401234 |
+       | Command Injection | CWE-78 | 🔎 LIKELY | system() called with user input |
+       | Integer Overflow | CWE-190 | ❓ POSSIBLE | Unchecked multiplication, needs verification |
+       
+       - Include code snippets for each finding
+       - Recommend PoC (Proof of Concept) strategies
+    """
+
+
+def crypto_analysis_mode(filename: str) -> str:
+    """Specialized mode for analyzing Cryptographic algorithms and Key management."""
+    return f"""
+    You are a Cryptography Analyst.
+    Analyze the binary '{filename}' to identify cryptographic algorithms and key management flaws.
+
+    {LANGUAGE_RULE}
+
+    {DOCKER_PATH_RULE}
+
+    [Analysis SOP]
+    1. Algo Identification:
+       - Identify crypto constants (S-Boxes, IVs, Magic Numbers) using `run_yara` (crypto-signatures) or `run_strings`.
+       - Identify standard crypto libraries (OpenSSL, mbedTLS) using `match_libraries`.
+
+    2. Key Management:
+       - Check for hardcoded keys or IVs.
+       - Analyze how keys are generated and stored.
+
+    3. Reporting:
+       - List identified algorithms (AES, RSA, ChaCha20, etc.) and their modes (ECB, CBC, GCM).
+       - Report any weak crypto usage (e.g., ECB mode, weak RNG).
+    """
+
+
+def firmware_analysis_mode(filename: str) -> str:
+    """Specialized mode for analyzing Firmware images and IoT devices."""
+    return f"""
+    You are an Embedded Systems Security Expert.
+    Analyze the firmware image '{filename}' to extract file systems and identify vulnerabilities.
+
+    {LANGUAGE_RULE}
+
+    {DOCKER_PATH_RULE}
+
+    [Analysis SOP]
+    1. Extraction:
+       - Use `run_binwalk` to identify and extract embedded file systems (SquashFS, UBIFS, etc.) and bootloaders.
+       - Identify the CPU architecture (ARM, MIPS, PowerPC) using `run_file` or `parse_binary_with_lief`.
+
+    2. Secret Hunting:
+       - Search for hardcoded credentials (root passwords, API keys, private keys) using `run_strings` and `run_yara`.
+       - Look for configuration files (/etc/shadow, /etc/passwd, .conf).
+
+    3. Vulnerability Check:
+       - Check for outdated components or known vulnerable services (telnet, old httpd).
+
+    4. Reporting:
+       - List extracted components, architecture, and potential backdoors/secrets.
+    """
+
+
+def patch_analysis_mode(original_binary: str, patched_binary: str) -> str:
+    """Analyze the differences between two binaries to identify patches or vulnerabilities (1-day analysis)."""
+    return f"""
+    You are a Patch Analyst / 1-Day Exploit Researcher.
+    Compare '{original_binary}' (vulnerable) and '{patched_binary}' (patched) to understand the security fix.
+
+    {LANGUAGE_RULE}
+
+    {DOCKER_PATH_RULE}
+
+    [Analysis SOP]
+    1. Binary Diffing:
+       - Run `diff_binaries("{original_binary}", "{patched_binary}")` to find changed functions.
+       - Focus on functions with 'unsafe' or 'security' related changes.
+
+    2. Change Analysis:
+       - For each changed function:
+         A. Decompile both versions using `smart_decompile` or `smart_decompile`.
+         B. Compare the logic to identify added checks (bounds check, integer overflow check, input validation).
+
+    3. Vulnerability Reconstruction:
+       - Based on the added check, infer the original vulnerability (Buffer Overflow, UAF, Integer Overflow).
+       - Determine if the patch is complete or if it can be bypassed.
+
+    4. Reporting:
+       - Summarize the vulnerability (CVE style).
+       - Explain the patch logic.
+       - Suggest a Proof-of-Concept (PoC) strategy to trigger the original bug.
+    """

reversecore_mcp/resources.py

@@ -0,0 +1,329 @@
+import asyncio
+from collections import deque
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import Any, TypeVar
+
+from fastmcp import FastMCP
+
+from reversecore_mcp.core import json_utils as json  # Use optimized JSON (3-5x faster)
+from reversecore_mcp.core.config import get_config
+from reversecore_mcp.core.decorators import log_execution
+from reversecore_mcp.core.metrics import track_metrics
+
+# Import tools at module level for better performance
+# These imports are used by resource functions below
+from reversecore_mcp.tools.ghidra import decompilation, r2_analysis, static_analysis
+from reversecore_mcp.tools.malware import ioc_tools
+
+# Type variable for generic function wrapper
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Type alias for decorator return
+DecoratorType = Callable[[F], F]
+
+
+def resource_decorator(resource_name: str) -> DecoratorType:
+    """Combined decorator for resource functions with logging and metrics.
+
+    Applies @log_execution and @track_metrics to resource functions
+    for consistent monitoring and observability.
+
+    Args:
+        resource_name: Name identifier for logging and metrics tracking
+
+    Returns:
+        A decorator that wraps the function with logging and metrics
+    """
+
+    def decorator(func: F) -> F:
+        # Apply decorators in reverse order (innermost first)
+        wrapped = track_metrics(resource_name)(func)
+        wrapped = log_execution(tool_name=resource_name)(wrapped)
+
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await wrapped(*args, **kwargs)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return wrapped(*args, **kwargs)
+
+        # Return appropriate wrapper based on function type
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _get_resources_path() -> Path:
+    """Get resources path from config or use default."""
+    config = get_config()
+    # Resources are typically in a sibling directory to workspace
+    resources_path = config.workspace.parent / "resources"
+    if resources_path.exists():
+        return resources_path
+    # Fallback to local resources directory
+    local_resources = Path(__file__).parent.parent / "resources"
+    if local_resources.exists():
+        return local_resources
+    return resources_path  # Return config-based path even if not exists
+
+
+def _get_workspace_path(filename: str) -> str:
+    """Get full path to a file in the workspace."""
+    return str(get_config().workspace / filename)
+
+
+def register_resources(mcp: FastMCP):
+    """Register MCP resources for AI agents."""
+
+    # ============================================================================
+    # Static Resources
+    # ============================================================================
+
+    @mcp.resource("reversecore://guide")
+    def get_guide() -> str:
+        """Reversecore MCP Tool Usage Guide"""
+        guide_path = _get_resources_path() / "FILE_COPY_TOOL_GUIDE.md"
+        if guide_path.exists():
+            return guide_path.read_text(encoding="utf-8")
+        return "Guide not found."
+
+    @mcp.resource("reversecore://guide/structures")
+    def get_structure_guide() -> str:
+        """Structure Recovery and Cross-Reference Analysis Technical Guide"""
+        doc_path = _get_resources_path() / "XREFS_AND_STRUCTURES_IMPLEMENTATION.md"
+        if doc_path.exists():
+            return doc_path.read_text(encoding="utf-8")
+        return "Documentation not found."
+
+    @mcp.resource("reversecore://tools")
+    def get_tools_doc() -> str:
+        """Complete documentation for all available tools"""
+        doc_path = _get_resources_path() / "TOOLS.md"
+        if doc_path.exists():
+            return doc_path.read_text(encoding="utf-8")
+        return "Tools documentation not found."
+
+    @mcp.resource("reversecore://logs")
+    def get_logs() -> str:
+        """Application logs (last 100 lines)"""
+        log_file = get_config().log_file
+        if log_file.exists():
+            try:
+                # OPTIMIZED: Use deque to read only last N lines efficiently
+                # This avoids loading the entire log file into memory
+                with open(log_file, encoding="utf-8", errors="replace") as f:
+                    # deque with maxlen automatically keeps only last N items
+                    last_lines = deque(f, maxlen=100)
+                    return "".join(last_lines)
+            except (OSError, PermissionError) as e:
+                return f"Error reading logs: {e}"
+        return "No logs found."
+
+    # ============================================================================
+    # Dynamic Resources - Binary Virtual File System
+    # ============================================================================
+
+    @mcp.resource("reversecore://{filename}/strings")
+    @resource_decorator("resource_get_file_strings")
+    async def get_file_strings(filename: str) -> str:
+        """Extract all strings from a binary file"""
+        try:
+            result = await static_analysis.run_strings(_get_workspace_path(filename))
+            if result.status == "success":
+                # Get content from ToolResult
+                content = result.data if isinstance(result.data, str) else str(result.data)
+                return f"# Strings from {filename}\n\n{content}"
+            return f"Error extracting strings: {result.message if hasattr(result, 'message') else 'Unknown error'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    @mcp.resource("reversecore://{filename}/iocs")
+    @resource_decorator("resource_get_file_iocs")
+    async def get_file_iocs(filename: str) -> str:
+        """Extract IOCs (IPs, URLs, Emails) from a binary file"""
+        try:
+            # 1. Extract strings
+            strings_res = await static_analysis.run_strings(_get_workspace_path(filename))
+            if strings_res.status != "success":
+                return f"Failed to extract strings from {filename}"
+
+            # 2. Extract IOCs from strings
+            strings_data = (
+                strings_res.data if isinstance(strings_res.data, str) else str(strings_res.data)
+            )
+            ioc_res = ioc_tools.extract_iocs(strings_data)
+
+            # 3. Format output
+            if ioc_res.status == "success":
+                data = ioc_res.data
+                ipv4_list = data.get("ipv4", [])
+                urls_list = data.get("urls", [])
+                emails_list = data.get("emails", [])
+
+                return f"""# IOC Report for {filename}
+
+## IPv4 Addresses ({len(ipv4_list)})
+{chr(10).join(f"- {ip}" for ip in ipv4_list) if ipv4_list else "No IPv4 addresses found"}
+
+## URLs ({len(urls_list)})
+{chr(10).join(f"- {url}" for url in urls_list) if urls_list else "No URLs found"}
+
+## Email Addresses ({len(emails_list)})
+{chr(10).join(f"- {email}" for email in emails_list) if emails_list else "No emails found"}
+"""
+            return f"Error extracting IOCs: {ioc_res.message if hasattr(ioc_res, 'message') else 'Unknown error'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    @mcp.resource("reversecore://{filename}/func/{address}/code")
+    @resource_decorator("resource_get_decompiled_code")
+    async def get_decompiled_code(filename: str, address: str) -> str:
+        """Get decompiled pseudo-C code for a specific function"""
+        try:
+            result = await decompilation.smart_decompile(
+                _get_workspace_path(filename), address, use_ghidra=True
+            )
+
+            if result.status == "success":
+                content = result.data if isinstance(result.data, str) else str(result.data)
+                return f"""# Decompiled Code: {filename} @ {address}
+
+```c
+{content}
+```
+"""
+            return f"Error decompiling {address}: {result.message if hasattr(result, 'message') else 'Decompilation failed'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    @mcp.resource("reversecore://{filename}/func/{address}/asm")
+    @resource_decorator("resource_get_disassembly")
+    async def get_disassembly(filename: str, address: str) -> str:
+        """Get disassembly for a specific function"""
+        try:
+            result = await r2_analysis.run_radare2(
+                _get_workspace_path(filename), f"pdf @ {address}"
+            )
+
+            if result.status == "success":
+                content = result.data if isinstance(result.data, str) else str(result.data)
+                return f"""# Disassembly: {filename} @ {address}
+
+```asm
+{content}
+```
+"""
+            return f"Error disassembling {address}: {result.message if hasattr(result, 'message') else 'Disassembly failed'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    @mcp.resource("reversecore://{filename}/func/{address}/cfg")
+    @resource_decorator("resource_get_function_cfg")
+    async def get_function_cfg(filename: str, address: str) -> str:
+        """Get Control Flow Graph (Mermaid) for a specific function"""
+        try:
+            result = await r2_analysis.generate_function_graph(
+                _get_workspace_path(filename), address, format="mermaid"
+            )
+
+            if result.status == "success":
+                content = result.data if isinstance(result.data, str) else str(result.data)
+                return f"""# Control Flow Graph: {filename} @ {address}
+
+{content}
+"""
+            return f"Error generating CFG for {address}: {result.message if hasattr(result, 'message') else 'CFG generation failed'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    @mcp.resource("reversecore://{filename}/functions")
+    @resource_decorator("resource_get_function_list")
+    async def get_function_list(filename: str) -> str:
+        """Get list of all functions in the binary"""
+        try:
+            result = await r2_analysis.run_radare2(
+                _get_workspace_path(filename), "aflj"
+            )  # List functions in JSON format
+
+            if result.status == "success":
+                content = result.data if isinstance(result.data, str) else str(result.data)
+
+                try:
+                    functions = json.loads(content)
+                    func_list = []
+                    for func in functions[:50]:  # Limit to first 50 for readability
+                        name = func.get("name", "unknown")
+                        offset = func.get("offset", 0)
+                        size = func.get("size", 0)
+                        func_list.append(f"- `{name}` @ 0x{offset:x} (size: {size} bytes)")
+
+                    total = len(functions)
+                    shown = min(50, total)
+
+                    return f"""# Functions in {filename}
+
+Total functions: {total}
+Showing: {shown}
+
+{chr(10).join(func_list)}
+"""
+                except Exception:  # Catch all JSON parsing errors
+                    return f"# Functions in {filename}\n\n{content}"
+
+            return f"Error listing functions: {result.message if hasattr(result, 'message') else 'Failed to list functions'}"
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    # ============================================================================
+    # Reversecore Signature Resources (Dormant Detector)
+    # ============================================================================
+
+    @mcp.resource("reversecore://{filename}/dormant_detector")
+    @resource_decorator("resource_get_dormant_detector_results")
+    async def get_dormant_detector_results(filename: str) -> str:
+        """Get Dormant Detector analysis results (orphan functions and logic bombs)"""
+        try:
+            from reversecore_mcp.tools import dormant_detector as dd_module
+
+            result = await dd_module.dormant_detector(file_path=_get_workspace_path(filename))
+
+            if result.status == "success":
+                data = result.data
+                orphans = data.get("orphan_functions", [])
+                suspicious = data.get("suspicious_logic", [])
+
+                report = f"""# 🔍 Dormant Detector Results: {filename}
+
+## Orphan Functions (Never Called)
+Found {len(orphans)} orphan function(s):
+
+"""
+                for func in orphans[:10]:
+                    report += f"""### {func.get("name", "unknown")}
+- **Address**: {func.get("address", "N/A")}
+- **Size**: {func.get("size", 0)} bytes
+- **Cross-References**: {func.get("xrefs", 0)}
+- **Assessment**: Potentially hidden backdoor or logic bomb
+
+"""
+
+                report += f"\n## Suspicious Logic (Magic Values)\nFound {len(suspicious)} suspicious pattern(s):\n\n"
+
+                for logic in suspicious[:10]:
+                    report += f"""### {logic.get("function", "unknown")}
+- **Address**: {logic.get("address", "N/A")}
+- **Instruction**: `{logic.get("instruction", "N/A")}`
+- **Reason**: {logic.get("reason", "N/A")}
+
+"""
+
+                return report
+
+            return f"Dormant Detector analysis failed: {result.message if hasattr(result, 'message') else 'Unknown error'}"
+        except Exception as e:
+            return f"Error: {str(e)}"