honeymcp 0.1.2__tar.gz → 0.1.4__tar.gz

{honeymcp-0.1.2 → honeymcp-0.1.4}/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.4}/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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: honeymcp
-Version: 0.1.2
+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
@@ -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,10 +128,13 @@ 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
 ```
 
+<img width="1426" height="972" alt="image" src="https://github.com/user-attachments/assets/2dfc37a2-8caa-4338-b7f7-1cbac7ed9d79" />
+
 ---
 
 ## 🎭 How It Works
@@ -168,18 +171,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.
+
 ---
 
 
@@ -261,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
@@ -456,21 +482,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 +492,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,183 +507,72 @@ 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 |
-All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
-
----
-
-
-
-## 🏗️ 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/     │    │                  │
-         └──────────────────┘    └──────────────────┘
-                     │
-                     ▼
-         ┌──────────────────┐
-         │ Streamlit        │
-         │ 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
+| `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 |
 
-### 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)
+All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
 
 ---
 
-## 💻 CLI Reference
+## 🤖 ToolGen Agent - Automated Tool Creation
 
-HoneyMCP includes a command-line tool for setup and management.
+HoneyMCP includes **ToolGen**, a ReAct-style agent that automatically creates new honeypot tools from natural language descriptions. No manual coding required.
 
-### Initialize Configuration
-
-```bash
-honeymcp init [--directory DIR] [--force]
-```
+### How It Works
 
-Creates `honeymcp.yaml` and `.env.honeymcp` in the target directory.
+ToolGen uses a **Reason-Act-Observe-Reflect** cycle:
 
-Options:
-- `-d, --directory` - Target directory (default: current directory)
-- `-f, --force` - Overwrite existing files
+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
 
-### Show Version
+### Usage
 
 ```bash
-honeymcp version
+honeymcp create-tool "dump container registry credentials"
 ```
 
----
-
-## 🛠️ Development
+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
 
-### Install from Source
+### Example
 
 ```bash
-git clone https://github.com/barvhaim/HoneyMCP.git
-cd HoneyMCP
-uv sync
+$ honeymcp create-tool "list terraform state files with secrets"
 
-# Run tests
-uv run pytest
-
-# Lint & format
-make lint
-make format
+✅ 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
 ```
 
-### 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/
-│       └── app.py               # Streamlit dashboard
-├── 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
-```
+The new tool is immediately available in your honeypot catalog.
 
-### Tests
+---
 
-```bash
-uv run pytest
-```
+## Documentation
 
-Notes:
-- Dynamic tool tests require LLM credentials in `.env.honeymcp` and will skip if env vars are missing.
+- [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)
+---
+---
 
 ## 📄 License