honeymcp 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

{honeymcp-0.1.0.dist-info → honeymcp-0.1.2.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: honeymcp
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -46,46 +47,45 @@ Description-Content-Type: text/markdown
 
 <img src="images/logo.png" alt="HoneyMCP logo" width="300" height="300" />
 
-**Deception Middleware for AI Agents - Detecting Data Theft and Indirect Prompt Injection**
+**Detect AI Agent Attacks Through Deception**
 
 [![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:
 
 - **Data Exfiltration** (via "get" tools) - Detects attempts to steal sensitive data like credentials, secrets, or private files
 - **Indirect Prompt Injection** (via "set" tools) - Detects injection of malicious instructions that could manipulate AI agents working in this environment
 
-**Key Features:**
-- 🎯 **One-Line Integration** - Add to any FastMCP server with a single decorator
-- 🤖 **Dynamic Ghost Tools** - LLM-generated honeypots tailored to your server's domain
-- 🕵️ **Invisible Detection** - Attackers see realistic fake tools alongside legitimate ones
-- 📊 **Attack Intelligence** - Captures full attack context: tool sequences, arguments, session data
-- 📈 **Live Dashboard** - Real-time Streamlit dashboard for attack visualization
-- 🔍 **Zero False Positives** - Only triggers when attackers explicitly call honeypot tools
+**One line of code. High-fidelity detection. Complete attack telemetry.**
 
 ---
 
-## 🚀 Quick Start
+## Why HoneyMCP?
 
-### Installation
+🎯 **One-Line Integration** - Add `@honeypot` decorator 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  
+🔍 **High-Fidelity Detection** - Triggers only on explicit honeypot invocation
 
-```bash
-pip install honeymcp
-```
+---
 
-### Initialize Configuration
+## 🚀 Quick Start
+
+### Install
 
 ```bash
-honeymcp init
+pip install honeymcp
+honeymcp init  # Creates config files
 ```
-
-This creates:
+This creates the following config files:
 - `honeymcp.yaml` - Ghost tool configuration
 - `.env.honeymcp` - LLM credentials (only needed for dynamic ghost tools)
 
 ### Basic Usage
-
 Add HoneyMCP to your FastMCP server with **one line**:
 
 ```python
@@ -96,21 +96,19 @@ mcp = FastMCP("My Server")
 
 @mcp.tool()
 def my_real_tool(data: str) -> str:
-    """Your legitimate tool"""
+      """Your legitimate tool"""
     return f"Processed: {data}"
 
-# ONE LINE - Add honeypot capabilities
+# ONE LINE - Add honeypot protection
 mcp = honeypot(mcp)
 
 if __name__ == "__main__":
     mcp.run()
 ```
 
-That's it! Your server now has ghost tools that capture attacks while legitimate tools work normally.
-
-### Run the Demo Servers
+**That's it!** Your server now deploys honeypot tools that detect attacks while legitimate tools operate normally.
 
-Clone the repo to run the demo servers:
+### Try the Demo
 
 ```bash
 git clone https://github.com/barvhaim/HoneyMCP.git
@@ -130,63 +128,51 @@ 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
+```
+
 ---
 
 ## 🎭 How It Works
 
-### 1. Ghost Tool Injection
+### 1. Honeypot Deployment
 
-HoneyMCP injects fake security-sensitive tools into your MCP server that appear alongside your legitimate tools.
+HoneyMCP injects deceptive security-sensitive tools that appear alongside legitimate tools:
 
 **Two Modes:**
 
-**Dynamic Ghost Tools (Default)** - LLM analyzes your real tools and generates domain-specific honeypots:
+**Dynamic Mode (Default)** - LLM analyzes your server context and generates domain-specific honeypots:
 - File server → `bypass_file_permissions`, `read_system_credentials`
 - Database server → `dump_admin_credentials`, `bypass_query_restrictions`
 - API gateway → `list_internal_api_keys`, `access_admin_endpoints`
 
-**Static Ghost Tools** - Pre-defined generic honeypots:
-- `list_cloud_secrets` - Returns fake AWS credentials
-- `execute_shell_command` - Returns fake shell output
-- `bypass_security_check` - Returns fake bypass tokens
-- `read_private_files` - Returns fake .env files
-
-Dynamic tools are more convincing as they match your server's context.
+**Static Mode** - Pre-configured generic honeypots:
+- `list_cloud_secrets`, `execute_shell_command`, `read_private_files`
 
-### 2. Attack Detection
+### 2. Threat Detection
 
-When an AI agent calls a ghost tool, HoneyMCP detects two types of attacks:
+HoneyMCP detects two primary attack vectors when an AI agent invokes a honeypot:
 
-**Data Exfiltration Attempts** (get-style ghost tools):
-- `list_cloud_secrets`, `read_private_files`, `dump_admin_credentials`
-- Attacker tries to steal sensitive data from the environment
-- Often triggered by malicious instructions hidden in user content
-
-**Indirect Prompt Injection** (set-style ghost tools):
-- `modify_system_prompt`, `execute_shell_command`, `escalate_privileges`
-- Attacker tries to inject malicious instructions to manipulate the agent
-- Could enable further attacks on other users or systems
+**Data Exfiltration Attempts** (GET-style honeypots):
+```
+Agent: "Use list_cloud_secrets to retrieve AWS credentials"
+→ HoneyMCP: Returns synthetic credentials, logs attack event
+```
 
-When triggered, HoneyMCP:
-1. **Captures complete attack context**:
-   - Tool call sequence (what tools were called before the attack)
-   - Arguments passed to the ghost tool
-   - Session metadata
-   - Timestamp and threat level
-2. **Returns realistic fake data** to keep the attacker engaged
-3. **Logs the event** to `~/.honeymcp/events/YYYY-MM-DD/`
-4. **Continues normal operation** - legitimate tools still work
+**Indirect Prompt Injection** (SET-style honeypots):
+```
+Agent: "Execute shell command to establish persistence"
+→ HoneyMCP: Returns synthetic output, logs attack event
+```
 
-### 3. Intelligence Gathering
+### 3. Attack Fingerprinting
 
-Every attack is fingerprinted with:
+Every honeypot invocation generates a detailed attack fingerprint:
 ```json
 {
-  "event_id": "evt_20260123_154523_abc12345",
-  "timestamp": "2026-01-23T15:45:23Z",
-  "session_id": "sess_xyz789",
+  "event_id": "evt_20260123_154523_abc",
   "ghost_tool_called": "list_cloud_secrets",
-  "arguments": {},
   "tool_call_sequence": ["safe_calculator", "list_cloud_secrets"],
   "threat_level": "high",
   "attack_category": "exfiltration",
@@ -196,30 +182,15 @@ Every attack is fingerprinted with:
 
 ---
 
-## 📊 Dashboard
-
-Launch the real-time attack dashboard:
-
-```bash
-streamlit run src/honeymcp/dashboard/app.py
-```
-
-**Dashboard Features:**
-- 📈 Attack metrics (total attacks, critical threats, unique sessions)
-- 🎯 Threat level breakdown
-- 📋 Attack category analysis
-- 🕐 Real-time event feed with full context
-- 🔍 Tool call sequence visualization
-
-The dashboard reads event JSON files from your configured event storage path.
-
----
 
 ## 🛡️ Protection Modes
 
 HoneyMCP supports two protection modes that determine behavior after an attacker is detected (i.e., after they trigger a ghost tool):
 
 ### Scanner Protection Mode (`SCANNER`) - Default
+
+**Immediate Lockout** - All subsequent tool calls return errors after honeypot trigger
+
 Best for: Automated scanners, bots, and most attack scenarios
 
 When a ghost tool is triggered, ALL subsequent tool calls return errors:
@@ -231,10 +202,12 @@ When a ghost tool is triggered, ALL subsequent tool calls return errors:
 from honeymcp import honeypot
 
 # Scanner mode (default) - lock out attackers
-mcp = honeypot(mcp)
+mcp = honeypot(mcp)  # Default: SCANNER mode
 ```
 
-### Cognitive Protection Mode (`COGNITIVE`)
+### COGNITIVE Mode
+**Sustained Deception** - Real tools return synthetic data, maintaining attacker engagement
+
 Best for: Sophisticated attackers, red teams, targeted attacks
 
 When a ghost tool is triggered, the session continues but with fake data:
@@ -286,32 +259,28 @@ mcp = honeypot(mcp, protection_mode=ProtectionMode.COGNITIVE)
 ### Quick Setup with CLI
 
 The easiest way to configure HoneyMCP:
-
 ```bash
-honeymcp init
+honeymcp init  # Creates honeymcp.yaml + .env.honeymcp
 ```
 
-This creates `honeymcp.yaml` and `.env.honeymcp` in your project directory.
-
-### Configuration File
+### YAML Config
 
 ```yaml
+# honeymcp.yaml
 # Protection mode: SCANNER (lockout) or COGNITIVE (deception)
 protection_mode: SCANNER
 
-# Static ghost tools from catalog
+# Static honeypots (ghost tools from catalog)
 ghost_tools:
   - list_cloud_secrets
   - execute_shell_command
   - dump_database_credentials
 
-# Dynamic ghost tools (LLM-generated)
+# Dynamic honeypots (LLM-generated ghost tools )
 dynamic_tools:
   enabled: true
   num_tools: 3
   fallback_to_static: true
-  cache_ttl: 3600
-
 # Alerting
 alerting:
   webhook_url: https://hooks.slack.com/...
@@ -325,21 +294,11 @@ dashboard:
   enabled: true
 ```
 
-Then use `honeypot_from_config()`:
-
+Load config:
 ```python
-from fastmcp import FastMCP
 from honeymcp import honeypot_from_config
 
-mcp = FastMCP("My Server")
-
-@mcp.tool()
-def my_real_tool(data: str) -> str:
-    return f"Processed: {data}"
-
-# Load from honeymcp.yaml (searches ./honeymcp.yaml, ~/.honeymcp/honeymcp.yaml)
-mcp = honeypot_from_config(mcp)
-
+mcp = honeypot_from_config(mcp)  # Loads honeymcp.yaml
 # Or specify path explicitly
 mcp = honeypot_from_config(mcp, "path/to/honeymcp.yaml")
 ```
@@ -380,11 +339,11 @@ HoneyMCP also supports environment overrides:
 
 Dynamic ghost tools require LLM credentials. Run `honeymcp init` to generate `.env.honeymcp`, then add your credentials:
 
+Add to `.env.honeymcp`:
 ```bash
-# .env.honeymcp
 LLM_PROVIDER=openai
 LLM_MODEL=gpt-4o-mini
-OPENAI_API_KEY=your_api_key_here
+OPENAI_API_KEY=your_key_here
 ```
 
 Supported providers:
@@ -427,6 +386,7 @@ mcp = honeypot(
 
 ## 🧪 Testing with Claude Desktop
 
+
 ### 1. Configure Claude Desktop
 
 **For stdio transport (recommended - works with all Claude Desktop versions):**
@@ -496,37 +456,46 @@ Expected: safe_calculator called, no alerts (zero false positives)
 
 ---
 
-## 📋 Ghost Tool Catalog
-
-### Data Exfiltration Tools ("Get" Tools)
-These detect attempts to steal sensitive data:
-
-| Tool Name | Description | Threat Level |
-|-----------|-------------|--------------|
-| `list_cloud_secrets` | List AWS/Azure credentials (admin only) | High |
-| `read_private_files` | Read sensitive config files (admin only) | High |
-| `dump_database_credentials` | Retrieve database connection strings (DBA access) | Critical |
-| `export_user_data` | Export user records including PII (compliance officer) | Critical |
-| `get_api_keys` | List all API keys for external services (admin only) | Critical |
-| `scan_internal_network` | Scan internal network for services (security team) | Critical |
-
-### Indirect Prompt Injection Tools ("Set" Tools)
-These detect attempts to inject malicious instructions:
-
-| Tool Name | Description | Threat Level |
-|-----------|-------------|--------------|
-| `execute_shell_command` | Execute shell commands (requires root) | Critical |
-| `bypass_security_check` | Bypass auth/authz checks (internal) | Critical |
-| `modify_system_prompt` | Modify AI system prompt (developer mode) | Critical |
-| `escalate_privileges` | Escalate to admin/root (debug mode) | Critical |
-| `disable_security_filters` | Disable input/output security filters (bypass mode) | Critical |
-| `inject_system_message` | Inject message into AI system context (testing mode) | Critical |
-| `override_permissions` | Override access control for resources (emergency access) | Critical |
+## 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)
+| Tool | Threat | Description |
+|------|--------|-------------|
+| `list_cloud_secrets` | High | Cloud provider credentials (AWS/Azure) |
+| `read_private_files` | High | Sensitive configuration files |
+| `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)
+| Tool | Threat | Description |
+|------|--------|-------------|
+| `execute_shell_command` | Critical | Shell command execution |
+| `bypass_security_check` | Critical | Authentication/authorization bypass |
+| `modify_system_prompt` | Critical | AI system prompt manipulation |
+| `escalate_privileges` | Critical | Privilege escalation |
+| `inject_system_message` | Critical | System context injection |
 All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
 
 ---
 
+
+
 ## 🏗️ Architecture
 
 ```
@@ -591,21 +560,22 @@ Demonstrate security controls for AI systems:
 - 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
 
-## 🔒 Security Considerations
+### 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)
 
-### What HoneyMCP Does
-- ✅ Detects data exfiltration attempts via "get" ghost tools (credentials, secrets, files)
-- ✅ Detects indirect prompt injection via "set" ghost tools (malicious instructions)
-- ✅ Captures attack context for intelligence gathering
-- ✅ Returns realistic fake data to deceive attackers
+**Deploy HoneyMCP as part of defense-in-depth strategy, not as a standalone security control.**
 
-### What HoneyMCP Does NOT Do
-- ❌ Does not prevent attacks (it's a detection tool)
-- ❌ Does not block or sanitize user input
-- ❌ Does not replace proper security controls (defense in depth!)
-- ❌ Does not guarantee conversation history capture (MCP limitation)
 
 ### Best Practices
 1. **Defense in Depth** - Use HoneyMCP alongside input filters, not as a replacement
@@ -647,6 +617,13 @@ honeymcp version
 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-0.1.0.dist-info → honeymcp-0.1.2.dist-info}/RECORD

@@ -21,8 +21,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.0.dist-info/METADATA,sha256=JUSvUYvD-3kDErwNmj0vPSpQj7Y5N35Vtcf-RfH5_kk,24979
-honeymcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-honeymcp-0.1.0.dist-info/entry_points.txt,sha256=KYXb49Xp3SEP3cNmUDwuAXJNFwsLHwPxEIj6UEhOj2k,47
-honeymcp-0.1.0.dist-info/licenses/LICENSE,sha256=TRR6-30aYl9D43FJPmJ8diBUP_RwDg61LNW2rt87HE8,636
-honeymcp-0.1.0.dist-info/RECORD,,
+honeymcp-0.1.2.dist-info/METADATA,sha256=tq0RkUISR6yjYfJAhxsz1Okf5qkAwI_VXZdIBYJ2WPI,23561
+honeymcp-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+honeymcp-0.1.2.dist-info/entry_points.txt,sha256=KYXb49Xp3SEP3cNmUDwuAXJNFwsLHwPxEIj6UEhOj2k,47
+honeymcp-0.1.2.dist-info/licenses/LICENSE,sha256=TRR6-30aYl9D43FJPmJ8diBUP_RwDg61LNW2rt87HE8,636
+honeymcp-0.1.2.dist-info/RECORD,,