@srhot/mcp-guard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial TypeScript CLI scanner.
+- Added policy engine with `off`, `warn`, and `error` modes.
+- Added seven initial MCP security rules.
+- Added safe and bad local MCP examples.
+- Added console, JSON, and Markdown reporters.
+- Added Vitest coverage and GitHub Actions CI.

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Thanks for helping improve MCP-Guard.
+
+## Development Setup
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## Rule Contributions
+
+Good v0.1 rules should be:
+
+- Deterministic and locally testable.
+- Focused on MCP security risks.
+- Backed by safe synthetic examples.
+- Configurable through the policy engine.
+
+Avoid rules that call external services, require credentials, or need a live MCP server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP-Guard contributors
+
+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,202 @@
+# MCP-Guard
+
+Open-source security scanner and policy engine for Model Context Protocol server projects.
+
+MCP-Guard helps detect tool poisoning, secret exposure, excessive permissions, risky command execution, missing audit controls, shadow MCP servers, and context over-sharing before an AI agent connects to them.
+
+## Quick Start
+
+Run MCP-Guard without installing it:
+
+```bash
+npx @srhot/mcp-guard scan .
+```
+
+Install it globally:
+
+```bash
+npm install -g @srhot/mcp-guard
+mcp-guard scan .
+```
+
+Write a Markdown report:
+
+```bash
+npx @srhot/mcp-guard scan . --format markdown --output mcp-guard-report.md
+```
+
+Write a JSON report:
+
+```bash
+npx @srhot/mcp-guard scan . --format json --output mcp-guard-report.json
+```
+
+Expected behavior:
+
+- Safe targets exit `0` and report no error-level findings.
+- Bad targets exit `1` when error-level findings are present.
+- Use `--no-fail` to print findings while exiting `0`, which is useful for demos and non-blocking CI checks.
+
+MCP-Guard v0.1 is a static scanner and policy engine. It is not a runtime MCP firewall or proxy yet.
+
+## What Can I Scan?
+
+You can scan:
+
+- MCP server repositories.
+- Folders containing `mcp.json`.
+- Folders containing `tools.json`.
+- TypeScript or JavaScript MCP server implementations.
+- Config folders used by MCP clients.
+
+MCP-Guard v0.1 performs static scanning and policy checks. It does not yet inspect live MCP JSON-RPC traffic.
+
+## Status
+
+MCP-Guard v0.1 is a scanner, policy engine, and local test laboratory. It is not a runtime firewall or proxy yet.
+
+## Why It Exists
+
+MCP servers can expose tools, files, credentials, commands, and instructions to AI agents. That makes small configuration mistakes unusually powerful. MCP-Guard gives maintainers a fast local check for common MCP security risks before those servers are used by agents or committed to shared repositories.
+
+## What It Detects
+
+- Likely hardcoded secrets and private keys.
+- Suspicious tool descriptions that look like hidden instructions.
+- Risky command execution surfaces.
+- Remote HTTP endpoints without clear authentication.
+- Missing audit logging when policy requires it.
+- MCP server names outside the allowlist.
+- Broad filesystem and context exposure.
+
+## Usage
+
+```bash
+mcp-guard scan <target>
+mcp-guard scan <target> --format json
+mcp-guard scan <target> --format markdown
+mcp-guard scan <target> --output report.md
+mcp-guard scan <target> --policy mcpguard.config.yml
+mcp-guard scan <target> --no-fail
+```
+
+Exit behavior:
+
+- Exit code `0` when there are no error-level findings.
+- Exit code `1` when there are error-level findings.
+- `--no-fail` always exits `0` while still printing findings.
+
+## Example Output
+
+```text
+MCP-Guard scan FAILED
+Target: /path/to/examples/bad-mcp-server
+Findings: 30 total, 27 error-level
+Severity: 1 critical, 26 high, 3 medium, 0 low, 0 info
+
+[HIGH] MCP05_COMMAND_EXECUTION Risky command execution surface
+  Policy: error (fails scan)
+  File: examples/bad-mcp-server/server.ts:4
+  Evidence: exec(
+```
+
+## Policy Configuration
+
+`mcpguard.config.yml` controls rule behavior and project expectations:
+
+```yaml
+rules:
+  MCP01_SECRET_EXPOSURE: error
+  MCP03_TOOL_POISONING: error
+  MCP05_COMMAND_EXECUTION: error
+  MCP07_INSUFFICIENT_AUTH: warn
+  MCP08_AUDIT_GAP: warn
+  MCP09_SHADOW_SERVER: warn
+  MCP10_CONTEXT_OVERSHARING: error
+
+allowlist:
+  servers:
+    - safe-filesystem-server
+    - safe-github-server
+
+require:
+  auditLogging: true
+  explicitToolConsent: true
+```
+
+Rule modes:
+
+- `off` suppresses a rule.
+- `warn` reports findings without failing the scan.
+- `error` fails the scan when the rule finds an issue.
+
+Without a policy override, high and critical findings fail the scan.
+
+## Try the Test Laboratory
+
+Clone the repository and run the local examples:
+
+```bash
+npm install
+npm run scan:safe
+npm run demo
+```
+
+`examples/safe-mcp-server` should pass. `examples/bad-mcp-server` intentionally contains risky patterns and should produce findings across the initial rule set.
+
+## GitHub Action
+
+Add MCP-Guard to another project with a workflow like this:
+
+```yaml
+name: MCP Guard
+
+on: [push, pull_request]
+
+jobs:
+  mcp-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - run: npx @srhot/mcp-guard scan .
+```
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm test
+npm run build
+npm run format
+npm run pack:check
+```
+
+## Local Package Smoke Test
+
+```bash
+npm pack
+npm install -g ./srhot-mcp-guard-0.1.0.tgz
+mcp-guard scan examples/safe-mcp-server
+mcp-guard scan examples/bad-mcp-server --no-fail
+npm uninstall -g @srhot/mcp-guard
+```
+
+## Roadmap
+
+- v0.1: static scanner + policy engine + test lab.
+- v0.2: SARIF output + stronger CI integration.
+- v0.3: runtime MCP proxy/firewall.
+- v0.4: dashboard and enterprise policy controls.
+
+## Disclaimer
+
+MCP-Guard is an early open-source security tool and does not replace a full security review.
+
+## Contributing
+
+Issues and pull requests are welcome. Please keep rules deterministic, locally testable, and free of external API requirements.

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+MCP-Guard is currently in v0.1. Security fixes target the latest release.
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities privately through the repository security advisory workflow when available. If that is not available, open a minimal issue that does not include exploitable details and ask the maintainers for a private contact path.
+
+Do not include real secrets, credentials, or private MCP server configuration in public issues.

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+interface CliIo {
+    stdout: Pick<NodeJS.WriteStream, "write">;
+    stderr: Pick<NodeJS.WriteStream, "write">;
+}
+export declare function runCli(argv?: string[], io?: CliIo): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command, CommanderError } from "commander";
+import { scanTarget } from "./scanner/scanTarget.js";
+import { renderConsoleReport } from "./reporters/consoleReporter.js";
+import { renderJsonReport } from "./reporters/jsonReporter.js";
+import { renderMarkdownReport } from "./reporters/markdownReporter.js";
+export async function runCli(argv = process.argv.slice(2), io = process) {
+    let exitCode = 0;
+    const program = new Command();
+    program
+        .name("mcp-guard")
+        .description("Security scanner and policy engine for MCP server projects")
+        .version("0.1.0")
+        .exitOverride();
+    program
+        .command("scan")
+        .argument("<target>", "MCP server project or config to scan")
+        .option("--format <format>", "report format: console, json, markdown", "console")
+        .option("--output <path>", "write report to a file")
+        .option("--policy <path>", "path to mcpguard.config.yml")
+        .option("--no-fail", "always exit 0 even when error-level findings are present")
+        .action(async (target, options) => {
+        const format = validateFormat(String(options.format ?? "console"));
+        const result = await scanTarget({
+            target,
+            policyPath: typeof options.policy === "string" ? options.policy : undefined
+        });
+        const report = renderReport(format, result);
+        if (typeof options.output === "string") {
+            await fs.mkdir(path.dirname(path.resolve(options.output)), { recursive: true });
+            await fs.writeFile(options.output, report, "utf8");
+        }
+        else {
+            io.stdout.write(report);
+        }
+        exitCode = result.shouldFail && options.fail !== false ? 1 : 0;
+    });
+    try {
+        await program.parseAsync(argv, { from: "user" });
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            return error.exitCode;
+        }
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    return exitCode;
+}
+function validateFormat(format) {
+    if (format === "console" || format === "json" || format === "markdown") {
+        return format;
+    }
+    throw new Error(`Unsupported format "${format}". Use console, json, or markdown.`);
+}
+function renderReport(format, result) {
+    if (format === "json") {
+        return renderJsonReport(result);
+    }
+    if (format === "markdown") {
+        return renderMarkdownReport(result);
+    }
+    return renderConsoleReport(result);
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    runCli().then((code) => {
+        process.exitCode = code;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { scanTarget } from "./scanner/scanTarget.js";
+export { loadPolicy } from "./policy/loadPolicy.js";
+export { applyPolicy, summarizeFindings } from "./policy/policyEngine.js";
+export { rules } from "./rules/index.js";
+export type { Finding, LoadedFile, Policy, Rule, RuleContext, ScanOptions, ScanResult, Severity } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { scanTarget } from "./scanner/scanTarget.js";
+export { loadPolicy } from "./policy/loadPolicy.js";
+export { applyPolicy, summarizeFindings } from "./policy/policyEngine.js";
+export { rules } from "./rules/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/policy/loadPolicy.d.ts

@@ -0,0 +1,3 @@
+import type { Policy } from "../types.js";
+export declare const defaultPolicy: Policy;
+export declare function loadPolicy(policyPath?: string): Promise<Policy>;

package/dist/policy/loadPolicy.js

@@ -0,0 +1,67 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+const ruleModeSchema = z.enum(["off", "warn", "error"]);
+const policySchema = z
+    .object({
+    rules: z.record(ruleModeSchema).default({}),
+    allowlist: z
+        .object({
+        servers: z.array(z.string()).default([])
+    })
+        .default({ servers: [] }),
+    deny: z
+        .object({
+        filesystemRoots: z.array(z.string()).default([]),
+        commands: z.array(z.string()).default([])
+    })
+        .default({ filesystemRoots: [], commands: [] }),
+    require: z
+        .object({
+        auditLogging: z.boolean().default(false),
+        explicitToolConsent: z.boolean().default(false)
+    })
+        .default({ auditLogging: false, explicitToolConsent: false })
+})
+    .default({});
+export const defaultPolicy = {
+    rules: {},
+    allowlist: {
+        servers: []
+    },
+    deny: {
+        filesystemRoots: ["/", "/home", "C:\\Users"],
+        commands: ["rm -rf", "curl | sh", "powershell -enc", "wget", "scp"]
+    },
+    require: {
+        auditLogging: false,
+        explicitToolConsent: false
+    }
+};
+export async function loadPolicy(policyPath) {
+    if (!policyPath) {
+        const candidate = path.resolve(process.cwd(), "mcpguard.config.yml");
+        try {
+            await fs.access(candidate);
+            return loadPolicy(candidate);
+        }
+        catch {
+            return defaultPolicy;
+        }
+    }
+    const raw = await fs.readFile(path.resolve(policyPath), "utf8");
+    const parsed = policySchema.parse(parse(raw) ?? {});
+    return {
+        rules: parsed.rules,
+        allowlist: parsed.allowlist,
+        deny: {
+            filesystemRoots: parsed.deny.filesystemRoots.length
+                ? parsed.deny.filesystemRoots
+                : defaultPolicy.deny.filesystemRoots,
+            commands: parsed.deny.commands.length ? parsed.deny.commands : defaultPolicy.deny.commands
+        },
+        require: parsed.require
+    };
+}
+//# sourceMappingURL=loadPolicy.js.map

package/dist/policy/loadPolicy.js.map

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

package/dist/policy/policyEngine.d.ts

@@ -0,0 +1,3 @@
+import type { Finding, Policy, ScanSummary } from "../types.js";
+export declare function applyPolicy(findings: Finding[], policy: Policy): Finding[];
+export declare function summarizeFindings(findings: Finding[]): ScanSummary;

package/dist/policy/policyEngine.js

@@ -0,0 +1,30 @@
+import { createSeverityCounts, shouldFailByDefault } from "../utils/severity.js";
+export function applyPolicy(findings, policy) {
+    return findings.flatMap((finding) => {
+        const mode = policy.rules[finding.id];
+        if (mode === "off") {
+            return [];
+        }
+        const failsScan = mode === "error" ? true : mode === "warn" ? false : shouldFailByDefault(finding.severity);
+        const policyLevel = mode === "error" || (mode === undefined && failsScan) ? "error" : "warn";
+        return [
+            {
+                ...finding,
+                policyLevel,
+                failsScan
+            }
+        ];
+    });
+}
+export function summarizeFindings(findings) {
+    const bySeverity = createSeverityCounts();
+    for (const finding of findings) {
+        bySeverity[finding.severity] += 1;
+    }
+    return {
+        total: findings.length,
+        failCount: findings.filter((finding) => finding.failsScan).length,
+        bySeverity
+    };
+}
+//# sourceMappingURL=policyEngine.js.map

package/dist/policy/policyEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyEngine.js","sourceRoot":"","sources":["../../src/policy/policyEngine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEjF,MAAM,UAAU,WAAW,CAAC,QAAmB,EAAE,MAAc;IAC7D,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAEtC,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,SAAS,GACb,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5F,MAAM,WAAW,GAAG,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QAE7F,OAAO;YACL;gBACE,GAAG,OAAO;gBACV,WAAW;gBACX,SAAS;aACV;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAmB;IACnD,MAAM,UAAU,GAAG,oBAAoB,EAAE,CAAC;IAC1C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,MAAM;QACtB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM;QACjE,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/reporters/consoleReporter.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "../types.js";
+export declare function renderConsoleReport(result: ScanResult): string;

package/dist/reporters/consoleReporter.js

@@ -0,0 +1,23 @@
+import { displayPath } from "../utils/paths.js";
+export function renderConsoleReport(result) {
+    const status = result.shouldFail ? "FAILED" : "PASSED";
+    const lines = [
+        `MCP-Guard scan ${status}`,
+        `Target: ${result.targetPath}`,
+        `Findings: ${result.summary.total} total, ${result.summary.failCount} error-level`,
+        `Severity: ${result.summary.bySeverity.CRITICAL} critical, ${result.summary.bySeverity.HIGH} high, ${result.summary.bySeverity.MEDIUM} medium, ${result.summary.bySeverity.LOW} low, ${result.summary.bySeverity.INFO} info`,
+        ""
+    ];
+    if (result.findings.length === 0) {
+        lines.push("No findings.");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const finding of result.findings) {
+        const location = finding.lineNumber
+            ? `${displayPath(finding.filePath)}:${finding.lineNumber}`
+            : displayPath(finding.filePath);
+        lines.push(`[${finding.severity}] ${finding.id} ${finding.title}`, `  Policy: ${finding.policyLevel ?? "warn"}${finding.failsScan ? " (fails scan)" : ""}`, `  File: ${location}`, `  Evidence: ${finding.evidence}`, `  Message: ${finding.message}`, `  Recommendation: ${finding.recommendation}`, "");
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=consoleReporter.js.map

package/dist/reporters/consoleReporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consoleReporter.js","sourceRoot":"","sources":["../../src/reporters/consoleReporter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,KAAK,GAAG;QACZ,kBAAkB,MAAM,EAAE;QAC1B,WAAW,MAAM,CAAC,UAAU,EAAE;QAC9B,aAAa,MAAM,CAAC,OAAO,CAAC,KAAK,WAAW,MAAM,CAAC,OAAO,CAAC,SAAS,cAAc;QAClF,aAAa,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,cAAc,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,SAAS,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO;QAC5N,EAAE;KACH,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3B,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU;YACjC,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE;YAC1D,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAElC,KAAK,CAAC,IAAI,CACR,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,EAAE,EACtD,aAAa,OAAO,CAAC,WAAW,IAAI,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,EACvF,WAAW,QAAQ,EAAE,EACrB,eAAe,OAAO,CAAC,QAAQ,EAAE,EACjC,cAAc,OAAO,CAAC,OAAO,EAAE,EAC/B,qBAAqB,OAAO,CAAC,cAAc,EAAE,EAC7C,EAAE,CACH,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/reporters/jsonReporter.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "../types.js";
+export declare function renderJsonReport(result: ScanResult): string;

package/dist/reporters/jsonReporter.js

@@ -0,0 +1,4 @@
+export function renderJsonReport(result) {
+    return `${JSON.stringify(result, null, 2)}\n`;
+}
+//# sourceMappingURL=jsonReporter.js.map

package/dist/reporters/jsonReporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonReporter.js","sourceRoot":"","sources":["../../src/reporters/jsonReporter.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/reporters/markdownReporter.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "../types.js";
+export declare function renderMarkdownReport(result: ScanResult): string;

package/dist/reporters/markdownReporter.js

@@ -0,0 +1,33 @@
+import { displayPath } from "../utils/paths.js";
+export function renderMarkdownReport(result) {
+    const lines = [
+        "# MCP-Guard Scan Report",
+        "",
+        `Target: \`${result.targetPath}\``,
+        `Status: **${result.shouldFail ? "failed" : "passed"}**`,
+        "",
+        "## Summary",
+        "",
+        `- Total findings: ${result.summary.total}`,
+        `- Error-level findings: ${result.summary.failCount}`,
+        `- Critical: ${result.summary.bySeverity.CRITICAL}`,
+        `- High: ${result.summary.bySeverity.HIGH}`,
+        `- Medium: ${result.summary.bySeverity.MEDIUM}`,
+        `- Low: ${result.summary.bySeverity.LOW}`,
+        `- Info: ${result.summary.bySeverity.INFO}`,
+        ""
+    ];
+    if (result.findings.length === 0) {
+        lines.push("No findings.");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push("## Findings", "");
+    for (const finding of result.findings) {
+        const location = finding.lineNumber
+            ? `${displayPath(finding.filePath)}:${finding.lineNumber}`
+            : displayPath(finding.filePath);
+        lines.push(`### ${finding.id}: ${finding.title}`, "", `- Severity: ${finding.severity}`, `- Policy: ${finding.policyLevel ?? "warn"}`, `- Location: \`${location}\``, `- Evidence: \`${finding.evidence}\``, `- Message: ${finding.message}`, `- Recommendation: ${finding.recommendation}`, "");
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=markdownReporter.js.map

package/dist/reporters/markdownReporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownReporter.js","sourceRoot":"","sources":["../../src/reporters/markdownReporter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,oBAAoB,CAAC,MAAkB;IACrD,MAAM,KAAK,GAAG;QACZ,yBAAyB;QACzB,EAAE;QACF,aAAa,MAAM,CAAC,UAAU,IAAI;QAClC,aAAa,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,IAAI;QACxD,EAAE;QACF,YAAY;QACZ,EAAE;QACF,qBAAqB,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE;QAC3C,2BAA2B,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE;QACrD,eAAe,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE;QACnD,WAAW,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE;QAC3C,aAAa,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE;QAC/C,UAAU,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE;QACzC,WAAW,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE;QAC3C,EAAE;KACH,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3B,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAE9B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU;YACjC,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE;YAC1D,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClC,KAAK,CAAC,IAAI,CACR,OAAO,OAAO,CAAC,EAAE,KAAK,OAAO,CAAC,KAAK,EAAE,EACrC,EAAE,EACF,eAAe,OAAO,CAAC,QAAQ,EAAE,EACjC,aAAa,OAAO,CAAC,WAAW,IAAI,MAAM,EAAE,EAC5C,iBAAiB,QAAQ,IAAI,EAC7B,iBAAiB,OAAO,CAAC,QAAQ,IAAI,EACrC,cAAc,OAAO,CAAC,OAAO,EAAE,EAC/B,qBAAqB,OAAO,CAAC,cAAc,EAAE,EAC7C,EAAE,CACH,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/rules/MCP01_SECRET_EXPOSURE.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const MCP01_SECRET_EXPOSURE: Rule;

package/dist/rules/MCP01_SECRET_EXPOSURE.js

@@ -0,0 +1,48 @@
+import { lineNumberForIndex } from "../scanner/fileLoader.js";
+const secretPatterns = [
+    {
+        label: "named secret assignment",
+        regex: /\b(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|GITHUB_TOKEN|API_KEY|SECRET|PASSWORD)\b\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{12,}/gi
+    },
+    {
+        label: "bearer token",
+        regex: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+        critical: true
+    },
+    {
+        label: "private key block",
+        regex: /-----BEGIN\s+(?:RSA\s+|EC\s+|OPENSSH\s+)?PRIVATE KEY-----/gi,
+        critical: true
+    }
+];
+export const MCP01_SECRET_EXPOSURE = {
+    id: "MCP01_SECRET_EXPOSURE",
+    scan(context) {
+        const findings = [];
+        for (const file of context.files) {
+            for (const pattern of secretPatterns) {
+                for (const match of file.content.matchAll(pattern.regex)) {
+                    findings.push({
+                        id: "MCP01_SECRET_EXPOSURE",
+                        title: "Possible secret exposure",
+                        severity: pattern.critical ? "CRITICAL" : "HIGH",
+                        category: "Secrets",
+                        message: `Detected a likely ${pattern.label} in a scanned file.`,
+                        filePath: file.filePath,
+                        lineNumber: lineNumberForIndex(file.content, match.index ?? 0),
+                        evidence: redactEvidence(match[0]),
+                        recommendation: "Move secrets to a secure secret manager or environment variable and rotate any exposed credentials."
+                    });
+                }
+            }
+        }
+        return findings;
+    }
+};
+function redactEvidence(value) {
+    if (value.length <= 16) {
+        return "[redacted]";
+    }
+    return `${value.slice(0, 12)}...[redacted]`;
+}
+//# sourceMappingURL=MCP01_SECRET_EXPOSURE.js.map

package/dist/rules/MCP01_SECRET_EXPOSURE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MCP01_SECRET_EXPOSURE.js","sourceRoot":"","sources":["../../src/rules/MCP01_SECRET_EXPOSURE.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,cAAc,GAAgE;IAClF;QACE,KAAK,EAAE,yBAAyB;QAChC,KAAK,EACH,sHAAsH;KACzH;IACD;QACE,KAAK,EAAE,cAAc;QACrB,KAAK,EAAE,sCAAsC;QAC7C,QAAQ,EAAE,IAAI;KACf;IACD;QACE,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,6DAA6D;QACpE,QAAQ,EAAE,IAAI;KACf;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAS;IACzC,EAAE,EAAE,uBAAuB;IAC3B,IAAI,CAAC,OAAO;QACV,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACjC,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;gBACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzD,QAAQ,CAAC,IAAI,CAAC;wBACZ,EAAE,EAAE,uBAAuB;wBAC3B,KAAK,EAAE,0BAA0B;wBACjC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM;wBAChD,QAAQ,EAAE,SAAS;wBACnB,OAAO,EAAE,qBAAqB,OAAO,CAAC,KAAK,qBAAqB;wBAChE,QAAQ,EAAE,IAAI,CAAC,QAAQ;wBACvB,UAAU,EAAE,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;wBAC9D,QAAQ,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;wBAClC,cAAc,EACZ,qGAAqG;qBACxG,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACvB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC;AAC9C,CAAC"}

package/dist/rules/MCP03_TOOL_POISONING.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const MCP03_TOOL_POISONING: Rule;