io.github.caglarbozkurt/heimdall

Heimdall

The watchman at your agent's gate.

A local, pre-flight security scanner for Model Context Protocol (MCP) servers — vet a server, or a whole agent config, before your agent trusts it. No account, no backend, and it never runs the server by default.

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. It runs entirely on your machine, needs no account, and never executes the server by default, so you can vet a package before you install it and gate it in CI.

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

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

• Local, and it doesn't run the server. Everything is static and offline by default — no account, no backend, nothing uploaded — and it never executes untrusted code unless you opt into --handshake (documented for a disposable VM only). You vet a package before installing.
• 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.
• 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.
• 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]

--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:

{
  "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" }]
}

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

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, it scores 100% on the small labeled fixture corpus (npm run eval, ~10 benign/malicious fixtures including the Damn Vulnerable MCP project) — a calibration check, not a broad real-world accuracy number; the field scans above are unlabeled and used only for robustness. Full log: benchmarks/field-run.md.

What that scan says about the ecosystem your agent trusts:

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