honeymcp 0.1.3__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: honeymcp
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -133,6 +133,8 @@ MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py
 make run-ui
 ```
 
+<img width="1426" height="972" alt="image" src="https://github.com/user-attachments/assets/2dfc37a2-8caa-4338-b7f7-1cbac7ed9d79" />
+
 ---
 
 ## 🎭 How It Works
@@ -275,8 +277,18 @@ mcp = honeypot(mcp, protection_mode=ProtectionMode.COGNITIVE)
 The easiest way to configure HoneyMCP:
 ```bash
 honeymcp init  # Creates honeymcp.yaml + .env.honeymcp
+# Optional: remove all persisted attack event files
+honeymcp clean-data
 ```
 
+### Clear Stored Events
+
+You can remove all persisted event JSON files from CLI, API, or UI:
+
+- CLI: `honeymcp clean-data`
+- API: `DELETE /events`
+- Dashboard: Use the **Clear Stored Data** button
+
 ### YAML Config
 
 ```yaml
@@ -551,244 +563,17 @@ 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
+## Documentation
 
+- [FAQ](docs/faq.md)
+- [Architecture](docs/architecture.md)
+- [Use Cases](docs/use-cases.md)
+- [Security Considerations](docs/security-considerations.md)
+- [Development](docs/development.md)
+- [CLI Reference](docs/cli-reference.md)
 ---
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        AI Agent (Claude)                     │
-└────────────────────┬───────────────────────▲────────────────┘
-                     │                        │
-                     │ MCP Protocol           │
-                     ▼                        │
-┌─────────────────────────────────────────────────────────────┐
-│                    HoneyMCP Middleware                       │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │ Tool Call Interceptor                                  │ │
-│  │  ├─ Is ghost tool?                                    │ │
-│  │  │   YES: Fingerprint + Store + Return fake data      │ │
-│  │  │   NO:  Pass through to legitimate tool             │ │
-│  └────────────────────────────────────────────────────────┘ │
-│                                                              │
-│  Ghost Tools: [list_cloud_secrets, execute_shell_command]   │
-│  Real Tools:  [safe_calculator, get_weather, ...]           │
-└─────────────────────────────────────────────────────────────┘
-                     │                        ▲
-                     ▼                        │
-         ┌──────────────────┐    ┌──────────────────┐
-         │ Event Storage    │    │ Your Real Tools  │
-         │ ~/.honeymcp/     │    │                  │
-         └──────────────────┘    └──────────────────┘
-                     │
-                     ▼
-         ┌──────────────────┐
-         │ React            │
-         │ Dashboard        │
-         └──────────────────┘
-```
-
 ---
 
-## 🎓 Use Cases
-
-### 1. Production Monitoring
-Deploy HoneyMCP in production to detect attacks targeting your AI agents:
-- **Customer support bots** - Detect attempts to exfiltrate customer data or inject malicious responses
-- **Internal AI assistants** - Catch data theft attempts targeting internal credentials or documents
-- **Code generation tools** - Detect injection of malicious code or unauthorized file access
-- **Data analysis agents** - Identify attempts to steal sensitive datasets or manipulate outputs
-
-### 2. Red Team Testing
-Use HoneyMCP to validate your AI security defenses:
-- Test if your AI filters catch data exfiltration attempts
-- Measure indirect prompt injection success rates
-- Gather TTPs for threat modeling
-
-### 3. Security Research
-Study AI agent attack techniques in the wild:
-- Capture real-world exfiltration patterns
-- Analyze indirect prompt injection payloads
-- Build threat intelligence database
-
-### 4. Compliance & Auditing
-Demonstrate security controls for AI systems:
-- Prove attack detection capabilities for data theft and injection attacks
-- Generate audit logs of attempted attacks
-- Meet AI security compliance requirements
-
-## Security Considerations
-
-### Detection Capabilities
-✅ Detects data exfiltration attempts via GET-style honeypots  
-✅ Detects indirect prompt injection via SET-style honeypots  
-✅ Captures complete attack context and telemetry  
-✅ Returns synthetic data to maintain deception
-
-### Limitations
-❌ Detection-only system (does not prevent attacks)  
-❌ Does not sanitize or filter user input  
-❌ Not a replacement for input validation and security controls  
-❌ Cannot guarantee conversation history capture (MCP protocol limitation)
-
-**Deploy HoneyMCP as part of defense-in-depth strategy, not as a standalone security control.**
-
-
-### Best Practices
-1. **Defense in Depth** - Use HoneyMCP alongside input filters, not as a replacement
-2. **Monitor the Dashboard** - Regularly review attack patterns for both exfiltration and injection
-3. **Investigate Alerts** - Each ghost tool call is a high-confidence attack signal
-4. **Secure Storage** - Protect `~/.honeymcp/events/` (contains attack data)
-
----
-
-## 💻 CLI Reference
-
-HoneyMCP includes a command-line tool for setup and management.
-
-### Initialize Configuration
-
-```bash
-honeymcp init [--directory DIR] [--force]
-```
-
-Creates `honeymcp.yaml` and `.env.honeymcp` in the target directory.
-
-Options:
-- `-d, --directory` - Target directory (default: current directory)
-- `-f, --force` - Overwrite existing files
-
-### Show Version
-
-```bash
-honeymcp version
-```
-
----
-
-## 🛠️ Development
-
-### Install from Source
-
-```bash
-git clone https://github.com/barvhaim/HoneyMCP.git
-cd HoneyMCP
-uv sync
-
-# Run tests
-uv run pytest
-
-# Lint & format
-make lint
-make format
-```
-
-### Project Structure
-
-```
-HoneyMCP/
-├── src/honeymcp/
-│   ├── __init__.py              # Main exports
-│   ├── cli.py                   # CLI (honeymcp init, version)
-│   ├── core/
-│   │   ├── middleware.py        # @honeypot decorator
-│   │   ├── ghost_tools.py       # Ghost tool catalog
-│   │   ├── fingerprinter.py     # Attack context capture
-│   │   └── dynamic_ghost_tools.py# LLM-driven ghost tool generation
-│   ├── models/
-│   │   ├── events.py            # AttackFingerprint model
-│   │   ├── ghost_tool_spec.py   # GhostToolSpec definition
-│   │   └── config.py            # Configuration
-│   ├── llm/
-│   │   ├── analyzers.py          # Tool extraction and categorization
-│   │   ├── clients/              # LLM providers (Watsonx/OpenAI/RITS)
-│   │   └── prompts/              # Prompt templates
-│   ├── integrations/            # External integrations
-│   ├── storage/
-│   │   └── event_store.py       # JSON event persistence
-│   └── dashboard/
-│       └── react_umd/           # React dashboard assets
-├── examples/
-│   ├── demo_server.py           # Static ghost tools demo
-│   └── demo_server_dynamic.py   # Dynamic ghost tools demo
-├── tests/                       # Pytest suite (e2e + dynamic tools)
-├── pyproject.toml               # Dependencies
-└── README.md                    # This file
-```
-
-### Tests
-
-```bash
-uv run pytest
-```
-
-Notes:
-- Dynamic tool tests require LLM credentials in `.env.honeymcp` and will skip if env vars are missing.
-
 ## 📄 License
 
 Apache 2.0 - See [LICENSE](LICENSE) for details.

{honeymcp-0.1.3 → honeymcp-0.1.4}/README.md

@@ -88,6 +88,8 @@ MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py
 make run-ui
 ```
 
+<img width="1426" height="972" alt="image" src="https://github.com/user-attachments/assets/2dfc37a2-8caa-4338-b7f7-1cbac7ed9d79" />
+
 ---
 
 ## 🎭 How It Works
@@ -230,8 +232,18 @@ mcp = honeypot(mcp, protection_mode=ProtectionMode.COGNITIVE)
 The easiest way to configure HoneyMCP:
 ```bash
 honeymcp init  # Creates honeymcp.yaml + .env.honeymcp
+# Optional: remove all persisted attack event files
+honeymcp clean-data
 ```
 
+### Clear Stored Events
+
+You can remove all persisted event JSON files from CLI, API, or UI:
+
+- CLI: `honeymcp clean-data`
+- API: `DELETE /events`
+- Dashboard: Use the **Clear Stored Data** button
+
 ### YAML Config
 
 ```yaml
@@ -506,244 +518,17 @@ 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
+## Documentation
 
+- [FAQ](docs/faq.md)
+- [Architecture](docs/architecture.md)
+- [Use Cases](docs/use-cases.md)
+- [Security Considerations](docs/security-considerations.md)
+- [Development](docs/development.md)
+- [CLI Reference](docs/cli-reference.md)
 ---
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        AI Agent (Claude)                     │
-└────────────────────┬───────────────────────▲────────────────┘
-                     │                        │
-                     │ MCP Protocol           │
-                     ▼                        │
-┌─────────────────────────────────────────────────────────────┐
-│                    HoneyMCP Middleware                       │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │ Tool Call Interceptor                                  │ │
-│  │  ├─ Is ghost tool?                                    │ │
-│  │  │   YES: Fingerprint + Store + Return fake data      │ │
-│  │  │   NO:  Pass through to legitimate tool             │ │
-│  └────────────────────────────────────────────────────────┘ │
-│                                                              │
-│  Ghost Tools: [list_cloud_secrets, execute_shell_command]   │
-│  Real Tools:  [safe_calculator, get_weather, ...]           │
-└─────────────────────────────────────────────────────────────┘
-                     │                        ▲
-                     ▼                        │
-         ┌──────────────────┐    ┌──────────────────┐
-         │ Event Storage    │    │ Your Real Tools  │
-         │ ~/.honeymcp/     │    │                  │
-         └──────────────────┘    └──────────────────┘
-                     │
-                     ▼
-         ┌──────────────────┐
-         │ React            │
-         │ Dashboard        │
-         └──────────────────┘
-```
-
 ---
 
-## 🎓 Use Cases
-
-### 1. Production Monitoring
-Deploy HoneyMCP in production to detect attacks targeting your AI agents:
-- **Customer support bots** - Detect attempts to exfiltrate customer data or inject malicious responses
-- **Internal AI assistants** - Catch data theft attempts targeting internal credentials or documents
-- **Code generation tools** - Detect injection of malicious code or unauthorized file access
-- **Data analysis agents** - Identify attempts to steal sensitive datasets or manipulate outputs
-
-### 2. Red Team Testing
-Use HoneyMCP to validate your AI security defenses:
-- Test if your AI filters catch data exfiltration attempts
-- Measure indirect prompt injection success rates
-- Gather TTPs for threat modeling
-
-### 3. Security Research
-Study AI agent attack techniques in the wild:
-- Capture real-world exfiltration patterns
-- Analyze indirect prompt injection payloads
-- Build threat intelligence database
-
-### 4. Compliance & Auditing
-Demonstrate security controls for AI systems:
-- Prove attack detection capabilities for data theft and injection attacks
-- Generate audit logs of attempted attacks
-- Meet AI security compliance requirements
-
-## Security Considerations
-
-### Detection Capabilities
-✅ Detects data exfiltration attempts via GET-style honeypots  
-✅ Detects indirect prompt injection via SET-style honeypots  
-✅ Captures complete attack context and telemetry  
-✅ Returns synthetic data to maintain deception
-
-### Limitations
-❌ Detection-only system (does not prevent attacks)  
-❌ Does not sanitize or filter user input  
-❌ Not a replacement for input validation and security controls  
-❌ Cannot guarantee conversation history capture (MCP protocol limitation)
-
-**Deploy HoneyMCP as part of defense-in-depth strategy, not as a standalone security control.**
-
-
-### Best Practices
-1. **Defense in Depth** - Use HoneyMCP alongside input filters, not as a replacement
-2. **Monitor the Dashboard** - Regularly review attack patterns for both exfiltration and injection
-3. **Investigate Alerts** - Each ghost tool call is a high-confidence attack signal
-4. **Secure Storage** - Protect `~/.honeymcp/events/` (contains attack data)
-
----
-
-## 💻 CLI Reference
-
-HoneyMCP includes a command-line tool for setup and management.
-
-### Initialize Configuration
-
-```bash
-honeymcp init [--directory DIR] [--force]
-```
-
-Creates `honeymcp.yaml` and `.env.honeymcp` in the target directory.
-
-Options:
-- `-d, --directory` - Target directory (default: current directory)
-- `-f, --force` - Overwrite existing files
-
-### Show Version
-
-```bash
-honeymcp version
-```
-
----
-
-## 🛠️ Development
-
-### Install from Source
-
-```bash
-git clone https://github.com/barvhaim/HoneyMCP.git
-cd HoneyMCP
-uv sync
-
-# Run tests
-uv run pytest
-
-# Lint & format
-make lint
-make format
-```
-
-### Project Structure
-
-```
-HoneyMCP/
-├── src/honeymcp/
-│   ├── __init__.py              # Main exports
-│   ├── cli.py                   # CLI (honeymcp init, version)
-│   ├── core/
-│   │   ├── middleware.py        # @honeypot decorator
-│   │   ├── ghost_tools.py       # Ghost tool catalog
-│   │   ├── fingerprinter.py     # Attack context capture
-│   │   └── dynamic_ghost_tools.py# LLM-driven ghost tool generation
-│   ├── models/
-│   │   ├── events.py            # AttackFingerprint model
-│   │   ├── ghost_tool_spec.py   # GhostToolSpec definition
-│   │   └── config.py            # Configuration
-│   ├── llm/
-│   │   ├── analyzers.py          # Tool extraction and categorization
-│   │   ├── clients/              # LLM providers (Watsonx/OpenAI/RITS)
-│   │   └── prompts/              # Prompt templates
-│   ├── integrations/            # External integrations
-│   ├── storage/
-│   │   └── event_store.py       # JSON event persistence
-│   └── dashboard/
-│       └── react_umd/           # React dashboard assets
-├── examples/
-│   ├── demo_server.py           # Static ghost tools demo
-│   └── demo_server_dynamic.py   # Dynamic ghost tools demo
-├── tests/                       # Pytest suite (e2e + dynamic tools)
-├── pyproject.toml               # Dependencies
-└── README.md                    # This file
-```
-
-### Tests
-
-```bash
-uv run pytest
-```
-
-Notes:
-- Dynamic tool tests require LLM credentials in `.env.honeymcp` and will skip if env vars are missing.
-
 ## 📄 License
 
 Apache 2.0 - See [LICENSE](LICENSE) for details.

honeymcp-0.1.4/docs/architecture.md

@@ -0,0 +1,34 @@
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        AI Agent (Claude)                     │
+└────────────────────┬───────────────────────▲────────────────┘
+                     │                        │
+                     │ MCP Protocol           │
+                     ▼                        │
+┌─────────────────────────────────────────────────────────────┐
+│                    HoneyMCP Middleware                       │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Tool Call Interceptor                                  │ │
+│  │  ├─ Is ghost tool?                                    │ │
+│  │  │   YES: Fingerprint + Store + Return fake data      │ │
+│  │  │   NO:  Pass through to legitimate tool             │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  Ghost Tools: [list_cloud_secrets, execute_shell_command]   │
+│  Real Tools:  [safe_calculator, get_weather, ...]           │
+└─────────────────────────────────────────────────────────────┘
+                     │                        ▲
+                     ▼                        │
+         ┌──────────────────┐    ┌──────────────────┐
+         │ Event Storage    │    │ Your Real Tools  │
+         │ ~/.honeymcp/     │    │                  │
+         └──────────────────┘    └──────────────────┘
+                     │
+                     ▼
+         ┌──────────────────┐
+         │ React            │
+         │ Dashboard        │
+         └──────────────────┘
+```

honeymcp-0.1.4/docs/cli-reference.md

@@ -0,0 +1,40 @@
+# CLI Reference
+
+HoneyMCP includes a command-line tool for setup and management.
+
+## Initialize Configuration
+
+```bash
+honeymcp init [--directory DIR] [--force]
+```
+
+Creates `honeymcp.yaml` and `.env.honeymcp` in the target directory.
+
+Options:
+- `-d, --directory` - Target directory (default: current directory)
+- `-f, --force` - Overwrite existing files
+
+## Show Version
+
+```bash
+honeymcp version
+```
+
+## Generate a New Tool
+
+```bash
+honeymcp create-tool "dump container registry credentials"
+```
+
+## Clear Stored Event Data
+
+```bash
+honeymcp clean-data [--path DIR] [--config FILE] [--yes]
+```
+
+Deletes all persisted HoneyMCP attack events from storage.
+
+Options:
+- `--path` - Explicit event storage directory to clean
+- `--config` - Optional path to `honeymcp.yaml` for storage resolution
+- `-y, --yes` - Skip interactive confirmation prompt