mcptrustchecker 1.1.0 → 1.2.0

package/dist/detectors/supplyChain.js

@@ -224,6 +224,67 @@ export function analyzeDependencies(meta, config) {
     }
     return findings;
 }
+/** Turn a failed published-artifact read into an honest finding (never silent). */
+export function analyzeArtifactError(meta) {
+    if (meta.requestedVersionMissing) {
+        return [
+            {
+                ruleId: 'MTC-SUP-015',
+                title: 'Pinned version is not published in the registry',
+                category: 'supply-chain',
+                severity: 'medium',
+                confidence: 'strong',
+                description: `The exact version you pinned (${meta.version ?? meta.requestedSpec ?? 'requested'}) is not listed by the ` +
+                    `registry — it may have been unpublished or yanked, or a hostile registry response may be hiding it to serve ` +
+                    `a different "latest". The scanner did NOT silently substitute another version: no source was read and no ` +
+                    `byte pin was recorded for a version that isn't there.`,
+                remediation: 'Confirm the version still exists and is the one you intend to install; if it was yanked, pin a known-good ' +
+                    'version and re-pin. Treat an unexpectedly-missing pinned version as a supply-chain signal.',
+                location: { kind: 'package', name: meta.name },
+                owasp: 'LLM03:2025 Supply Chain',
+                evidence: `requested ${meta.requestedSpec ?? meta.version ?? ''}`.trim(),
+            },
+        ];
+    }
+    const err = meta.artifactError;
+    if (!err)
+        return [];
+    if (err.kind === 'integrity' || err.kind === 'untrusted-redirect') {
+        return [
+            {
+                ruleId: 'MTC-TOFU-003',
+                title: 'Published artifact failed integrity verification',
+                category: 'supply-chain',
+                severity: 'critical',
+                confidence: 'confirmed',
+                description: `The published artifact for this package could not be verified against the registry's own declared hash ` +
+                    `(or was served from a host outside the registry's allowlist). Its bytes were NOT trusted, scanned, or ` +
+                    `pinned. This is exactly the signal a CDN/MITM tamper or a spoofed registry response would produce.\n  • ${err.detail}`,
+                remediation: 'Do not install this package until resolved: re-fetch from a trusted network, confirm the registry ' +
+                    'metadata, and compare the artifact hash against a known-good source.',
+                location: { kind: 'package', name: meta.name },
+                owasp: 'LLM03:2025 Supply Chain',
+                evidence: err.detail,
+            },
+        ];
+    }
+    // Transient/other: not an attack claim, but the scan is NOT verified — say so.
+    return [
+        {
+            ruleId: 'MTC-TOFU-004',
+            title: 'Published-source byte check did not run',
+            category: 'supply-chain',
+            severity: 'info',
+            confidence: 'heuristic',
+            description: `An online scan was requested but the published artifact could not be downloaded, so the implementation ` +
+                `source was NOT read and the byte-level integrity pin was NOT recorded. This scan reflects registry ` +
+                `metadata only — treat it as incomplete, not as a clean bill of health.\n  • ${err.detail}`,
+            remediation: 'Re-run the scan when the registry/network is reachable to complete the source-level analysis.',
+            location: { kind: 'package', name: meta.name },
+            evidence: err.detail,
+        },
+    ];
+}
 export const supplyChainDetector = {
     id: 'supply-chain',
     stage: 5,
@@ -237,6 +298,7 @@ export const supplyChainDetector = {
         if (meta) {
             findings.push(...analyzeProvenance(meta));
             findings.push(...analyzeDependencies(meta, ctx.config));
+            findings.push(...analyzeArtifactError(meta));
         }
         return findings;
     },

package/dist/engine.js

@@ -62,22 +62,46 @@ export async function scanSurface(rawSurface, options = {}) {
     if (options.lockfile !== undefined) {
         integrity = checkIntegrity(surface, options.lockfile);
         if (integrity.status === 'drift') {
-            raw.push({
-                ruleId: 'MTC-TOFU-001',
-                title: 'Server surface changed since it was pinned (possible rug pull)',
-                category: 'supply-chain',
-                severity: 'high',
-                confidence: 'confirmed',
-                description: `The canonical fingerprint of this server no longer matches its pinned value in the lockfile. ` +
-                    `Tool definitions can change silently after you approve them (a rug pull); review every change before ` +
-                    `trusting it again.\n` +
-                    (integrity.changes ?? []).map((c) => `  • ${c.detail}`).join('\n'),
-                remediation: 'Review the diff; re-pin only after confirming the changes are legitimate (`mcptrustchecker pin`).',
-                location: { kind: 'server' },
-                owasp: 'LLM03:2025 Supply Chain',
-                evidence: `${integrity.changes?.length ?? 0} change(s) since pin`,
-                data: { changes: integrity.changes },
-            });
+            const allChanges = integrity.changes ?? [];
+            const packageChanges = allChanges.filter((ch) => ch.kind === 'package-changed');
+            const surfaceChanges = allChanges.filter((ch) => ch.kind !== 'package-changed');
+            if (surfaceChanges.length > 0 || integrity.currentDigest !== integrity.previousDigest) {
+                raw.push({
+                    ruleId: 'MTC-TOFU-001',
+                    title: 'Server surface changed since it was pinned (possible rug pull)',
+                    category: 'supply-chain',
+                    severity: 'high',
+                    confidence: 'confirmed',
+                    description: `The canonical fingerprint of this server no longer matches its pinned value in the lockfile. ` +
+                        `Tool definitions can change silently after you approve them (a rug pull); review every change before ` +
+                        `trusting it again.\n` +
+                        surfaceChanges.map((c) => `  • ${c.detail}`).join('\n'),
+                    remediation: 'Review the diff; re-pin only after confirming the changes are legitimate (`mcptrustchecker pin`).',
+                    location: { kind: 'server' },
+                    owasp: 'LLM03:2025 Supply Chain',
+                    evidence: `${surfaceChanges.length} change(s) since pin`,
+                    data: { changes: surfaceChanges },
+                });
+            }
+            if (packageChanges.length > 0) {
+                raw.push({
+                    ruleId: 'MTC-TOFU-002',
+                    title: 'Package republished with different content at the same version',
+                    category: 'supply-chain',
+                    severity: 'critical',
+                    confidence: 'confirmed',
+                    description: `The registry artifact for the pinned version no longer contains the bytes that were verified at pin ` +
+                        `time. The tool surface can look completely unchanged while the implementation behind it was swapped — ` +
+                        `the byte-level rug pull that metadata-only checks cannot see.\n` +
+                        packageChanges.map((c) => `  • ${c.detail}`).join('\n'),
+                    remediation: 'Treat this as a potential supply-chain compromise: diff the published code against the version you ' +
+                        'approved before trusting it again, and re-pin (`mcptrustchecker pin`) only after review.',
+                    location: { kind: 'package', name: packageChanges[0].name },
+                    owasp: 'LLM03:2025 Supply Chain',
+                    evidence: packageChanges[0].detail,
+                    data: { changes: packageChanges },
+                });
+            }
         }
     }
     // Filter: disabled rules, whole-rule allowlist waivers, and location-scoped

package/dist/lockfile.d.ts

@@ -12,6 +12,17 @@ export interface LockEntry {
     digest: string;
     tools: Record<string, string>;
     instructionsDigest: string;
+    /** Package version whose published artifact was verified at pin time. */
+    packageVersion?: string;
+    /**
+     * Identity of the pinned artifact (its registry URL). A registry can publish
+     * several artifacts per version (a PyPI sdist AND wheels); the byte pin is
+     * only comparable to the SAME artifact, so a later-added sibling artifact
+     * isn't mistaken for a same-version republish.
+     */
+    tarballUrl?: string;
+    /** SHA-256 of that verified artifact — pins the actual published bytes. */
+    tarballSha256?: string;
     pinnedAt?: string;
 }
 export interface Lockfile {

package/dist/lockfile.js

@@ -14,6 +14,15 @@ import { METHODOLOGY_VERSION } from './version.js';
 function hashString(s) {
     return createHash('sha256').update(s).digest('hex');
 }
+/** The artifact's file name (last path segment, query/fragment stripped). */
+function artifactBasename(url) {
+    try {
+        return new URL(url).pathname.split('/').pop() ?? url;
+    }
+    catch {
+        return url.split(/[?#]/)[0].split('/').pop() ?? url;
+    }
+}
 export function emptyLockfile() {
     return { lockfileVersion: 1, methodologyVersion: METHODOLOGY_VERSION, servers: {} };
 }
@@ -35,19 +44,37 @@ export function entryFor(surface, pinnedAt) {
     const tools = {};
     for (const t of surface.tools)
         tools[t.name] = toolDigest(t);
+    const meta = surface.packageMeta;
     return {
         digest: surfaceDigest(surface),
         tools,
         instructionsDigest: hashString(surface.server.instructions ?? ''),
+        ...(typeof meta?.version === 'string' && meta.tarballSha256
+            ? { packageVersion: meta.version, tarballUrl: meta.tarballUrl ?? undefined, tarballSha256: meta.tarballSha256 }
+            : {}),
         ...(pinnedAt ? { pinnedAt } : {}),
     };
 }
 /** Add/update this surface's pin in the lockfile (returns a new object). */
 export function pinSurface(lock, surface, pinnedAt) {
+    const entry = entryFor(surface, pinnedAt);
+    // Never DROP an existing byte-level pin unless this scan positively verified a
+    // DIFFERENT version. An offline / metadata-only / failed-download re-pin has no
+    // fresh hash (and often no observed version at all) — carrying the previous pin
+    // forward keeps rug-pull protection alive rather than silently un-pinning it on
+    // a networkless CI re-pin or a transient outage.
+    const prev = lock.servers[surface.id];
+    const observedVersion = surface.packageMeta?.version;
+    const versionChanged = Boolean(observedVersion && prev?.packageVersion && observedVersion !== prev.packageVersion);
+    if (!entry.tarballSha256 && prev?.tarballSha256 && !versionChanged) {
+        entry.packageVersion = prev.packageVersion;
+        entry.tarballUrl = prev.tarballUrl;
+        entry.tarballSha256 = prev.tarballSha256;
+    }
     return {
         ...lock,
         methodologyVersion: METHODOLOGY_VERSION,
-        servers: { ...lock.servers, [surface.id]: entryFor(surface, pinnedAt) },
+        servers: { ...lock.servers, [surface.id]: entry },
     };
 }
 /** Compare the current surface against its pinned entry. */
@@ -56,7 +83,40 @@ export function checkIntegrity(surface, lock) {
     const entry = lock?.servers[surface.id];
     if (!entry)
         return { status: 'first-seen', currentDigest };
-    if (entry.digest === currentDigest)
+    // Byte-level rug pull: the SAME pinned version was republished with different
+    // content. The tool surface (and therefore the digest) may be identical —
+    // that is exactly what makes this attack invisible to a metadata-only check.
+    //
+    // Artifact identity is registry-aware, because the tarball URL comes from the
+    // (attacker-controllable) registry response and MUST NOT be trusted to gate
+    // the comparison:
+    //   • npm — a version maps to exactly ONE canonical tarball, so we compare by
+    //     VERSION only and ignore the URL entirely. That defeats a forged registry
+    //     that appends `?rev=2` (or any different path) to dodge the check.
+    //   • PyPI — a version legitimately has several immutable, differently-named
+    //     files (sdist + wheels), so we compare by the artifact FILE NAME (query
+    //     stripped) to avoid a false republish when a sibling file is added, while
+    //     still catching a same-file byte change (PyPI enforces file immutability,
+    //     so a same-name/different-bytes swap is itself the anomaly).
+    const meta = surface.packageMeta;
+    // Require a STRING version on both sides: a non-primitive `meta.version`
+    // (a hostile registry can make it an array/object) would never compare equal
+    // after the lockfile's JSON round-trip, silently suppressing the byte check.
+    const sameVersion = Boolean(typeof meta?.version === 'string' && meta.version === entry.packageVersion);
+    const sameArtifact = sameVersion &&
+        (meta?.registry !== 'pypi' ||
+            !entry.tarballUrl ||
+            !meta?.tarballUrl ||
+            artifactBasename(entry.tarballUrl) === artifactBasename(meta.tarballUrl));
+    const tarballChange = entry.tarballSha256 && entry.packageVersion && meta?.tarballSha256 && sameArtifact && meta.tarballSha256 !== entry.tarballSha256
+        ? {
+            kind: 'package-changed',
+            name: meta.name,
+            detail: `Version ${meta.version} was republished with different content: the verified artifact hash changed ` +
+                `from ${entry.tarballSha256.slice(0, 12)}… to ${meta.tarballSha256.slice(0, 12)}… since the pin (same version, different bytes).`,
+        }
+        : undefined;
+    if (entry.digest === currentDigest && !tarballChange)
         return { status: 'unchanged', currentDigest, previousDigest: entry.digest };
     const changes = [];
     const currentTools = {};
@@ -83,5 +143,7 @@ export function checkIntegrity(surface, lock) {
     if (entry.instructionsDigest !== hashString(surface.server.instructions ?? '')) {
         changes.push({ kind: 'instructions-changed', detail: 'Server instructions changed since the pin.' });
     }
+    if (tarballChange)
+        changes.push(tarballChange);
     return { status: 'drift', currentDigest, previousDigest: entry.digest, changes };
 }

package/dist/types.d.ts

@@ -102,6 +102,28 @@ export interface PackageMeta {
     pinned?: boolean;
     /** The raw version token from the install spec, if any (e.g. "latest", "^1.2.0"). */
     requestedSpec?: string;
+    /**
+     * True when an EXACT pinned version was requested but the registry does not
+     * list it (unpublished, yanked, or hidden by a hostile registry response). The
+     * artifact is deliberately left unresolved rather than silently substituting
+     * `latest`, and a finding is raised.
+     */
+    requestedVersionMissing?: boolean;
+    /** URL of the published artifact (npm dist.tarball / PyPI sdist or wheel). */
+    tarballUrl?: string | null;
+    /** Registry-declared artifact hash: SRI (`sha512-<b64>`) or `<algo>:<hex>`. */
+    tarballIntegrity?: string | null;
+    /** SHA-256 (hex) of the verified artifact the scan actually read — the byte-level pin. */
+    tarballSha256?: string;
+    /**
+     * Set when an `--online` artifact read was attempted but did not complete.
+     * `integrity`/`untrusted-redirect` are tamper evidence (a detector raises a
+     * finding); `network`/`other` mean the byte check simply could not run.
+     */
+    artifactError?: {
+        kind: 'integrity' | 'untrusted-redirect' | 'network' | 'other';
+        detail: string;
+    };
 }
 /** The single normalized object every detector operates on. */
 export interface ServerSurface {
@@ -237,7 +259,7 @@ export interface Score {
 }
 export type IntegrityStatus = 'first-seen' | 'unchanged' | 'drift';
 export interface SurfaceChange {
-    kind: 'tool-added' | 'tool-removed' | 'tool-changed' | 'instructions-changed';
+    kind: 'tool-added' | 'tool-removed' | 'tool-changed' | 'instructions-changed' | 'package-changed';
     name?: string;
     detail: string;
 }

package/dist/version.d.ts

@@ -1,6 +1,6 @@
 /*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
 /** Package version. Keep in sync with package.json. */
-export declare const TOOL_VERSION = "1.1.0";
+export declare const TOOL_VERSION = "1.2.0";
 /**
  * Methodology version. Bump this whenever scoring weights, gates, rule
  * severities, or bundled threat data change in a way that could move a score.

package/dist/version.js

@@ -1,6 +1,6 @@
 /*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
 /** Package version. Keep in sync with package.json. */
-export const TOOL_VERSION = '1.1.0';
+export const TOOL_VERSION = '1.2.0';
 /**
  * Methodology version. Bump this whenever scoring weights, gates, rule
  * severities, or bundled threat data change in a way that could move a score.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcptrustchecker",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Local-first, deterministic security scanner for Model Context Protocol (MCP) servers. Cross-tool toxic-flow analysis, Unicode-smuggling decode, prompt-injection & supply-chain detection, with an auditable 0–100 Trust Score.",
   "type": "module",
   "license": "MIT",