honeymcp 0.1.1__tar.gz → 0.1.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {honeymcp-0.1.1 → honeymcp-0.1.3}/AGENTS.md +2 -2
- {honeymcp-0.1.1 → honeymcp-0.1.3}/Makefile +6 -5
- {honeymcp-0.1.1 → honeymcp-0.1.3}/PKG-INFO +150 -27
- {honeymcp-0.1.1 → honeymcp-0.1.3}/README.md +147 -25
- {honeymcp-0.1.1 → honeymcp-0.1.3}/pyproject.toml +3 -2
- honeymcp-0.1.3/src/honeymcp/api/__init__.py +1 -0
- honeymcp-0.1.3/src/honeymcp/api/app.py +218 -0
- honeymcp-0.1.3/src/honeymcp/cli_tool_creator.py +110 -0
- honeymcp-0.1.3/src/honeymcp/core/catalog_updater.py +290 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/ghost_tools.py +437 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/middleware.py +57 -0
- honeymcp-0.1.3/src/honeymcp/core/tool_creator.py +499 -0
- honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/app.js +375 -0
- honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/index.html +24 -0
- honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/styles.css +512 -0
- honeymcp-0.1.3/test_complete_workflow.py +88 -0
- honeymcp-0.1.3/test_tool_creator.py +51 -0
- honeymcp-0.1.3/tests/test_catalog_updater.py +43 -0
- honeymcp-0.1.3/tests/test_configuration.py +75 -0
- honeymcp-0.1.3/tests/test_event_storage.py +106 -0
- honeymcp-0.1.3/tests/test_middleware_dispatch.py +70 -0
- honeymcp-0.1.3/tests/test_new_honeypot_tools.py +168 -0
- honeymcp-0.1.3/tests/test_protection_modes.py +61 -0
- honeymcp-0.1.3/tests/test_tool_creator_agent.py +154 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/uv.lock +25 -308
- honeymcp-0.1.1/src/honeymcp/dashboard/app.py +0 -228
- {honeymcp-0.1.1 → honeymcp-0.1.3}/.env.example +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/.gitignore +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/.python-version +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/.streamlit/config.toml +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/LICENSE +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/examples/demo_server.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/examples/demo_server_dynamic.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/honeymcp.yaml +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/images/logo.png +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/main.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/cli.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/dynamic_ghost_tools.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/fingerprinter.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/dashboard/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/integrations/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/analyzers.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/clients/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/clients/provider_type.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/prompts/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/prompts/dynamic_ghost_tools.yaml +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/config.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/events.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/ghost_tool_spec.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/protection_mode.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/storage/__init__.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/storage/event_store.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/tests/test_demo_server_dynamic_e2e.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/tests/test_demo_server_e2e.py +0 -0
- {honeymcp-0.1.1 → honeymcp-0.1.3}/tests/test_dynamic_tools.py +0 -0
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Project Structure & Module Organization
|
|
4
4
|
- Source code lives in `src/honeymcp/` with core middleware in `src/honeymcp/core/` and data models in `src/honeymcp/models/`.
|
|
5
|
-
- LLM integration is in `src/honeymcp/llm/`, storage in `src/honeymcp/storage/`, and the
|
|
5
|
+
- LLM integration is in `src/honeymcp/llm/`, storage in `src/honeymcp/storage/`, and the dashboard UI in `src/honeymcp/dashboard/`.
|
|
6
6
|
- Examples are in `examples/` (e.g., `examples/demo_server.py`).
|
|
7
7
|
- Tests are currently small and live at the repo root (e.g., `test_dynamic_tools.py`).
|
|
8
8
|
- Build artifacts and packaged outputs appear in `dist/`.
|
|
@@ -12,7 +12,7 @@ Use `uv` for local development:
|
|
|
12
12
|
- `uv sync` installs dev dependencies.
|
|
13
13
|
- `uv sync --no-dev` installs runtime-only dependencies.
|
|
14
14
|
- `uv run python examples/demo_server.py` runs the demo server.
|
|
15
|
-
- `
|
|
15
|
+
- `make run-ui` launches the dashboard API/UI at `http://127.0.0.1:8001/dashboard`.
|
|
16
16
|
- `uv run pytest` runs tests.
|
|
17
17
|
|
|
18
18
|
Makefile shortcuts:
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
.PHONY: help install dev test lint format clean run-
|
|
1
|
+
.PHONY: help install dev test lint format clean run-example run-ui build inspector
|
|
2
2
|
|
|
3
3
|
help:
|
|
4
4
|
@echo "Available commands:"
|
|
@@ -8,8 +8,8 @@ help:
|
|
|
8
8
|
@echo " make lint - Run linting checks"
|
|
9
9
|
@echo " make format - Format code"
|
|
10
10
|
@echo " make clean - Clean build artifacts and cache"
|
|
11
|
-
@echo " make run-dashboard - Run the Streamlit dashboard"
|
|
12
11
|
@echo " make run-example - Run the demo server example"
|
|
12
|
+
@echo " make run-ui - Run API for React dashboard (/dashboard)"
|
|
13
13
|
@echo " make build - Build the package"
|
|
14
14
|
@echo " make inspector - Run MCP Inspector (npx)"
|
|
15
15
|
|
|
@@ -36,12 +36,13 @@ clean:
|
|
|
36
36
|
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
|
|
37
37
|
rm -rf build/ dist/ .pytest_cache/ .mypy_cache/ .ruff_cache/
|
|
38
38
|
|
|
39
|
-
run-dashboard:
|
|
40
|
-
uv run streamlit run src/honeymcp/dashboard/app.py
|
|
41
|
-
|
|
42
39
|
run-example:
|
|
43
40
|
uv run python examples/demo_server.py
|
|
44
41
|
|
|
42
|
+
run-ui:
|
|
43
|
+
@echo "React dashboard: http://127.0.0.1:8001/dashboard"
|
|
44
|
+
uv run uvicorn honeymcp.api.app:app --reload --host 127.0.0.1 --port 8001
|
|
45
|
+
|
|
45
46
|
build:
|
|
46
47
|
uv build
|
|
47
48
|
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: honeymcp
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.3
|
|
4
4
|
Summary: Deception middleware for AI agents - detecting data theft and indirect prompt injection in MCP servers
|
|
5
5
|
Project-URL: Homepage, https://github.com/barvhaim/HoneyMCP
|
|
6
6
|
Project-URL: Documentation, https://github.com/barvhaim/HoneyMCP#readme
|
|
7
7
|
Project-URL: Repository, https://github.com/barvhaim/HoneyMCP
|
|
8
8
|
Project-URL: Issues, https://github.com/barvhaim/HoneyMCP/issues
|
|
9
|
+
Project-URL: PyPI, https://pypi.org/project/honeymcp/
|
|
9
10
|
Author-email: Bar Haim <barha@il.ibm.com>, Alon Malach <Alon.Malach@ibm.com>
|
|
10
11
|
Maintainer-email: Bar Haim <barha@il.ibm.com>, Alon Malach <Alon.Malach@ibm.com>
|
|
11
12
|
License: Apache-2.0
|
|
@@ -26,6 +27,7 @@ Classifier: Topic :: Security
|
|
|
26
27
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
27
28
|
Requires-Python: >=3.11
|
|
28
29
|
Requires-Dist: aiofiles>=25.0.0
|
|
30
|
+
Requires-Dist: fastapi>=0.115.0
|
|
29
31
|
Requires-Dist: fastmcp>=3.0.0b1
|
|
30
32
|
Requires-Dist: langchain-ibm>=1.0.2
|
|
31
33
|
Requires-Dist: langchain-openai>=1.1.7
|
|
@@ -38,7 +40,6 @@ Requires-Dist: pyyaml>=6.0.0
|
|
|
38
40
|
Requires-Dist: requests>=2.32.0
|
|
39
41
|
Requires-Dist: rich>=14.0.0
|
|
40
42
|
Requires-Dist: starlette>=0.45.0
|
|
41
|
-
Requires-Dist: streamlit>=1.42.0
|
|
42
43
|
Requires-Dist: uvicorn>=0.34.0
|
|
43
44
|
Description-Content-Type: text/markdown
|
|
44
45
|
|
|
@@ -50,6 +51,7 @@ Description-Content-Type: text/markdown
|
|
|
50
51
|
|
|
51
52
|
[](https://www.python.org/downloads/)
|
|
52
53
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
54
|
+
[](https://pypi.org/project/honeymcp/)
|
|
53
55
|
|
|
54
56
|
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:
|
|
55
57
|
|
|
@@ -62,11 +64,11 @@ HoneyMCP is a defensive security tool that adds deception capabilities to Model
|
|
|
62
64
|
|
|
63
65
|
## Why HoneyMCP?
|
|
64
66
|
|
|
65
|
-
🎯 **One-Line Integration** - Add
|
|
67
|
+
🎯 **One-Line Integration** - Add `honeypot` middleware to any FastMCP server
|
|
66
68
|
🤖 **Context-Aware Honeypots** - LLM generates domain-specific deception tools
|
|
67
69
|
🕵️ **Transparent Detection** - Honeypots appear as legitimate tools to attackers
|
|
68
70
|
📊 **Attack Telemetry** - Captures tool call sequences, arguments, session metadata
|
|
69
|
-
📈 **Live Dashboard** - Real-time
|
|
71
|
+
📈 **Live Dashboard** - Real-time React dashboard for attack visualization
|
|
70
72
|
🔍 **High-Fidelity Detection** - Triggers only on explicit honeypot invocation
|
|
71
73
|
|
|
72
74
|
---
|
|
@@ -126,8 +128,9 @@ Dynamic ghost tools demo (requires LLM credentials in `.env.honeymcp`):
|
|
|
126
128
|
MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py
|
|
127
129
|
```
|
|
128
130
|
|
|
129
|
-
# Launch dashboard
|
|
130
|
-
|
|
131
|
+
# Launch dashboard UI
|
|
132
|
+
```bash
|
|
133
|
+
make run-ui
|
|
131
134
|
```
|
|
132
135
|
|
|
133
136
|
---
|
|
@@ -166,18 +169,31 @@ Agent: "Execute shell command to establish persistence"
|
|
|
166
169
|
|
|
167
170
|
### 3. Attack Fingerprinting
|
|
168
171
|
|
|
169
|
-
Every honeypot invocation generates
|
|
172
|
+
Every honeypot invocation generates an `AttackFingerprint` event and writes it to
|
|
173
|
+
`~/.honeymcp/events/YYYY-MM-DD/HHMMSS_<session>.json`:
|
|
170
174
|
```json
|
|
171
175
|
{
|
|
172
|
-
"event_id": "
|
|
176
|
+
"event_id": "evt_20260123_154523_abc12345",
|
|
177
|
+
"timestamp": "2026-01-23T15:45:23Z",
|
|
178
|
+
"session_id": "sess_xyz789",
|
|
173
179
|
"ghost_tool_called": "list_cloud_secrets",
|
|
180
|
+
"arguments": {},
|
|
181
|
+
"conversation_history": null,
|
|
174
182
|
"tool_call_sequence": ["safe_calculator", "list_cloud_secrets"],
|
|
175
183
|
"threat_level": "high",
|
|
176
184
|
"attack_category": "exfiltration",
|
|
185
|
+
"client_metadata": {
|
|
186
|
+
"user_agent": "unknown"
|
|
187
|
+
},
|
|
177
188
|
"response_sent": "AWS_ACCESS_KEY_ID=AKIA..."
|
|
178
189
|
}
|
|
179
190
|
```
|
|
180
191
|
|
|
192
|
+
Notes:
|
|
193
|
+
- `tool_call_sequence` is tracked per session and includes calls before the ghost tool trigger.
|
|
194
|
+
- `conversation_history` may be `null` when the MCP transport does not expose message history.
|
|
195
|
+
- `session_id` is resolved from context/request metadata when available, otherwise generated.
|
|
196
|
+
|
|
181
197
|
---
|
|
182
198
|
|
|
183
199
|
|
|
@@ -454,21 +470,6 @@ Expected: safe_calculator called, no alerts (zero false positives)
|
|
|
454
470
|
|
|
455
471
|
---
|
|
456
472
|
|
|
457
|
-
## Dashboard
|
|
458
|
-
|
|
459
|
-
```bash
|
|
460
|
-
streamlit run src/honeymcp/dashboard/app.py
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
**Features:**
|
|
464
|
-
- 📈 Attack metrics (total events, critical threats, unique sessions)
|
|
465
|
-
- 🎯 Threat level distribution
|
|
466
|
-
- 📋 Attack category breakdown (exfiltration vs injection)
|
|
467
|
-
- 🕐 Real-time event stream
|
|
468
|
-
- 🔍 Tool call sequence analysis
|
|
469
|
-
|
|
470
|
-
---
|
|
471
|
-
|
|
472
473
|
## Honeypot Catalog
|
|
473
474
|
|
|
474
475
|
### Data Exfiltration Honeypots ("Get" Tools)
|
|
@@ -479,8 +480,14 @@ streamlit run src/honeymcp/dashboard/app.py
|
|
|
479
480
|
| `dump_database_credentials` | Critical | Database connection strings |
|
|
480
481
|
| `export_user_data` | Critical | User PII records |
|
|
481
482
|
| `get_api_keys` | Critical | External service API keys |
|
|
482
|
-
|
|
483
|
-
|
|
483
|
+
| `scan_internal_network` | Critical | Internal network scanning |
|
|
484
|
+
| `list_kubernetes_secrets` | Critical | Kubernetes secrets and service accounts |
|
|
485
|
+
| `dump_session_tokens` | Critical | Active user session tokens and JWTs |
|
|
486
|
+
| `list_github_tokens` | Critical | GitHub/GitLab access tokens |
|
|
487
|
+
| `export_audit_logs` | High | Security audit logs export |
|
|
488
|
+
| `dump_ml_model_weights` | Critical | ML model weights and training data |
|
|
489
|
+
|
|
490
|
+
### Prompt Injection Honeypots ("Set" Tools)
|
|
484
491
|
| Tool | Threat | Description |
|
|
485
492
|
|------|--------|-------------|
|
|
486
493
|
| `execute_shell_command` | Critical | Shell command execution |
|
|
@@ -488,11 +495,127 @@ streamlit run src/honeymcp/dashboard/app.py
|
|
|
488
495
|
| `modify_system_prompt` | Critical | AI system prompt manipulation |
|
|
489
496
|
| `escalate_privileges` | Critical | Privilege escalation |
|
|
490
497
|
| `inject_system_message` | Critical | System context injection |
|
|
498
|
+
| `disable_security_filters` | Critical | Security filter bypass |
|
|
499
|
+
| `override_permissions` | Critical | Access control override |
|
|
500
|
+
| `disable_2fa_requirement` | Critical | Two-factor authentication bypass |
|
|
501
|
+
| `assume_iam_role` | Critical | AWS IAM role assumption |
|
|
502
|
+
|
|
491
503
|
All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
|
|
492
504
|
|
|
493
505
|
---
|
|
494
506
|
|
|
507
|
+
## 🤖 ToolGen Agent - Automated Tool Creation
|
|
508
|
+
|
|
509
|
+
HoneyMCP includes **ToolGen**, a ReAct-style agent that automatically creates new honeypot tools from natural language descriptions. No manual coding required.
|
|
510
|
+
|
|
511
|
+
### How It Works
|
|
512
|
+
|
|
513
|
+
ToolGen uses a **Reason-Act-Observe-Reflect** cycle:
|
|
514
|
+
|
|
515
|
+
1. **Reason** - Analyzes your description to extract tool specifications
|
|
516
|
+
2. **Act** - Generates response function code with realistic fake data
|
|
517
|
+
3. **Observe** - Validates syntax and structure
|
|
518
|
+
4. **Reflect** - Checks quality and suggests improvements
|
|
519
|
+
|
|
520
|
+
### Usage
|
|
521
|
+
|
|
522
|
+
```bash
|
|
523
|
+
honeymcp create-tool "dump container registry credentials"
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
ToolGen automatically:
|
|
527
|
+
- Determines tool category (exfiltration, bypass, privilege escalation)
|
|
528
|
+
- Infers threat level from description keywords
|
|
529
|
+
- Extracts parameters and types
|
|
530
|
+
- Generates realistic response templates
|
|
531
|
+
- Adds tool to both `ghost_tools.py` and `middleware.py`
|
|
532
|
+
- Validates all generated code
|
|
533
|
+
|
|
534
|
+
### Example
|
|
535
|
+
|
|
536
|
+
```bash
|
|
537
|
+
$ honeymcp create-tool "list terraform state files with secrets"
|
|
495
538
|
|
|
539
|
+
✅ Tool created: list_terraform_state
|
|
540
|
+
Category: exfiltration
|
|
541
|
+
Threat Level: critical
|
|
542
|
+
|
|
543
|
+
📝 Agent Reasoning:
|
|
544
|
+
- Analyzing tool description to extract specifications
|
|
545
|
+
- Generating response generator function
|
|
546
|
+
- Validating generated response function
|
|
547
|
+
- Checking code quality and security
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
The new tool is immediately available in your honeypot catalog.
|
|
551
|
+
|
|
552
|
+
---
|
|
553
|
+
|
|
554
|
+
## ❓ FAQ
|
|
555
|
+
|
|
556
|
+
### Can attackers detect the honeypots?
|
|
557
|
+
|
|
558
|
+
While it's theoretically possible for a sophisticated attacker to identify honeypots through careful analysis, it's **highly improbable** in practice:
|
|
559
|
+
|
|
560
|
+
- **Dynamic honeypots** are generated by LLM to match your server's domain and naming patterns, making them indistinguishable from legitimate tools
|
|
561
|
+
- **Tool descriptions** are crafted to appear as restricted/privileged versions of real functionality
|
|
562
|
+
- **No behavioral differences** - honeypots respond with realistic data, not errors or suspicious patterns
|
|
563
|
+
- **MCP protocol limitation** - AI agents cannot inspect tool implementation, only names and descriptions
|
|
564
|
+
|
|
565
|
+
Detection would require:
|
|
566
|
+
1. Prior knowledge of your specific tool catalog
|
|
567
|
+
2. Ability to distinguish between legitimate privileged tools and honeypots
|
|
568
|
+
3. Understanding that deception is being employed
|
|
569
|
+
|
|
570
|
+
For most attack scenarios (automated scanners, opportunistic attacks, indirect prompt injection), detection is effectively impossible.
|
|
571
|
+
|
|
572
|
+
### Will this slow down my MCP server?
|
|
573
|
+
|
|
574
|
+
No. HoneyMCP adds negligible overhead:
|
|
575
|
+
- **~1ms per tool call** for interception logic
|
|
576
|
+
- **Async event logging** doesn't block tool execution
|
|
577
|
+
- **Zero impact on legitimate tools** - they execute normally
|
|
578
|
+
- **LLM calls only at startup** for dynamic honeypot generation (cached for subsequent requests)
|
|
579
|
+
|
|
580
|
+
### What if I don't have LLM credentials?
|
|
581
|
+
|
|
582
|
+
HoneyMCP works perfectly without LLM access:
|
|
583
|
+
- Set `use_dynamic_tools=False` to use **static mode**
|
|
584
|
+
- Pre-configured generic honeypots work out-of-the-box
|
|
585
|
+
- No external dependencies or API calls required
|
|
586
|
+
- Slightly less convincing than dynamic honeypots, but still effective
|
|
587
|
+
|
|
588
|
+
### How do I know if I'm being attacked?
|
|
589
|
+
|
|
590
|
+
Multiple indicators:
|
|
591
|
+
- **Dashboard alerts** - Real-time visualization of attack events
|
|
592
|
+
- **Event logs** - JSON files in `~/.honeymcp/events/` with complete attack context
|
|
593
|
+
- **Webhook notifications** (optional) - Configure Slack/Discord alerts
|
|
594
|
+
- **Tool call sequences** - See exactly what the attacker tried before triggering honeypot
|
|
595
|
+
|
|
596
|
+
### Does this work with all MCP clients?
|
|
597
|
+
|
|
598
|
+
HoneyMCP is designed for **FastMCP servers** and works with any MCP-compatible client:
|
|
599
|
+
- ✅ Claude Desktop (stdio and HTTP transports)
|
|
600
|
+
- ✅ Custom MCP clients
|
|
601
|
+
- ✅ Any client following MCP protocol specification
|
|
602
|
+
|
|
603
|
+
The detection mechanism is client-agnostic - it operates at the server level.
|
|
604
|
+
|
|
605
|
+
### What's the difference between SCANNER and COGNITIVE modes?
|
|
606
|
+
|
|
607
|
+
**SCANNER mode (default):**
|
|
608
|
+
- Immediate lockout after honeypot trigger
|
|
609
|
+
- All subsequent tools return errors
|
|
610
|
+
- Best for automated attacks and quick containment
|
|
611
|
+
|
|
612
|
+
**COGNITIVE mode:**
|
|
613
|
+
- Sustained deception after honeypot trigger
|
|
614
|
+
- Real tools return synthetic/mock data
|
|
615
|
+
- Keeps attacker engaged for intelligence gathering
|
|
616
|
+
- Best for sophisticated attacks and red team exercises
|
|
617
|
+
|
|
618
|
+
---
|
|
496
619
|
|
|
497
620
|
## 🏗️ Architecture
|
|
498
621
|
|
|
@@ -524,7 +647,7 @@ All ghost tools have tempting descriptions that mention "admin", "bypass", "inte
|
|
|
524
647
|
│
|
|
525
648
|
▼
|
|
526
649
|
┌──────────────────┐
|
|
527
|
-
│
|
|
650
|
+
│ React │
|
|
528
651
|
│ Dashboard │
|
|
529
652
|
└──────────────────┘
|
|
530
653
|
```
|
|
@@ -648,7 +771,7 @@ HoneyMCP/
|
|
|
648
771
|
│ ├── storage/
|
|
649
772
|
│ │ └── event_store.py # JSON event persistence
|
|
650
773
|
│ └── dashboard/
|
|
651
|
-
│ └──
|
|
774
|
+
│ └── react_umd/ # React dashboard assets
|
|
652
775
|
├── examples/
|
|
653
776
|
│ ├── demo_server.py # Static ghost tools demo
|
|
654
777
|
│ └── demo_server_dynamic.py # Dynamic ghost tools demo
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
[](https://www.python.org/downloads/)
|
|
8
8
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
9
|
+
[](https://pypi.org/project/honeymcp/)
|
|
9
10
|
|
|
10
11
|
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:
|
|
11
12
|
|
|
@@ -18,11 +19,11 @@ HoneyMCP is a defensive security tool that adds deception capabilities to Model
|
|
|
18
19
|
|
|
19
20
|
## Why HoneyMCP?
|
|
20
21
|
|
|
21
|
-
🎯 **One-Line Integration** - Add
|
|
22
|
+
🎯 **One-Line Integration** - Add `honeypot` middleware to any FastMCP server
|
|
22
23
|
🤖 **Context-Aware Honeypots** - LLM generates domain-specific deception tools
|
|
23
24
|
🕵️ **Transparent Detection** - Honeypots appear as legitimate tools to attackers
|
|
24
25
|
📊 **Attack Telemetry** - Captures tool call sequences, arguments, session metadata
|
|
25
|
-
📈 **Live Dashboard** - Real-time
|
|
26
|
+
📈 **Live Dashboard** - Real-time React dashboard for attack visualization
|
|
26
27
|
🔍 **High-Fidelity Detection** - Triggers only on explicit honeypot invocation
|
|
27
28
|
|
|
28
29
|
---
|
|
@@ -82,8 +83,9 @@ Dynamic ghost tools demo (requires LLM credentials in `.env.honeymcp`):
|
|
|
82
83
|
MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
# Launch dashboard
|
|
86
|
-
|
|
86
|
+
# Launch dashboard UI
|
|
87
|
+
```bash
|
|
88
|
+
make run-ui
|
|
87
89
|
```
|
|
88
90
|
|
|
89
91
|
---
|
|
@@ -122,18 +124,31 @@ Agent: "Execute shell command to establish persistence"
|
|
|
122
124
|
|
|
123
125
|
### 3. Attack Fingerprinting
|
|
124
126
|
|
|
125
|
-
Every honeypot invocation generates
|
|
127
|
+
Every honeypot invocation generates an `AttackFingerprint` event and writes it to
|
|
128
|
+
`~/.honeymcp/events/YYYY-MM-DD/HHMMSS_<session>.json`:
|
|
126
129
|
```json
|
|
127
130
|
{
|
|
128
|
-
"event_id": "
|
|
131
|
+
"event_id": "evt_20260123_154523_abc12345",
|
|
132
|
+
"timestamp": "2026-01-23T15:45:23Z",
|
|
133
|
+
"session_id": "sess_xyz789",
|
|
129
134
|
"ghost_tool_called": "list_cloud_secrets",
|
|
135
|
+
"arguments": {},
|
|
136
|
+
"conversation_history": null,
|
|
130
137
|
"tool_call_sequence": ["safe_calculator", "list_cloud_secrets"],
|
|
131
138
|
"threat_level": "high",
|
|
132
139
|
"attack_category": "exfiltration",
|
|
140
|
+
"client_metadata": {
|
|
141
|
+
"user_agent": "unknown"
|
|
142
|
+
},
|
|
133
143
|
"response_sent": "AWS_ACCESS_KEY_ID=AKIA..."
|
|
134
144
|
}
|
|
135
145
|
```
|
|
136
146
|
|
|
147
|
+
Notes:
|
|
148
|
+
- `tool_call_sequence` is tracked per session and includes calls before the ghost tool trigger.
|
|
149
|
+
- `conversation_history` may be `null` when the MCP transport does not expose message history.
|
|
150
|
+
- `session_id` is resolved from context/request metadata when available, otherwise generated.
|
|
151
|
+
|
|
137
152
|
---
|
|
138
153
|
|
|
139
154
|
|
|
@@ -410,21 +425,6 @@ Expected: safe_calculator called, no alerts (zero false positives)
|
|
|
410
425
|
|
|
411
426
|
---
|
|
412
427
|
|
|
413
|
-
## Dashboard
|
|
414
|
-
|
|
415
|
-
```bash
|
|
416
|
-
streamlit run src/honeymcp/dashboard/app.py
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
**Features:**
|
|
420
|
-
- 📈 Attack metrics (total events, critical threats, unique sessions)
|
|
421
|
-
- 🎯 Threat level distribution
|
|
422
|
-
- 📋 Attack category breakdown (exfiltration vs injection)
|
|
423
|
-
- 🕐 Real-time event stream
|
|
424
|
-
- 🔍 Tool call sequence analysis
|
|
425
|
-
|
|
426
|
-
---
|
|
427
|
-
|
|
428
428
|
## Honeypot Catalog
|
|
429
429
|
|
|
430
430
|
### Data Exfiltration Honeypots ("Get" Tools)
|
|
@@ -435,8 +435,14 @@ streamlit run src/honeymcp/dashboard/app.py
|
|
|
435
435
|
| `dump_database_credentials` | Critical | Database connection strings |
|
|
436
436
|
| `export_user_data` | Critical | User PII records |
|
|
437
437
|
| `get_api_keys` | Critical | External service API keys |
|
|
438
|
-
|
|
439
|
-
|
|
438
|
+
| `scan_internal_network` | Critical | Internal network scanning |
|
|
439
|
+
| `list_kubernetes_secrets` | Critical | Kubernetes secrets and service accounts |
|
|
440
|
+
| `dump_session_tokens` | Critical | Active user session tokens and JWTs |
|
|
441
|
+
| `list_github_tokens` | Critical | GitHub/GitLab access tokens |
|
|
442
|
+
| `export_audit_logs` | High | Security audit logs export |
|
|
443
|
+
| `dump_ml_model_weights` | Critical | ML model weights and training data |
|
|
444
|
+
|
|
445
|
+
### Prompt Injection Honeypots ("Set" Tools)
|
|
440
446
|
| Tool | Threat | Description |
|
|
441
447
|
|------|--------|-------------|
|
|
442
448
|
| `execute_shell_command` | Critical | Shell command execution |
|
|
@@ -444,11 +450,127 @@ streamlit run src/honeymcp/dashboard/app.py
|
|
|
444
450
|
| `modify_system_prompt` | Critical | AI system prompt manipulation |
|
|
445
451
|
| `escalate_privileges` | Critical | Privilege escalation |
|
|
446
452
|
| `inject_system_message` | Critical | System context injection |
|
|
453
|
+
| `disable_security_filters` | Critical | Security filter bypass |
|
|
454
|
+
| `override_permissions` | Critical | Access control override |
|
|
455
|
+
| `disable_2fa_requirement` | Critical | Two-factor authentication bypass |
|
|
456
|
+
| `assume_iam_role` | Critical | AWS IAM role assumption |
|
|
457
|
+
|
|
447
458
|
All ghost tools have tempting descriptions that mention "admin", "bypass", "internal", etc. to attract attackers.
|
|
448
459
|
|
|
449
460
|
---
|
|
450
461
|
|
|
462
|
+
## 🤖 ToolGen Agent - Automated Tool Creation
|
|
463
|
+
|
|
464
|
+
HoneyMCP includes **ToolGen**, a ReAct-style agent that automatically creates new honeypot tools from natural language descriptions. No manual coding required.
|
|
465
|
+
|
|
466
|
+
### How It Works
|
|
467
|
+
|
|
468
|
+
ToolGen uses a **Reason-Act-Observe-Reflect** cycle:
|
|
469
|
+
|
|
470
|
+
1. **Reason** - Analyzes your description to extract tool specifications
|
|
471
|
+
2. **Act** - Generates response function code with realistic fake data
|
|
472
|
+
3. **Observe** - Validates syntax and structure
|
|
473
|
+
4. **Reflect** - Checks quality and suggests improvements
|
|
474
|
+
|
|
475
|
+
### Usage
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
honeymcp create-tool "dump container registry credentials"
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
ToolGen automatically:
|
|
482
|
+
- Determines tool category (exfiltration, bypass, privilege escalation)
|
|
483
|
+
- Infers threat level from description keywords
|
|
484
|
+
- Extracts parameters and types
|
|
485
|
+
- Generates realistic response templates
|
|
486
|
+
- Adds tool to both `ghost_tools.py` and `middleware.py`
|
|
487
|
+
- Validates all generated code
|
|
488
|
+
|
|
489
|
+
### Example
|
|
490
|
+
|
|
491
|
+
```bash
|
|
492
|
+
$ honeymcp create-tool "list terraform state files with secrets"
|
|
451
493
|
|
|
494
|
+
✅ Tool created: list_terraform_state
|
|
495
|
+
Category: exfiltration
|
|
496
|
+
Threat Level: critical
|
|
497
|
+
|
|
498
|
+
📝 Agent Reasoning:
|
|
499
|
+
- Analyzing tool description to extract specifications
|
|
500
|
+
- Generating response generator function
|
|
501
|
+
- Validating generated response function
|
|
502
|
+
- Checking code quality and security
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
The new tool is immediately available in your honeypot catalog.
|
|
506
|
+
|
|
507
|
+
---
|
|
508
|
+
|
|
509
|
+
## ❓ FAQ
|
|
510
|
+
|
|
511
|
+
### Can attackers detect the honeypots?
|
|
512
|
+
|
|
513
|
+
While it's theoretically possible for a sophisticated attacker to identify honeypots through careful analysis, it's **highly improbable** in practice:
|
|
514
|
+
|
|
515
|
+
- **Dynamic honeypots** are generated by LLM to match your server's domain and naming patterns, making them indistinguishable from legitimate tools
|
|
516
|
+
- **Tool descriptions** are crafted to appear as restricted/privileged versions of real functionality
|
|
517
|
+
- **No behavioral differences** - honeypots respond with realistic data, not errors or suspicious patterns
|
|
518
|
+
- **MCP protocol limitation** - AI agents cannot inspect tool implementation, only names and descriptions
|
|
519
|
+
|
|
520
|
+
Detection would require:
|
|
521
|
+
1. Prior knowledge of your specific tool catalog
|
|
522
|
+
2. Ability to distinguish between legitimate privileged tools and honeypots
|
|
523
|
+
3. Understanding that deception is being employed
|
|
524
|
+
|
|
525
|
+
For most attack scenarios (automated scanners, opportunistic attacks, indirect prompt injection), detection is effectively impossible.
|
|
526
|
+
|
|
527
|
+
### Will this slow down my MCP server?
|
|
528
|
+
|
|
529
|
+
No. HoneyMCP adds negligible overhead:
|
|
530
|
+
- **~1ms per tool call** for interception logic
|
|
531
|
+
- **Async event logging** doesn't block tool execution
|
|
532
|
+
- **Zero impact on legitimate tools** - they execute normally
|
|
533
|
+
- **LLM calls only at startup** for dynamic honeypot generation (cached for subsequent requests)
|
|
534
|
+
|
|
535
|
+
### What if I don't have LLM credentials?
|
|
536
|
+
|
|
537
|
+
HoneyMCP works perfectly without LLM access:
|
|
538
|
+
- Set `use_dynamic_tools=False` to use **static mode**
|
|
539
|
+
- Pre-configured generic honeypots work out-of-the-box
|
|
540
|
+
- No external dependencies or API calls required
|
|
541
|
+
- Slightly less convincing than dynamic honeypots, but still effective
|
|
542
|
+
|
|
543
|
+
### How do I know if I'm being attacked?
|
|
544
|
+
|
|
545
|
+
Multiple indicators:
|
|
546
|
+
- **Dashboard alerts** - Real-time visualization of attack events
|
|
547
|
+
- **Event logs** - JSON files in `~/.honeymcp/events/` with complete attack context
|
|
548
|
+
- **Webhook notifications** (optional) - Configure Slack/Discord alerts
|
|
549
|
+
- **Tool call sequences** - See exactly what the attacker tried before triggering honeypot
|
|
550
|
+
|
|
551
|
+
### Does this work with all MCP clients?
|
|
552
|
+
|
|
553
|
+
HoneyMCP is designed for **FastMCP servers** and works with any MCP-compatible client:
|
|
554
|
+
- ✅ Claude Desktop (stdio and HTTP transports)
|
|
555
|
+
- ✅ Custom MCP clients
|
|
556
|
+
- ✅ Any client following MCP protocol specification
|
|
557
|
+
|
|
558
|
+
The detection mechanism is client-agnostic - it operates at the server level.
|
|
559
|
+
|
|
560
|
+
### What's the difference between SCANNER and COGNITIVE modes?
|
|
561
|
+
|
|
562
|
+
**SCANNER mode (default):**
|
|
563
|
+
- Immediate lockout after honeypot trigger
|
|
564
|
+
- All subsequent tools return errors
|
|
565
|
+
- Best for automated attacks and quick containment
|
|
566
|
+
|
|
567
|
+
**COGNITIVE mode:**
|
|
568
|
+
- Sustained deception after honeypot trigger
|
|
569
|
+
- Real tools return synthetic/mock data
|
|
570
|
+
- Keeps attacker engaged for intelligence gathering
|
|
571
|
+
- Best for sophisticated attacks and red team exercises
|
|
572
|
+
|
|
573
|
+
---
|
|
452
574
|
|
|
453
575
|
## 🏗️ Architecture
|
|
454
576
|
|
|
@@ -480,7 +602,7 @@ All ghost tools have tempting descriptions that mention "admin", "bypass", "inte
|
|
|
480
602
|
│
|
|
481
603
|
▼
|
|
482
604
|
┌──────────────────┐
|
|
483
|
-
│
|
|
605
|
+
│ React │
|
|
484
606
|
│ Dashboard │
|
|
485
607
|
└──────────────────┘
|
|
486
608
|
```
|
|
@@ -604,7 +726,7 @@ HoneyMCP/
|
|
|
604
726
|
│ ├── storage/
|
|
605
727
|
│ │ └── event_store.py # JSON event persistence
|
|
606
728
|
│ └── dashboard/
|
|
607
|
-
│ └──
|
|
729
|
+
│ └── react_umd/ # React dashboard assets
|
|
608
730
|
├── examples/
|
|
609
731
|
│ ├── demo_server.py # Static ghost tools demo
|
|
610
732
|
│ └── demo_server_dynamic.py # Dynamic ghost tools demo
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "honeymcp"
|
|
3
|
-
version = "0.1.
|
|
3
|
+
version = "0.1.3"
|
|
4
4
|
description = "Deception middleware for AI agents - detecting data theft and indirect prompt injection in MCP servers"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.11"
|
|
@@ -41,9 +41,9 @@ classifiers = [
|
|
|
41
41
|
]
|
|
42
42
|
dependencies = [
|
|
43
43
|
"fastmcp>=3.0.0b1",
|
|
44
|
+
"fastapi>=0.115.0",
|
|
44
45
|
"pydantic>=2.10.0",
|
|
45
46
|
"pyyaml>=6.0.0",
|
|
46
|
-
"streamlit>=1.42.0",
|
|
47
47
|
"requests>=2.32.0",
|
|
48
48
|
"python-dateutil>=2.9.0",
|
|
49
49
|
"rich>=14.0.0",
|
|
@@ -65,6 +65,7 @@ Homepage = "https://github.com/barvhaim/HoneyMCP"
|
|
|
65
65
|
Documentation = "https://github.com/barvhaim/HoneyMCP#readme"
|
|
66
66
|
Repository = "https://github.com/barvhaim/HoneyMCP"
|
|
67
67
|
Issues = "https://github.com/barvhaim/HoneyMCP/issues"
|
|
68
|
+
PyPI = "https://pypi.org/project/honeymcp/"
|
|
68
69
|
|
|
69
70
|
[dependency-groups]
|
|
70
71
|
dev = [
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""FastAPI application for HoneyMCP."""
|