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.
Files changed (59) hide show
  1. {honeymcp-0.1.1 → honeymcp-0.1.3}/AGENTS.md +2 -2
  2. {honeymcp-0.1.1 → honeymcp-0.1.3}/Makefile +6 -5
  3. {honeymcp-0.1.1 → honeymcp-0.1.3}/PKG-INFO +150 -27
  4. {honeymcp-0.1.1 → honeymcp-0.1.3}/README.md +147 -25
  5. {honeymcp-0.1.1 → honeymcp-0.1.3}/pyproject.toml +3 -2
  6. honeymcp-0.1.3/src/honeymcp/api/__init__.py +1 -0
  7. honeymcp-0.1.3/src/honeymcp/api/app.py +218 -0
  8. honeymcp-0.1.3/src/honeymcp/cli_tool_creator.py +110 -0
  9. honeymcp-0.1.3/src/honeymcp/core/catalog_updater.py +290 -0
  10. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/ghost_tools.py +437 -0
  11. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/middleware.py +57 -0
  12. honeymcp-0.1.3/src/honeymcp/core/tool_creator.py +499 -0
  13. honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/app.js +375 -0
  14. honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/index.html +24 -0
  15. honeymcp-0.1.3/src/honeymcp/dashboard/react_umd/styles.css +512 -0
  16. honeymcp-0.1.3/test_complete_workflow.py +88 -0
  17. honeymcp-0.1.3/test_tool_creator.py +51 -0
  18. honeymcp-0.1.3/tests/test_catalog_updater.py +43 -0
  19. honeymcp-0.1.3/tests/test_configuration.py +75 -0
  20. honeymcp-0.1.3/tests/test_event_storage.py +106 -0
  21. honeymcp-0.1.3/tests/test_middleware_dispatch.py +70 -0
  22. honeymcp-0.1.3/tests/test_new_honeypot_tools.py +168 -0
  23. honeymcp-0.1.3/tests/test_protection_modes.py +61 -0
  24. honeymcp-0.1.3/tests/test_tool_creator_agent.py +154 -0
  25. {honeymcp-0.1.1 → honeymcp-0.1.3}/uv.lock +25 -308
  26. honeymcp-0.1.1/src/honeymcp/dashboard/app.py +0 -228
  27. {honeymcp-0.1.1 → honeymcp-0.1.3}/.env.example +0 -0
  28. {honeymcp-0.1.1 → honeymcp-0.1.3}/.gitignore +0 -0
  29. {honeymcp-0.1.1 → honeymcp-0.1.3}/.python-version +0 -0
  30. {honeymcp-0.1.1 → honeymcp-0.1.3}/.streamlit/config.toml +0 -0
  31. {honeymcp-0.1.1 → honeymcp-0.1.3}/LICENSE +0 -0
  32. {honeymcp-0.1.1 → honeymcp-0.1.3}/examples/demo_server.py +0 -0
  33. {honeymcp-0.1.1 → honeymcp-0.1.3}/examples/demo_server_dynamic.py +0 -0
  34. {honeymcp-0.1.1 → honeymcp-0.1.3}/honeymcp.yaml +0 -0
  35. {honeymcp-0.1.1 → honeymcp-0.1.3}/images/logo.png +0 -0
  36. {honeymcp-0.1.1 → honeymcp-0.1.3}/main.py +0 -0
  37. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/__init__.py +0 -0
  38. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/cli.py +0 -0
  39. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/__init__.py +0 -0
  40. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/dynamic_ghost_tools.py +0 -0
  41. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/core/fingerprinter.py +0 -0
  42. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/dashboard/__init__.py +0 -0
  43. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/integrations/__init__.py +0 -0
  44. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/__init__.py +0 -0
  45. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/analyzers.py +0 -0
  46. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/clients/__init__.py +0 -0
  47. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/clients/provider_type.py +0 -0
  48. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/prompts/__init__.py +0 -0
  49. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/llm/prompts/dynamic_ghost_tools.yaml +0 -0
  50. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/__init__.py +0 -0
  51. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/config.py +0 -0
  52. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/events.py +0 -0
  53. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/ghost_tool_spec.py +0 -0
  54. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/models/protection_mode.py +0 -0
  55. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/storage/__init__.py +0 -0
  56. {honeymcp-0.1.1 → honeymcp-0.1.3}/src/honeymcp/storage/event_store.py +0 -0
  57. {honeymcp-0.1.1 → honeymcp-0.1.3}/tests/test_demo_server_dynamic_e2e.py +0 -0
  58. {honeymcp-0.1.1 → honeymcp-0.1.3}/tests/test_demo_server_e2e.py +0 -0
  59. {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 Streamlit UI in `src/honeymcp/dashboard/`.
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
- - `streamlit run src/honeymcp/dashboard/app.py` launches the dashboard.
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-dashboard run-example build inspector
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.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
  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
52
53
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
54
+ [![PyPI](https://img.shields.io/pypi/v/honeymcp)](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 `@honeypot` decorator to any FastMCP server
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 Streamlit dashboard for attack visualization
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
- streamlit run src/honeymcp/dashboard/app.py
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 a detailed attack fingerprint:
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": "evt_20260123_154523_abc",
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
- ### Prompt Injection Honeypots (SET)
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
- Streamlit
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
- │ └── app.py # Streamlit dashboard
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
  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
8
8
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
9
+ [![PyPI](https://img.shields.io/pypi/v/honeymcp)](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 `@honeypot` decorator to any FastMCP server
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 Streamlit dashboard for attack visualization
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
- streamlit run src/honeymcp/dashboard/app.py
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 a detailed attack fingerprint:
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": "evt_20260123_154523_abc",
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
- ### Prompt Injection Honeypots (SET)
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
- Streamlit
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
- │ └── app.py # Streamlit dashboard
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.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."""