honeymcp 0.1.2__tar.gz → 0.1.3__tar.gz

{honeymcp-0.1.2 → honeymcp-0.1.3}/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 - Source code lives in `src/honeymcp/` with core middleware in `src/honeymcp/core/` and data models in `src/honeymcp/models/`.
-- LLM integration is in `src/honeymcp/llm/`, storage in `src/honeymcp/storage/`, and the Streamlit UI in `src/honeymcp/dashboard/`.
+- LLM integration is in `src/honeymcp/llm/`, storage in `src/honeymcp/storage/`, and the dashboard UI in `src/honeymcp/dashboard/`.
 - Examples are in `examples/` (e.g., `examples/demo_server.py`).
 - Tests are currently small and live at the repo root (e.g., `test_dynamic_tools.py`).
 - Build artifacts and packaged outputs appear in `dist/`.
@@ -12,7 +12,7 @@ Use `uv` for local development:
 - `uv sync` installs dev dependencies.
 - `uv sync --no-dev` installs runtime-only dependencies.
 - `uv run python examples/demo_server.py` runs the demo server.
-- `streamlit run src/honeymcp/dashboard/app.py` launches the dashboard.
+- `make run-ui` launches the dashboard API/UI at `http://127.0.0.1:8001/dashboard`.
 - `uv run pytest` runs tests.
 
 Makefile shortcuts:

{honeymcp-0.1.2 → honeymcp-0.1.3}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install dev test lint format clean run-dashboard run-example build inspector
+.PHONY: help install dev test lint format clean run-example run-ui build inspector
 
 help:
 	@echo "Available commands:"
@@ -8,8 +8,8 @@ help:
 	@echo "  make lint           - Run linting checks"
 	@echo "  make format         - Format code"
 	@echo "  make clean          - Clean build artifacts and cache"
-	@echo "  make run-dashboard  - Run the Streamlit dashboard"
 	@echo "  make run-example    - Run the demo server example"
+	@echo "  make run-ui         - Run API for React dashboard (/dashboard)"
 	@echo "  make build          - Build the package"
 	@echo "  make inspector      - Run MCP Inspector (npx)"
 
@@ -36,12 +36,13 @@ clean:
 	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
 	rm -rf build/ dist/ .pytest_cache/ .mypy_cache/ .ruff_cache/
 
-run-dashboard:
-	uv run streamlit run src/honeymcp/dashboard/app.py
-
 run-example:
 	uv run python examples/demo_server.py
 
+run-ui:
+	@echo "React dashboard: http://127.0.0.1:8001/dashboard"
+	uv run uvicorn honeymcp.api.app:app --reload --host 127.0.0.1 --port 8001
+
 build:
 	uv build
 

{honeymcp-0.1.2 → honeymcp-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: honeymcp
-Version: 0.1.2
+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
@@ -27,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
@@ -39,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
 
@@ -64,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
 
 ---
@@ -128,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
 ```
 
 ---
@@ -168,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.
+
 ---
 
 
@@ -456,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)
@@ -481,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 |
@@ -490,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
 
@@ -526,7 +647,7 @@ All ghost tools have tempting descriptions that mention "admin", "bypass", "inte
                      │
                      ▼
          ┌──────────────────┐
-         │ Streamlit        │
+         │ React            │
          │ Dashboard        │
          └──────────────────┘
 ```
@@ -650,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.2 → honeymcp-0.1.3}/README.md

@@ -19,11 +19,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
 
 ---
@@ -83,8 +83,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
 ```
 
 ---
@@ -123,18 +124,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.
+
 ---
 
 
@@ -411,21 +425,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)
@@ -436,8 +435,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 |
@@ -445,11 +450,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
 
@@ -481,7 +602,7 @@ All ghost tools have tempting descriptions that mention "admin", "bypass", "inte
                      │
                      ▼
          ┌──────────────────┐
-         │ Streamlit        │
+         │ React            │
          │ Dashboard        │
          └──────────────────┘
 ```
@@ -605,7 +726,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.2 → honeymcp-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "honeymcp"
-version = "0.1.2"
+version = "0.1.3"
 description = "Deception middleware for AI agents - detecting data theft and indirect prompt injection in MCP servers"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,9 +41,9 @@ classifiers = [
 ]
 dependencies = [
     "fastmcp>=3.0.0b1",
+    "fastapi>=0.115.0",
     "pydantic>=2.10.0",
     "pyyaml>=6.0.0",
-    "streamlit>=1.42.0",
     "requests>=2.32.0",
     "python-dateutil>=2.9.0",
     "rich>=14.0.0",

honeymcp-0.1.3/src/honeymcp/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI application for HoneyMCP."""