Decoy Scan

Zero-dependency security scanner for MCP servers. Zero config, runs anywhere npx runs.

Decoy Scan is a CLI that audits every MCP server reachable from your machine or CI environment. It's designed to be the cheapest step in your security workflow: no server, no account, no background processes. Run it, read the output, move on.

What it checks

Seven analyzer categories, 37 tool-poisoning regexes across 20 injection categories, and 40+ supply-chain advisories:

Tool risk classification — every tool graded critical/high/medium/low on name patterns and description analysis
Tool poisoning detection — prompt injection hidden in tool descriptions (instruction override, concealment, data exfiltration, credential harvesting, coercive execution, tool shadowing, evasion)
Server command analysis — spawn commands flagged for pipe-to-shell, temp directories, inline code, typosquatting, network tools
Credential handling — 12 categories of sensitive env vars passed to servers (API keys, tokens, passwords, DB URLs, cloud creds)
Production readiness — missing descriptions, missing schemas, destructive tools without safety hints
Supply chain advisories — cross-referenced against Decoy's advisory database
OWASP Agentic Top 10 mapping — findings tagged ASI01, ASI02, ASI03, ASI05

Usage

One-off scan

npx decoy-scan

Walks your MCP client configs (Claude Desktop, Cursor, VS Code, and more), spawns each server, queries its tool list, and prints a human-readable report.

SARIF for CI

npx decoy-scan --sarif > decoy.sarif

SARIF 2.1.0 plugs directly into GitHub Code Scanning. See CI/CD for the official action.

Report to your Guard workspace

npx decoy-scan --report --token=$DECOY_TOKEN

Uploads results so they show up in the dashboard, trend history, and Guard's decoy_scan_summary tool.

Explain

When a scan flags something and you want to know why, ask the scanner:

npx decoy-scan explain critical          # What "critical" means + what to do
npx decoy-scan explain tool-description  # What a finding category checks
npx decoy-scan explain prompt-override   # What a poisoning type looks like
npx decoy-scan explain evaluate_script   # Why a tool was classified the way it was
npx decoy-scan explain list              # Everything you can explain

Explanations resolve against the same patterns the scanner uses, so they can't drift. --json works on every target for agents and automation.

Exit codes

0 — no critical or high-risk issues
1 — high-risk issues found
2 — critical issues or tool poisoning found

Flags

Flag	Purpose
`--json`	JSON output
`--sarif`	SARIF 2.1.0 output
`--brief`	Minimal JSON summary (use with `--json`)
`--no-probe`	Config-only scan, don't spawn servers
`--no-advisories`	Skip advisory database lookup
`--share`	Generate a shareable public URL
`--report`	Upload to your Guard dashboard (requires `--token`)
`--token=xxx`	Decoy API token
`--verbose` / `-v`	Show low-risk tools too
`--quiet` / `-q`	Suppress status output
`-y` / `--yes`	Skip confirmation prompts (for CI)

Configuration

There's no config file. Flags cover every knob, and the default behavior (auto-discover every MCP client config, probe every server, run every check) is what you want in nearly every case.