mcp-security-lab 0.2.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 MCP Security Lab contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,175 @@
+# MCP Security Lab
+
+[![CI](https://github.com/warlyjr-cloud/mcp-security-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/warlyjr-cloud/mcp-security-lab/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/mcp-security-lab.svg)](https://badge.fury.io/js/mcp-security-lab)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Evidence-first security checks for local and remote Model Context Protocol (MCP) servers.
+
+> **MCP Security Lab is a DevSecOps DevTool that automatically audits Model Context Protocol (MCP) servers for prompt injections, context window exhaustion, and unsafe tool schemas without requiring an LLM or API keys. It runs natively in CI/CD pipelines (SARIF 2.1.0) and supports Docker Sandboxing for safe active probing.**
+
+The MVP audits how a local or remote MCP server is launched and what it advertises during the MCP
+handshake. It detects risky launcher patterns (including inline code execution and encoded payloads),
+missing tool annotations, mixed read/write interfaces, least-privilege violations, overly broad
+schemas, context exhaustion risks, and prompt-injection-like text. Prompt-injection scanning covers
+the full surface a server injects into the model's context — tool descriptions, annotation titles,
+parameter names, enum values, server instructions, and every advertised **prompt** and **resource** —
+and is resilient to Unicode evasion (homoglyphs, zero-width and bidirectional characters).
+
+Every finding is mapped to a **CWE** and, where relevant, to the **OWASP Top 10 for LLM Applications**,
+and this taxonomy is emitted in the SARIF output. By default the scanner does not call discovered
+tools and requires no LLM or API key. Reports can be emitted as text, JSON, or SARIF 2.1.0. The full
+rule catalog is documented in [docs/RULES.md](docs/RULES.md); the trust boundaries are described in
+[THREAT_MODEL.md](THREAT_MODEL.md).
+
+## Why this exists
+
+Installing a local MCP server executes code with the user's privileges. Protocol compliance
+alone does not show whether a server asks for excessive access or advertises unsafe tools.
+MCP Security Lab produces a small, reviewable report before deeper testing.
+
+## Quick start
+
+```powershell
+npm.cmd install
+npm.cmd run build
+node dist/src/cli.js scan --config examples/insecure-server.json
+node dist/src/cli.js scan --config examples/insecure-server.json --execute
+```
+
+The first scan performs launch-configuration checks only. `--execute` acknowledges that the
+target command will run and enables MCP discovery.
+
+## Configuration
+
+```json
+{
+  "target": {
+    "command": "node",
+    "args": ["dist/fixtures/insecure-server.js"],
+    "cwd": "."
+  },
+  "policy": {
+    "timeoutMs": 5000,
+    "maxTools": 100
+  }
+}
+```
+
+Paths are resolved relative to the configuration file. Environment values are intentionally
+not supported in the MVP; this prevents secrets from entering reports or committed examples.
+
+## Output
+
+```powershell
+node dist/src/cli.js scan --config examples/insecure-server.json --execute --format json
+node dist/src/cli.js scan --config examples/insecure-server.json --execute --format sarif
+node dist/src/cli.js scan --config examples/insecure-server.json --execute --output reports/scan.json
+```
+
+Sensitive values supplied through common arguments such as `--token`, `--api-key`,
+`--password`, and `--secret` are redacted from every report. Avoid credentials in command
+arguments entirely when the target supports a safer authentication mechanism.
+
+Exit codes:
+
+- `0`: scan completed without high or critical findings
+- `1`: invalid input or runtime failure
+- `2`: scan completed with at least one high or critical finding
+
+## Remote servers
+
+To scan a remote MCP server, give the target a `url` instead of a `command`:
+
+```json
+{
+  "target": {
+    "url": "https://mcp.example.com/mcp",
+    "transport": "http"
+  },
+  "policy": { "timeoutMs": 5000, "maxTools": 100 }
+}
+```
+
+`transport` defaults to `"http"` (the modern **Streamable HTTP** transport); use `"sse"` only for
+legacy servers. Remote targets are checked for plaintext HTTP on non-local hosts (`REMOTE002`),
+credentials embedded in the URL (`REMOTE003`, redacted from the report), and — with `--execute` —
+whether the server accepts unauthenticated connections (`REMOTE004`).
+
+With `--execute`, a protected remote server is also audited against the MCP authorization spec
+(OAuth 2.1 + RFC 9728 / RFC 8414): a missing resource-metadata pointer (`AUTH001`), unreachable or
+malformed OAuth metadata (`AUTH002`), an authorization server that does not require PKCE/S256
+(`AUTH003`), and OAuth endpoints served over plaintext HTTP (`AUTH004`). See [docs/RULES.md](docs/RULES.md).
+
+```powershell
+node dist/src/cli.js scan --config examples/remote-server.json --execute
+```
+
+## Active probing (fuzzing)
+
+By default the scanner never invokes a discovered tool. Active probing is opt-in through `--fuzz`,
+which sends malformed and injection-shaped arguments to each tool to see whether the server validates
+input or crashes/hangs. Because this executes tool code, `--fuzz` **requires both `--execute` and
+`--sandbox docker`** so the target is network-isolated; the scanner refuses to fuzz on the host.
+
+```powershell
+node dist/src/cli.js scan --config examples/vulnerable-server.json --execute --sandbox docker --fuzz
+```
+
+`examples/vulnerable-server.json` targets a bundled honeypot (`fixtures/honeypot.ts`) that intentionally
+crashes on malicious input, so this command demonstrates a `FUZZ001` critical finding. A well-behaved
+server that returns a proper MCP error for bad input produces no fuzzing finding.
+
+## GitHub Action
+
+The repository includes a composite action that generates SARIF and can upload it to GitHub
+code scanning. The calling workflow must grant `security-events: write`.
+
+```yaml
+name: MCP security
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: warlyjr-cloud/mcp-security-lab@v0.2.0
+        with:
+          config: mcp-security-lab.json
+          execute: "true"
+          upload-sarif: "true"
+          fail-on-findings: "true"
+```
+
+Use `execute: "false"` for launch-configuration checks that must not start the target.
+SARIF upload is available for public repositories and for eligible private repositories with
+GitHub Code Security enabled.
+
+`execute: "true"` runs the configured server without OS-level filesystem or network isolation.
+Use it only for reviewed code or inside a disposable runner that contains no sensitive source
+or credentials.
+
+## Current limitations
+
+Without `--sandbox docker`, `--execute` provides no OS-level filesystem or network isolation: the
+server runs with the current user's permissions. Use `--sandbox docker` (which runs the target in a
+`--network none` container) or a disposable VM for untrusted software. The Docker adapter is
+POSIX-oriented; Windows paths are translated for bind-mounts but Docker Desktop must be running.
+Remote scanning uses the Streamable HTTP transport by default (SSE is available for legacy servers).
+See [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md).
+
+## Roadmap
+
+1. Windows Sandbox execution adapter (Docker container adapter shipped).
+2. Explicit, synthetic tool-call scenarios with canary files and blocked egress.
+3. Public conformance corpus maintained with the MCP community.
+
+Shipped: Streamable HTTP transport, remote transport checks, and OAuth authorization-posture checks
+(RFC 9728 / RFC 8414).

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security model
+
+MCP Security Lab treats a configured MCP server as untrusted code.
+
+## What the MVP protects
+
+- Dynamic scanning requires the explicit `--execute` flag.
+- The target receives a small allowlist of inherited environment variables.
+- Target startup and protocol discovery have a hard timeout.
+- The scanner lists tools but never calls them.
+- Findings are deterministic and contain no environment values.
+
+## What the MVP does not protect
+
+The current process runner is not an OS-level sandbox. A target process still runs with the
+current user's operating-system permissions and may access the filesystem or network. Run
+unknown servers inside a disposable VM or container.
+
+Future releases may add platform adapters for Windows Sandbox, containers, and restricted
+egress. Those adapters must be opt-in and independently verifiable.
+
+## Reporting vulnerabilities
+
+Do not include credentials, private server configuration, or personal data in a public issue.
+Provide a minimal synthetic reproduction and identify the affected version.

package/THREAT_MODEL.md

@@ -0,0 +1,66 @@
+# Threat model
+
+This document states what MCP Security Lab treats as trusted, what it treats as hostile, and what
+it does and does not guarantee. It complements [SECURITY.md](SECURITY.md), which covers vulnerability
+reporting.
+
+## Assets we protect
+
+- The operator's workstation or CI runner (filesystem, network, credentials, environment).
+- The integrity of the scan report itself (no secret leakage, no attacker-controlled content that
+  can crash or mislead the scanner).
+
+## Trust boundaries
+
+| Component                         | Trust level | Rationale                                              |
+| --------------------------------- | ----------- | ------------------------------------------------------ |
+| The scanner code and its config   | Trusted     | Authored and reviewed by the operator.                 |
+| The target MCP server binary/args | Untrusted   | May be third-party or malicious; running it is a risk. |
+| Everything the server sends       | Untrusted   | Tool/prompt/resource metadata is attacker-controlled.  |
+| The parent process environment    | Sensitive   | Must not leak into the target or the report.           |
+
+Everything a target server returns — names, descriptions, schemas, annotations, instructions, prompt
+and resource metadata — is untrusted input and is handled defensively. A target must never be able to
+crash the scanner, exfiltrate the operator's environment, or inject content into the report.
+
+## Adversaries and the mitigations against them
+
+- **Malicious launcher (supply chain).** A config that runs a shell, a network installer
+  (`npx`/`uvx`), inline interpreter code (`node -e`, `python -c`), or encoded payloads. Detected
+  statically without execution (`LAUNCH001`–`LAUNCH004`).
+- **Prompt injection via advertised metadata.** Hidden instructions in tool descriptions, parameter
+  names, enum values, server instructions, prompts, or resources — including Unicode-obfuscated
+  variants. Detected after NFKC normalization and invisible-character stripping (`TOOL003`,
+  `TOOL012`).
+- **Excessive agency / least-privilege violations.** Undeclared destructive tools, missing safety
+  hints, read+write capability mixing (`TOOL005`–`TOOL008`, `TOOL011`).
+- **Context-exhaustion / denial of service.** Unbounded read tools, tool flooding, or oversized
+  discovery payloads (`TOOL010`, `DISC001`, `DISC002`). The scanner bounds process lifetime with a
+  timeout and caps the size of discovery responses so a hostile server cannot exhaust the scanner.
+- **Insecure remote transport.** Plaintext HTTP on non-local endpoints, credentials in the URL, or a
+  remote server that accepts anonymous connections (`REMOTE002`–`REMOTE004`).
+- **Weak OAuth authorization posture.** A protected remote server that omits its resource-metadata
+  pointer, serves unreachable/malformed OAuth metadata, does not require PKCE, or exposes OAuth
+  endpoints over plaintext HTTP (`AUTH001`–`AUTH004`, per RFC 9728 / RFC 8414).
+- **Secret leakage into reports.** Credentials passed as arguments or in URLs are redacted; only an
+  allowlist of environment variables is inherited by the target.
+- **Uncontrolled active probing.** `--fuzz` executes tool code, so it requires an OS-level sandbox
+  (`--sandbox docker`, `--network none`) and refuses to run on the host.
+
+## Explicit non-goals
+
+- **No isolation without `--sandbox docker`.** A target started with `--execute` alone runs with the
+  operator's OS permissions. The scanner never claims isolation it does not enforce.
+- **No dynamic tool invocation by default.** Tools are only called when `--fuzz` is explicitly
+  requested and a sandbox is active.
+- **Not a substitute for code review.** Static launcher checks and advertised-metadata analysis
+  reduce risk; they do not prove a server is safe.
+- **No guarantee against a determined sandbox escape.** Container isolation reduces, but does not
+  eliminate, the risk of running untrusted code. Use disposable runners for unknown software.
+- **OAuth discovery follows server-controlled URLs (SSRF).** Auditing a remote server's authorization
+  posture (`AUTH00x`) requires fetching the metadata URLs the server advertises. Before contacting any
+  such URL the scanner resolves the host and refuses loopback, link-local (incl. `169.254.169.254`),
+  and private addresses — reporting the attempt as `AUTH005` — requires https for non-local hosts, uses
+  `redirect: "manual"` so a 3xx cannot bypass the check, caps the number of authorization servers
+  contacted, and bounds every request with a timeout. Loopback metadata is followed only when the
+  operator's own target is local (a dev scan). The scanner never forwards responses anywhere.

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { reportAsJson, reportAsSarif, reportAsText } from "./reporter.js";
+import { scan } from "./scanner.js";
+function usage() {
+    return [
+        "Usage:",
+        "  mcpsl scan --config <path> [--execute] [--sandbox docker|none] [--fuzz]",
+        "            [--format text|json|sarif] [--output <path>]",
+        "",
+        "Safety:",
+        "  Without --execute, only the launch configuration is inspected.",
+        "  With --execute, the target starts with a filtered environment; its tools are never called.",
+        "  Use --sandbox docker to run the target inside a disposable Docker container.",
+        "  Use --fuzz to actively call discovered tools with malicious inputs (DANGEROUS).",
+        "  --fuzz requires --execute and --sandbox docker so probing stays isolated.",
+    ].join("\n");
+}
+function parseArgs(args) {
+    if (args[0] !== "scan") {
+        throw new Error(usage());
+    }
+    let configPath;
+    let execute = false;
+    let fuzz = false;
+    let format = "text";
+    let outputPath;
+    let sandbox = "none";
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--execute") {
+            execute = true;
+            continue;
+        }
+        if (argument === "--fuzz") {
+            fuzz = true;
+            continue;
+        }
+        if (argument === "--config" ||
+            argument === "--format" ||
+            argument === "--output" ||
+            argument === "--sandbox") {
+            const value = args[index + 1];
+            if (value === undefined) {
+                throw new Error(`${argument} requires a value.`);
+            }
+            index += 1;
+            if (argument === "--config") {
+                configPath = value;
+            }
+            else if (argument === "--output") {
+                outputPath = value;
+            }
+            else if (argument === "--sandbox") {
+                if (value === "docker" || value === "none") {
+                    sandbox = value;
+                }
+                else {
+                    throw new Error("--sandbox must be docker or none.");
+                }
+            }
+            else if (value === "text" || value === "json" || value === "sarif") {
+                format = value;
+            }
+            else {
+                throw new Error("--format must be text, json, or sarif.");
+            }
+            continue;
+        }
+        throw new Error(`Unknown argument: ${argument}\n\n${usage()}`);
+    }
+    if (configPath === undefined) {
+        throw new Error(`--config is required.\n\n${usage()}`);
+    }
+    return {
+        configPath,
+        execute,
+        fuzz,
+        format,
+        sandbox,
+        ...(outputPath === undefined ? {} : { outputPath }),
+    };
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const config = await loadConfig(options.configPath);
+    const report = await scan(config, options.execute, options.sandbox, options.fuzz);
+    const output = options.format === "json"
+        ? reportAsJson(report)
+        : options.format === "sarif"
+            ? reportAsSarif(report, options.configPath)
+            : reportAsText(report);
+    if (options.outputPath === undefined) {
+        process.stdout.write(output);
+    }
+    else {
+        const absoluteOutputPath = resolve(options.outputPath);
+        await mkdir(dirname(absoluteOutputPath), { recursive: true });
+        await writeFile(absoluteOutputPath, output, "utf8");
+        process.stdout.write(`Report written to ${absoluteOutputPath}\n`);
+    }
+    if (report.summary.critical > 0 || report.summary.high > 0) {
+        process.exitCode = 2;
+    }
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/config.d.ts

@@ -0,0 +1,2 @@
+import type { ScanConfig } from "./types.js";
+export declare function loadConfig(configPath: string): Promise<ScanConfig>;

package/dist/src/config.js

@@ -0,0 +1,90 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { RESERVED_ENV_KEYS } from "./environment.js";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_TOOLS = 100;
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_TOOLS = 1_000;
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertRecord(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object.`);
+    }
+}
+function readPositiveInteger(value, fallback, maximum, label) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isInteger(value) || value <= 0 || value > maximum) {
+        throw new Error(`${label} must be an integer between 1 and ${maximum}.`);
+    }
+    return value;
+}
+function readTargetEnvironment(value) {
+    assertRecord(value, "target.env");
+    const environment = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!ENV_KEY_PATTERN.test(key)) {
+            throw new Error(`target.env['${key}'] is not a valid environment variable name.`);
+        }
+        if (RESERVED_ENV_KEYS.has(key.toUpperCase())) {
+            throw new Error(`target.env['${key}'] is reserved by the sanitized environment and cannot be overridden.`);
+        }
+        if (typeof entry !== "string") {
+            throw new Error(`target.env['${key}'] must be a string.`);
+        }
+        environment[key] = entry;
+    }
+    return environment;
+}
+export async function loadConfig(configPath) {
+    const absoluteConfigPath = resolve(configPath);
+    const raw = await readFile(absoluteConfigPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Config is not valid JSON: ${message}`, { cause: error });
+    }
+    assertRecord(parsed, "Config");
+    assertRecord(parsed.target, "target");
+    const { command, args = [], cwd = ".", env = {}, url, transport = "http" } = parsed.target;
+    if (url !== undefined && typeof url !== "string") {
+        throw new Error("target.url must be a string if provided.");
+    }
+    if (transport !== "http" && transport !== "sse") {
+        throw new Error('target.transport must be "http" or "sse".');
+    }
+    if (url === undefined) {
+        if (typeof command !== "string" || command.trim() === "") {
+            throw new Error("target.command must be a non-empty string when url is not provided.");
+        }
+        if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+            throw new Error("target.args must be an array of strings.");
+        }
+        if (typeof cwd !== "string" || cwd.trim() === "") {
+            throw new Error("target.cwd must be a non-empty string.");
+        }
+    }
+    const policyValue = parsed.policy ?? {};
+    assertRecord(policyValue, "policy");
+    return {
+        target: {
+            ...(url !== undefined
+                ? { url: url, transport: transport }
+                : {
+                    command: command,
+                    args: [...args],
+                    cwd: resolve(dirname(absoluteConfigPath), cwd),
+                }),
+            env: readTargetEnvironment(env),
+        },
+        policy: {
+            timeoutMs: readPositiveInteger(policyValue.timeoutMs, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, "policy.timeoutMs"),
+            maxTools: readPositiveInteger(policyValue.maxTools, DEFAULT_MAX_TOOLS, MAX_TOOLS, "policy.maxTools"),
+        },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/environment.d.ts

@@ -0,0 +1,12 @@
+export declare const RESERVED_ENV_KEYS: ReadonlySet<string>;
+export declare function createSanitizedEnvironment(source?: NodeJS.ProcessEnv): Record<string, string>;
+/** Strong, low-false-positive test used to RAISE a credentials-in-URL finding. */
+export declare function isCredentialQueryKey(key: string): boolean;
+/**
+ * Remove credentials from a URL before it enters a report: strip any userinfo
+ * (`user:pass@`) and redact the value of sensitive query AND fragment parameters
+ * (OAuth implicit-flow tokens live in the fragment). Falls back to a coarse regex
+ * when the string is not a parseable URL.
+ */
+export declare function redactUrl(rawUrl: string): string;
+export declare function redactArguments(args: string[]): string[];