mcptrustchecker 1.0.0

package/dist/detectors/supplyChain.js

@@ -0,0 +1,243 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Stage 5 — Supply-chain & typosquatting.
+ *
+ * Multi-signal, not a single edit-distance number: known-squat table, fake
+ * official scope, unscoped shadowing, confusable skeleton, Damerau-Levenshtein
+ * gated by a download anomaly, combosquat suffix stripping, plus install-script
+ * / provenance risk. Anchored to the curated protected list (never all-pairs).
+ */
+import { COMBOSQUAT_SUFFIXES, FAKE_SCOPE_PATTERNS, KNOWN_SQUATS, PROTECTED_PACKAGES, UNSCOPED_SHADOWS, } from '../data/protectedPackages.js';
+import { skeleton } from '../data/confusables.js';
+import { KNOWN_VULNS } from '../data/knownCves.js';
+import { bareName, damerauLevenshtein, isKeyboardTypo } from '../util/distance.js';
+const SUP_REF = ['https://github.com/ossf/package-analysis', 'https://owasp.org/www-project-top-10-ci-cd-security-risks/'];
+function protectedNames(config) {
+    return [...PROTECTED_PACKAGES.map((p) => p.name), ...config.protectedPackages];
+}
+function downloadsFor(name) {
+    return PROTECTED_PACKAGES.find((p) => p.name === name)?.weeklyDownloads;
+}
+/** Pure typosquat analysis for a single package name. Exported for tests. */
+export function analyzeTyposquat(name, meta, config) {
+    const findings = [];
+    if (typeof name !== 'string' || name.length === 0)
+        return findings;
+    const lower = name.toLowerCase();
+    const protectedList = protectedNames(config);
+    const protectedSet = new Set(protectedList.map((p) => p.toLowerCase()));
+    // It IS a protected package — nothing to squat.
+    if (protectedSet.has(lower))
+        return findings;
+    const push = (ruleId, severity, confidence, title, description, target) => {
+        findings.push({
+            ruleId,
+            title,
+            category: 'supply-chain',
+            severity,
+            confidence,
+            description,
+            remediation: target
+                ? `Confirm you meant "${target}". Install packages only from their documented, official name.`
+                : 'Verify the package name against its official source before installing.',
+            location: { kind: 'package', name },
+            owasp: 'LLM03:2025 Supply Chain',
+            references: SUP_REF,
+            data: { candidate: name, target },
+        });
+    };
+    // 1) Known pre-computed squat.
+    if (KNOWN_SQUATS[lower]) {
+        push('MTC-SUP-001', 'high', 'strong', `Known typosquat of ${KNOWN_SQUATS[lower]}`, `"${name}" is a known impersonation of the popular package "${KNOWN_SQUATS[lower]}".`, KNOWN_SQUATS[lower]);
+        return findings; // definitive; don't pile on
+    }
+    // 2) Fake official scope.
+    for (const re of FAKE_SCOPE_PATTERNS) {
+        if (re.test(name)) {
+            push('MTC-SUP-002', 'high', 'strong', 'Impersonated official scope', `"${name}" uses a scope crafted to look like the official @modelcontextprotocol namespace.`, '@modelcontextprotocol/*');
+            return findings;
+        }
+    }
+    // 3) Unscoped shadow of an official scoped package.
+    if (UNSCOPED_SHADOWS.has(lower)) {
+        push('MTC-SUP-003', 'high', 'strong', 'Unscoped shadow of an official package', `"${name}" is an unscoped name that shadows an official scoped @modelcontextprotocol package.`);
+        return findings;
+    }
+    const bare = bareName(lower);
+    const skel = skeleton(bare);
+    for (const prot of protectedList) {
+        const protLower = prot.toLowerCase();
+        const protBare = bareName(protLower);
+        if (bare === protBare)
+            continue; // same bare name, different scope handled above
+        // 4) Confusable skeleton collision (homoglyph squat).
+        if (skel === skeleton(protBare) && bare !== protBare) {
+            push('MTC-SUP-004', 'high', 'strong', `Homoglyph squat of ${prot}`, `"${name}" is visually confusable with "${prot}" (identical confusable skeleton "${skel}").`, prot);
+            continue;
+        }
+        // 5) Edit-distance near-miss, gated by download anomaly.
+        if (protBare.length >= 5) {
+            const dist = damerauLevenshtein(bare, protBare);
+            if (dist >= 1 && dist <= 2) {
+                const dl = downloadsFor(prot);
+                const highTraffic = dl !== undefined && dl >= 50_000;
+                const keyboardSlip = isKeyboardTypo(bare, protBare);
+                const severity = dist === 1 && highTraffic ? 'high' : 'medium';
+                const confidence = dist === 1 ? 'strong' : 'heuristic';
+                push('MTC-SUP-005', severity, confidence, `Near-miss of ${prot} (edit distance ${dist})`, `"${name}" is edit-distance ${dist} from the ${highTraffic ? 'high-traffic ' : ''}package "${prot}"` +
+                    `${keyboardSlip ? ' (keyboard-adjacent slip)' : ''}. ${meta?.weeklyDownloads != null && meta.weeklyDownloads < 500 ? 'Its own download count is negligible, consistent with a squat.' : 'Verify this is the intended package.'}`, prot);
+                continue;
+            }
+        }
+        // 6) Combosquat: strip decorative suffixes and re-compare.
+        let stripped = bare;
+        for (const suf of COMBOSQUAT_SUFFIXES)
+            if (stripped.endsWith(suf))
+                stripped = stripped.slice(0, -suf.length);
+        if (stripped !== bare && stripped === protBare) {
+            push('MTC-SUP-006', 'medium', 'heuristic', `Possible combosquat of ${prot}`, `"${name}" is "${prot}" with a decorative suffix — a common combosquat pattern.`, prot);
+        }
+    }
+    return findings;
+}
+/** Install-script & provenance risk from package metadata. */
+export function analyzeProvenance(meta) {
+    const findings = [];
+    const name = meta.name ?? 'package';
+    const scripts = meta.scripts ?? {};
+    const lifecycle = ['preinstall', 'install', 'postinstall'].filter((s) => scripts[s]);
+    if (lifecycle.length > 0) {
+        const hasPre = lifecycle.includes('preinstall');
+        findings.push({
+            ruleId: 'MTC-SUP-010',
+            title: `Package runs install-time scripts (${lifecycle.join(', ')})`,
+            category: 'supply-chain',
+            severity: hasPre ? 'high' : 'medium',
+            confidence: 'strong',
+            description: `"${name}" executes ${lifecycle.join('/')} script(s) at install time. The large majority of malicious ` +
+                `packages abuse install hooks to run code before you ever import them.`,
+            remediation: 'Review the scripts; install with --ignore-scripts where possible and vet what they do.',
+            location: { kind: 'package', name },
+            owasp: 'LLM03:2025 Supply Chain',
+            references: SUP_REF,
+            data: { scripts: lifecycle },
+        });
+    }
+    if (meta.pinned === false) {
+        findings.push({
+            ruleId: 'MTC-SUP-013',
+            title: `Package is not version-pinned (${meta.requestedSpec ?? 'no version'})`,
+            category: 'supply-chain',
+            severity: lifecycle.length > 0 ? 'medium' : 'low',
+            confidence: 'strong',
+            description: `"${name}" is installed with a floating/latest spec (${meta.requestedSpec ?? 'no version'}), so its tool ` +
+                `definitions and code can change silently after you approve it — the rug-pull enabler. Pinning is the ` +
+                `recommended static control.`,
+            remediation: 'Pin an exact version (and commit mcptrustchecker.lock so drift is caught on rescan).',
+            location: { kind: 'package', name },
+            owasp: 'LLM03:2025 Supply Chain',
+            data: { requestedSpec: meta.requestedSpec ?? null },
+        });
+    }
+    if (meta.repositoryUrl === null) {
+        findings.push({
+            ruleId: 'MTC-SUP-011',
+            title: 'Package has no source repository',
+            category: 'supply-chain',
+            severity: 'low',
+            confidence: 'strong',
+            description: `"${name}" declares no repository URL, so its published artifact cannot be compared against reviewable source.`,
+            remediation: 'Prefer packages that link to public, reviewable source.',
+            location: { kind: 'package', name },
+        });
+    }
+    if (meta.license === null) {
+        findings.push({
+            ruleId: 'MTC-SUP-012',
+            title: 'Package has no license',
+            category: 'hygiene',
+            severity: 'low',
+            confidence: 'strong',
+            description: `"${name}" has no declared license.`,
+            location: { kind: 'package', name },
+        });
+    }
+    return findings;
+}
+/** Check a package's declared dependencies for squats / known-vuln names. */
+export function analyzeDependencies(meta, config) {
+    const findings = [];
+    const deps = (Array.isArray(meta.dependencies) ? meta.dependencies : []).filter((d) => typeof d === 'string');
+    if (deps.length === 0)
+        return findings;
+    const protectedList = protectedNames(config);
+    for (const dep of deps) {
+        const lower = dep.toLowerCase();
+        if (protectedList.some((p) => p.toLowerCase() === lower))
+            continue; // it's a real one
+        let squatOf;
+        if (KNOWN_SQUATS[lower])
+            squatOf = KNOWN_SQUATS[lower];
+        else if (FAKE_SCOPE_PATTERNS.some((re) => re.test(dep)))
+            squatOf = '@modelcontextprotocol/*';
+        else {
+            const sk = skeleton(bareName(lower));
+            for (const p of protectedList) {
+                const pb = bareName(p.toLowerCase());
+                if (pb !== bareName(lower) && skeleton(pb) === sk) {
+                    squatOf = p;
+                    break;
+                }
+            }
+        }
+        if (squatOf) {
+            findings.push({
+                ruleId: 'MTC-SUP-014',
+                title: `Dependency "${dep}" resembles ${squatOf}`,
+                category: 'supply-chain',
+                severity: 'medium',
+                confidence: 'heuristic',
+                description: `A declared dependency "${dep}" looks like a squat of "${squatOf}" — a transitive supply-chain risk.`,
+                remediation: `Confirm the dependency is the intended "${squatOf}".`,
+                location: { kind: 'package', name: meta.name ?? dep },
+                owasp: 'LLM03:2025 Supply Chain',
+                data: { dependency: dep, target: squatOf },
+            });
+            continue;
+        }
+        const vuln = KNOWN_VULNS.find((v) => v.package === dep);
+        if (vuln) {
+            findings.push({
+                ruleId: 'MTC-SUP-014',
+                title: `Dependency "${dep}" has a known advisory (${vuln.id})`,
+                category: 'supply-chain',
+                severity: 'low',
+                confidence: 'heuristic',
+                description: `Declared dependency "${dep}" matches a known-vulnerable package (${vuln.id}); the pinned version is not resolvable from metadata, so verify it is patched.`,
+                remediation: `Ensure "${dep}" is upgraded past the ${vuln.id} fix.`,
+                location: { kind: 'package', name: meta.name ?? dep },
+                references: [vuln.reference],
+                owasp: 'LLM03:2025 Supply Chain',
+                data: { dependency: dep, advisory: vuln.id },
+            });
+        }
+    }
+    return findings;
+}
+export const supplyChainDetector = {
+    id: 'supply-chain',
+    stage: 5,
+    title: 'Supply-chain & typosquatting',
+    run(ctx) {
+        const findings = [];
+        const meta = ctx.surface.packageMeta;
+        const name = meta?.name ?? (ctx.surface.source.kind === 'package' ? ctx.surface.id : undefined);
+        if (name)
+            findings.push(...analyzeTyposquat(name, meta, ctx.config));
+        if (meta) {
+            findings.push(...analyzeProvenance(meta));
+            findings.push(...analyzeDependencies(meta, ctx.config));
+        }
+        return findings;
+    },
+};

package/dist/detectors/toxicFlow.d.ts

@@ -0,0 +1,22 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Stage 4 — Toxic-flow graph (the flagship analysis).
+ *
+ * The "lethal trifecta": an agent session that can reach
+ *   UNTRUSTED_INPUT  →  SENSITIVE_DATA_SOURCE  →  EXTERNAL_SINK
+ * holds an exfiltration primitive, whether those roles live in one tool or are
+ * composed across several tools and the client's built-ins.
+ *
+ * Honesty contract: static analysis proves the primitive *exists* (capability
+ * co-presence), not that a runtime chain *will* execute. Findings are worded
+ * accordingly, and only a single-tool completed trifecta is `confirmed`.
+ */
+import type { DetectorContext, Finding, ServerSurface, ToolCapability, ToxicFlow } from '../types.js';
+interface FlowAnalysis {
+    flows: ToxicFlow[];
+    findings: Finding[];
+}
+export declare function analyzeToxicFlows(ctx: DetectorContext): FlowAnalysis;
+/** Convenience wrapper matching the pipeline stage description. */
+export declare function toxicFlowStage(surface: ServerSurface, capabilities: ToolCapability[], config: DetectorContext['config']): FlowAnalysis;
+export {};

package/dist/detectors/toxicFlow.js

@@ -0,0 +1,201 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Stage 4 — Toxic-flow graph (the flagship analysis).
+ *
+ * The "lethal trifecta": an agent session that can reach
+ *   UNTRUSTED_INPUT  →  SENSITIVE_DATA_SOURCE  →  EXTERNAL_SINK
+ * holds an exfiltration primitive, whether those roles live in one tool or are
+ * composed across several tools and the client's built-ins.
+ *
+ * Honesty contract: static analysis proves the primitive *exists* (capability
+ * co-presence), not that a runtime chain *will* execute. Findings are worded
+ * accordingly, and only a single-tool completed trifecta is `confirmed`.
+ */
+import { CLIENT_BUILTINS } from '../data/capabilityLexicon.js';
+import { representativeTrifectaPath, representativeExfilPath, renderPath } from './flowGraph.js';
+const FLOW_REFS = [];
+function isSinkCap(c) {
+    return c.tags.includes('external-sink') || c.tags.includes('code-exec');
+}
+export function analyzeToxicFlows(ctx) {
+    const caps = [...ctx.capabilities];
+    if (ctx.config.includeBuiltins) {
+        for (const b of CLIENT_BUILTINS)
+            caps.push({ tool: b.tool, tags: b.tags, reasons: {} });
+    }
+    const untrusted = caps.filter((c) => c.tags.includes('untrusted-input')).map((c) => c.tool);
+    const sources = caps.filter((c) => c.tags.includes('sensitive-source')).map((c) => c.tool);
+    const sinks = caps.filter(isSinkCap).map((c) => c.tool);
+    const selfTrifecta = caps.filter((c) => c.tags.includes('untrusted-input') && c.tags.includes('sensitive-source') && isSinkCap(c));
+    const selfTrifectaNames = new Set(selfTrifecta.map((c) => c.tool));
+    const selfExfil = caps.filter((c) => !selfTrifectaNames.has(c.tool) &&
+        c.tags.includes('sensitive-source') &&
+        isSinkCap(c) &&
+        !c.tags.includes('untrusted-input'));
+    const fullTrifectaPresent = untrusted.length > 0 && sources.length > 0 && sinks.length > 0;
+    const flows = [];
+    const findings = [];
+    let flowSeq = 0;
+    const nextId = () => `flow-${++flowSeq}`;
+    // 1) Self-contained completed trifecta — one tool ingests, reads, and exfiltrates.
+    for (const c of selfTrifecta) {
+        const id = nextId();
+        flows.push({
+            id,
+            severity: 'critical',
+            confidence: 'confirmed',
+            untrustedInput: [c.tool],
+            sensitiveSource: [c.tool],
+            externalSink: [c.tool],
+            selfContained: true,
+            description: `Tool "${c.tool}" alone ingests untrusted input, reads sensitive data, and can send it out.`,
+        });
+        findings.push({
+            ruleId: 'MTC-FLOW-001',
+            title: `Self-contained exfiltration primitive: "${c.tool}"`,
+            category: 'exfiltration',
+            severity: 'critical',
+            confidence: 'confirmed',
+            description: `Tool "${c.tool}" holds all three trifecta roles by itself (untrusted-input + sensitive-source + ` +
+                `external-sink). A single call can pull attacker-controlled content, read private data, and exfiltrate ` +
+                `it — no composition required.`,
+            remediation: 'Split responsibilities across separate, individually-consented tools; never combine untrusted input, secret reads, and egress in one tool.',
+            location: { kind: 'flow', name: c.tool },
+            owasp: 'LLM02:2025 Sensitive Information Disclosure',
+            references: FLOW_REFS,
+            data: { tags: c.tags },
+        });
+    }
+    // 2) Cross-tool completed trifecta (only if no single tool already completes it).
+    if (fullTrifectaPresent && selfTrifecta.length === 0) {
+        const id = nextId();
+        const p = representativeTrifectaPath(caps, ctx.surface.tools);
+        const chain = p ? renderPath(p) : `[${untrusted.join(', ')}] → [${sources.join(', ')}] → [${sinks.join(', ')}]`;
+        flows.push({
+            id,
+            severity: 'critical',
+            confidence: 'strong',
+            untrustedInput: untrusted,
+            sensitiveSource: sources,
+            externalSink: sinks,
+            selfContained: false,
+            path: p?.path,
+            pathWired: p?.wired,
+            description: `A cross-tool exfiltration chain exists: ${chain}.`,
+        });
+        findings.push({
+            ruleId: 'MTC-FLOW-002',
+            title: 'Completed toxic-flow trifecta across tools',
+            category: 'exfiltration',
+            severity: 'critical',
+            confidence: 'strong',
+            description: `This server (with${ctx.config.includeBuiltins ? '' : 'out'} client built-ins) exposes a complete ` +
+                `data-exfiltration chain: ${chain}. Untrusted input is ingested, private data is read, and it can be sent ` +
+                `to an external sink` +
+                (p?.wired
+                    ? ` — and at least one leg is a direct schema wire (⇒), where a producer's output drops straight into a ` +
+                        `free-text parameter of the next tool, so the chain needs little agent cooperation.`
+                    : ` via the agent composing the tools (→).`) +
+                ` Static analysis proves the primitive exists, not that a specific run will occur.`,
+            remediation: 'Remove one leg of the trifecta: isolate untrusted-input tools from secret-reading tools and from egress tools, or require human approval between them.',
+            location: { kind: 'flow', name: p?.path?.join(' → ') },
+            owasp: 'LLM02:2025 Sensitive Information Disclosure',
+            references: FLOW_REFS,
+            data: { untrusted, sources, sinks, path: p?.path, edges: p?.edges, wired: p?.wired },
+        });
+    }
+    // 3) Self-contained exfil (reads secrets + can egress, no untrusted input leg).
+    for (const c of selfExfil) {
+        const id = nextId();
+        flows.push({
+            id,
+            severity: 'high',
+            confidence: 'strong',
+            untrustedInput: [],
+            sensitiveSource: [c.tool],
+            externalSink: [c.tool],
+            selfContained: true,
+            description: `Tool "${c.tool}" both reads sensitive data and can send it externally.`,
+        });
+        findings.push({
+            ruleId: 'MTC-FLOW-003',
+            title: `Read-and-egress in one tool: "${c.tool}"`,
+            category: 'exfiltration',
+            severity: 'high',
+            confidence: 'strong',
+            description: `Tool "${c.tool}" can both read sensitive data and send data to an external destination. Even without an ` +
+                `explicit untrusted-input leg, this is a single-call data-exfiltration path if the model is ever ` +
+                `manipulated.`,
+            remediation: 'Separate reading from sending; require explicit user confirmation before egress of file/secret contents.',
+            location: { kind: 'flow', name: c.tool },
+            owasp: 'LLM02:2025 Sensitive Information Disclosure',
+            references: FLOW_REFS,
+            data: { tags: c.tags },
+        });
+    }
+    // 4) Cross-tool data-out path: a source tool and a *different* sink tool exist.
+    const crossExfil = !fullTrifectaPresent && sources.some((s) => sinks.some((k) => k !== s));
+    if (crossExfil) {
+        const id = nextId();
+        const p = representativeExfilPath(caps, ctx.surface.tools);
+        flows.push({
+            id,
+            severity: 'high',
+            confidence: 'strong',
+            untrustedInput: [],
+            sensitiveSource: sources,
+            externalSink: sinks,
+            selfContained: false,
+            path: p?.path,
+            pathWired: p?.wired,
+            description: `A sensitive-source → external-sink chain exists: ${p ? renderPath(p) : ''}.`,
+        });
+        findings.push({
+            ruleId: 'MTC-FLOW-004',
+            title: 'Sensitive-source and external-sink co-exist',
+            category: 'exfiltration',
+            severity: 'high',
+            confidence: 'strong',
+            description: `Tools that read sensitive data ([${sources.join(', ')}]) and tools that can send data out ` +
+                `([${sinks.join(', ')}]) are exposed together. An agent can move private data to the sink.`,
+            remediation: 'Keep secret-reading and egress capabilities on separate, separately-approved servers.',
+            location: { kind: 'flow' },
+            owasp: 'LLM02:2025 Sensitive Information Disclosure',
+            references: FLOW_REFS,
+            data: { sources, sinks },
+        });
+    }
+    // 5) Untrusted input reaching an action sink (no sensitive source involved).
+    if (!fullTrifectaPresent && untrusted.length > 0 && sinks.length > 0 && sources.length === 0) {
+        const id = nextId();
+        flows.push({
+            id,
+            severity: 'medium',
+            confidence: 'strong',
+            untrustedInput: untrusted,
+            sensitiveSource: [],
+            externalSink: sinks,
+            selfContained: false,
+            description: 'Untrusted input can drive an external action even though no sensitive source is exposed.',
+        });
+        findings.push({
+            ruleId: 'MTC-FLOW-005',
+            title: 'Untrusted input can drive an external action',
+            category: 'exfiltration',
+            severity: 'medium',
+            confidence: 'strong',
+            description: `Untrusted-input tools ([${untrusted.join(', ')}]) co-exist with external-action tools ([${sinks.join(', ')}]). ` +
+                `A prompt injection could cause unwanted external actions, though no direct sensitive-data leak path was found.`,
+            remediation: 'Require confirmation for state-changing/egress actions triggered after processing untrusted content.',
+            location: { kind: 'flow' },
+            owasp: 'LLM06:2025 Excessive Agency',
+            references: FLOW_REFS,
+            data: { untrusted, sinks },
+        });
+    }
+    return { flows, findings };
+}
+/** Convenience wrapper matching the pipeline stage description. */
+export function toxicFlowStage(surface, capabilities, config) {
+    return analyzeToxicFlows({ surface, capabilities, config });
+}

package/dist/detectors/unicode.d.ts

@@ -0,0 +1,21 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Stage 1 — Lexical / Unicode integrity.
+ *
+ * Scans every text field for the invisible-character families used to smuggle
+ * instructions past human review, and **decodes** the two families that carry a
+ * payload (Tags block, variation-selector channel) so the recovered text is
+ * surfaced as evidence. Also runs a mixed-script (homoglyph) check using Unicode
+ * script properties — a codepoint blocklist cannot catch visible confusables.
+ */
+import type { Detector } from '../types.js';
+import { type InvisibleFamily } from '../data/unicode.js';
+interface FamilyHit {
+    family: InvisibleFamily;
+    count: number;
+    decoded?: string;
+}
+/** Group invisible-character hits by family, decoding payload channels. */
+export declare function analyzeText(text: string): FamilyHit[];
+export declare const unicodeDetector: Detector;
+export {};