Related Pages

Related topics: System Architecture and Source Modules, CLI, GitHub Action, and Library API

Introduction and Getting Started

decoy-scan is a zero-dependency, read-only security scanner for Model Context Protocol (MCP) server configurations. It discovers MCP configs across seven supported hosts, spawns each server, classifies its tools by risk, scans tool descriptions for prompt injection, and cross-references against a live advisory database — all without requiring an account or modifying any files on disk. Source: README.md

This page covers what the tool does, how to install it, and how to interpret the output. It is the entry point for both human operators and AI agents that need to invoke the scanner from a shell.

Purpose and Scope

decoy-scan answers a single question: *are the MCP servers connected to my editors and agents configured safely?* It evaluates risk along seven axes:

Source: README.md

The scanner never modifies configs, only reads them, and runs locally by default. It supports Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Zed, and Cline, with platform-aware config paths for macOS, Windows, and Linux. Source: AGENTS.md

Prerequisites and Installation

decoy-scan is shipped as a single ES module with zero runtime dependencies and requires Node.js 18 or later. Source: package.json

The recommended install is via npx, which avoids global pollution:

npx decoy-scan               # full scan of all discovered hosts
npx decoy-scan --no-probe     # config-only (skip server spawning)
npx decoy-scan --verbose      # include low-risk tools
npx decoy-scan --quiet        # exit code only
npx decoy-scan --no-color     # disable ANSI colors for CI logs

To install globally, use npm i -g decoy-scan; the CLI binary is registered under the decoy-scan name in package.json. Source: package.json

When run from a project root, decoy-scan also picks up project-level .mcp.json files alongside the host-level configs. Source: README.md

Scan Workflow

Internally, the scanner follows a fixed pipeline: discover configs → spawn servers over the MCP handshake → read the tool list → classify each tool → run static analyses → aggregate findings.

flowchart LR
    A[Discover MCP configs] --> B[Probe each server<br/>MCP initialize + tools/list]
    B --> C[Classify tool risk<br/>RISK_PATTERNS]
    B --> D[Detect poisoning<br/>POISONING_PATTERNS]
    B --> E[Static analyses<br/>env, command, readiness, advisories]
    C --> F[Aggregate findings<br/>+ OWASP mapping]
    D --> F
    E --> F
    F --> G[Render human / JSON / SARIF / --brief]

The MCP handshake is strict: the scanner sends initialize, waits for the response, sends notifications/initialized, then issues tools/list with a 15-second timeout per server. Source: AGENTS.md

Interpreting Output and Exit Codes

decoy-scan exits with a deterministic code so it can gate CI pipelines:

Source: README.md

Three output modes are available:

• Human (default) — colorized per-server report. The summary line reads N issues found · N critical, N high · N checks passed · Ns, followed by a one-line review guidance. Source: CHANGELOG.md
• --json — full structured report with servers, summary, advisories, and owasp blocks.
• --brief — minimal { servers, critical, high, medium, low, poisoned, status, exitCode } object for agent consumption. Source: AGENTS.md

The end-of-run claim line in human mode has been evolving across releases — in v0.5.8 it ends with a one-line GitHub star ask, matching decoy-tripwire and decoy-redteam for consistency across Decoy CLIs. Source: CHANGELOG.md

Programmatic and CI/CD Use

The same logic is exposed as a library from index.mjs:

import { scan, toSarif, classifyTool, detectPoisoning } from 'decoy-scan';

const results = await scan({ skills: true });
console.log(results.servers[0].manifestHash);
console.log(results.toxicFlows);

Source: README.md

For CI, a one-step GitHub Action is provided at decoy-run/decoy-scan@v1. It scans MCP configs, enforces a policy (default no-critical,no-poisoning), and uploads SARIF to the GitHub Security tab. Source: action.yml

- uses: decoy-run/decoy-scan@v1
  with:
    policy: no-critical,no-poisoning
    sarif: true
    report: false

To report a vulnerability in the scanner itself, follow the coordinated disclosure process in SECURITY.md (email [email protected], no public issues). Source: SECURITY.md

See Also

• What decoy-scan Checks — full table of check categories
• explain subcommand — structured explanations for tiers, categories, and tool names
• Output Schemas — --json and --brief field reference
• GitHub Action inputs — policy rules, SARIF upload, and report flags
• decoy-tripwire — companion tool for runtime tripwires
• decoy-redteam — autonomous red team for MCP servers

Related Pages

Related topics: Introduction and Getting Started, Security Checks, Patterns, and Detection Rules

System Architecture and Source Modules

Purpose and Scope

decoy-scan is a read-only, zero-dependency security scanner for Model Context Protocol (MCP) server configurations. It ships as a CLI binary, a composite GitHub Action, and an ES module library that other tools can embed. The architecture is intentionally small: a single library entry point, a thin CLI shim, and a lib/ tree of analyzer and probe modules — all distributed without a build step.

Source: package.json:1-5 Source: AGENTS.md

The project positions itself as a config-and-runtime scanner across seven supported hosts (Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Zed, and Cline) and targets three concerns: tool risk classification, prompt-injection detection in tool descriptions, and toxic-flow / supply-chain analysis. It is read-only by contract — the agent documentation explicitly states the scanner "never modify configs."

Source: AGENTS.md Source: README.md

Top-Level Layout

The repository exposes a deliberately compact surface area. The shipped files array in package.json is the authoritative runtime layout: ["index.mjs", "lib/", "bin/"]. Everything else (docs, the action definition, tests) is host-side.

decoy-scan/
├── index.mjs      — library (all exports)
├── bin/cli.mjs    — CLI entry point
├── lib/           — analyzer and probe modules
├── package.json   — zero dependencies, ES modules
├── action.yml     — composite GitHub Action
├── README.md      — human docs
├── AGENTS.md      — agent docs
└── LICENSE        — MIT

Source: AGENTS.md Source: package.json:7-15

package.json declares "type": "module", "main": "index.mjs", and exports: { ".": "./index.mjs" }, and registers the decoy-scan binary against bin/cli.mjs. The Node engine requirement is >=18.0.0, and there are zero runtime dependencies — a constraint reaffirmed in the contributing guidance.

Source: package.json:4-18,55-57

Module Architecture

The library is a single re-export hub over composable analyzer functions. The agent documentation enumerates the public surface: scan (the full pipeline: discover → probe → classify → check), classifyTool, detectPoisoning, analyzeServerCommand, analyzeEnvExposure, analyzeReadiness, discoverConfigs, probeServer, and checkAdvisories. Each is independently callable so consumers can run a subset of checks.

flowchart LR
  A[index.mjs<br/>library entry] --> B[scan]
  A --> C[classifyTool]
  A --> D[detectPoisoning]
  A --> E[analyzeServerCommand]
  A --> F[analyzeEnvExposure]
  A --> G[analyzeReadiness]
  A --> H[discoverConfigs]
  A --> I[probeServer]
  A --> J[checkAdvisories]
  B --> H
  B --> I
  B --> C
  B --> D
  B --> E
  B --> F
  B --> G
  B --> J

Source: AGENTS.md

The internal modules map directly to the seven published check families in the README — tool risk classification, prompt-injection detection, toxic-flow analysis, environment-variable exposure, supply-chain advisories, and OWASP ASI mapping — with discoverConfigs and probeServer providing the host-discovery and MCP-handshake layers that feed them.

Source: README.md Source: AGENTS.md

CLI and GitHub Action Surfaces

The CLI is a thin shim that consumes the same library exports. The bin/cli.mjs entry is registered in package.json, and the action entry is action.yml, which is a composite action. It accepts six inputs and surfaces three outputs:

Source: action.yml Source: README.md

The action wires setup-node@v4 with the decoy-scan invocation, then conditionally uploads SARIF via github/codeql-action/upload-sarif@v3 under category decoy-scan. SARIF upload is wrapped in continue-on-error: true to avoid masking scan failures, and the step summary surfaces a clean / issues-found banner based on the exit code.

Source: action.yml

The exit-code contract is uniform across surfaces: 0 for clean, 1 for high-risk issues, 2 for critical issues or tool poisoning. The same code is mirrored as the exitCode field on --json and --brief output, so agents and CI consumers can branch on a single signal.

Source: AGENTS.md Source: README.md

Operational Posture and Versioning

The scanner's network surface is intentionally narrow: the only default outbound call is the optional advisory database lookup via checkAdvisories. Writes are user-initiated — the report flag, the SARIF upload, and the opt-in v2 telemetry envelope introduced in v0.7.0. The closing line in the v0.8.1 release is itself findings-aware, tying the dashboard CTA to the actual result count rather than emitting a generic footer.

Source: CHANGELOG.md Source: package.json:3

The current package.json reports version 0.8.1, and supported versions per the security policy are the 0.4.x line. The engines.node floor is 18.0.0, which is also the test runner target — package.json invokes node --test over cli.test.mjs, unit.test.mjs, probe.test.mjs, and telemetry.test.mjs.

Source: package.json:3,18,55-57 Source: SECURITY.md

See Also

• decoy-tripwire — Tripwire tools that detect compromised agents
• decoy-redteam — Autonomous red team for MCP servers
• Decoy Guard — Dashboard, threat intel, and compliance reports

Related Pages

Related topics: System Architecture and Source Modules, CLI, GitHub Action, and Library API

Security Checks, Patterns, and Detection Rules

decoy-scan is a zero-dependency, read-only security scanner for Model Context Protocol (MCP) server configurations. It discovers MCP configs across seven supported hosts, probes running servers, then applies a layered set of detection rules to classify risk. The pattern engine is the heart of the scanner: every finding emitted to the terminal, SARIF, or JSON output originates from one of the rule tables described below.

The scanner is structured around the principle that explanations cannot drift from detections — the same RISK_PATTERNS and POISONING_PATTERNS tables that produce findings also back the decoy-scan explain subcommand. Source: CONTRIBUTING.md.

Rule Categories and Execution Order

A full scan runs seven distinct check families against each discovered server. Each family emits findings with a type, severity, and OWASP tag.

Source: AGENTS.md, CONTRIBUTING.md.

flowchart TD
    A[Discover MCP configs<br/>7 hosts] --> B[Spawn & probe server<br/>15s timeout]
    B --> C[tools/list response]
    C --> D{Tool name +<br/>description}
    D --> E[RISK_PATTERNS<br/>classifyTool]
    D --> F[POISONING_PATTERNS<br/>detectPoisoning]
    D --> G[analyzeServerCommand]
    D --> H[analyzeEnvExposure]
    D --> I[analyzeReadiness]
    C --> J[checkAdvisories<br/>Decoy DB]
    E --> K[OWASP_MAP]
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    K --> L[Findings + exit code]

Tool Risk Classification

Tool classification matches a tool's name and description against a regex table (RISK_PATTERNS). The classification covers the four tiers defined in CHANGELOG.md:

• Critical — code execution, file write, destructive verbs. Patterns like ^(execute|run|eval)(script|code)$ and (write|save|delete|remove)_(file|dir|folder) resolve here.
• High — file read, network calls, credentials access. Substring fallback also runs against the lowercased name (CHANGELOG v0.5.6) so verbs like evaluate, spawn, fetch classify correctly when no description is provided.
• Medium / Low — lower-impact operations and safe read-only tools.

When a name matches but the description is absent or unscored, the scanner notes that classification relied on name alone. Source: CHANGELOG.md, AGENTS.md.

Prompt Injection Detection

The poisoning detector matches tool descriptions against POISONING_PATTERNS — 37 regexes spanning 20 attack categories such as prompt-override, tool-description, instruction-hijack, and data-exfil. Each pattern has a fixed shape:

{ pattern: /regex/i, type: "category-name", severity: "critical|high|medium|low", description: "..." }

A poisoned tool triggers a magenta ! badge in CLI output and forces exitCode: 2. Poisoned tools are also deduplicated from the safe summary in --brief mode. Source: README.md, CHANGELOG.md, CONTRIBUTING.md.

Toxic Flow Analysis

Toxic flows evaluate *cross-server* attack chains rather than individual tool risk:

• TF001 — Cross-server data leak: a high-read tool in one server combined with an exfiltration-capable tool in another.
• TF002 — Destructive attack chain: a write/delete tool chained with a privilege-escalation or persistence tool across hosts.

These are the only checks that join findings across multiple servers; everything else is per-server. The no-toxic-flows policy rule fails CI when either chain is detected. Source: README.md, action.yml.

Server Command, Env, and Readiness Checks

Three additional analyzers run on the static config:

• analyzeServerCommand — flags pipe-to-shell, inline code (bash -c "..."), typosquatting of well-known server package names, and temp-directory spawning (/tmp, $TMPDIR).
• analyzeEnvExposure — flags 12 categories of sensitive credentials passed through server env blocks: API keys, OAuth tokens, passwords, database URLs, cloud credentials (AWS, GCP, Azure), and private keys.
• analyzeReadiness — checks for missing descriptions, missing schemas, no required fields, unconstrained parameters, missing maxLength, and destructive tools without safety hints.

Source: AGENTS.md, README.md.

Supply Chain Advisories and OWASP Mapping

checkAdvisories cross-references every server's package identifier against the Decoy advisory database (40+ known vulnerable MCP packages). The lookup runs against the local advisory feed and can be skipped with --no-advisories. Source: README.md, AGENTS.md.

Every finding is then tagged via OWASP_MAP to one of the OWASP Agentic Top 10 categories: ASI01 (prompt injection), ASI02 (unsafe tool use), ASI03 (supply chain), and ASI05 (improper output handling). The result.kind field in explain --json output reuses the same tags, so agent consumers can correlate findings to framework requirements. Source: README.md, AGENTS.md.

Exit Codes and Policy Gating

Findings map to process exit codes so CI pipelines can branch on them:

The --policy flag accepts comma-separated rules (no-critical, no-high, no-poisoning, no-toxic-flows, no-secrets, require-tripwires, max-critical=N, max-high=N). The GitHub Action defaults to no-critical,no-poisoning and uploads SARIF to the Security tab by default. Source: README.md, action.yml.

Adding New Patterns

To add a poisoning rule, append an entry to POISONING_PATTERNS in index.mjs and add its type to OWASP_MAP if a new OWASP category applies. To support a new MCP host, add an entry to HOST_CONFIGS returning the platform-aware config path. The test suite (npm test) runs 48 tests covering CLI output, JSON/SARIF structure, policy gates, toxic flow detection, skill analysis, and manifest hashing. Source: CONTRIBUTING.md, package.json.

See Also

• CLI Usage and Output Formats
• JSON and SARIF Output Schemas
• GitHub Action Integration
• Library API and Exports

Related Pages

Related topics: Introduction and Getting Started, Security Checks, Patterns, and Detection Rules

CLI, GitHub Action, and Library API

decoy-scan ships three integration surfaces — a CLI binary, a GitHub Action, and an ES-module library — all backed by the same zero-dependency scanner core. Each surface is designed for a different audience: developers running it locally, CI pipelines gating PRs, and software embedding the scanner into larger systems.

CLI Interface

The CLI is defined as a binary in package.json ("bin": { "decoy-scan": "bin/cli.mjs" }) and targets Node.js >= 18. Running npx decoy-scan with no arguments performs a full scan of every MCP config on the current machine across seven supported hosts: Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, Zed, and Cline. Source: README.md.

Common Flags

Source: README.md and AGENTS.md.

`explain` Subcommand

decoy-scan explain <target> resolves what a finding means without re-running a scan. Targets include severity tiers (critical, high, medium, low), finding categories, poisoning types, and individual tool names. The lookup is sourced from the same RISK_PATTERNS and POISONING_PATTERNS the scanner uses internally, so explanations cannot drift from detection logic. --json is supported on every path, with result.kind being one of tier, category, poisoning, or tool. Source: CHANGELOG.md and AGENTS.md.

Exit Codes

The exit code is also surfaced as exitCode on --json and --brief output, allowing agents to branch on it without re-deriving severity from summary counts. Source: AGENTS.md.

Brief Output

--brief (which implies --json) returns a minimal summary object: { servers, critical, high, medium, low, poisoned, status, exitCode }. status is "pass" for clean runs, "warn" when only high-risk findings exist, and "fail" for critical, poisoned, or toxic flow detections. Source: AGENTS.md.

Community Note

Per the v0.5.8 release, scan output ends with a one-line GitHub star ask — mirroring the same line in decoy-tripwire and decoy-redteam for consistency across Decoy CLIs. Source: CHANGELOG.md.

GitHub Action

The Action is declared in action.yml. It wraps a single npx decoy-scan invocation, enforces a policy, optionally uploads SARIF to the GitHub Security tab, and writes a human-readable summary to $GITHUB_STEP_SUMMARY. Source: action.yml.

Minimal Workflow

# .github/workflows/mcp-security.yml
name: MCP Security
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: decoy-run/decoy-scan@v1

The build fails on critical tools or prompt injection; SARIF results appear in the Security tab. Source: README.md.

Action Inputs

Policy Rules

Valid policy rules include no-critical, no-high, no-poisoning, no-toxic-flows, no-secrets, require-tripwires, and max-critical=N. Multiple rules are comma-separated. Source: README.md.

Library API

The library entry point is index.mjs (ES modules, "type": "module" in package.json). It exports scanner primitives so embedders can compose their own pipelines.

import {
  scan,                    // Full scan: discover + probe + classify + check
  toSarif,                 // SARIF output generator
  classifyTool,            // Classify a single tool's risk level
  detectPoisoning,         // Detect prompt injection in tool descriptions
  analyzeToxicFlows,       // Cross-server data leak / destructive chains
  hashToolManifest,        // Hash a server's tool list
  detectManifestChanges,   // Diff manifest hashes between scans
  discoverSkills,          // Find Claude Code skills on this machine
  analyzeSkill,            // Scan a single skill for risks
  analyzeServerCommand,    // Check spawn command for suspicious patterns
  analyzeEnvExposure,      // Flag sensitive env vars passed to servers
  analyzeReadiness,        // Production readiness heuristics
  discoverConfigs,         // Find MCP config files on this machine
  probeServer,             // Spawn and query a single MCP server
  checkAdvisories,         // Fetch advisory database from Decoy API
} from 'decoy-scan';

Source: AGENTS.md, README.md, and CONTRIBUTING.md.

Usage Example

import { scan, toSarif } from 'decoy-scan';

const results = await scan({ skills: true });
console.log(results.toxicFlows);                     // [{ id: "TF001", severity: "critical", ... }]
console.log(results.skills);                         // [{ name: "...", findings: [...] }]
console.log(results.servers[0].manifestHash);        // "45c4c571f03c78a2"

const sarif = toSarif(results);

scan() orchestrates discovery, probing, classification, and advisory cross-reference in one call. Individual primitives are also exported for embedders that need to build a custom pipeline. Source: README.md and AGENTS.md.

Integration Architecture

flowchart LR
  A[bin/cli.mjs] --> C[index.mjs]
  B[action.yml] --> C
  C --> D[discoverConfigs]
  D --> E[probeServer]
  E --> F[classifyTool]
  E --> G[detectPoisoning]
  E --> H[analyzeEnvExposure]
  F --> I[scan]
  G --> I
  H --> I
  I --> J[toSarif]
  I --> K[--json / --brief / --sarif]
  I --> L[exit code]

All three surfaces funnel into the same index.mjs core, which is why the CLI, the Action, and library consumers see identical detection behavior. Source: CONTRIBUTING.md and package.json.

See Also

• Architecture Overview — how the scanner primitives fit together
• Detection Patterns — the RISK_PATTERNS and POISONING_PATTERNS catalogs
• Output Schemas — full JSON and SARIF reference
• Related: decoy-tripwire, decoy-redteam

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/decoy-run/decoy-scan

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/decoy-run/decoy-scan

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/decoy-run/decoy-scan

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/decoy-run/decoy-scan

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/decoy-run/decoy-scan

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using decoy-scan with real data or production workflows.

• v0.5.8 - github / github_release
• Decoy Scan - MCP Security for CI/CD - github / github_release
• Configuration risk requires verification - GitHub / issue