@polygraphso/litmus 0.3.0 → 0.4.0

package/dist/{chunk-SAZKXB35.js → chunk-K7UEK2BA.js}

@@ -1,6 +1,6 @@
 // ../core/src/types.ts
-var METHODOLOGY_VERSION = "litmus-v2";
-var BUNDLE_SCHEMA_VERSION = "1.1.0";
+var METHODOLOGY_VERSION = "litmus-v3";
+var BUNDLE_SCHEMA_VERSION = "1.2.0";
 var CATEGORY_STATUS_UINT8 = {
   pass: 0,
   fail: 1,

package/dist/{chunk-2K6T4FZX.js → chunk-MB5EPL2V.js}

@@ -3,10 +3,10 @@ import {
   METHODOLOGY_VERSION,
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../probes/src/harness.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 
 // ../probes/src/connect/index.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -138,7 +138,7 @@ function resolveDockerDir() {
   }
   return fileURLToPath(new URL("../../docker", import.meta.url));
 }
-var RESOLVER_SCRIPT = `const p=require("path");const d="/stage/node_modules/"+process.argv[1];let j;try{j=require(d+'/package.json')}catch{}let entry=null;if(j){const b=j.bin;const r=typeof b==="string"?b:(b&&Object.values(b)[0]);if(r)entry=p.join(d,r);}const version=j&&j.version?j.version:null;process.stdout.write(JSON.stringify({entry,version}));`;
+var RESOLVER_SCRIPT = `const p=require("path");const n=process.argv[1];const d="/stage/node_modules/"+n;let j;try{j=require(d+'/package.json')}catch{}let bins={};if(j){const b=j.bin;if(typeof b==="string"){bins[n.replace(/^@[^/]+\\//,"")]=p.join(d,b);}else if(b){for(const k in b){bins[k]=p.join(d,b[k]);}}}const version=j&&j.version?j.version:null;let declaredEgress=[];if(j&&j.polygraph&&Array.isArray(j.polygraph.egress)){declaredEgress=j.polygraph.egress.filter(function(x){return typeof x==="string"});}process.stdout.write(JSON.stringify({bins,version,declaredEgress}));`;
 function labelFlags(runLabel) {
   return runLabel ? ["--label", `${LABEL_KEY}=${runLabel}`] : [];
 }
@@ -211,12 +211,16 @@ function resolverRunArgs(vol, image, pkgName, runLabel, runtime) {
 function parseResolverOutput(output) {
   try {
     const rec = JSON.parse(output);
-    return {
-      entry: typeof rec.entry === "string" ? rec.entry : null,
-      version: typeof rec.version === "string" ? rec.version : null
-    };
+    const bins = {};
+    if (rec.bins && typeof rec.bins === "object" && !Array.isArray(rec.bins)) {
+      for (const [k, v] of Object.entries(rec.bins)) {
+        if (typeof v === "string") bins[k] = v;
+      }
+    }
+    const declaredEgress = Array.isArray(rec.declaredEgress) ? rec.declaredEgress.filter((x) => typeof x === "string") : [];
+    return { bins, version: typeof rec.version === "string" ? rec.version : null, declaredEgress };
   } catch {
-    return { entry: null, version: null };
+    return { bins: {}, version: null, declaredEgress: [] };
   }
 }
 function buildImageArgs(pull) {
@@ -250,13 +254,13 @@ async function stageInto(vol, image, spec, pkgName, opts) {
   try {
     await docker(stageInstallArgs(vol, image, spec, opts.runLabel, runtime), 18e4);
     const resolved = parseResolverOutput((await docker(resolverRunArgs(vol, image, pkgName, opts.runLabel, runtime))).trim());
-    if (!resolved.entry) {
+    if (Object.keys(resolved.bins).length === 0) {
       await cleanup();
       throw new Error(
         `target package ${pkgName} exposes no launchable bin under the sandbox policy (install scripts are skipped)`
       );
     }
-    return { volume: vol, entry: resolved.entry, resolvedVersion: resolved.version, cleanup };
+    return { volume: vol, bins: resolved.bins, resolvedVersion: resolved.version, declaredEgress: resolved.declaredEgress, cleanup };
   } catch (err) {
     await cleanup();
     throw err;
@@ -397,125 +401,228 @@ function resolveStagedVersion(requested, staged) {
   return staged;
 }
 
+// ../probes/src/connect/bin-candidates.ts
+var MCP_NAME = /mcp/i;
+function orderBinCandidates(binNames, pkgName) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const take = (name) => {
+    if (!seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  };
+  for (const n of binNames) if (MCP_NAME.test(n)) take(n);
+  for (const n of binNames) if (n === pkgName) take(n);
+  for (const n of binNames) take(n);
+  return out;
+}
+function parseNpmBins(stdout, pkgName) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  let v;
+  try {
+    v = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  if (typeof v === "string") return [pkgName];
+  if (v && typeof v === "object" && !Array.isArray(v)) return Object.keys(v);
+  return [];
+}
+var NoMcpBinError = class extends Error {
+  constructor(ref, tried) {
+    super(
+      `${ref}: no bin spoke MCP \u2014 tried ${tried.length ? tried.join(", ") : "no launchable bins"}. The target must be an MCP server; a CLI-only package can't be graded.`
+    );
+    this.name = "NoMcpBinError";
+  }
+};
+async function probeForMcpBin(ref, candidates, attempt) {
+  for (const bin of candidates) {
+    const result = await attempt(bin);
+    if (result !== null) return { bin, result };
+  }
+  throw new NoMcpBinError(ref, candidates);
+}
+
 // ../probes/src/connect/index.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify } from "util";
 import { randomUUID as randomUUID3 } from "crypto";
+var execFileP = promisify(execFile2);
 var CLIENT_INFO = { name: "polygraph-litmus", version: "0.0.0" };
 async function connectTarget(input, opts = {}) {
   const isolated = opts.isolation === "docker";
-  let kind;
-  let descriptor;
-  let serverRef;
-  let resolvedVersion = null;
-  let transport;
-  const teardownExtra = [];
   if (typeof input !== "string") {
     if (isolated) {
       throw new IsolationUnsupportedError(
         "docker isolation is unsupported for an explicit stdio command \u2014 only an npm ref can be containerized"
       );
     }
-    kind = "stdio";
-    transport = new StdioClientTransport({
+    const transport2 = new StdioClientTransport({
       command: input.command,
       args: input.args ?? [],
       env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {}, ...input.env ?? {} },
       ...input.cwd ?? opts.seedCwd ? { cwd: input.cwd ?? opts.seedCwd } : {}
     });
     const cmdline = [input.command, ...input.args ?? []].join(" ");
-    descriptor = { kind, command: cmdline, url: null };
-    serverRef = input.serverRef ?? cmdline;
-  } else if (/^https?:\/\//i.test(input)) {
-    kind = "http";
+    const client2 = await connectOrThrow(transport2);
+    return makeResult(client2, "stdio", { kind: "stdio", command: cmdline, url: null }, input.serverRef ?? cmdline, null, []);
+  }
+  if (/^https?:\/\//i.test(input)) {
     await assertPublicHttpUrl(input);
     const headers = opts.httpHeaders && Object.keys(opts.httpHeaders).length > 0 ? opts.httpHeaders : void 0;
-    transport = new StreamableHTTPClientTransport(
+    const transport2 = new StreamableHTTPClientTransport(
       new URL(input),
       headers ? { requestInit: { headers }, fetch: sameOriginAuthFetch(input, headers) } : void 0
     );
-    descriptor = { kind, command: null, url: input };
-    serverRef = input;
-  } else {
-    const parsed = parseServerRef(input);
-    kind = "stdio";
-    if (isolated) {
-      if (parsed.registry !== "npm") {
-        throw new IsolationUnsupportedError(
-          `docker isolation is unsupported for ${parsed.registry} refs \u2014 only npm refs can be containerized`
-        );
-      }
-      const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
-      const stageOpts = opts.runLabel ? { runLabel: opts.runLabel } : {};
-      await ensureImage();
-      let staged = null;
-      let seed = null;
-      try {
-        staged = await stageNpmPackage(spec, stageOpts);
-        if (!opts.seedCwd) {
-          throw new Error("docker isolation requires a canary seed directory (seedCwd)");
-        }
-        seed = await prepareSeedVolume(opts.seedCwd, stageOpts);
-        const launch = containerLaunch({
-          entry: staged.entry,
-          stageVolume: staged.volume,
-          seedVolume: seed.volume,
-          // Canaries travel INTO the container via -e, NOT via the docker CLI's
-          // own env (the CLI runs on the secrets-bearing host).
-          canaryEnv: opts.seedEnv ?? {},
-          ...opts.runLabel ? { runLabel: opts.runLabel } : {},
-          ...process.env.LITMUS_DOCKER_RUNTIME ? { runtime: process.env.LITMUS_DOCKER_RUNTIME } : {}
-        });
-        const containerName = `pg-connect-${randomUUID3().slice(0, 8)}`;
-        const namedArgs = [launch.args[0], "--name", containerName, ...launch.args.slice(1)];
-        transport = new StdioClientTransport({
-          command: launch.command,
-          args: namedArgs,
-          // Default env only: no host secrets, no canaries (those are -e args).
-          env: getDefaultEnvironment()
-        });
-        descriptor = {
-          kind,
-          command: recordedContainerCommand(launch.command, launch.args, {
-            stageVolume: staged.volume,
-            seedVolume: seed.volume
-          }),
-          url: null
-        };
-        resolvedVersion = resolveStagedVersion(parsed.version, staged.resolvedVersion);
-        const stagedCleanup = staged.cleanup;
-        const seedCleanup = seed.cleanup;
-        teardownExtra.push(
-          () => docker(["rm", "-f", containerName]).then(() => {
-          }).catch(() => {
-          }),
-          stagedCleanup,
-          seedCleanup
-        );
-      } catch (err) {
-        if (seed) await seed.cleanup();
-        if (staged) await staged.cleanup();
-        throw err;
-      }
-      serverRef = serverKey(parsed);
-    } else {
-      const launch = launchForRef(parsed);
-      resolvedVersion = parsed.version ?? null;
-      transport = new StdioClientTransport({
+    const client2 = await connectOrThrow(transport2);
+    return makeResult(client2, "http", { kind: "http", command: null, url: input }, input, null, []);
+  }
+  const parsed = parseServerRef(input);
+  if (isolated) {
+    if (parsed.registry !== "npm") {
+      throw new IsolationUnsupportedError(
+        `docker isolation is unsupported for ${parsed.registry} refs \u2014 only npm refs can be containerized`
+      );
+    }
+    return connectIsolatedNpm(input, parsed, opts);
+  }
+  if (parsed.registry === "npm") {
+    return connectHostNpm(input, parsed, opts);
+  }
+  const launch = launchForRef(parsed);
+  const transport = new StdioClientTransport({
+    command: launch.command,
+    args: launch.args,
+    env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} },
+    ...opts.seedCwd ? { cwd: opts.seedCwd } : {}
+  });
+  const client = await connectOrThrow(transport);
+  return makeResult(
+    client,
+    "stdio",
+    { kind: "stdio", command: [launch.command, ...launch.args].join(" "), url: null },
+    serverKey(parsed),
+    parsed.version ?? null,
+    []
+  );
+}
+async function connectHostNpm(ref, parsed, opts) {
+  const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
+  const serverRefVal = serverKey(parsed);
+  const resolvedVersion = parsed.version ?? null;
+  const env = { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} };
+  const cwd = opts.seedCwd ? { cwd: opts.seedCwd } : {};
+  const binNames = await fetchNpmBins(spec, parsed.name);
+  if (!binNames || binNames.length === 0) {
+    const args = ["-y", spec];
+    const transport = new StdioClientTransport({ command: "npx", args, env, ...cwd });
+    const client = await connectOrThrow(transport);
+    return makeResult(client, "stdio", { kind: "stdio", command: ["npx", ...args].join(" "), url: null }, serverRefVal, resolvedVersion, []);
+  }
+  const candidates = orderBinCandidates(binNames, parsed.name);
+  const { result } = await probeForMcpBin(ref, candidates, async (bin) => {
+    const args = ["-y", "-p", spec, bin];
+    const transport = new StdioClientTransport({ command: "npx", args, env, ...cwd });
+    const client = await tryConnect(transport);
+    return client ? { client, descriptor: { kind: "stdio", command: ["npx", ...args].join(" "), url: null } } : null;
+  });
+  return makeResult(result.client, "stdio", result.descriptor, serverRefVal, resolvedVersion, []);
+}
+async function connectIsolatedNpm(ref, parsed, opts) {
+  const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
+  const stageOpts = opts.runLabel ? { runLabel: opts.runLabel } : {};
+  await ensureImage();
+  let staged = null;
+  let seed = null;
+  try {
+    staged = await stageNpmPackage(spec, stageOpts);
+    if (!opts.seedCwd) {
+      throw new Error("docker isolation requires a canary seed directory (seedCwd)");
+    }
+    seed = await prepareSeedVolume(opts.seedCwd, stageOpts);
+    const resolvedVersion = resolveStagedVersion(parsed.version, staged.resolvedVersion);
+    const stagedPkg = staged;
+    const seedVol = seed;
+    const candidates = orderBinCandidates(Object.keys(stagedPkg.bins), parsed.name);
+    const { result } = await probeForMcpBin(ref, candidates, async (binName) => {
+      const launch = containerLaunch({
+        entry: stagedPkg.bins[binName],
+        stageVolume: stagedPkg.volume,
+        seedVolume: seedVol.volume,
+        // Canaries travel INTO the container via -e, NOT via the docker CLI's own env.
+        canaryEnv: opts.seedEnv ?? {},
+        ...opts.runLabel ? { runLabel: opts.runLabel } : {},
+        ...process.env.LITMUS_DOCKER_RUNTIME ? { runtime: process.env.LITMUS_DOCKER_RUNTIME } : {}
+      });
+      const containerName = `pg-connect-${randomUUID3().slice(0, 8)}`;
+      const namedArgs = [launch.args[0], "--name", containerName, ...launch.args.slice(1)];
+      const transport = new StdioClientTransport({
         command: launch.command,
-        args: launch.args,
-        env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} },
-        ...opts.seedCwd ? { cwd: opts.seedCwd } : {}
+        args: namedArgs,
+        env: getDefaultEnvironment()
+        // default env only: no host secrets, no canaries
       });
-      descriptor = { kind, command: [launch.command, ...launch.args].join(" "), url: null };
-      serverRef = serverKey(parsed);
-    }
+      const client = await tryConnect(transport);
+      if (!client) {
+        await docker(["rm", "-f", containerName]).then(() => {
+        }).catch(() => {
+        });
+        return null;
+      }
+      const descriptor = {
+        kind: "stdio",
+        command: recordedContainerCommand(launch.command, launch.args, {
+          stageVolume: stagedPkg.volume,
+          seedVolume: seedVol.volume
+        }),
+        url: null
+      };
+      return { client, descriptor, containerName };
+    });
+    const teardownExtra = [
+      () => docker(["rm", "-f", result.containerName]).then(() => {
+      }).catch(() => {
+      }),
+      staged.cleanup,
+      seed.cleanup
+    ];
+    return makeResult(result.client, "stdio", result.descriptor, serverKey(parsed), resolvedVersion, teardownExtra);
+  } catch (err) {
+    if (seed) await seed.cleanup();
+    if (staged) await staged.cleanup();
+    throw err;
+  }
+}
+async function fetchNpmBins(spec, pkgName) {
+  try {
+    const { stdout } = await execFileP("npm", ["view", spec, "bin", "--json"], { timeout: 2e4 });
+    return parseNpmBins(stdout, pkgName);
+  } catch {
+    return null;
   }
+}
+async function tryConnect(transport) {
   const client = new Client(CLIENT_INFO, { capabilities: {} });
   try {
     await withConnectTimeout(client.connect(transport), transport);
-  } catch (err) {
-    for (const c of teardownExtra) await c();
-    throw err;
+    return client;
+  } catch {
+    try {
+      await client.close();
+    } catch {
+    }
+    return null;
   }
+}
+async function connectOrThrow(transport) {
+  const client = new Client(CLIENT_INFO, { capabilities: {} });
+  await withConnectTimeout(client.connect(transport), transport);
+  return client;
+}
+function makeResult(client, kind, descriptor, serverRef, resolvedVersion, teardownExtra) {
   return {
     client,
     kind,
@@ -549,10 +656,6 @@ async function withConnectTimeout(connecting, transport) {
   }
 }
 function launchForRef(p) {
-  if (p.registry === "npm") {
-    const spec = (p.owner ? `${p.owner}/${p.name}` : p.name) + (p.version ? `@${p.version}` : "");
-    return { command: "npx", args: ["-y", spec] };
-  }
   if (p.registry === "pypi") {
     return { command: "uvx", args: [p.version ? `${p.name}@${p.version}` : p.name] };
   }
@@ -929,9 +1032,29 @@ async function c01Injection(ctx) {
 
 // ../probes/src/docker/egress-runner.ts
 import { randomUUID as randomUUID4 } from "crypto";
+
+// ../probes/src/probes/host-match.ts
+function normalizeHost(h) {
+  let s = h.trim().toLowerCase();
+  const colon = s.indexOf(":");
+  if (colon !== -1) s = s.slice(0, colon);
+  if (s.endsWith(".")) s = s.slice(0, -1);
+  return s;
+}
+function hostMatchesPattern(host, pattern) {
+  const h = normalizeHost(host);
+  const p = pattern.trim().toLowerCase();
+  if (p.startsWith("*.")) {
+    const suffix = p.slice(1);
+    return h.endsWith(suffix) && h.length > suffix.length;
+  }
+  return h === p;
+}
+
+// ../probes/src/docker/egress-runner.ts
 var IMAGE_TAG3 = "polygraph-egress-sniff:latest";
 function notRan(reason) {
-  return { ran: false, reason, attempts: [] };
+  return { ran: false, reason, attempts: [], declaredEgress: [], baselineAllowlist: [] };
 }
 function parseSinkholeOutput(output) {
   const attempts = [];
@@ -963,6 +1086,40 @@ function egressToFindings(attempts) {
     ...a.firstBytes !== void 0 ? { firstBytes: a.firstBytes } : {}
   }));
 }
+function correlateEgress(attempts) {
+  const pendingDnsHosts = [];
+  const out = [];
+  for (const a of attempts) {
+    if (a.kind === "dns") {
+      out.push({ ...a, hostSource: a.host ? "given" : "none" });
+      if (a.host) pendingDnsHosts.push(a.host);
+    } else if (a.host) {
+      out.push({ ...a, hostSource: "given" });
+    } else {
+      const host = pendingDnsHosts.shift();
+      out.push({ ...a, ...host ? { host } : {}, hostSource: host ? "dns-correlation" : "none" });
+    }
+  }
+  return out;
+}
+function classifyEgress(correlated, allowlist) {
+  return correlated.map((c) => {
+    if (c.host !== void 0) {
+      const matchedPattern = allowlist.find((p) => hostMatchesPattern(c.host, p));
+      return matchedPattern ? { ...c, allowed: true, matchedPattern } : { ...c, allowed: false };
+    }
+    return { ...c, allowed: false };
+  });
+}
+function egressAllowedFindings(classified) {
+  return classified.filter((c) => c.allowed).map((c) => ({
+    kind: "egress-allowed",
+    severity: "low",
+    match: `${c.host ?? "?"}${c.port ? `:${c.port}` : ""} (allowed: ${c.matchedPattern ?? "?"})`,
+    ...c.host !== void 0 ? { host: c.host } : {},
+    ...c.port !== void 0 ? { port: c.port } : {}
+  }));
+}
 function egressCanaryFindings(attempts, canaries) {
   const findings = [];
   for (const a of attempts) {
@@ -1041,7 +1198,8 @@ async function runEgressProbe(ref, opts) {
       if (msg.includes("exposes no launchable bin")) return notRan(msg);
       throw err;
     }
-    const { volume: vol, entry } = staged;
+    const vol = staged.volume;
+    const entry = staged.bins[orderBinCandidates(Object.keys(staged.bins), parsed.name)[0]];
     await docker(["network", "create", "--internal", ...label, net]);
     await docker([
       "run",
@@ -1081,7 +1239,13 @@ async function runEgressProbe(ref, opts) {
       await conn.teardown();
     }
     const logs = await docker(["logs", sink]);
-    return { ran: true, reason: null, attempts: parseSinkholeOutput(logs) };
+    return {
+      ran: true,
+      reason: null,
+      attempts: parseSinkholeOutput(logs),
+      declaredEgress: staged.declaredEgress,
+      baselineAllowlist: opts.baselineAllowlist ?? []
+    };
   } catch (err) {
     return notRan(`egress sandbox unavailable: ${err instanceof Error ? err.message : String(err)}`);
   } finally {
@@ -1095,6 +1259,28 @@ async function runEgressProbe(ref, opts) {
   }
 }
 
+// ../probes/src/probes/egress-allowlist.ts
+var DEFAULT_EGRESS_BASELINE = [];
+function normalizePattern(p) {
+  return p.trim().toLowerCase();
+}
+function parseAllowlistEnv(raw) {
+  if (!raw) return [];
+  return raw.split(",").map(normalizePattern).filter((s) => s.length > 0);
+}
+function effectiveAllowlist(baseline, declared) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const p of [...baseline, ...declared]) {
+    const n = normalizePattern(p);
+    if (n.length > 0 && !seen.has(n)) {
+      seen.add(n);
+      out.push(n);
+    }
+  }
+  return out;
+}
+
 // ../probes/src/probes/c02-egress.ts
 function probe21Declaration(tools) {
   const findings = [];
@@ -1113,8 +1299,18 @@ function probe21Declaration(tools) {
 }
 function probe22Egress(egress) {
   if (!egress.ran) return { id: "2.2", status: "skipped", findings: [], reason: egress.reason };
-  const findings = egressToFindings(egress.attempts);
-  return { id: "2.2", status: findings.length > 0 ? "fail" : "pass", findings };
+  const allowlist = effectiveAllowlist(egress.baselineAllowlist, egress.declaredEgress);
+  const classified = classifyEgress(correlateEgress(egress.attempts), allowlist);
+  const overreach = classified.filter((c) => !c.allowed);
+  const allowed = classified.filter((c) => c.allowed);
+  const findings = [...egressToFindings(overreach), ...egressAllowedFindings(allowed)];
+  if (overreach.length > 0) return { id: "2.2", status: "fail", findings };
+  return {
+    id: "2.2",
+    status: "pass",
+    findings,
+    reason: allowed.length > 0 ? `${allowed.length} declared/baseline egress attempt(s) permitted; 0 overreach` : null
+  };
 }
 function c02Permission(declaration, egress) {
   const egressProbe = probe22Egress(egress);
@@ -1245,11 +1441,14 @@ function gradeFromCategories(categories) {
   if (c02?.status === "fail") {
     return {
       grade: "D",
-      rationale: "Unexpected egress (C-02 failed); no injection or data leak. Egress is serious but not proven exfiltration, so the grade caps at D."
+      rationale: "Egress overreach (C-02 failed): reached a host outside its declared/baseline allowlist (or mislabeled a tool). No injection or data leak, so the grade caps at D."
     };
   }
   if (c01?.status === "pass" && c02?.status === "pass" && c03?.status === "pass") {
-    return { grade: "A", rationale: "All three categories passed. No injection, no unexpected egress, no data leak." };
+    return {
+      grade: "A",
+      rationale: "All three categories passed. No injection, no data leak, and no egress overreach \u2014 declared/baseline egress, if any, was permitted (A means no overreach, not no network)."
+    };
   }
   if (c01?.status === "pass") {
     const note = skipped.length ? ` Not verified: ${skipped.join(", ")} (${skipped.map((c) => byCode(c)?.reason).filter(Boolean).join("; ")}).` : "";
@@ -1304,6 +1503,7 @@ function assembleBundle(input) {
 async function runLitmus(target, opts = {}) {
   const isolation = opts.isolation ?? (process.env.LITMUS_STDIO_ISOLATION === "docker" ? "docker" : "none");
   const ranAt = (/* @__PURE__ */ new Date()).toISOString();
+  const baselineAllowlist = [...DEFAULT_EGRESS_BASELINE, ...parseAllowlistEnv(process.env.LITMUS_EGRESS_ALLOWLIST)];
   const dockerAvailable = await checkDocker();
   const canaries = mintCanaries();
   const seedEnv = canaryEnv(canaries);
@@ -1344,10 +1544,12 @@ async function runLitmus(target, opts = {}) {
         stateChangingTools,
         allowStateChanging: opts.allowStateChanging ?? false
       };
-      const egress = dockerAvailable && typeof target === "string" && !/^https?:\/\//i.test(target) ? await runEgressProbe(target, { canaryEnv: seedEnv, ...opts.runLabel ? { runLabel: opts.runLabel } : {} }) : {
+      const egress = dockerAvailable && typeof target === "string" && !/^https?:\/\//i.test(target) ? await runEgressProbe(target, { canaryEnv: seedEnv, baselineAllowlist, ...opts.runLabel ? { runLabel: opts.runLabel } : {} }) : {
         ran: false,
         reason: dockerAvailable ? "egress not run for this target" : "no sandbox (Docker unavailable)",
-        attempts: []
+        attempts: [],
+        declaredEgress: [],
+        baselineAllowlist: []
       };
       assertEgressRanUnderIsolation(egress, isolation, isStdio);
       const categories = [
@@ -1359,7 +1561,9 @@ async function runLitmus(target, opts = {}) {
       return assembleBundle({
         serverRef: conn.serverRef,
         resolvedVersion: conn.resolvedVersion,
-        target: conn.descriptor,
+        // Surface the server's declared egress in the bundle (disclosure: a
+        // declaration is not exoneration — the consumer/agent-gate can judge).
+        target: egress.declaredEgress.length ? { ...conn.descriptor, declaredEgress: egress.declaredEgress } : conn.descriptor,
         toolDefsFingerprint: fingerprint,
         toolDefs: canonical,
         categories,
@@ -1437,7 +1641,7 @@ function withTimeout(p, ms, label) {
 }
 function checkDocker() {
   return new Promise((resolve) => {
-    const child = execFile2("docker", ["info"], { timeout: 4e3 }, (err) => resolve(!err));
+    const child = execFile3("docker", ["info"], { timeout: 4e3 }, (err) => resolve(!err));
     child.on("error", () => resolve(false));
   });
 }

package/dist/{chunk-JK3UGN2G.js → chunk-UA4BIHP4.js}

@@ -1,13 +1,13 @@
 import {
   resolveTarget
-} from "./chunk-BIALP22F.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   runLitmus
-} from "./chunk-2K6T4FZX.js";
+} from "./chunk-MB5EPL2V.js";
 import {
   CATEGORY_STATUS_UINT8,
   METHODOLOGY_VERSION
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../onchain/src/networks.ts
 var NETWORKS = {

package/dist/{chunk-BIALP22F.js → chunk-WBXHDYIV.js}

@@ -1,6 +1,6 @@
 import {
   canonicalStringify
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../cli/src/litmus.ts
 import { existsSync } from "fs";
@@ -44,7 +44,7 @@ async function runLitmusCli(args) {
     );
     return 2;
   }
-  const { runLitmus } = await import("./src-XIEFSTXC.js");
+  const { runLitmus } = await import("./src-PTK3WEGQ.js");
   const input = resolveTarget(target);
   try {
     const bundle = await runLitmus(input, { headers, allowStateChanging });

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   runLitmusCli
-} from "./chunk-BIALP22F.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";

package/dist/index.d.ts

@@ -11,13 +11,16 @@ import { z } from 'zod';
 /** Package registries a server ref can name. */
 type Registry = "npm" | "pypi" | "github";
 /** The methodology this build implements; embedded in every bundle + attestation.
- *  v2 adds C-02 probe 2.1 (declared-permission honesty), a new fail condition —
- *  a pass/fail-semantics change, so the version bumps per litmus-test §8. */
-declare const METHODOLOGY_VERSION: "litmus-v2";
+ *  v3 reframes C-02 probe 2.2 from default-deny (any egress fails) to OVERREACH:
+ *  egress to a host the server declared (`polygraph.egress`) or on the operator
+ *  baseline allowlist is permitted; only egress beyond that union fails. A
+ *  pass/fail-semantics change → version bumps per litmus-test §8. NOTE: under v3,
+ *  grade "A" means "no overreach", NOT "no network". (v2 added probe 2.1.) */
+declare const METHODOLOGY_VERSION: "litmus-v3";
 /** Evidence-bundle format version (owned by onchain-proof-spec §2).
- *  1.1.0 adds the optional `harness.stdioIsolation` field and permits the
- *  disclaimer to vary by run mode; 1.0.0 bundles remain valid. */
-declare const BUNDLE_SCHEMA_VERSION: "1.1.0";
+ *  1.2.0 adds the optional `target.declaredEgress` field and the `egress-allowed`
+ *  finding kind (litmus-v3); 1.1.0 adds `harness.stdioIsolation`; older remain valid. */
+declare const BUNDLE_SCHEMA_VERSION: "1.2.0";
 type CategoryCode = "C-01" | "C-02" | "C-03" | "C-04";
 /** Probe IDs carry their family number (1=injection, 2=permission, 4=sensitive). */
 type ProbeId = "1.1" | "1.2" | "2.1" | "2.2" | "4.1" | "4.2";
@@ -27,7 +30,7 @@ type LitmusGrade = "A" | "B" | "C" | "D" | "F";
 type Severity = "low" | "medium" | "high";
 /** uint8 encoding for per-category verdicts on the attestation (onchain-proof-spec §5). */
 declare const CATEGORY_STATUS_UINT8: Record<CategoryStatus, number>;
-type FindingKind = "invisible-unicode" | "instruction-mimicry" | "markdown-trick" | "canary" | "egress" | "permission-mislabel";
+type FindingKind = "invisible-unicode" | "instruction-mimicry" | "markdown-trick" | "canary" | "egress" | "egress-allowed" | "permission-mislabel";
 interface Finding {
     kind: FindingKind;
     severity: Severity;
@@ -61,6 +64,9 @@ interface TargetDescriptor {
     command?: string | null;
     /** http: the remote MCP URL. */
     url?: string | null;
+    /** The server's declared egress host patterns (`polygraph.egress`, C-02
+     *  litmus-v3). Present only when non-empty. Disclosure, not exoneration. */
+    declaredEgress?: string[];
 }
 /** The canonicalized fields of a tool that the fingerprint hashes. */
 interface ToolDef {
@@ -159,6 +165,11 @@ declare function canonicalStringify(value: unknown): string;
  * - an explicit `{command,args}` (for in-repo demo servers and tests) launches
  *   over stdio directly.
  *
+ * For an npm ref the package may ship several bins (e.g. a CLI plus a `*-mcp`
+ * server) or a default bin that isn't an MCP server. We enumerate the bins and
+ * PROBE them in order (mcp-named first), keeping the first that completes the MCP
+ * handshake — so a CLI-first or multi-bin package still grades.
+ *
  * Returns the connected `Client`, a descriptor for the evidence bundle, and a
  * teardown. The normal MCP handshake (`initialize`) happens inside `connect()`.
  */

package/dist/index.js

@@ -14,11 +14,11 @@ import {
   rpcUrl,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-JK3UGN2G.js";
+} from "./chunk-UA4BIHP4.js";
 import {
   parseAuthFlags,
   resolveTarget
-} from "./chunk-BIALP22F.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   assembleBundle,
   canaryMatch,
@@ -32,7 +32,7 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-2K6T4FZX.js";
+} from "./chunk-MB5EPL2V.js";
 import {
   BUNDLE_SCHEMA_VERSION,
   CATEGORY_STATUS_UINT8,
@@ -42,7 +42,7 @@ import {
   formatServerRef,
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../agent/src/gate.ts
 function sameServer(a, b) {

package/dist/mcp.js

@@ -7,13 +7,13 @@ import {
   readAttestation,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-JK3UGN2G.js";
-import "./chunk-BIALP22F.js";
-import "./chunk-2K6T4FZX.js";
+} from "./chunk-UA4BIHP4.js";
+import "./chunk-WBXHDYIV.js";
+import "./chunk-MB5EPL2V.js";
 import {
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // src/mcp.ts
 import { realpathSync } from "fs";

package/dist/{src-XIEFSTXC.js → src-PTK3WEGQ.js}

@@ -11,8 +11,8 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-2K6T4FZX.js";
-import "./chunk-SAZKXB35.js";
+} from "./chunk-MB5EPL2V.js";
+import "./chunk-K7UEK2BA.js";
 export {
   assembleBundle,
   canaryMatch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraphso/litmus",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Behavioral litmus harness for MCP servers — grade a server A–F (tool-output injection, egress, sensitive-data) with reproducible, content-addressed evidence. Ships a CLI and an MCP server with a run_litmus tool for AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://polygraph.so",
@@ -58,10 +58,10 @@
     "typescript": "^5.9.3",
     "vitest": "^2.1.0",
     "@polygraph/core": "0.0.0",
-    "@polygraph/onchain": "0.0.0",
     "@polygraph/probes": "0.0.0",
-    "@polygraph/agent": "0.0.0",
+    "@polygraph/onchain": "0.0.0",
     "@polygraph/mcp": "0.0.0",
+    "@polygraph/agent": "0.0.0",
     "@polygraph/cli": "0.0.0"
   },
   "publishConfig": {