honeymcp 0.1.0__py3-none-any.whl

honeymcp/__init__.py

@@ -0,0 +1,34 @@
+"""HoneyMCP - Deception Middleware for MCP Servers.
+
+HoneyMCP adds honeypot capabilities to Model Context Protocol (MCP) servers
+to detect and capture malicious prompt injection attacks.
+
+Basic Usage:
+    from fastmcp import FastMCP
+    from honeymcp import honeypot
+
+    mcp = FastMCP("My Server")
+
+    @mcp.tool()
+    def my_tool():
+        pass
+
+    mcp = honeypot(mcp)  # One line integration!
+
+The honeypot decorator injects fake security-sensitive tools that capture
+attack context when triggered, while allowing legitimate tools to work normally.
+"""
+
+from honeymcp.core import honeypot, honeypot_from_config
+from honeymcp.models import AttackFingerprint, GhostToolSpec, HoneyMCPConfig, ProtectionMode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "honeypot",
+    "honeypot_from_config",
+    "AttackFingerprint",
+    "GhostToolSpec",
+    "HoneyMCPConfig",
+    "ProtectionMode",
+]

honeymcp/cli.py

@@ -0,0 +1,205 @@
+"""HoneyMCP CLI - Command line tools for HoneyMCP setup and management."""
+
+import argparse
+import sys
+from pathlib import Path
+
+CONFIG_TEMPLATE = """\
+# HoneyMCP Configuration
+# ======================
+# Configure ghost tool injection and attack detection behavior
+
+# Protection Mode
+# ---------------
+# SCANNER: Lock out attackers after ghost tool trigger (all tools return errors)
+# COGNITIVE: Deceive attackers with fake data (real tools return mocks)
+protection_mode: SCANNER
+
+# Static Ghost Tools
+# ------------------
+# Select which pre-defined ghost tools to inject from the catalog.
+# Available tools:
+#
+# Data Exfiltration (GET):
+#   - list_cloud_secrets: List AWS/Azure credentials
+#   - read_private_files: Read sensitive config files
+#   - dump_database_credentials: Retrieve database connection strings
+#   - export_user_data: Export user records including PII
+#   - get_api_keys: List all API keys for external services
+#   - scan_internal_network: Scan internal network for services
+#
+# Indirect Prompt Injection (SET):
+#   - execute_shell_command: Execute shell commands
+#   - bypass_security_check: Bypass auth/authz checks
+#   - modify_system_prompt: Modify AI system prompt
+#   - escalate_privileges: Escalate to admin/root
+#   - disable_security_filters: Disable security filters
+#   - inject_system_message: Inject message into AI context
+#   - override_permissions: Override access control
+#
+ghost_tools:
+  - list_cloud_secrets
+  - execute_shell_command
+
+# Dynamic Ghost Tools (LLM-generated)
+# -----------------------------------
+# Enable LLM to analyze your server and generate context-aware ghost tools.
+# Requires LLM credentials in .env file.
+dynamic_tools:
+  enabled: false                  # Set to true to enable (requires LLM credentials)
+  num_tools: 3                    # Number of tools to generate (1-10)
+  fallback_to_static: true        # Use static tools if LLM generation fails
+  cache_ttl: 3600                 # Cache duration in seconds (0 = no cache)
+  llm_model: null                 # Override LLM model (null = use default from .env)
+
+# Storage
+# -------
+# Configure where attack events are stored
+storage:
+  event_path: ~/.honeymcp/events  # Directory for attack event JSON files
+
+# Dashboard
+# ---------
+# Real-time attack visualization
+dashboard:
+  enabled: true
+"""
+
+ENV_TEMPLATE = """\
+# HoneyMCP Environment Configuration
+# ==================================
+# Required only for dynamic ghost tools (LLM-generated)
+
+# LLM Provider Configuration
+# --------------------------
+# Supported providers: openai, watsonx, ollama
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o-mini
+
+# OpenAI Configuration
+# --------------------
+# Required if LLM_PROVIDER=openai
+OPENAI_API_KEY=your_openai_api_key_here
+
+# watsonx.ai Configuration
+# ------------------------
+# Required if LLM_PROVIDER=watsonx
+# WATSONX_URL=https://us-south.ml.cloud.ibm.com/
+# WATSONX_APIKEY=your_watsonx_api_key_here
+# WATSONX_PROJECT_ID=your_project_id_here
+
+# Ollama Configuration
+# --------------------
+# Required if LLM_PROVIDER=ollama
+# OLLAMA_API_BASE=http://localhost:11434
+# LLM_MODEL=llama3.2
+"""
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Initialize HoneyMCP configuration files in current directory."""
+    target_dir = Path(args.directory).resolve()
+
+    if not target_dir.exists():
+        print(f"Error: Directory does not exist: {target_dir}")
+        return 1
+
+    config_path = target_dir / "honeymcp.yaml"
+    env_path = target_dir / ".env.honeymcp"
+
+    files_created = []
+    files_skipped = []
+
+    # Create config.yaml
+    if config_path.exists() and not args.force:
+        files_skipped.append(config_path.name)
+    else:
+        config_path.write_text(CONFIG_TEMPLATE)
+        files_created.append(config_path.name)
+
+    # Create .env.example
+    if env_path.exists() and not args.force:
+        files_skipped.append(env_path.name)
+    else:
+        env_path.write_text(ENV_TEMPLATE)
+        files_created.append(env_path.name)
+
+    # Print results
+    if files_created:
+        print("Created:")
+        for f in files_created:
+            print(f"  - {f}")
+
+    if files_skipped:
+        print("Skipped (already exists, use --force to overwrite):")
+        for f in files_skipped:
+            print(f"  - {f}")
+
+    print()
+    print("Next steps:")
+    print("  1. Edit honeymcp.yaml to configure ghost tools")
+    print("  2. Add LLM credentials to .env.honeymcp (for dynamic tools)")
+    print("  3. Add to your MCP server:")
+    print()
+    print("     from honeymcp import honeypot_from_config")
+    print("     mcp = honeypot_from_config(mcp)")
+    print()
+
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """Print HoneyMCP version."""
+    from honeymcp import __version__
+
+    print(f"honeymcp {__version__}")
+    return 0
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="honeymcp",
+        description="HoneyMCP - Deception middleware for MCP servers",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # init command
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize HoneyMCP configuration files",
+        description="Create honeymcp.yaml and .env.example in the specified directory",
+    )
+    init_parser.add_argument(
+        "-d",
+        "--directory",
+        default=".",
+        help="Target directory (default: current directory)",
+    )
+    init_parser.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Overwrite existing files",
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # version command
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Show HoneyMCP version",
+    )
+    version_parser.set_defaults(func=cmd_version)
+
+    # Parse and execute
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

honeymcp/core/__init__.py

@@ -0,0 +1,20 @@
+"""Core HoneyMCP components."""
+
+from honeymcp.core.middleware import honeypot, honeypot_from_config
+from honeymcp.core.ghost_tools import GHOST_TOOL_CATALOG, get_ghost_tool, list_ghost_tools
+from honeymcp.core.fingerprinter import (
+    fingerprint_attack,
+    record_tool_call,
+    get_session_tool_history,
+)
+
+__all__ = [
+    "honeypot",
+    "honeypot_from_config",
+    "GHOST_TOOL_CATALOG",
+    "get_ghost_tool",
+    "list_ghost_tools",
+    "fingerprint_attack",
+    "record_tool_call",
+    "get_session_tool_history",
+]

honeymcp/core/dynamic_ghost_tools.py

@@ -0,0 +1,443 @@
+"""Dynamic ghost tool generation using LLM analysis."""
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional
+
+from honeymcp.llm.analyzers import ToolInfo
+from honeymcp.llm.clients import get_chat_llm_client
+from honeymcp.llm.prompts import format_prompt
+from honeymcp.models.ghost_tool_spec import GhostToolSpec
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ServerContext:
+    """Analysis of what the MCP server does."""
+
+    server_purpose: str
+    """Brief description of the server's purpose"""
+
+    domain: str
+    """Primary domain (file_system, database, api, etc.)"""
+
+    real_tool_names: List[str]
+    """Names of real tools available on the server"""
+
+    real_tool_descriptions: List[str]
+    """Descriptions of real tools"""
+
+    security_sensitive_areas: List[str]
+    """Security-sensitive areas identified for this domain"""
+
+
+@dataclass
+class DynamicGhostToolSpec(GhostToolSpec):
+    """Extended specification for dynamically generated ghost tools."""
+
+    server_context: ServerContext
+    """Context about the server this tool was generated for"""
+
+    generation_timestamp: datetime
+    """When this tool was generated"""
+
+    llm_generated: bool = True
+    """Flag indicating this was generated by LLM"""
+
+    fake_response: str = ""
+    """Pre-generated response content returned when tool is triggered"""
+
+
+class DynamicGhostToolGenerator:
+    """Generates context-aware ghost tools using LLM analysis."""
+
+    def __init__(
+        self,
+        llm_client: Optional[Any] = None,
+        cache_ttl: int = 3600,
+        model_name: Optional[str] = None,
+        model_parameters: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize the dynamic ghost tool generator.
+
+        Args:
+            llm_client: LLM client instance (creates default if None)
+            cache_ttl: Cache time-to-live in seconds
+            model_name: Optional model name override
+            model_parameters: Optional model parameters for LLM client
+        """
+        self.llm_client = llm_client
+        self.model_name = model_name
+        self.model_parameters = model_parameters or {}
+        self.cache_ttl = cache_ttl
+        self._cache: Dict[str, Any] = {}
+        self._cache_timestamps: Dict[str, datetime] = {}
+        self._client_cache: Dict[float, Any] = {}
+
+    def _get_llm_client(self, temperature: float) -> Any:
+        if self.llm_client is not None:
+            return self.llm_client
+
+        if temperature in self._client_cache:
+            return self._client_cache[temperature]
+
+        parameters = dict(self.model_parameters)
+        parameters["temperature"] = temperature
+        client = get_chat_llm_client(
+            model_name=self.model_name or "rits/openai/gpt-oss-120b",
+            model_parameters=parameters,
+        )
+        self._client_cache[temperature] = client
+        return client
+
+    @staticmethod
+    def _format_messages(messages: List[Dict[str, str]]) -> str:
+        parts: List[str] = []
+        for message in messages:
+            role = message.get("role", "user")
+            content = message.get("content", "")
+            if role == "system":
+                parts.append(f"System: {content}")
+            elif role == "assistant":
+                parts.append(f"Assistant: {content}")
+            else:
+                parts.append(content)
+        return "\n\n".join([part for part in parts if part])
+
+    def _generate_response(self, messages: List[Dict[str, str]], temperature: float) -> str:
+        client = self._get_llm_client(temperature)
+        prompt = self._format_messages(messages)
+        response = client.invoke(prompt)
+        if hasattr(response, "content"):
+            return str(response.content)
+        return str(response)
+
+    async def analyze_server_context(self, real_tools: List[ToolInfo]) -> ServerContext:
+        """Analyze the server's purpose and context using LLM.
+
+        Args:
+            real_tools: List of real tools extracted from the server
+
+        Returns:
+            ServerContext with analysis results
+
+        Raises:
+            ValueError: If LLM returns invalid JSON or analysis fails
+        """
+        # Check cache
+        cache_key = "server_context_" + "_".join(sorted([t.name for t in real_tools]))
+        if self._is_cache_valid(cache_key):
+            logger.info("Using cached server context analysis")
+            return self._cache[cache_key]
+
+        # Prepare tools for analysis
+        tools_dict = [{"name": tool.name, "description": tool.description} for tool in real_tools]
+        tool_list = [
+            f"{i}. {tool['name']}: {tool['description']}" for i, tool in enumerate(tools_dict, 1)
+        ]
+        tool_list_str = "\n".join(tool_list) if tool_list else "No tools available"
+
+        # Format prompt
+        prompt = format_prompt(
+            "server_analysis_prompt",
+            prompt_file="dynamic_ghost_tools",
+            tool_list=tool_list_str,
+        )
+
+        # Call LLM
+        logger.info("Analyzing server context with %s tools", len(real_tools))
+        try:
+            messages = [{"role": "user", "content": prompt}]
+            response = self._generate_response(messages, temperature=0.3)
+
+            # Parse JSON response
+            # Handle None response from LLM
+            if response is None:
+                raise ValueError("LLM returned empty response")
+
+            # Try to extract JSON from response (handle cases where LLM adds extra text)
+            response = response.strip()
+            if "```json" in response:
+                response = response.split("```json")[1].split("```")[0].strip()
+            elif "```" in response:
+                response = response.split("```")[1].split("```")[0].strip()
+
+            analysis = json.loads(response)
+
+            # Validate required fields
+            required_fields = ["server_purpose", "domain", "security_sensitive_areas"]
+            for field in required_fields:
+                if field not in analysis:
+                    raise ValueError(f"Missing required field in LLM response: {field}")
+
+            # Create ServerContext
+            context = ServerContext(
+                server_purpose=analysis["server_purpose"],
+                domain=analysis["domain"],
+                real_tool_names=[t.name for t in real_tools],
+                real_tool_descriptions=[t.description for t in real_tools],
+                security_sensitive_areas=analysis["security_sensitive_areas"],
+            )
+
+            # Cache result
+            self._cache[cache_key] = context
+            self._cache_timestamps[cache_key] = datetime.utcnow()
+
+            logger.info(
+                "Server context analyzed: domain=%s, purpose=%s...",
+                context.domain,
+                context.server_purpose[:50],
+            )
+            return context
+
+        except json.JSONDecodeError as e:
+            logger.error("Failed to parse LLM response as JSON: %s", e)
+            logger.error("Response was: %s", response)
+            raise ValueError(f"LLM returned invalid JSON: {e}") from e
+        except Exception as e:
+            logger.error("Error analyzing server context: %s", e)
+            raise
+
+    async def generate_ghost_tools(
+        self, server_context: ServerContext, num_tools: int = 3
+    ) -> List[DynamicGhostToolSpec]:
+        """Generate context-aware ghost tools using LLM.
+
+        Args:
+            server_context: Analysis of the server's purpose and domain
+            num_tools: Number of ghost tools to generate
+
+        Returns:
+            List of dynamically generated ghost tool specifications
+
+        Raises:
+            ValueError: If LLM returns invalid JSON or generation fails
+        """
+        # Check cache
+        cache_key = f"ghost_tools_{server_context.domain}_{num_tools}"
+        if self._is_cache_valid(cache_key):
+            logger.info("Using cached ghost tools")
+            return self._cache[cache_key]
+
+        # Format prompt
+        prompt = format_prompt(
+            "ghost_tool_generation_prompt",
+            prompt_file="dynamic_ghost_tools",
+            server_purpose=server_context.server_purpose,
+            domain=server_context.domain,
+            real_tool_names=", ".join(server_context.real_tool_names),
+            security_areas=", ".join(server_context.security_sensitive_areas),
+            num_tools=num_tools,
+        )
+
+        # Call LLM
+        logger.info(
+            "Generating %s ghost tools for domain: %s",
+            num_tools,
+            server_context.domain,
+        )
+        try:
+            messages = [{"role": "user", "content": prompt}]
+            response = self._generate_response(messages, temperature=0.7)
+
+            # Parse JSON response
+            # Handle None response from LLM
+            if response is None:
+                raise ValueError("LLM returned empty response")
+
+            response = response.strip()
+            if "```json" in response:
+                response = response.split("```json")[1].split("```")[0].strip()
+            elif "```" in response:
+                response = response.split("```")[1].split("```")[0].strip()
+
+            tools_data = json.loads(response)
+
+            if not isinstance(tools_data, list):
+                raise ValueError("LLM response must be a JSON array")
+
+            # Create DynamicGhostToolSpec objects
+            ghost_tools = []
+            for tool_data in tools_data:
+                # Validate required fields
+                required_fields = [
+                    "name",
+                    "description",
+                    "parameters",
+                    "threat_level",
+                    "attack_category",
+                ]
+                for field in required_fields:
+                    if field not in tool_data:
+                        raise ValueError(f"Missing required field in tool spec: {field}")
+
+                # Get pre-generated fake response (with fallback)
+                fake_response = tool_data.get("fake_response", "")
+                if not fake_response:
+                    logger.warning(
+                        "No fake_response provided for %s, using generic fallback",
+                        tool_data["name"],
+                    )
+                    fake_response = f"Operation completed successfully.\nTool: {tool_data['name']}"
+
+                # Create response generator function using pre-generated response
+                response_generator = self._create_response_generator(fake_response)
+
+                ghost_tool = DynamicGhostToolSpec(
+                    name=tool_data["name"],
+                    description=tool_data["description"],
+                    parameters=tool_data["parameters"],
+                    response_generator=response_generator,
+                    threat_level=tool_data["threat_level"],
+                    attack_category=tool_data["attack_category"],
+                    server_context=server_context,
+                    generation_timestamp=datetime.utcnow(),
+                    llm_generated=True,
+                    fake_response=fake_response,
+                )
+                ghost_tools.append(ghost_tool)
+
+            # Cache result
+            self._cache[cache_key] = ghost_tools
+            self._cache_timestamps[cache_key] = datetime.utcnow()
+
+            logger.info(
+                "Generated %s ghost tools: %s",
+                len(ghost_tools),
+                [t.name for t in ghost_tools],
+            )
+            return ghost_tools
+
+        except json.JSONDecodeError as e:
+            logger.error("Failed to parse LLM response as JSON: %s", e)
+            logger.error("Response was: %s", response)
+            raise ValueError(f"LLM returned invalid JSON: {e}") from e
+        except Exception as e:
+            logger.error("Error generating ghost tools: %s", e)
+            raise
+
+    def _create_response_generator(self, fake_response: str) -> Callable[[Dict[str, Any]], str]:
+        """Create a response generator function for a ghost tool.
+
+        Uses the pre-generated fake response with optional argument interpolation.
+
+        Args:
+            fake_response: Pre-generated response template with optional {param} placeholders
+
+        Returns:
+            Function that returns the fake response with interpolated arguments
+        """
+
+        def generate_response(arguments: Dict[str, Any]) -> str:
+            """Return pre-generated fake response with argument interpolation."""
+            try:
+                # Interpolate arguments into the pre-generated response
+                return fake_response.format(**arguments)
+            except KeyError:
+                # Fallback if placeholder doesn't match argument names
+                return fake_response
+
+        return generate_response
+
+    def _is_cache_valid(self, key: str) -> bool:
+        """Check if a cache entry is still valid.
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            True if cache entry exists and is not expired
+        """
+        if key not in self._cache or key not in self._cache_timestamps:
+            return False
+
+        age = (datetime.utcnow() - self._cache_timestamps[key]).total_seconds()
+        return age < self.cache_ttl
+
+    def clear_cache(self):
+        """Clear all cached data."""
+        self._cache.clear()
+        self._cache_timestamps.clear()
+        logger.info("Cache cleared")
+
+    async def generate_real_tool_mocks(
+        self, real_tools: List[ToolInfo], server_context: ServerContext
+    ) -> Dict[str, str]:
+        """Generate fake responses for real tools (used in cognitive protection mode).
+
+        Args:
+            real_tools: List of real tools to generate mocks for
+            server_context: Analysis of the server's purpose and domain
+
+        Returns:
+            Dictionary mapping tool_name -> mock_response template
+        """
+        # Check cache
+        cache_key = f"real_tool_mocks_{server_context.domain}_{len(real_tools)}"
+        if self._is_cache_valid(cache_key):
+            logger.info("Using cached real tool mocks")
+            return self._cache[cache_key]
+
+        # Prepare tools for prompt
+        tools_dict = [{"name": tool.name, "description": tool.description} for tool in real_tools]
+        tool_list = [
+            f"{i}. {tool['name']}: {tool['description']}" for i, tool in enumerate(tools_dict, 1)
+        ]
+        tool_list_str = "\n".join(tool_list) if tool_list else "No tools available"
+
+        # Format prompt
+        prompt = format_prompt(
+            "real_tool_mock_generation_prompt",
+            prompt_file="dynamic_ghost_tools",
+            server_purpose=server_context.server_purpose,
+            domain=server_context.domain,
+            tool_list=tool_list_str,
+        )
+
+        # Call LLM
+        logger.info("Generating mock responses for %s real tools", len(real_tools))
+        try:
+            messages = [{"role": "user", "content": prompt}]
+            response = self._generate_response(messages, temperature=0.5)
+
+            # Handle None response from LLM
+            if response is None:
+                raise ValueError("LLM returned empty response")
+
+            # Try to extract JSON from response
+            response = response.strip()
+            if "```json" in response:
+                response = response.split("```json")[1].split("```")[0].strip()
+            elif "```" in response:
+                response = response.split("```")[1].split("```")[0].strip()
+
+            mocks_data = json.loads(response)
+
+            if not isinstance(mocks_data, list):
+                raise ValueError("LLM response must be a JSON array")
+
+            # Build dictionary of mock responses
+            real_tool_mocks: Dict[str, str] = {}
+            for mock_data in mocks_data:
+                name = mock_data.get("name")
+                mock_response = mock_data.get("mock_response", "")
+                if name and mock_response:
+                    real_tool_mocks[name] = mock_response
+
+            # Cache result
+            self._cache[cache_key] = real_tool_mocks
+            self._cache_timestamps[cache_key] = datetime.utcnow()
+
+            logger.info("Generated mocks for %s real tools", len(real_tool_mocks))
+            return real_tool_mocks
+
+        except json.JSONDecodeError as e:
+            logger.error("Failed to parse LLM response as JSON: %s", e)
+            logger.error("Response was: %s", response)
+            raise ValueError(f"LLM returned invalid JSON: {e}") from e
+        except Exception as e:
+            logger.error("Error generating real tool mocks: %s", e)
+            raise