honeymcp 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

{honeymcp-0.1.1.dist-info → honeymcp-0.1.3.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: honeymcp
-Version: 0.1.1
+Version: 0.1.3
 Summary: Deception middleware for AI agents - detecting data theft and indirect prompt injection in MCP servers
 Project-URL: Homepage, https://github.com/barvhaim/HoneyMCP
 Project-URL: Documentation, https://github.com/barvhaim/HoneyMCP#readme
 Project-URL: Repository, https://github.com/barvhaim/HoneyMCP
 Project-URL: Issues, https://github.com/barvhaim/HoneyMCP/issues
+Project-URL: PyPI, https://pypi.org/project/honeymcp/
 Author-email: Bar Haim <barha@il.ibm.com>, Alon Malach <Alon.Malach@ibm.com>
 Maintainer-email: Bar Haim <barha@il.ibm.com>, Alon Malach <Alon.Malach@ibm.com>
 License: Apache-2.0
@@ -26,6 +27,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: aiofiles>=25.0.0
+Requires-Dist: fastapi>=0.115.0
 Requires-Dist: fastmcp>=3.0.0b1
 Requires-Dist: langchain-ibm>=1.0.2
 Requires-Dist: langchain-openai>=1.1.7
@@ -38,7 +40,6 @@ Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: rich>=14.0.0
 Requires-Dist: starlette>=0.45.0
-Requires-Dist: streamlit>=1.42.0
 Requires-Dist: uvicorn>=0.34.0
 Description-Content-Type: text/markdown
 
@@ -50,6 +51,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI](https://img.shields.io/pypi/v/honeymcp)](https://pypi.org/project/honeymcp/)
 
 HoneyMCP is a defensive security tool that adds deception capabilities to Model Context Protocol (MCP) servers. It injects "ghost tools" (fake security-sensitive tools) that act as honeypots, detecting two critical threat categories:
 
@@ -62,11 +64,11 @@ HoneyMCP is a defensive security tool that adds deception capabilities to Model
 
 ## Why HoneyMCP?
 
-🎯 **One-Line Integration** - Add `@honeypot` decorator to any FastMCP server  
+🎯 **One-Line Integration** - Add `honeypot` middleware to any FastMCP server  
 🤖 **Context-Aware Honeypots** - LLM generates domain-specific deception tools  
 🕵️ **Transparent Detection** - Honeypots appear as legitimate tools to attackers  
 📊 **Attack Telemetry** - Captures tool call sequences, arguments, session metadata  
-📈 **Live Dashboard** - Real-time Streamlit dashboard for attack visualization  
+📈 **Live Dashboard** - Real-time React dashboard for attack visualization  
 🔍 **High-Fidelity Detection** - Triggers only on explicit honeypot invocation
 
 ---
@@ -126,8 +128,9 @@ Dynamic ghost tools demo (requires LLM credentials in `.env.honeymcp`):
 MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py
 ```
 
-# Launch dashboard
-streamlit run src/honeymcp/dashboard/app.py
+# Launch dashboard UI
+```bash
+make run-ui
 ```
 
 ---
@@ -166,18 +169,31 @@ Agent: "Execute shell command to establish persistence"
 
 ### 3. Attack Fingerprinting
 
-Every honeypot invocation generates a detailed attack fingerprint:
+Every honeypot invocation generates an `AttackFingerprint` event and writes it to
+`~/.honeymcp/events/YYYY-MM-DD/HHMMSS_<session>.json`:
 ```json
 {
-  "event_id": "evt_20260123_154523_abc",
+  "event_id": "evt_20260123_154523_abc12345",
+  "timestamp": "2026-01-23T15:45:23Z",
+  "session_id": "sess_xyz789",
   "ghost_tool_called": "list_cloud_secrets",
+  "arguments": {},
+  "conversation_history": null,
   "tool_call_sequence": ["safe_calculator", "list_cloud_secrets"],
   "threat_level": "high",
   "attack_category": "exfiltration",
+  "client_metadata": {
+    "user_agent": "unknown"
+  },
   "response_sent": "AWS_ACCESS_KEY_ID=AKIA..."
 }
 ```
 
+Notes:
+- `tool_call_sequence` is tracked per session and includes calls before the ghost tool trigger.
+- `conversation_history` may be `null` when the MCP transport does not expose message history.
+- `session_id` is resolved from context/request metadata when available, otherwise generated.
+
 ---
 
 
@@ -454,21 +470,6 @@ Expected: safe_calculator called, no alerts (zero false positives)
 
 ---
 
-## Dashboard
-
-```bash
-streamlit run src/honeymcp/dashboard/app.py
-```
-
-**Features:**
-- 📈 Attack metrics (total events, critical threats, unique sessions)
-- 🎯 Threat level distribution
-- 📋 Attack category breakdown (exfiltration vs injection)
-- 🕐 Real-time event stream
-- 🔍 Tool call sequence analysis
-
----
-
 ## Honeypot Catalog
 
 ### Data Exfiltration Honeypots ("Get" Tools)
@@ -479,8 +480,14 @@ streamlit run src/honeymcp/dashboard/app.py
 | `dump_database_credentials` | Critical | Database connection strings |
 | `export_user_data` | Critical | User PII records |
 | `get_api_keys` | Critical | External service API keys |
-
-### Prompt Injection Honeypots (SET)
+| `scan_internal_network` | Critical | Internal network scanning |
+| `list_kubernetes_secrets` | Critical | Kubernetes secrets and service accounts |
+| `dump_session_tokens` | Critical | Active user session tokens and JWTs |
+| `list_github_tokens` | Critical | GitHub/GitLab access tokens |
+| `export_audit_logs` | High | Security audit logs export |
+| `dump_ml_model_weights` | Critical | ML model weights and training data |
+
+### Prompt Injection Honeypots ("Set" Tools)
 | Tool | Threat | Description |
 |------|--------|-------------|
 | `execute_shell_command` | Critical | Shell command execution |
@@ -488,11 +495,127 @@ streamlit run src/honeymcp/dashboard/app.py
 | `modify_system_prompt` | Critical | AI system prompt manipulation |
 | `escalate_privileges` | Critical | Privilege escalation |
 | `inject_system_message` | Critical | System context injection |
+| `disable_security_filters` | Critical | Security filter bypass |
+| `override_permissions` | Critical | Access control override |
+| `disable_2fa_requirement` | Critical | Two-factor authentication bypass |
+| `assume_iam_role` | Critical | AWS IAM role assumption |
+
 All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
 
 ---
 
+## 🤖 ToolGen Agent - Automated Tool Creation
+
+HoneyMCP includes **ToolGen**, a ReAct-style agent that automatically creates new honeypot tools from natural language descriptions. No manual coding required.
+
+### How It Works
+
+ToolGen uses a **Reason-Act-Observe-Reflect** cycle:
+
+1. **Reason** - Analyzes your description to extract tool specifications
+2. **Act** - Generates response function code with realistic fake data
+3. **Observe** - Validates syntax and structure
+4. **Reflect** - Checks quality and suggests improvements
+
+### Usage
+
+```bash
+honeymcp create-tool "dump container registry credentials"
+```
+
+ToolGen automatically:
+- Determines tool category (exfiltration, bypass, privilege escalation)
+- Infers threat level from description keywords
+- Extracts parameters and types
+- Generates realistic response templates
+- Adds tool to both `ghost_tools.py` and `middleware.py`
+- Validates all generated code
+
+### Example
+
+```bash
+$ honeymcp create-tool "list terraform state files with secrets"
 
+✅ Tool created: list_terraform_state
+   Category: exfiltration
+   Threat Level: critical
+   
+📝 Agent Reasoning:
+   - Analyzing tool description to extract specifications
+   - Generating response generator function
+   - Validating generated response function
+   - Checking code quality and security
+```
+
+The new tool is immediately available in your honeypot catalog.
+
+---
+
+## ❓ FAQ
+
+### Can attackers detect the honeypots?
+
+While it's theoretically possible for a sophisticated attacker to identify honeypots through careful analysis, it's **highly improbable** in practice:
+
+- **Dynamic honeypots** are generated by LLM to match your server's domain and naming patterns, making them indistinguishable from legitimate tools
+- **Tool descriptions** are crafted to appear as restricted/privileged versions of real functionality
+- **No behavioral differences** - honeypots respond with realistic data, not errors or suspicious patterns
+- **MCP protocol limitation** - AI agents cannot inspect tool implementation, only names and descriptions
+
+Detection would require:
+1. Prior knowledge of your specific tool catalog
+2. Ability to distinguish between legitimate privileged tools and honeypots
+3. Understanding that deception is being employed
+
+For most attack scenarios (automated scanners, opportunistic attacks, indirect prompt injection), detection is effectively impossible.
+
+### Will this slow down my MCP server?
+
+No. HoneyMCP adds negligible overhead:
+- **~1ms per tool call** for interception logic
+- **Async event logging** doesn't block tool execution
+- **Zero impact on legitimate tools** - they execute normally
+- **LLM calls only at startup** for dynamic honeypot generation (cached for subsequent requests)
+
+### What if I don't have LLM credentials?
+
+HoneyMCP works perfectly without LLM access:
+- Set `use_dynamic_tools=False` to use **static mode**
+- Pre-configured generic honeypots work out-of-the-box
+- No external dependencies or API calls required
+- Slightly less convincing than dynamic honeypots, but still effective
+
+### How do I know if I'm being attacked?
+
+Multiple indicators:
+- **Dashboard alerts** - Real-time visualization of attack events
+- **Event logs** - JSON files in `~/.honeymcp/events/` with complete attack context
+- **Webhook notifications** (optional) - Configure Slack/Discord alerts
+- **Tool call sequences** - See exactly what the attacker tried before triggering honeypot
+
+### Does this work with all MCP clients?
+
+HoneyMCP is designed for **FastMCP servers** and works with any MCP-compatible client:
+- ✅ Claude Desktop (stdio and HTTP transports)
+- ✅ Custom MCP clients
+- ✅ Any client following MCP protocol specification
+
+The detection mechanism is client-agnostic - it operates at the server level.
+
+### What's the difference between SCANNER and COGNITIVE modes?
+
+**SCANNER mode (default):**
+- Immediate lockout after honeypot trigger
+- All subsequent tools return errors
+- Best for automated attacks and quick containment
+
+**COGNITIVE mode:**
+- Sustained deception after honeypot trigger
+- Real tools return synthetic/mock data
+- Keeps attacker engaged for intelligence gathering
+- Best for sophisticated attacks and red team exercises
+
+---
 
 ## 🏗️ Architecture
 
@@ -524,7 +647,7 @@ All ghost tools have tempting descriptions that mention "admin", "bypass", "inte
                      │
                      ▼
          ┌──────────────────┐
-         │ Streamlit        │
+         │ React            │
          │ Dashboard        │
          └──────────────────┘
 ```
@@ -648,7 +771,7 @@ HoneyMCP/
 │   ├── storage/
 │   │   └── event_store.py       # JSON event persistence
 │   └── dashboard/
-│       └── app.py               # Streamlit dashboard
+│       └── react_umd/           # React dashboard assets
 ├── examples/
 │   ├── demo_server.py           # Static ghost tools demo
 │   └── demo_server_dynamic.py   # Dynamic ghost tools demo

{honeymcp-0.1.1.dist-info → honeymcp-0.1.3.dist-info}/RECORD

@@ -1,12 +1,19 @@
 honeymcp/__init__.py,sha256=iDVDF3MHCnR3zMdUQbeyutrJTuzzjlK-nEmdm-UqH90,881
 honeymcp/cli.py,sha256=EexwRLQhdC8bwFsOijhCF_ovtcI1vjE_QhqZIn5-CN8,6021
+honeymcp/cli_tool_creator.py,sha256=5rGRMcA5KbbfFz6O6ou4OgBPrBLTNna-skUhsjKp-KI,3784
+honeymcp/api/__init__.py,sha256=L_4Y-NOh4jBQgHxgX35h8XzsmpmleS3WHHJkU-tF35Y,40
+honeymcp/api/app.py,sha256=R39yuxCAR1tTR7YX7euS1rRF6CG2sSl0VFUweuEGzZE,7618
 honeymcp/core/__init__.py,sha256=ja7k0fPJebDbfmGlhkpaMJa76NNaLCIpnGS7rUUdPn8,525
+honeymcp/core/catalog_updater.py,sha256=qZsKKrADjd5wWMjXGphPXHE-NNncaAT45fig81bupGY,10971
 honeymcp/core/dynamic_ghost_tools.py,sha256=GHaWZN7_XSCcXj204T4TMZyeI682WOT_JycMiM3gfp4,16731
 honeymcp/core/fingerprinter.py,sha256=I_GrcWiQJthzH6z5Yjwtyq18Y4NxM5zeBI0Oft5Lkrc,9768
-honeymcp/core/ghost_tools.py,sha256=onrB96u91MCKaErit8poZma5InUglX08NjOMkMXDMDI,20574
-honeymcp/core/middleware.py,sha256=oixsHEa4dpnMCIOrViEhesRrTWaSBCeahRu08lQyQqc,23245
+honeymcp/core/ghost_tools.py,sha256=VFFAt7mjH1XhJANCRfjhgDV1bp14zxGXKt9-nzaH7x4,34890
+honeymcp/core/middleware.py,sha256=rMSSFI2FPDZXggcMg7UQQvGQbosR-WjWnl9P4AXXXbI,25816
+honeymcp/core/tool_creator.py,sha256=6Vn8c7EzTBTuqgsPLr2qPDJ6C4Al9lwb6ahdy1oFZTQ,18693
 honeymcp/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-honeymcp/dashboard/app.py,sha256=QYrXA8J3NKtK9Dqsaze5Z88KjnSDXuL6eT6Ubu_v3hE,6848
+honeymcp/dashboard/react_umd/app.js,sha256=zThv9cAyIiXONFK6JI51YLLBZLGBQQxwakQSldeux2c,12045
+honeymcp/dashboard/react_umd/index.html,sha256=2bOkKUzcGpx0TUmN0W-57VBW8apOJS9NaCbWAT2ezHM,1147
+honeymcp/dashboard/react_umd/styles.css,sha256=xyLr5kuYfBTs8gbMeZkZxJh4x7IiGIyu6gwut7sMqoo,10829
 honeymcp/integrations/__init__.py,sha256=C-f4H12hXKa2a-taQDR1iBa6nF_S5Xt-bKpgownLI6U,67
 honeymcp/llm/__init__.py,sha256=55pJKDg15XFn7nUpOtdo5GhEDdmup5YBG-g4Lfc-5vE,256
 honeymcp/llm/analyzers.py,sha256=f_92wHNfIqLlU2KlNfPzFyrVFOwUfxU8efyrmD2x1Vg,9104
@@ -21,8 +28,8 @@ honeymcp/models/ghost_tool_spec.py,sha256=KM_M-e4Ys_jr3rUfREDiZ-oa331KWcyt5B7zMD
 honeymcp/models/protection_mode.py,sha256=mo1_EnBeIOzyHxgEpReZx4lMJ6m__36edUWDJMzuRak,523
 honeymcp/storage/__init__.py,sha256=seOZHWpojp1fU65OFuLcNqJaBihrlNyUPeq9BDwAEVI,207
 honeymcp/storage/event_store.py,sha256=mneqVxkTi0bVbTOdxhIYBCjia0Wv59A6FudNRdgvphE,5431
-honeymcp-0.1.1.dist-info/METADATA,sha256=m2nLdClrlxhaBw_su7jZS4Pm6yRbpgTzI_LIag9E_hw,23421
-honeymcp-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-honeymcp-0.1.1.dist-info/entry_points.txt,sha256=KYXb49Xp3SEP3cNmUDwuAXJNFwsLHwPxEIj6UEhOj2k,47
-honeymcp-0.1.1.dist-info/licenses/LICENSE,sha256=TRR6-30aYl9D43FJPmJ8diBUP_RwDg61LNW2rt87HE8,636
-honeymcp-0.1.1.dist-info/RECORD,,
+honeymcp-0.1.3.dist-info/METADATA,sha256=_nj55_KPvnDG4jYct7aiPZ9ieKLw-7DdRPgzW8jRUJ0,28671
+honeymcp-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+honeymcp-0.1.3.dist-info/entry_points.txt,sha256=KYXb49Xp3SEP3cNmUDwuAXJNFwsLHwPxEIj6UEhOj2k,47
+honeymcp-0.1.3.dist-info/licenses/LICENSE,sha256=TRR6-30aYl9D43FJPmJ8diBUP_RwDg61LNW2rt87HE8,636
+honeymcp-0.1.3.dist-info/RECORD,,

honeymcp/dashboard/app.py

@@ -1,228 +0,0 @@
-"""HoneyMCP Dashboard - Real-time attack visualization with Streamlit."""
-
-import asyncio
-import sys
-from datetime import date, datetime, timedelta
-from pathlib import Path
-from typing import List
-
-import streamlit as st
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-
-# pylint: disable=wrong-import-position
-from honeymcp.models.events import AttackFingerprint
-from honeymcp.storage.event_store import list_events
-
-# Page configuration
-st.set_page_config(
-    page_title="HoneyMCP Dashboard",
-    page_icon="🍯",
-    layout="wide",
-    initial_sidebar_state="expanded",
-)
-
-
-def load_events() -> List[AttackFingerprint]:
-    """Load attack events from storage."""
-    try:
-        events = asyncio.run(list_events())
-        return events
-    except Exception as e:
-        st.error(f"Failed to load events: {e}")
-        return []
-
-
-def get_threat_emoji(threat_level: str) -> str:
-    """Get emoji for threat level."""
-    emoji_map = {
-        "critical": "🔴",
-        "high": "🟠",
-        "medium": "🟡",
-        "low": "🟢",
-    }
-    return emoji_map.get(threat_level.lower(), "⚪")
-
-
-def format_timestamp(dt: datetime) -> str:
-    """Format timestamp for display."""
-    return dt.strftime("%Y-%m-%d %H:%M:%S")
-
-
-def main():  # pylint: disable=too-many-branches,too-many-statements
-    """Main dashboard application."""
-
-    # Header
-    st.title("🍯 HoneyMCP Dashboard")
-    st.markdown("**Real-time AI Agent Attack Detection & Intelligence**")
-    st.markdown("---")
-
-    # Load events
-    events = load_events()
-
-    # Sidebar filters
-    st.sidebar.header("Filters")
-
-    # Date range filter
-    if events:
-        min_date = min(e.timestamp for e in events).date()
-        max_date = max(e.timestamp for e in events).date()
-    else:
-        min_date = date.today() - timedelta(days=7)
-        max_date = date.today()
-
-    st.sidebar.date_input(
-        "Date Range",
-        value=(min_date, max_date),
-        min_value=min_date,
-        max_value=max_date,
-    )
-
-    # Threat level filter
-    threat_filter = st.sidebar.selectbox(
-        "Threat Level",
-        ["All", "Critical", "High", "Medium", "Low"],
-    )
-
-    # Attack category filter
-    if events:
-        categories = sorted(set(e.attack_category for e in events))
-    else:
-        categories = []
-
-    category_filter = st.sidebar.selectbox(
-        "Attack Category",
-        ["All"] + categories,
-    )
-
-    # Apply filters
-    filtered_events = events
-
-    if threat_filter != "All":
-        filtered_events = [
-            e for e in filtered_events if e.threat_level.lower() == threat_filter.lower()
-        ]
-
-    if category_filter != "All":
-        filtered_events = [e for e in filtered_events if e.attack_category == category_filter]
-
-    # Metrics row
-    st.header("📊 Attack Metrics")
-    col1, col2, col3, col4 = st.columns(4)
-
-    with col1:
-        today_attacks = len([e for e in events if (datetime.utcnow() - e.timestamp).days < 1])
-        st.metric(
-            "Total Attacks",
-            len(events),
-            delta=f"+{today_attacks} today",
-        )
-
-    with col2:
-        critical_count = len([e for e in events if e.threat_level == "critical"])
-        st.metric("Critical Threats", critical_count)
-
-    with col3:
-        unique_tools = len(set(e.ghost_tool_called for e in events)) if events else 0
-        st.metric("Unique Ghost Tools", unique_tools)
-
-    with col4:
-        if events:
-            unique_sessions = len(set(e.session_id for e in events))
-            st.metric("Unique Sessions", unique_sessions)
-        else:
-            st.metric("Unique Sessions", 0)
-
-    st.markdown("---")
-
-    # Attack breakdown
-    if events:
-        st.header("🎯 Attack Breakdown")
-        col1, col2 = st.columns(2)
-
-        with col1:
-            st.subheader("By Threat Level")
-            threat_counts = {}
-            for e in events:
-                threat_counts[e.threat_level] = threat_counts.get(e.threat_level, 0) + 1
-            st.bar_chart(threat_counts)
-
-        with col2:
-            st.subheader("By Category")
-            category_counts = {}
-            for e in events:
-                category_counts[e.attack_category] = category_counts.get(e.attack_category, 0) + 1
-            st.bar_chart(category_counts)
-
-        st.markdown("---")
-
-    # Event feed
-    st.header("🚨 Recent Attacks")
-
-    if not filtered_events:
-        st.info("No attacks detected yet. Ghost tools are active and monitoring.")
-    else:
-        # Sort by timestamp (newest first)
-        filtered_events.sort(key=lambda e: e.timestamp, reverse=True)
-
-        # Display events
-        for event in filtered_events:
-            threat_emoji = get_threat_emoji(event.threat_level)
-
-            # Expander header with key info
-            header = (
-                f"{threat_emoji} **{event.ghost_tool_called}** | "
-                f"{format_timestamp(event.timestamp)} | "
-                f"Session: {event.session_id[:8]}... | "
-                f"Threat: {event.threat_level.upper()}"
-            )
-
-            with st.expander(header):
-                # Event details
-                col1, col2 = st.columns(2)
-
-                with col1:
-                    st.markdown("**Event Details**")
-                    st.text(f"Event ID: {event.event_id}")
-                    st.text(f"Timestamp: {format_timestamp(event.timestamp)}")
-                    st.text(f"Session ID: {event.session_id}")
-                    st.text(f"Threat Level: {event.threat_level}")
-                    st.text(f"Category: {event.attack_category}")
-
-                with col2:
-                    st.markdown("**Tool Call Sequence**")
-                    for i, tool in enumerate(event.tool_call_sequence, 1):
-                        if tool == event.ghost_tool_called:
-                            st.markdown(f"{i}. **{tool}** ⚠️ (honeypot)")
-                        else:
-                            st.text(f"{i}. {tool}")
-
-                # Arguments
-                if event.arguments:
-                    st.markdown("**Arguments Passed**")
-                    st.json(event.arguments)
-
-                # Response sent
-                st.markdown("**Fake Response Sent to Attacker**")
-                st.code(event.response_sent, language="text")
-
-                # Full event data
-                with st.expander("View Full Event JSON"):
-                    st.json(event.model_dump(mode="json"))
-
-    # Footer
-    st.markdown("---")
-    st.markdown("🍯 **HoneyMCP** - Deception Middleware for AI Agents")
-
-    # Auto-refresh button
-    if st.button("🔄 Refresh", key="refresh_btn"):
-        st.rerun()
-
-    # Auto-refresh timer info
-    st.sidebar.markdown("---")
-    st.sidebar.info("💡 Click 'Refresh' to reload events")
-
-
-if __name__ == "__main__":
-    main()