vsguard-mcp

An MCP server that audits installed VS Code extensions for supply-chain risk — deterministic static analysis, grounded by LLM reasoning, runnable from any MCP-capable agent.

The problem

VS Code extensions run arbitrary code on your machine with your privileges — your SSH keys, cloud tokens, signing keys, and browser cookies are all on the box that runs the editor.

In May 2026 that stopped being theoretical:

• Nx Console (2.2M installs, verified publisher) was backdoored in a point release. For an 18-minute window, version 18.95.0 harvested GitHub, npm, AWS, Vault, Kubernetes, and 1Password credentials — and specifically read ~/.claude/settings.json.
• GitHub itself was breached days later: an employee installed a poisoned VS Code extension, and roughly 3,800 internal repositories were exfiltrated. Public reporting confirms a poisoned extension as the vector but has not named the specific extension, so treat this as a related incident, not a confirmed repeat of the Nx Console attack.

Marketplace verification badges, install counts, and publisher reputation are no longer trust signals. They are attack signals. And nobody re-reviews 40 extensions every time they auto-update.

The solution

vsguard-mcp lets any AI agent — Claude Code, Claude Desktop, Cursor, Continue — audit the VS Code extensions installed on your machine. You ask, in plain language, "audit my installed extensions and flag anything risky"; the agent calls vsguard's tools and answers with a ranked, explained list.

It is built on three commitments:

1. Findings, not vibes. Every result points at concrete evidence — a file, a line, an API call. The LLM explains findings; it never invents them.
2. MCP-native. No browser extension, no separate app. Every agentic IDE gets the capability for free.
3. Offline by default, no telemetry ever. Core analysis needs zero network. The server never phones home. A security tool you cannot trust is worthless.

How it works

vsguard uses a tiered model — cheap deterministic checks gate expensive reasoning:

• Tier 1 — deterministic static analysis. Manifest, capability, and publisher scanners. Offline, explainable, fast. (Lands in M1.)
• Tier 2 — LLM reasoning. Turns Tier 1 findings into a plain-English risk narrative. Optional, bring-your-own-key.
• Tier 3 — sandbox detonation. (Future — M3.)

This release (M0) is the walking skeleton: a working MCP server that enumerates your installed extensions and exercises every MCP primitive. The deterministic scanners arrive in M1.

What M0 ships

MCP primitive	In vsguard
Tool	list_installed_extensions — enumerate the extension attack surface
Tool	explain_finding — plain-English explanation via LLM sampling
Resource	vsguard://threat-intel/may-2026 — the May 2026 incident IOCs
Resource template	vsguard://allowlist/{category} — legitimate-host allowlist
Prompt	audit_narrative — a reusable risk-narrative prompt template
Elicitation	the listing tool asks for a directory when none is found
Sampling	explain_finding asks the client's LLM to explain a finding

Quickstart

# 1. Clone and install (uv handles Python, the venv, and dependencies)
git clone https://github.com/timothywarner/vsguard-mcp.git
cd vsguard-mcp
uv sync

# 2. (Optional) bring your own key for LLM features
Copy-Item .env.example .env   # then paste your ANTHROPIC_API_KEY

# 3. Run it
uv run vsguard-mcp

Add it to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "vsguard": {
      "command": "uv",
      "args": ["run", "vsguard-mcp"],
      "cwd": "C:/path/to/vsguard-mcp"
    }
  }
}

Then ask your agent: "List my installed VS Code extensions."

To explore the server interactively, use the Anthropic MCP Inspector:

npx @modelcontextprotocol/inspector uv run vsguard-mcp

Configuration

vsguard is bring-your-own-key. LLM-backed features (the explain_finding sampling tool, and the Tier 2 narrative layer in M1) need an Anthropic API key:

1. Copy .env.example to .env in the repo root.
2. Paste your key into ANTHROPIC_API_KEY.

Without a key the server runs fine — LLM features simply report that they are unavailable. .env is gitignored; your key never leaves your machine.

Runtime dependencies

The runtime dependency list is small and deliberate — vsguard audits supply-chain risk, so it minimizes its own.

Dependency	Why
fastmcp	The MCP server framework: tools, resources, prompts, elicitation, sampling.
python-dotenv	Loads ANTHROPIC_API_KEY from a gitignored .env (bring-your-own-key).

That is the entire runtime footprint. A supply-chain security tool must not depend on an LLM SDK to do its core job, so anthropic is an optional extra (uv sync --extra llm-anthropic) used only by direct-provider LLM mode. MCP sampling needs no SDK — it is mediated by the client. Everything else (ZIP handling, hashing, SQLite) uses the Python standard library.

Roadmap

Milestone	Scope
M0 (this release)	MCP server, list_installed_extensions, all primitives.
M1	Tier 1 deterministic scanners, version diffing, the full tool surface, PyPI.
M2	Provenance checks, cross-marketplace consistency, audit history.
M3	Sandbox detonation, honeypot canary tokens, behavioral fingerprinting.

Documentation

• Architecture — design, primitive coverage, key decisions
• Development — setup, testing, debugging
• Security policy — reporting vulnerabilities
• Contributing — how to contribute

License

MIT — see LICENSE.

Built by Tim Warner.