mcp-heimdall-scan

Heimdall

The watchman at your agent's gate.

A security scanner for Model Context Protocol (MCP) servers — vet a server, or a whole agent config, before your agent trusts it.

MCP servers are unvetted code with a natural-language attack surface: their tool descriptions go straight to your model, and the server runs with your machine's access. Heimdall scores what a server can actually do — not what it claims — and cites the exact evidence.

Quickstart

npx mcp-heimdall-scan firecrawl-mcp                   # scan a published server
npx mcp-heimdall-scan ./claude_desktop_config.json    # audit your whole agent config
npx mcp-heimdall-scan firecrawl-mcp --online          # + check its deps for known CVEs (OSV.dev)
npx mcp-heimdall-scan ./my-server --policy strict     # gate it in CI

No install, runs locally, nothing leaves your machine.

Or try it in your browser: caglarbozkurt.github.io/mcp-heimdall — the full scanner runs 100% client-side (npm packages are fetched via jsDelivr; or paste a tools.json / MCP config). No backend, nothing uploaded. Local paths and --handshake need the CLI.

What it checks

Check	What it catches
🧬 Injection	tool-poisoning across tools, resources & prompts — override, concealment, hidden chars, fake <IMPORTANT> tags
🔓 Capability	filesystem, network, shell, eval, and specific credential access (SSH / AWS / keychain / .env)
🎯 Proven exfil paths	data-flow that proves secret → network or fetch → eval, file:line → file:line
📦 Provenance & deps	install-time scripts, missing repo/license, capabilities inherited from dependencies
🛡️ Known CVEs (opt-in)	declared dependencies checked against the OSV.dev advisory DB — real CVE IDs, severity-ranked (--online)
🕸️ Composition	audits a whole config: cross-server exfiltration chains & tool-name collisions
🔁 Drift	fingerprints the surface — a silently changed tool description (rug-pull) is a hard fail

Every finding cites file:line or tool:name. Capability ≠ risk: raw power is shown as an informational profile and never fails the scan — only hard gates and real anomalies do.

What makes it different

• Sees the whole gate. It reasons across the set of servers you've configured — the cross-server exfil path neither server shows alone. Most scanners look at one at a time.
• Proves the path. Taint/data-flow turns "reads files AND has network = fail" into a concrete, located flow — so it doesn't cry wolf on a config read plus an unrelated API call.
• A gate you control. Detectors emit facts; a policy you define turns them into pass / warn / fail. Deny capabilities, require provenance, add audited waivers, gate CI.

Usage

heimdall <target> [options]

Target	Example
local directory	heimdall ./servers/my-mcp
npm package	heimdall some-mcp-package
PyPI package	heimdall pypi:some-mcp-server
git repository	heimdall https://github.com/user/repo
tools/list dump	heimdall tools.json
MCP client config	heimdall ./claude_desktop_config.json

Options

--tools <file>     supplement analysis with a tools/list (or {tools,resources,prompts}) dump
--policy <p>       "default", "strict", or a JSON policy file
--baseline <file>  diff against a prior --json report (drift / rug-pull detection)
--handshake        RUN the server(s) for the live tool list (untrusted code — VM/container only)
--online           check declared deps against OSV.dev for known CVEs (sends dep names, not source)
--json             machine-readable report
--sarif            SARIF 2.1.0 (GitHub code-scanning / CI)
--no-fail          always exit 0

Exit codes: 0 pass/warn · 1 fail · 2 error

Policies

Detectors emit facts; a policy turns them into the verdict. Ship the default, pick strict, or write your own procurement/security criteria:

Example policy (policy.example.json)

{
  "name": "acme-procurement",
  "denyCapabilities": ["exec", "dynamic-eval", "secret-access"],
  "require": ["has_repository", "has_license"],
  "failOnSeverity": "high",
  "warnOnSeverity": "low",
  "allow": [{ "id": "capability/scope-mismatch", "reason": "reviewed", "expires": "2026-12-31" }]
}

Waivers carry a reason and optional expiry — an expired waiver lapses and re-flags.

Library

import { scan } from "mcp-heimdall-scan";

const report = await scan("some-mcp-server", { policy: "strict" });
if (report.verdict === "fail") throw new Error(report.reasons.join("; "));

Also ships as a Claude Code skill (skill/) — vet a server in-conversation before installing.

Use it as an MCP server

Give your agent a scan_mcp_server tool so it can vet a server before connecting to it — "scan this before you add it." Add Heimdall to your MCP client config:

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": ["-y", "--package", "mcp-heimdall-scan", "heimdall-mcp"]
    }
  }
}

The tool takes target (npm package, pypi:<name>, path, GitHub URL, tools.json, or a client config), plus optional policy and online. It's static-only — it downloads but never executes the server, and the code-execution modes (--handshake, validate) are intentionally not exposed to the agent.

Use it in CI (GitHub Action)

Gate every pull request — scan your MCP config (or a server) and fail the build if it's risky. Add this to .github/workflows/:

- uses: caglarbozkurt/mcp-heimdall@v1
  with:
    target: ./claude_desktop_config.json   # a path, npm/pypi package, github URL, or tools.json
    policy: strict                          # "default", "strict", or a JSON policy file
    online: true                            # also check deps for known CVEs (OSV.dev)
    sarif: heimdall.sarif                   # optional: emit SARIF for code scanning

Input	Default	Description
target	—	what to scan (required)
policy	default	default, strict, or a path to a JSON policy
online	false	check dependencies for known CVEs via OSV.dev
sarif	—	write SARIF to this path (for github/codeql-action/upload-sarif)
fail-on-findings	true	fail the job on a FAIL verdict (set false to report only)
version	latest	pin the mcp-heimdall-scan version for reproducible CI

Runs entirely on your own CI runner — no backend, and free on public repos.

Validate (behavioral cross-check)

Static analysis says what a server can do. heimdall validate checks that against what it actually does — it runs the server with a capability recorder preloaded (hooking fs / net / http(s) / child_process / vm / fetch / process.env), drives each tool, and diffs observed runtime behavior against the static flags:

heimdall validate ./my-server            # one server: confirmed / missed / not-exercised
heimdall validate --list servers.txt     # batch: a recall number over observed behavior

• confirmed — flagged and observed (the static claim held up).
• not exercised — flagged but not triggered by naive args (a lower bound, not proof the flag is wrong).
• missed — observed but not flagged → a real static gap to review (or an incidental library side effect).

So it's trustworthy for finding false negatives (static misses); it does not disprove a flag. Each server runs in a throwaway HOME + working directory with no inherited secrets, but it still runs the server and calls its tools (network/exec side effects) — use a disposable VM/container.

Behavioral run over 200 real packages (benchmarks/validate-run.md): 55 booted, 34 exercised an observable capability. Of the capabilities servers actually exercised at runtime, the static scan flagged 80.9% (55/68) — up from 75.8% after the first run's misses became a fix-list (we widened dependency-based network detection, which roughly halved the network misses). The misses that remain are structural: a capability exercised inside a dependency's internals or a subprocess, which static analysis fundamentally can't see — which is exactly why validate exists as the backstop. Honest recall, openly reported, improving run over run.

Tested at scale

Run against 2,500 real MCP packages from the npm registry (benchmarks/): 1,726 scanned in ~5 minutes, 0.7% flagged — robust on messy real-world code. Separately, 100% precision / recall on a small labeled corpus (npm run eval), including the Damn Vulnerable MCP project. Full log: benchmarks/field-run.md.

What that scan says about the ecosystem your agent trusts:

Of 1,726 real MCP servers…	share
can run shell commands	45%
make network calls	67%
can eval code at runtime	9%
can do both exec + network	34%
touch credential files	5%

The 0.7% flagged were driven by install-time code execution and prompt-injection — including real servers with hidden zero-width characters embedded in their tool descriptions, the kind of stealth tool-poisoning a keyword scanner sails past.

A robustness + distribution run is not an accuracy benchmark — the 2,500 servers are unlabeled. A flag means review this, not proven malicious.

Security & limitations

Heimdall is a heuristic pre-flight check, not a guarantee — a PASS isn't proof of safety. Capability, provenance, and CVE analysis cover JS/TS and Python; injection is language-agnostic. Proven taint/data-flow is JS/TS only — Python falls back to capability co-presence (a conservative gate, not a proven flow). Everything runs offline by default; --online is the one network call (it sends dependency names + versions to OSV.dev, never your source), and the CVE match is against the declared range, not a lockfile. --handshake runs untrusted code and is not a real sandbox. See SECURITY.md for the full threat model and how to report a vulnerability.

Contributing

New detection rules are the highest-value contribution — see CONTRIBUTING.md. By participating you agree to the Code of Conduct.

License

MIT · built by Çağlar Bozkurt