@mayhemx87/mcpscan 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bob Kolosky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# mcpscan
+
+[![CI](https://github.com/mayhemx87/mcpscan/actions/workflows/ci.yml/badge.svg)](https://github.com/mayhemx87/mcpscan/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
+
+**Static scanner for MCP config files committed in repos — catch malicious
+configs before your AI editor auto-executes them.**
+
+When you open a repo in Claude Code, Cursor, VS Code, Windsurf, Amazon Q, Roo,
+Kiro, or Gemini CLI, MCP config files in that repo can declare servers that the
+editor launches automatically — as *your* user, inheriting *your* environment and
+credentials (see CVE-2026-12957). A cloned repo is arbitrary-code-execution
+waiting for an editor to open it.
+
+`mcpscan` scans a checkout **statically** — no network calls, no subprocess
+execution of anything in the scanned repo — and flags:
+
+- commands that fetch and execute remote code (`curl … | sh`)
+- unpinned `npx`/`uvx`/`pipx` packages (supply-chain risk)
+- credential env inheritance (`AWS_*`, `GITHUB_TOKEN`, …) and **hardcoded secrets**
+- remote (`url`-based) MCP endpoints, escalating over insecure `http://`
+- shell metacharacter chaining, paths escaping the repo, untracked config files
+
+## How it differs from other MCP security tools
+
+Most MCP scanners ([mcp-scan](https://github.com/invariantlabs-ai/mcp-scan),
+[MCP-Shield](https://github.com/riseandignite/mcp-shield),
+[Snyk agent-scan](https://github.com/snyk/agent-scan)) analyze the MCP servers
+**you have installed** — connecting to them at runtime to detect tool poisoning
+and prompt injection. That protects you from servers you chose to run.
+
+`mcpscan` covers the step *before* that: the repo you just cloned, in CI, or at
+`git commit` time. It never starts a server, never needs an API key, and is safe
+to point at hostile checkouts. Use both — they solve different halves of the
+problem.
+
+## Install
+
+```sh
+npm install -g @mayhemx87/mcpscan
+
+# or straight from the repo
+npm install -g github:mayhemx87/mcpscan
+```
+
+Either way the installed command is `mcpscan`. (The npm package is scoped
+because the registry reserves the bare name as too similar to `mcp-scan` —
+a different, runtime-focused tool.)
+
+## Usage
+
+```sh
+mcpscan .                     # scan current directory
+mcpscan path/to/checkout      # scan any checkout
+mcpscan . --json              # machine-readable findings
+mcpscan . --sarif             # SARIF 2.1.0 for GitHub code scanning
+mcpscan . --fail-on critical  # only exit non-zero on critical
+mcpscan . --quiet             # exit code only
+mcpscan install-hook          # install the git pre-commit hook
+mcpscan rules                 # list detection rules
+```
+
+### GitHub Actions
+
+```yaml
+jobs:
+  mcpscan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # only needed for SARIF upload
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mayhemx87/mcpscan@main
+        with:
+          fail-on: high
+          sarif-file: mcpscan.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: mcpscan.sarif
+```
+
+Findings then appear in the repo's **Security → Code scanning** tab, annotated on
+the exact line of the offending server definition.
+
+### pre-commit framework
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/mayhemx87/mcpscan
+    rev: v0.3.1
+    hooks:
+      - id: mcpscan
+```
+
+### Plain git hook
+
+`mcpscan install-hook` installs a POSIX pre-commit hook (respects
+`core.hooksPath`; appends safely to an existing hook; idempotent). Bypass a
+single commit with `MCPSCAN_SKIP=1 git commit`.
+
+## What gets scanned
+
+Dedicated MCP config files and editor settings files that embed MCP servers:
+
+| Path | Client |
+|---|---|
+| `.mcp.json`, `mcp.json` | Claude Code and others |
+| `.cursor/mcp.json` | Cursor |
+| `.vscode/mcp.json`, `.vscode/settings.json` (`mcp.servers`) | VS Code |
+| `.windsurf/mcp.json` | Windsurf |
+| `.amazonq/mcp.json` | Amazon Q |
+| `.roo/mcp.json` | Roo Code |
+| `.kiro/settings/mcp.json` | Kiro |
+| `.claude/settings.json`, `.claude/settings.local.json` | Claude Code |
+| `.gemini/settings.json` | Gemini CLI |
+
+Both `mcpServers` and VS Code's `servers` keys are understood; `command` and
+`args` are analyzed together; remote (`url`-based) servers are covered. Nested
+occurrences of these paths are scanned too (any subdirectory can be opened as a
+workspace root). Only `.git/` and `node_modules/` are skipped; `.gitignore` is
+deliberately ignored — an injected config would be exactly the file that's
+untracked. Symlinked directories are never followed.
+
+Your editor auto-loads a config path we don't scan?
+[Open a "new client" issue](../../issues/new?template=new-client.md) — it's a
+one-line fix and the best first contribution.
+
+## Detection rules
+
+| Rule | Severity | Description |
+|---|---|---|
+| MCP-001 | CRITICAL | Server command executes a remote URL or network tool (curl, wget, https://) |
+| MCP-002 | HIGH | Server uses npx/uvx/pipx with an unversioned package (supply-chain risk) |
+| MCP-003 | HIGH | Server env block inherits high-value credential env vars (AWS_*, GITHUB_TOKEN, etc.) |
+| MCP-004 | MEDIUM | Server command references a path outside the repository (absolute or ../) |
+| MCP-005 | MEDIUM | MCP config file is not tracked by git (may have been injected) |
+| MCP-006 | INFO | Server passed all detection rules (inventory signal) |
+| MCP-007 | CRITICAL | Hardcoded secret-looking value in env or headers (`${VAR}` interpolations exempt) |
+| MCP-008 | INFO/HIGH | Remote MCP server (`url`-based) declared — inventory; HIGH over insecure http:// |
+| MCP-009 | MEDIUM | Shell command-chaining metacharacters in command/args (`$()`, backticks, `\| sh`) |
+| MCP-PARSE | HIGH | Config file has invalid JSON — cannot verify safety |
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--json` | off | Output findings as a JSON array |
+| `--sarif` | off | Output SARIF 2.1.0 (GitHub code scanning) |
+| `--quiet` | off | Suppress all output (exit code only) |
+| `--severity <level>` | info | Minimum severity to report |
+| `--fail-on <level>` | high | Exit non-zero if any finding at or above this severity |
+| `--max-depth <n>` | unlimited | Limit directory traversal depth |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | No findings at or above `--fail-on` threshold |
+| 1 | One or more findings at or above `--fail-on` threshold |
+| 2 | Scan error (invalid argument, cannot determine git root, etc.) |
+
+## Limitations
+
+Static and heuristic by design: a clean scan lowers risk, it does not certify a
+repo as safe, and it says nothing about what a declared server *does* at
+runtime. Bypass reports are treated as vulnerabilities — see
+[SECURITY.md](SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Adding a client config path is a
+one-line change with a test; new detection rules and false-positive reports are
+equally welcome.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { resolve, relative, dirname, join } from 'path';
+import { discoverConfigs } from './discovery.js';
+import { analyzeConfig, RULES, SEVERITY_RANK } from './engine.js';
+import { toSarif } from './sarif.js';
+// Single source of truth for the version: this package's package.json. The
+// location differs between the built layout (dist/cli.js, one level down) and
+// running the TypeScript source directly under tsx (cli.ts, package root).
+// The name check prevents picking up an unrelated parent package.json.
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+function loadVersion() {
+    for (const p of [join(moduleDir, 'package.json'), join(moduleDir, '..', 'package.json')]) {
+        try {
+            const pkg = JSON.parse(readFileSync(p, 'utf-8'));
+            if ((pkg.name === '@mayhemx87/mcpscan' || pkg.name === 'mcpscan') && pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return '0.0.0';
+}
+const VERSION = loadVersion();
+const SEVERITY_LABEL = {
+    critical: '[CRITICAL]',
+    high: '[HIGH]    ',
+    medium: '[MEDIUM]  ',
+    info: '[INFO]    ',
+};
+function isFileGitTracked(filePath) {
+    try {
+        // cwd MUST be the file's own directory: without it the check runs
+        // against whatever repo the shell happens to be in, corrupting MCP-005
+        // both directions when scanning a repo from outside it (v0.1.0 bug).
+        // execFileSync (no shell): the path is untrusted input from the scanned
+        // repo -- interpolating it into a shell string would let a crafted
+        // filename execute commands.
+        execFileSync('git', ['ls-files', '--error-unmatch', '--', filePath], {
+            stdio: 'ignore',
+            cwd: dirname(filePath),
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isInGitRepo(dir) {
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore', cwd: dir });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseSeverity(s) {
+    if (['critical', 'high', 'medium', 'info'].includes(s))
+        return s;
+    throw new Error(`Invalid severity: ${s}`);
+}
+function scanDirectory(scanRoot, opts) {
+    const absRoot = resolve(scanRoot);
+    const configFiles = discoverConfigs(absRoot, opts.maxDepth);
+    const inGit = isInGitRepo(absRoot);
+    const allFindings = [];
+    for (const configPath of configFiles) {
+        let content;
+        try {
+            content = readFileSync(configPath, 'utf-8');
+        }
+        catch {
+            if (!opts.quiet) {
+                console.log(`  ${configPath}\n  [HIGH]     MCP-SCAN: cannot read file (permission denied)\n`);
+            }
+            allFindings.push({
+                file: relative(absRoot, configPath),
+                rule_id: 'MCP-SCAN',
+                severity: 'high',
+                server_name: '(file)',
+                message: 'Cannot read MCP config file (permission denied).',
+                remediation: 'Check file permissions.',
+            });
+            continue;
+        }
+        const tracked = inGit ? isFileGitTracked(configPath) : true;
+        const findings = analyzeConfig(relative(absRoot, configPath), content, tracked);
+        allFindings.push(...findings);
+    }
+    // Filter by --severity threshold
+    const filtered = allFindings.filter(f => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[opts.severity]);
+    if (opts.sarif) {
+        process.stdout.write(JSON.stringify(toSarif(filtered, VERSION), null, 2) + '\n');
+        return filtered.some(f => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[opts.failOn]) ? 1 : 0;
+    }
+    if (opts.json) {
+        if (!opts.quiet)
+            process.stdout.write(JSON.stringify(filtered, null, 2) + '\n');
+        return filtered.some(f => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[opts.failOn]) ? 1 : 0;
+    }
+    if (!opts.quiet) {
+        if (!opts.json) {
+            console.log(`mcpscan ${VERSION} -- scanning ${absRoot}\n`);
+        }
+        // Group by file
+        const byFile = new Map();
+        for (const f of filtered) {
+            if (!byFile.has(f.file))
+                byFile.set(f.file, []);
+            byFile.get(f.file).push(f);
+        }
+        for (const [file, findings] of byFile) {
+            console.log(`  ${file}`);
+            for (const f of findings) {
+                console.log(`  ${SEVERITY_LABEL[f.severity]} ${f.rule_id}: ${f.message}`);
+                if (f.rule_id !== 'MCP-006') {
+                    console.log(`             Remediation: ${f.remediation}`);
+                }
+            }
+            console.log('');
+        }
+        const critical = filtered.filter(f => f.severity === 'critical').length;
+        const high = filtered.filter(f => f.severity === 'high').length;
+        const medium = filtered.filter(f => f.severity === 'medium').length;
+        const info = filtered.filter(f => f.severity === 'info').length;
+        if (filtered.length === 0) {
+            console.log(`0 findings -- no MCP config files detected or all passed.`);
+        }
+        else {
+            console.log(`${filtered.length} findings (${critical} critical, ${high} high, ${medium} medium, ${info} info)`);
+            if (!opts.json) {
+                console.log('Run with --json for machine-readable output.');
+            }
+        }
+    }
+    return filtered.some(f => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[opts.failOn]) ? 1 : 0;
+}
+const HOOK_TEMPLATE = `#!/bin/sh
+# MCPScan pre-commit hook -- do not edit manually
+# To bypass: MCPSCAN_SKIP=1 git commit
+# mcpscan exit codes: 0 = clean, 1 = findings at/above --fail-on, 2 = scan error
+
+if [ "\${MCPSCAN_SKIP}" = "1" ]; then
+  printf 'mcpscan: skipping MCP config scan (MCPSCAN_SKIP=1)\\n' >&2
+  exit 0
+fi
+
+if command -v mcpscan >/dev/null 2>&1; then
+  mcpscan . --fail-on high --quiet
+  MCPSCAN_EXIT=$?
+else
+  npx --yes @mayhemx87/mcpscan@latest . --fail-on high --quiet
+  MCPSCAN_EXIT=$?
+fi
+
+if [ $MCPSCAN_EXIT -eq 1 ]; then
+  printf '\\nmcpscan: commit blocked -- high or critical MCP config findings detected.\\n' >&2
+  printf "Run 'mcpscan .' for details, or set MCPSCAN_SKIP=1 to bypass.\\n" >&2
+elif [ $MCPSCAN_EXIT -ne 0 ]; then
+  printf '\\nmcpscan: commit blocked -- the scan failed to run (exit %s, NOT a security finding).\\n' "\$MCPSCAN_EXIT" >&2
+  printf "Run 'mcpscan .' for the error, or bypass once with MCPSCAN_SKIP=1 git commit.\\n" >&2
+fi
+
+exit $MCPSCAN_EXIT
+`;
+const HOOK_MARKER = '# MCPScan pre-commit hook';
+function installHook(targetDir) {
+    const absDir = resolve(targetDir);
+    if (!isInGitRepo(absDir)) {
+        console.error(`mcpscan: no git repository found at ${absDir}`);
+        process.exit(2);
+    }
+    // --git-path respects core.hooksPath, worktrees, and submodules -- a
+    // hardcoded .git/hooks path silently installs a hook git never runs.
+    let hooksDir;
+    try {
+        const raw = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+            cwd: absDir,
+            encoding: 'utf-8',
+        }).trim();
+        hooksDir = resolve(absDir, raw);
+    }
+    catch {
+        console.error('mcpscan: could not determine git hooks directory');
+        process.exit(2);
+    }
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, 'pre-commit');
+    if (existsSync(hookPath)) {
+        const existing = readFileSync(hookPath, 'utf-8');
+        if (existing.includes(HOOK_MARKER)) {
+            console.log('mcpscan: pre-commit hook already installed (idempotent -- no changes).');
+            return;
+        }
+        // Append to existing hook
+        console.warn(`mcpscan: existing pre-commit hook found at ${hookPath} -- appending mcpscan hook.`);
+        writeFileSync(hookPath, existing.trimEnd() + '\n\n' + HOOK_TEMPLATE, 'utf-8');
+    }
+    else {
+        writeFileSync(hookPath, HOOK_TEMPLATE, 'utf-8');
+    }
+    chmodSync(hookPath, 0o755);
+    console.log(`mcpscan: pre-commit hook installed at ${hookPath}`);
+    console.log('Commits will be blocked if high or critical MCP config findings are detected.');
+    console.log('Override: MCPSCAN_SKIP=1 git commit');
+}
+// ---- CLI definition ----
+const program = new Command();
+program
+    .name('mcpscan')
+    .description('Static scanner for malicious MCP config files in AI-integrated editor repos')
+    .version(VERSION, '-v, --version')
+    .argument('[path]', 'directory to scan', '.')
+    .option('--json', 'output findings as JSON array')
+    .option('--sarif', 'output findings as SARIF 2.1.0 (for GitHub code scanning)')
+    .option('--quiet', 'suppress all output (exit code only)')
+    .option('--max-depth <n>', 'limit directory traversal depth', parseInt)
+    .option('--severity <level>', 'minimum severity to report (critical|high|medium|info)', 'info')
+    .option('--fail-on <level>', 'exit non-zero if any finding at or above this severity (critical|high|medium)', 'high')
+    .action((scanPath, opts) => {
+    try {
+        const severity = parseSeverity(opts.severity);
+        const failOn = parseSeverity(opts.failOn);
+        if (opts.json && opts.sarif) {
+            throw new Error('--json and --sarif are mutually exclusive');
+        }
+        const maxDepth = opts.maxDepth;
+        if (maxDepth !== undefined && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+            throw new Error('--max-depth must be a non-negative integer');
+        }
+        const exitCode = scanDirectory(scanPath, {
+            json: Boolean(opts.json),
+            sarif: Boolean(opts.sarif),
+            quiet: Boolean(opts.quiet),
+            severity,
+            failOn,
+            maxDepth,
+        });
+        process.exit(exitCode);
+    }
+    catch (err) {
+        console.error(`mcpscan: error -- ${err.message}`);
+        process.exit(2);
+    }
+});
+program
+    .command('install-hook [path]')
+    .description('install mcpscan as a pre-commit hook in the git repository')
+    .action((hookPath = '.') => {
+    installHook(hookPath);
+});
+program
+    .command('rules')
+    .description('list all detection rules')
+    .action(() => {
+    console.log('MCPScan detection rules:\n');
+    for (const rule of RULES) {
+        console.log(`  ${rule.id}  [${rule.severity.toUpperCase()}]`);
+        console.log(`       ${rule.description}\n`);
+    }
+    process.exit(0);
+});
+program
+    .command('version')
+    .description('print version')
+    .action(() => {
+    console.log(`mcpscan ${VERSION}`);
+    process.exit(0);
+});
+program.parse();

package/dist/discovery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recursively discovers MCP config files under rootDir.
+ * Does not consult .gitignore -- security tools must scan all files.
+ * Skips node_modules and .git for performance.
+ */
+export declare function discoverConfigs(rootDir: string, maxDepth?: number): string[];

package/dist/discovery.js

@@ -0,0 +1,77 @@
+import { readdirSync, lstatSync } from 'fs';
+import { join, relative, resolve } from 'path';
+// Only .git (never auto-loaded) and node_modules (never auto-loaded, huge) are
+// skipped. Everything else is scanned -- a security tool must not assume a
+// directory name like "dist" or "__tests__" makes a config harmless, because
+// any subdirectory can be opened as a workspace root.
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+/**
+ * Returns true if the relative path from scan root matches a known
+ * auto-loading MCP config file pattern.
+ */
+const MCP_CONFIG_SUFFIXES = [
+    '.mcp.json',
+    'mcp.json',
+    '.amazonq/mcp.json',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+    '.windsurf/mcp.json',
+    '.roo/mcp.json',
+    '.kiro/settings/mcp.json',
+    // Embedded hosts (v0.2.0): MCP servers under a nested key; the engine
+    // ignores these files entirely when they carry no MCP section.
+    '.vscode/settings.json',
+    '.claude/settings.json',
+    '.claude/settings.local.json',
+    '.gemini/settings.json',
+];
+function isMcpConfigPath(relPath) {
+    const p = relPath.replace(/\\/g, '/');
+    return MCP_CONFIG_SUFFIXES.some(s => p === s || p.endsWith('/' + s));
+}
+/**
+ * Recursively discovers MCP config files under rootDir.
+ * Does not consult .gitignore -- security tools must scan all files.
+ * Skips node_modules and .git for performance.
+ */
+export function discoverConfigs(rootDir, maxDepth) {
+    const absRoot = resolve(rootDir);
+    const found = [];
+    walkDir(absRoot, absRoot, found, 0, maxDepth);
+    return found;
+}
+function walkDir(absRoot, currentDir, found, depth, maxDepth) {
+    if (maxDepth !== undefined && depth > maxDepth)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(currentDir);
+    }
+    catch {
+        return; // permission denied or other OS error -- skip silently
+    }
+    for (const entry of entries) {
+        const fullPath = join(currentDir, entry);
+        // lstat, not stat: symlinked directories are never followed. This keeps
+        // traversal inside the scan root and immune to symlink loops -- a
+        // malicious repo must not be able to point the scanner at / or at itself.
+        let isDir = false;
+        try {
+            isDir = lstatSync(fullPath).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            walkDir(absRoot, fullPath, found, depth + 1, maxDepth);
+        }
+        else {
+            const relPath = relative(absRoot, fullPath);
+            if (isMcpConfigPath(relPath)) {
+                found.push(fullPath);
+            }
+        }
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,28 @@
+export type Severity = 'critical' | 'high' | 'medium' | 'info';
+export declare const SEVERITY_RANK: Record<Severity, number>;
+export interface RuleMeta {
+    id: string;
+    severity: Severity;
+    description: string;
+}
+export declare const RULES: RuleMeta[];
+export interface Finding {
+    file: string;
+    rule_id: string;
+    severity: Severity;
+    server_name: string;
+    message: string;
+    remediation: string;
+    /** 1-based line of the server's definition in the config file, when resolvable. */
+    line?: number;
+}
+/** Embedded-host files (editor/agent settings.json) carry MCP servers under a
+ * nested key; a settings file with NO MCP section is out of scope entirely --
+ * no findings, not even MCP-005, or every untracked settings.json in the wild
+ * would produce noise. */
+export declare function isEmbeddedHostFile(filePath: string): boolean;
+/**
+ * Statically analyzes the content of an MCP config file and returns findings.
+ * Pure function -- no filesystem access, no subprocesses, no network calls.
+ */
+export declare function analyzeConfig(filePath: string, content: string, isGitTracked: boolean): Finding[];

package/dist/engine.js

@@ -0,0 +1,289 @@
+import { parse as parseJsonc, parseTree, findNodeAtLocation, } from 'jsonc-parser';
+export const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    info: 1,
+};
+export const RULES = [
+    { id: 'MCP-001', severity: 'critical', description: 'Server command or args execute a remote URL or network tool (curl, wget, https://)' },
+    { id: 'MCP-002', severity: 'high', description: 'Server uses npx/uvx/pipx with an unversioned package, in command or args (supply-chain risk)' },
+    { id: 'MCP-003', severity: 'high', description: 'Server env block inherits high-value credential env vars (AWS_*, GITHUB_TOKEN, etc.)' },
+    { id: 'MCP-004', severity: 'medium', description: 'Server command or args reference a path outside the repository (absolute or ../)' },
+    { id: 'MCP-005', severity: 'medium', description: 'MCP config file is not tracked by git (may have been injected)' },
+    { id: 'MCP-006', severity: 'info', description: 'Server passed all detection rules (inventory signal)' },
+    { id: 'MCP-007', severity: 'critical', description: 'Hardcoded secret-looking value in env or headers (committed credential; ${VAR} interpolations exempt)' },
+    { id: 'MCP-008', severity: 'info', description: 'Remote MCP server (url-based) declared -- inventory; escalates to HIGH over insecure http://' },
+    { id: 'MCP-009', severity: 'medium', description: 'Shell command-chaining metacharacters in command/args ($(), backticks, | sh)' },
+    { id: 'MCP-PARSE', severity: 'high', description: 'MCP config file has invalid JSON syntax -- cannot verify safety' },
+    { id: 'MCP-SCAN', severity: 'high', description: 'MCP config file could not be read (permission denied)' },
+];
+const CREDENTIAL_PATTERNS = [
+    /^AWS_/,
+    /^GITHUB_TOKEN$/,
+    /^ANTHROPIC_API_KEY$/,
+    /^OPENAI_API_KEY$/,
+    /^AZURE_/,
+    /^GCP_/,
+    /^GOOGLE_APPLICATION_CREDENTIALS$/,
+    /SECRET/i,
+    /PRIVATE_KEY/i,
+];
+/** Literal secret-looking VALUES (v0.2.0, MCP-007). A hardcoded credential in
+ * a committed config is worse than env inheritance. `${...}`/`$VAR`
+ * interpolations are exempt -- they resolve at runtime, nothing is committed. */
+const SECRET_VALUE_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/, // AWS access key id
+    /sk-ant-[A-Za-z0-9_-]{8,}/, // Anthropic
+    /sk-[A-Za-z0-9]{20,}/, // OpenAI-style
+    /ghp_[A-Za-z0-9]{36}/, // GitHub PAT (classic)
+    /github_pat_[A-Za-z0-9_]{20,}/, // GitHub PAT (fine-grained)
+    /xox[abps]-[A-Za-z0-9-]{10,}/, // Slack
+    /AIza[0-9A-Za-z_-]{35}/, // Google API key
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+];
+function isHighValueCredential(key) {
+    return CREDENTIAL_PATTERNS.some(p => p.test(key));
+}
+function isInterpolation(value) {
+    return value.includes('${') || value.trim().startsWith('$');
+}
+function looksLikeLiteralSecret(value) {
+    if (isInterpolation(value))
+        return false;
+    return SECRET_VALUE_PATTERNS.some(p => p.test(value));
+}
+/**
+ * Returns true if the command line contains npx/uvx/pipx with an unversioned
+ * package (handles compound commands like cmd1 && npx pkg). Runner flags
+ * (-y, --yes, -q, --package=...) are skipped to find the real package token.
+ * A version pin looks like @1.2.3 after the package name; scoped packages
+ * (@scope/name) need a second @.
+ */
+function isUnversionedPackageRunner(line) {
+    const matches = [...line.matchAll(/\b(npx|uvx|pipx)\s+((?:[-@\w./=:]+\s+)*?)([@\w][\w./@-]*)/g)];
+    for (const match of matches) {
+        // Walk tokens after the runner, skipping flags, to the package token.
+        const tokens = (match[2] + match[3]).trim().split(/\s+/).filter(Boolean);
+        const pkg = tokens.find(t => !t.startsWith('-'));
+        if (!pkg)
+            continue;
+        if (pkg.startsWith('@')) {
+            if (!pkg.slice(1).includes('@'))
+                return true; // @scope/pkg without @version
+        }
+        else if (!pkg.includes('@')) {
+            return true; // pkg without @version
+        }
+    }
+    return false;
+}
+/** Embedded-host files (editor/agent settings.json) carry MCP servers under a
+ * nested key; a settings file with NO MCP section is out of scope entirely --
+ * no findings, not even MCP-005, or every untracked settings.json in the wild
+ * would produce noise. */
+export function isEmbeddedHostFile(filePath) {
+    const p = filePath.replace(/\\/g, '/');
+    return p.endsWith('settings.json') || p.endsWith('settings.local.json');
+}
+/** Extract the server map from any known config shape:
+ * - dedicated files: { mcpServers: {...} } or VS Code's { servers: {...} }
+ * - embedded hosts:  { mcpServers: {...} } (Claude/Gemini settings) or
+ *                    { mcp: { servers: {...} } } (VS Code settings.json)
+ * Also returns the JSON path to the map so findings can carry line numbers. */
+function extractServers(config) {
+    if (config.mcpServers && typeof config.mcpServers === 'object') {
+        return { servers: config.mcpServers, path: ['mcpServers'] };
+    }
+    if (config.servers && typeof config.servers === 'object') {
+        return { servers: config.servers, path: ['servers'] };
+    }
+    const mcp = config.mcp;
+    if (mcp && typeof mcp === 'object' && mcp.servers && typeof mcp.servers === 'object') {
+        return { servers: mcp.servers, path: ['mcp', 'servers'] };
+    }
+    return null;
+}
+/**
+ * Statically analyzes the content of an MCP config file and returns findings.
+ * Pure function -- no filesystem access, no subprocesses, no network calls.
+ */
+export function analyzeConfig(filePath, content, isGitTracked) {
+    const findings = [];
+    const embedded = isEmbeddedHostFile(filePath);
+    const errors = [];
+    let config;
+    try {
+        config = parseJsonc(content, errors);
+    }
+    catch {
+        return embedded ? [] : [parseErrorFinding(filePath)];
+    }
+    if (errors.length > 0 || config === null || typeof config !== 'object' || Array.isArray(config)) {
+        return embedded ? [] : [parseErrorFinding(filePath)];
+    }
+    const extracted = extractServers(config);
+    const servers = extracted?.servers ?? null;
+    // Embedded settings files without an MCP section are out of scope.
+    if (embedded && servers === null)
+        return [];
+    // Best-effort parse tree so findings can carry the line each server is
+    // defined on (SARIF regions, clickable output). Analysis never depends on it.
+    let tree;
+    try {
+        tree = parseTree(content);
+    }
+    catch {
+        tree = undefined;
+    }
+    const lineOf = (serverName) => {
+        if (!tree || !extracted)
+            return undefined;
+        const node = findNodeAtLocation(tree, [...extracted.path, serverName]);
+        if (!node)
+            return undefined;
+        return content.slice(0, node.offset).split('\n').length;
+    };
+    // MCP-005: file not tracked by git (may have been injected)
+    if (!isGitTracked) {
+        findings.push({
+            file: filePath,
+            rule_id: 'MCP-005',
+            severity: 'medium',
+            server_name: '(file)',
+            message: 'MCP config file is not tracked by git -- may have been injected.',
+            remediation: 'Run `git add` to track intentionally, or delete if not placed by your team.',
+        });
+    }
+    for (const [serverName, server] of Object.entries(servers ?? {})) {
+        if (!server || typeof server !== 'object')
+            continue;
+        // Analyze command AND args as one line -- the dominant real-world shape
+        // is {"command": "npx", "args": ["-y", "pkg"]}, invisible to any rule
+        // that inspects `command` alone (the v0.1.0 gap).
+        const args = Array.isArray(server.args) ? server.args.filter(a => typeof a === 'string') : [];
+        const line = [server.command ?? '', ...args].join(' ').trim();
+        const serverFindings = [];
+        // MCP-001: remote URL or network command execution
+        if (line && (/https?:\/\//.test(line) || /\b(curl|wget)\b/.test(line))) {
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-001',
+                severity: 'critical',
+                server_name: serverName,
+                message: `Server "${serverName}" executes a remote URL or network command: ${line}`,
+                remediation: 'Replace with a locally-installed binary or a pinned, audited npm package.',
+            });
+        }
+        // MCP-002: unversioned package runner (supply-chain risk)
+        if (line && isUnversionedPackageRunner(line)) {
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-002',
+                severity: 'high',
+                server_name: serverName,
+                message: `Server "${serverName}" runs an unversioned package: ${line}`,
+                remediation: 'Pin to a specific version (e.g., npx package@1.2.3) and audit the package.',
+            });
+        }
+        // MCP-003: high-value credential env inheritance (key names)
+        const env = server.env ?? {};
+        for (const key of Object.keys(env)) {
+            if (isHighValueCredential(key)) {
+                serverFindings.push({
+                    file: filePath,
+                    rule_id: 'MCP-003',
+                    severity: 'high',
+                    server_name: serverName,
+                    message: `Server "${serverName}" inherits high-value credential env var: ${key}`,
+                    remediation: 'Review whether this server requires live credentials and scope to least-privilege.',
+                });
+                break; // one MCP-003 finding per server
+            }
+        }
+        // MCP-004: absolute path or path traversal outside repo
+        const cmd = server.command ?? '';
+        if (cmd.startsWith('/') ||
+            args.some(a => a.startsWith('/')) ||
+            /(?:^|[\s;|&])\.\.\//.test(line)) {
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-004',
+                severity: 'medium',
+                server_name: serverName,
+                message: `Server "${serverName}" references a path outside the repository: ${line}`,
+                remediation: 'Use a relative path within the repo or a globally-installed binary on PATH.',
+            });
+        }
+        // MCP-007: hardcoded secret-looking value in env or headers
+        for (const [source, record] of [['env', env], ['headers', server.headers ?? {}]]) {
+            for (const [key, value] of Object.entries(record)) {
+                if (typeof value === 'string' && looksLikeLiteralSecret(value)) {
+                    serverFindings.push({
+                        file: filePath,
+                        rule_id: 'MCP-007',
+                        severity: 'critical',
+                        server_name: serverName,
+                        message: `Server "${serverName}" has a hardcoded secret-looking value in ${source}.${key} -- a committed credential.`,
+                        remediation: 'Remove the literal secret, rotate it immediately, and use an env interpolation (${VAR}) instead.',
+                    });
+                }
+            }
+        }
+        // MCP-008: remote MCP server (url-based) -- invisible in v0.1.0
+        if (typeof server.url === 'string' && server.url.length > 0) {
+            const insecure = server.url.startsWith('http://');
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-008',
+                severity: insecure ? 'high' : 'info',
+                server_name: serverName,
+                message: insecure
+                    ? `Server "${serverName}" connects to a remote MCP endpoint over insecure HTTP: ${server.url}`
+                    : `Server "${serverName}" is a remote MCP endpoint: ${server.url} -- verify the endpoint is trusted.`,
+                remediation: insecure
+                    ? 'Use HTTPS for remote MCP endpoints.'
+                    : 'Confirm this endpoint is operated by a party you trust; remote servers receive your prompts and tool traffic.',
+            });
+        }
+        // MCP-009: shell metacharacters (execution chaining without literal curl/URL)
+        if (line && (/\$\(/.test(line) || /`/.test(line) || /\|\s*(sh|bash|zsh)\b/.test(line))) {
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-009',
+                severity: 'medium',
+                server_name: serverName,
+                message: `Server "${serverName}" uses shell command-chaining metacharacters: ${line}`,
+                remediation: 'Avoid command substitution and pipes in MCP server commands; invoke a single audited binary directly.',
+            });
+        }
+        // MCP-006: clean server -- no other findings for this server
+        if (serverFindings.length === 0) {
+            serverFindings.push({
+                file: filePath,
+                rule_id: 'MCP-006',
+                severity: 'info',
+                server_name: serverName,
+                message: `Server "${serverName}" passed all detection rules.`,
+                remediation: 'No action required.',
+            });
+        }
+        const lineNo = lineOf(serverName);
+        if (lineNo !== undefined) {
+            for (const f of serverFindings)
+                f.line = lineNo;
+        }
+        findings.push(...serverFindings);
+    }
+    return findings;
+}
+function parseErrorFinding(filePath) {
+    return {
+        file: filePath,
+        rule_id: 'MCP-PARSE',
+        severity: 'high',
+        server_name: '(unknown)',
+        message: 'MCP config file has invalid JSON syntax -- cannot verify safety.',
+        remediation: 'Fix the JSON syntax or remove the file if it is not a valid MCP config.',
+    };
+}

package/dist/sarif.d.ts

@@ -0,0 +1,2 @@
+import { type Finding } from './engine.js';
+export declare function toSarif(findings: Finding[], version: string): object;

package/dist/sarif.js

@@ -0,0 +1,60 @@
+import { RULES } from './engine.js';
+/** SARIF 2.1.0 output for GitHub code scanning and other SARIF consumers. */
+const LEVEL = {
+    critical: 'error',
+    high: 'error',
+    medium: 'warning',
+    info: 'note',
+};
+// GitHub code scanning buckets: 9.0+ critical, 7.0-8.9 high, 4.0-6.9 medium.
+const SECURITY_SEVERITY = {
+    critical: '9.5',
+    high: '8.0',
+    medium: '5.0',
+    info: '0.0',
+};
+export function toSarif(findings, version) {
+    const ruleIndex = new Map(RULES.map((r, i) => [r.id, i]));
+    return {
+        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'mcpscan',
+                        version,
+                        informationUri: 'https://github.com/mayhemx87/mcpscan',
+                        rules: RULES.map(r => ({
+                            id: r.id,
+                            shortDescription: { text: r.description },
+                            helpUri: 'https://github.com/mayhemx87/mcpscan#detection-rules',
+                            defaultConfiguration: { level: LEVEL[r.severity] },
+                            properties: {
+                                'security-severity': SECURITY_SEVERITY[r.severity],
+                                tags: ['security', 'supply-chain', 'mcp'],
+                            },
+                        })),
+                    },
+                },
+                results: findings.map(f => ({
+                    ruleId: f.rule_id,
+                    ...(ruleIndex.has(f.rule_id) ? { ruleIndex: ruleIndex.get(f.rule_id) } : {}),
+                    level: LEVEL[f.severity],
+                    message: { text: `${f.message} Remediation: ${f.remediation}` },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: {
+                                    uri: f.file.replace(/\\/g, '/'),
+                                    uriBaseId: '%SRCROOT%',
+                                },
+                                region: { startLine: f.line ?? 1 },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    };
+}

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        include: ['__tests__/**/*.test.ts'],
+        environment: 'node',
+        testTimeout: 15000,
+    },
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mayhemx87/mcpscan",
+  "version": "0.3.1",
+  "description": "Static scanner for malicious MCP config files in AI-integrated editor repos",
+  "type": "module",
+  "bin": {
+    "mcpscan": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mayhemx87/mcpscan.git"
+  },
+  "homepage": "https://github.com/mayhemx87/mcpscan#readme",
+  "bugs": {
+    "url": "https://github.com/mayhemx87/mcpscan/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "prepublishOnly": "npm test && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "security",
+    "scanner",
+    "static-analysis",
+    "supply-chain",
+    "sarif",
+    "ai",
+    "claude",
+    "cursor",
+    "vscode"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "overrides": {
+    "nanoid": "3.3.18"
+  }
+}