dsh-plugin-inspector 0.6.0 → 0.7.0

package/README.md

@@ -45,7 +45,8 @@ node lib/cli.js --help
 dsh-inspect <target> [options]
 dsh-inspect --from-npm <name>[@<version>] [options]
 
-  --from-npm <spec>       Fetch from the registry, verify dist.integrity, analyse in memory.
+  --from-npm <spec>       Fetch from the registry, verify dist.integrity, read the
+                          provenance attestation if there is one, analyse in memory.
   --registry <url>        Registry base URL for --from-npm.
   --json                  Emit the machine-readable JSON document on stdout.
   --fail-on <severity>    Exit 1 at or above this severity.  (default: high)
@@ -100,13 +101,14 @@ pnpm run test:coverage
 pnpm run test:e2e
 ```
 
-Severity calibration is pinned against a corpus of forty published packages, in
-`tests/ecosystem-baseline.json`. **The sweep is not part of CI** — every other workflow here runs
-without a network, which is what lets the unit suite claim that analysing a package touches nothing
-outside the process — so it runs as a weekly cron and on request, and a change that starts firing
-on ordinary code does not fail the pull request that makes it. What catches it is the release: the
-baseline records the build that measured it and a unit test fails unless that matches the version
-in `package.json`, so a version bump is not finished until the sweep has been re-run against it.
+Two checks need a network and are therefore **not part of CI**, which is what lets the unit suite
+claim that analysing a package touches nothing outside the process. Both run on a weekly cron and
+on request. `pnpm run sweep` measures severity calibration against a corpus of forty published
+packages, pinned in `tests/ecosystem-baseline.json`; the baseline records the build that measured
+it and a unit test fails unless that matches the version in `package.json`, so a version bump is
+not finished until the sweep has been re-run against it. `pnpm run sync` diffs the harness ground
+truth in `src/knowledge.ts` against a published harness release, because every Tier A verdict is a
+claim about what one harness version does with a declaration.
 
 Design decisions and their rationale live in [ADR.md](ADR.md). Security policy is in
 [SECURITY.md](SECURITY.md).

package/lib/attestation.js

@@ -0,0 +1,374 @@
+/**
+ * npm provenance attestations: what the registry says about where a published
+ * tarball was built, and how much of that this tool can check for itself.
+ *
+ * A provenance attestation is a Sigstore bundle holding a DSSE envelope over an
+ * in-toto statement. The statement names the tarball by digest and, for a
+ * GitHub Actions build, the source repository, the commit, and the workflow
+ * file that produced it. npm publishes one when a package is released from a
+ * trusted CI environment.
+ *
+ * **This module is careful about the difference between reading a claim and
+ * checking one, because a reader who confuses them is worse off than one who
+ * has neither.** Everything it can check runs offline against bytes already in
+ * hand, and everything it cannot check is named in the same record:
+ *
+ * - `subject-digest` — the statement's subject digest is the SHA-512 of the
+ *   tarball this run analysed. This is the binding that makes the rest mean
+ *   anything: without it the attestation could be about another version.
+ * - `subject-package` — that subject is this package at this version, written
+ *   as a package URL.
+ * - `dsse-signature` — the envelope's signature verifies under the public key
+ *   of the certificate carried inside the bundle.
+ * - `certificate-identity` — the certificate's subject alternative name is the
+ *   workflow the statement claims built the package, so payload and signer
+ *   agree.
+ *
+ * What it does **not** do is establish that the certificate is Sigstore's. That
+ * needs the Fulcio root, which lives in the Sigstore trust root and not on any
+ * npm registry, and the same root is what a Rekor inclusion proof is checked
+ * against. Without it these four checks prove the bundle is internally
+ * consistent and is about these exact bytes — not that the identity in it is
+ * real. Those gaps are listed in {@link ProvenanceFact.notChecked} and printed
+ * in the report, so no reader has to infer them.
+ * @module dsh-plugin-inspector/attestation
+ */
+import { X509Certificate, createHash, createVerify } from 'node:crypto';
+/** The SLSA predicate type npm publishes a build provenance statement under. */
+export const PROVENANCE_PREDICATE_TYPE = 'https://slsa.dev/provenance/v1';
+/**
+ * Largest attestation document the tool will read. Real bundles are tens of
+ * kilobytes; the transparency-log inclusion proof is most of that.
+ */
+export const MAX_ATTESTATION_BYTES = 1024 * 1024;
+/** Gaps that hold for every attestation, whatever is in it. */
+const UNCONDITIONAL_GAPS = ['certificate-chain', 'transparency-log'];
+/** A fact carrying no attestation, with every claim spelled out as absent. */
+const NOTHING = {
+    predicateType: null,
+    sourceRepository: null,
+    sourceCommit: null,
+    sourceRef: null,
+    workflow: null,
+    builder: null,
+    signerIdentity: null,
+    checks: [],
+    notChecked: [],
+};
+/**
+ * The fact for a target that has no registry statement: a directory, or a
+ * tarball on disk. Stated rather than reported as an absence, because "this
+ * package has no provenance" and "this mode cannot read provenance" are
+ * different answers and only one of them is about the package.
+ * @returns the fact.
+ */
+export function provenanceUnavailable() {
+    return {
+        ...NOTHING,
+        state: 'unavailable',
+        reason: 'a directory or local tarball carries no registry attestation; --from-npm reads one',
+        attestationUrl: null,
+    };
+}
+/**
+ * The fact for a published package whose version document declares no
+ * provenance attestation.
+ * @returns the fact.
+ */
+export function provenanceAbsent() {
+    return { ...NOTHING, state: 'absent', reason: null, attestationUrl: null };
+}
+/**
+ * The fact for an attestation the registry named but this run could not read.
+ * @param url - the endpoint that was asked, or `null` when none could be built.
+ * @param reason - what went wrong.
+ * @returns the fact.
+ */
+export function provenanceUnreadable(url, reason) {
+    return { ...NOTHING, state: 'unreadable', reason, attestationUrl: url };
+}
+/**
+ * Narrow an unknown JSON value to a record, so a hostile document's
+ * `attestations: 7` reads as "no fields" rather than throwing further down.
+ * @param value - the parsed JSON value.
+ * @returns the value as a record, or an empty one.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Read a string field, or `null` when it is absent or of another type.
+ * @param record - the containing record.
+ * @param key - the field name.
+ * @returns the string, or `null`.
+ */
+function asString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * The package URL npm writes an attestation subject's name as. A scope's `@`
+ * is percent-encoded there and nowhere else in the document.
+ * @param name - the package name.
+ * @param version - the resolved version.
+ * @returns the package URL.
+ */
+export function packageUrl(name, version) {
+    return `pkg:npm/${name.replace(/^@/, '%40')}@${version}`;
+}
+/**
+ * The pre-authentication encoding DSSE signs: the payload type and the payload,
+ * each preceded by its length, so neither can be shifted into the other.
+ * @param payloadType - the envelope's declared payload type.
+ * @param payload - the decoded payload.
+ * @returns the bytes the signature covers.
+ */
+function preAuthenticationEncoding(payloadType, payload) {
+    const type = Buffer.from(payloadType, 'utf8');
+    return Buffer.concat([
+        Buffer.from(`DSSEv1 ${type.length} `, 'utf8'),
+        type,
+        Buffer.from(` ${payload.length} `, 'utf8'),
+        payload,
+    ]);
+}
+/**
+ * The signing certificate a Sigstore bundle carries. Bundle media type 0.2
+ * carries a chain and 0.3 carries the leaf alone; npm publishes both, so both
+ * are read.
+ * @param material - the bundle's `verificationMaterial`.
+ * @returns the leaf certificate's DER bytes, or `null`.
+ */
+function leafCertificate(material) {
+    const single = asString(asRecord(material.certificate), 'rawBytes');
+    if (single !== null)
+        return Buffer.from(single, 'base64');
+    const chain = asRecord(material.x509CertificateChain).certificates;
+    if (!Array.isArray(chain))
+        return null;
+    const first = asString(asRecord(chain[0]), 'rawBytes');
+    return first === null ? null : Buffer.from(first, 'base64');
+}
+/** Raised for an attestation document this tool cannot read at all. */
+class UnreadableAttestation extends Error {
+}
+/**
+ * Pull the provenance bundle out of a registry attestation document.
+ * @param body - the document as served.
+ * @returns the parts the checks read.
+ * @throws UnreadableAttestation when the document holds no readable provenance bundle.
+ */
+function decode(body) {
+    let document;
+    try {
+        document = JSON.parse(body.toString('utf8'));
+    }
+    catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new UnreadableAttestation(`the attestation endpoint did not return JSON: ${detail}`);
+    }
+    const list = asRecord(document).attestations;
+    const entries = Array.isArray(list) ? list.map(asRecord) : [];
+    const entry = entries.find(candidate => asString(candidate, 'predicateType') === PROVENANCE_PREDICATE_TYPE);
+    if (entry === undefined) {
+        throw new UnreadableAttestation(`the document carries no ${PROVENANCE_PREDICATE_TYPE} attestation`);
+    }
+    const bundle = asRecord(entry.bundle);
+    const der = leafCertificate(asRecord(bundle.verificationMaterial));
+    if (der === null)
+        throw new UnreadableAttestation('the bundle carries no signing certificate');
+    let certificate;
+    try {
+        certificate = new X509Certificate(der);
+    }
+    catch (error) {
+        /* v8 ignore next -- X509Certificate rejects bytes only with an Error. */
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new UnreadableAttestation(`the bundle's signing certificate does not parse: ${detail}`);
+    }
+    const envelope = asRecord(bundle.dsseEnvelope);
+    const encoded = asString(envelope, 'payload');
+    const payloadType = asString(envelope, 'payloadType');
+    const signatures = envelope.signatures;
+    const signature = Array.isArray(signatures) ? asString(asRecord(signatures[0]), 'sig') : null;
+    if (encoded === null || payloadType === null || signature === null) {
+        throw new UnreadableAttestation('the bundle carries no complete DSSE envelope');
+    }
+    const payload = Buffer.from(encoded, 'base64');
+    let statement;
+    try {
+        statement = JSON.parse(payload.toString('utf8'));
+    }
+    catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new UnreadableAttestation(`the signed statement is not JSON: ${detail}`);
+    }
+    return {
+        certificate,
+        payload,
+        payloadType,
+        signature: Buffer.from(signature, 'base64'),
+        statement: asRecord(statement),
+    };
+}
+/**
+ * Read the build claims out of a SLSA v1 predicate.
+ * @param statement - the decoded in-toto statement.
+ * @returns what it says about the source and the builder.
+ */
+function readClaims(statement) {
+    const predicate = asRecord(statement.predicate);
+    const definition = asRecord(predicate.buildDefinition);
+    const workflow = asRecord(asRecord(definition.externalParameters).workflow);
+    const dependencies = definition.resolvedDependencies;
+    const source = asRecord(Array.isArray(dependencies) ? dependencies[0] : undefined);
+    return {
+        repository: asString(workflow, 'repository'),
+        commit: asString(asRecord(source.digest), 'gitCommit'),
+        ref: asString(workflow, 'ref'),
+        workflow: asString(workflow, 'path'),
+        builder: asString(asRecord(asRecord(predicate.runDetails).builder), 'id'),
+    };
+}
+/**
+ * Every subject the statement names, as name and SHA-512 pairs.
+ * @param statement - the decoded in-toto statement.
+ * @returns one entry per subject the document could be read for.
+ */
+function readSubjects(statement) {
+    const subjects = statement.subject;
+    if (!Array.isArray(subjects))
+        return [];
+    return subjects.map(asRecord).map(subject => ({
+        name: asString(subject, 'name'),
+        sha512: asString(asRecord(subject.digest), 'sha512'),
+    }));
+}
+/**
+ * Verify the DSSE signature under the public key of the certificate in the
+ * bundle.
+ *
+ * A failure here is a bundle whose payload and signature disagree. A success
+ * says only that; it says nothing about who holds the key, which is the gap
+ * `certificate-chain` names.
+ * @param bundle - the decoded bundle.
+ * @returns the check result.
+ */
+function checkSignature(bundle) {
+    const signed = preAuthenticationEncoding(bundle.payloadType, bundle.payload);
+    let passed;
+    try {
+        const verifier = createVerify('sha256');
+        verifier.update(signed);
+        verifier.end();
+        passed = verifier.verify(bundle.certificate.publicKey, bundle.signature);
+    }
+    catch (error) {
+        /* v8 ignore next -- `verify` refuses a key it cannot use only with an Error. */
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'dsse-signature',
+            detail: `the signature could not be checked against the bundle's certificate: ${detail}`,
+            passed: false,
+        };
+    }
+    return {
+        name: 'dsse-signature',
+        detail: passed
+            ? 'the DSSE signature verifies under the public key of the certificate in the bundle'
+            : 'the DSSE signature does not verify under the public key of the certificate in the bundle',
+        passed,
+    };
+}
+/**
+ * Compare the certificate's subject alternative name against the workflow the
+ * statement claims. Fulcio writes the workflow identity there as
+ * `<repository>/<path>@<ref>`, so the two are the same claim from two places in
+ * the bundle and a mismatch means one of them was swapped.
+ * @param bundle - the decoded bundle.
+ * @param claims - what the statement says about the build.
+ * @returns the check, or `null` when the statement names no workflow to compare.
+ */
+function checkIdentity(bundle, claims) {
+    if (claims.repository === null || claims.workflow === null || claims.ref === null)
+        return null;
+    const expected = `${claims.repository}/${claims.workflow}@${claims.ref}`;
+    const names = (bundle.certificate.subjectAltName ?? '').split(', ');
+    const passed = names.includes(`URI:${expected}`);
+    return {
+        name: 'certificate-identity',
+        detail: passed
+            ? `the signing certificate names ${expected}, which is the workflow the statement claims`
+            : `the statement claims ${expected} but the signing certificate names `
+                + `${bundle.certificate.subjectAltName ?? 'nothing'}`,
+        passed,
+    };
+}
+/**
+ * Check a fetched attestation document against the tarball this run analysed.
+ *
+ * The digest comparison is the load-bearing one: it is what ties the statement
+ * to these bytes rather than to some other version of the same package. The
+ * bytes handed in are the ones `dist.integrity` already vouched for, so a pass
+ * here means one chain of digests runs from the version document through the
+ * download to the signed statement.
+ * @param body - the attestation document as served.
+ * @param subject - the package the document is supposed to be about.
+ * @returns the fact, in state `attested`, `failed`, or `unreadable`.
+ */
+export function readProvenance(body, subject) {
+    let bundle;
+    try {
+        bundle = decode(body);
+    }
+    catch (error) {
+        /* v8 ignore next -- `decode` reports every refusal as an UnreadableAttestation. */
+        if (!(error instanceof UnreadableAttestation))
+            throw error;
+        return provenanceUnreadable(subject.url, error.message);
+    }
+    const claims = readClaims(bundle.statement);
+    const subjects = readSubjects(bundle.statement);
+    const digest = createHash('sha512').update(subject.tarball).digest('hex');
+    const expectedName = packageUrl(subject.name, subject.version);
+    const digestMatched = subjects.some(entry => entry.sha512 === digest);
+    const nameMatched = subjects.some(entry => entry.name === expectedName);
+    const identity = checkIdentity(bundle, claims);
+    const checks = [
+        {
+            name: 'subject-digest',
+            detail: digestMatched
+                ? 'the statement covers the exact bytes this run analysed, by SHA-512'
+                : `the statement covers no artifact with the SHA-512 of the downloaded tarball (${digest})`,
+            passed: digestMatched,
+        },
+        {
+            name: 'subject-package',
+            detail: nameMatched
+                ? `the statement is about ${expectedName}`
+                : `the statement names ${subjects.map(entry => entry.name ?? '(unnamed)').join(', ') || 'no subject'}`
+                    + `, not ${expectedName}`,
+            passed: nameMatched,
+        },
+        checkSignature(bundle),
+        ...identity === null ? [] : [identity],
+    ];
+    return {
+        state: checks.every(check => check.passed) ? 'attested' : 'failed',
+        reason: null,
+        predicateType: PROVENANCE_PREDICATE_TYPE,
+        sourceRepository: claims.repository,
+        sourceCommit: claims.commit,
+        sourceRef: claims.ref,
+        workflow: claims.workflow,
+        builder: claims.builder,
+        signerIdentity: bundle.certificate.subjectAltName ?? null,
+        attestationUrl: subject.url,
+        checks,
+        notChecked: identity === null ? [...UNCONDITIONAL_GAPS, 'builder-identity'] : UNCONDITIONAL_GAPS,
+    };
+}

package/lib/checks/tier-a.js

@@ -725,6 +725,46 @@ function checkInjectionText(input) {
     }
     return findings;
 }
+/**
+ * A25 — a provenance attestation that does not check out.
+ *
+ * Only a `failed` fact reaches here, and `failed` means the registry published
+ * an attestation for these bytes and one of the checks in `attestation.ts`
+ * contradicted it. That is a narrow claim on purpose:
+ *
+ * - **Absence is not this finding, and no severity fires on it.** 28 of the 40
+ *   packages in the pinned corpus publish no attestation at all. A finding on
+ *   the majority of legitimate packages is the miscalibration the 0.2 release
+ *   existed to remove, so absence is reported as a fact and nothing else.
+ * - **This is not an attack detector.** A publisher who wants no provenance
+ *   simply publishes none, which produces no finding, so nothing here can be
+ *   evaded by making it fail. What it catches is an attestation that is real
+ *   and does not describe this download: the wrong artifact, a mirror serving
+ *   one version's bundle for another, or a payload edited after signing.
+ * - It is Tier A because it is decidable. The comparisons are digests and a
+ *   signature over bytes already in hand, with no heuristic anywhere in them.
+ */
+function checkProvenance(input) {
+    const { provenance } = input;
+    if (provenance.state !== 'failed')
+        return [];
+    const failed = provenance.checks.filter(check => !check.passed);
+    return failed.map(check => tierA({
+        checkId: 'A25',
+        name: 'provenance-mismatch',
+        subject: check.name,
+        severity: 'high',
+        title: `Provenance attestation fails its \`${check.name}\` check`,
+        detail: `The registry published a build provenance attestation for this version and it does not hold: `
+            + `${check.detail}. The attestation is at ${provenance.attestationUrl}. `
+            + 'A published attestation that does not describe the downloaded artifact is worth more attention than no '
+            + 'attestation at all, because a reader who saw the badge and not this line would conclude the opposite. '
+            + 'What this does NOT establish is that the signing certificate is genuinely Sigstore\'s: that needs a '
+            + 'trust root this tool does not carry, so a registry that serves a doctored bundle can make every other '
+            + 'check pass.',
+        evidence: { file: 'dist.attestations', path: check.name },
+    }));
+}
 /**
  * Run every Tier A check.
  *
@@ -749,6 +789,7 @@ export function runTierA(input) {
         ...checkServiceRemapping(input),
         ...checkModelVisibleText(input),
         ...checkInjectionText(input),
+        ...checkProvenance(input),
     ];
     if (input.mountsAsBundle)
         return findings;

package/lib/checks/tier-b.js

@@ -16,6 +16,7 @@ import ts from 'typescript';
 import { lineColumn, snippet } from "../files.js";
 import { scanInjection } from "../injection.js";
 import { NETWORK_MODULES, SEAM_KEYS, SECURITY_SEAM_KEYS, UNMEDIATED_FS_MODULES, UNMEDIATED_PROCESS_MODULES, } from "../knowledge.js";
+import { foldConstantString, isBuiltinModuleGetter } from "../syntax.js";
 /** Global functions that fetch over the network without any `ctx` service. */
 const NETWORK_GLOBALS = new Set(['fetch', 'WebSocket', 'EventSource', 'XMLHttpRequest']);
 /** `process.env` keys whose names say they hold a secret. */
@@ -74,18 +75,18 @@ function tierB(finding) {
     return { ...finding, tier: 'B', confidence: 'high', examples: [finding.evidence], occurrences: 1 };
 }
 /**
- * The literal text of a string argument, or `null` when it is computed.
- * A computed argument is not a Tier B miss to paper over — it is a Tier C
- * signal, and `tier-c.ts` records it.
+ * The text a string argument holds, folding the constant forms — a `+` chain of
+ * literals, a template whose spans are literals, `[…].join(…)` over literals.
+ *
+ * Folding is bounded on purpose. An argument this cannot resolve is not a
+ * Tier B miss to paper over: it is a Tier C signal, and `tier-c.ts` records it
+ * by asking the same folder, so a site is either matched here or degraded
+ * there and never both.
  * @param node - the argument expression.
- * @returns the literal text, or `null`.
+ * @returns the text, or `null`.
  */
 function literalText(node) {
-    if (node === undefined)
-        return null;
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
-        return node.text;
-    return null;
+    return foldConstantString(node);
 }
 /**
  * Strip the `node:` prefix so `node:fs` and `fs` compare equal.
@@ -96,9 +97,13 @@ function bareModule(specifier) {
     return specifier.startsWith('node:') ? specifier.slice(5) : specifier;
 }
 /**
- * Every module specifier the file imports or requires, as literal text.
+ * Every module the file reaches by a name this tool can resolve.
+ *
+ * Three ways in, not two. `import` and `require` are the declarations a reader
+ * looks for; `process.getBuiltinModule('node:fs')` is a third that needs
+ * neither, returns the same module object, and appears in no import list.
  * @param file - the parsed file.
- * @returns specifier text paired with the node it came from.
+ * @returns one entry per resolved reference.
  */
 function moduleSpecifiers(file) {
     const found = [];
@@ -107,15 +112,16 @@ function moduleSpecifiers(file) {
             const text = literalText(node.moduleSpecifier);
             /* v8 ignore next -- an import declaration only parses with a string-literal specifier. */
             if (text !== null)
-                found.push({ specifier: text, node });
+                found.push({ specifier: text, node, via: 'import' });
         }
         if (ts.isCallExpression(node)) {
             const isRequire = ts.isIdentifier(node.expression) && node.expression.text === 'require';
             const isImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
-            if (isRequire || isImport) {
+            const isBuiltin = isBuiltinModuleGetter(node);
+            if (isRequire || isImport || isBuiltin) {
                 const text = literalText(node.arguments[0]);
                 if (text !== null)
-                    found.push({ specifier: text, node });
+                    found.push({ specifier: text, node, via: isBuiltin ? 'builtin-getter' : 'import' });
             }
         }
         ts.forEachChild(node, visit);
@@ -136,9 +142,25 @@ function at(file, node) {
         snippet: snippet(file.text.slice(node.getStart(file.node), node.end)),
     };
 }
-/** B9, B7, B13 — what the file imports. */
+/**
+ * How a finding names the way a module was reached.
+ *
+ * `Imports` would be false of `process.getBuiltinModule('node:fs')`, and the
+ * difference is the point of covering it: the module arrives with no import
+ * declaration and no `require` for a reader to find.
+ * @param reference - the resolved module reference.
+ * @returns the opening clause of the finding's title.
+ */
+function reachedBy(reference) {
+    return reference.via === 'import'
+        ? `Imports \`${reference.specifier}\``
+        : `Loads \`${reference.specifier}\` through \`process.getBuiltinModule\``;
+}
+/** B9, B7, B13 — what modules the file reaches. */
 function checkImports(file, accumulator) {
-    for (const { specifier, node } of moduleSpecifiers(file)) {
+    for (const reference of moduleSpecifiers(file)) {
+        const { specifier, node } = reference;
+        const reached = reachedBy(reference);
         const bare = bareModule(specifier);
         const unmediated = UNMEDIATED_PROCESS_MODULES.get(bare);
         if (unmediated !== undefined) {
@@ -150,12 +172,13 @@ function checkImports(file, accumulator) {
                 // reads a credential or reaches the network. On its own it is a
                 // capability half the ecosystem has.
                 severity: 'medium',
-                title: `Imports \`${specifier}\`, which ${unmediated}`,
+                title: `${reached}, which ${unmediated}`,
                 detail: 'A mounted bundle layer is imported into the harness process at the agent\'s uid. The harness\'s own '
                     + 'dynamic-package sandbox denies untrusted code `require` outright and redirects it to ctx services; a '
                     + 'bundle layer gets no such restriction, so this import does exactly what the harness forbids elsewhere.',
                 evidence: at(file, node),
-                bypass: 'a computed specifier — `await import(["node","child_process"].join(":"))` — is not matched, which is why C2 downgrades every Tier B negative',
+                bypass: 'a specifier this tool cannot fold to a constant — `import(name)` against a binding — which C2 '
+                    + 'reports, so the negative degrades rather than passing quietly',
             }));
         }
         if (NETWORK_MODULES.has(bare)) {
@@ -164,11 +187,11 @@ function checkImports(file, accumulator) {
                 name: 'network-egress',
                 subject: specifier,
                 severity: 'medium',
-                title: `Imports \`${specifier}\`, which can move bytes off the machine`,
+                title: `${reached}, which can move bytes off the machine`,
                 detail: 'Network access is a capability, not a verdict: most plugins that reach the network do so for a '
                     + 'declared reason. It is recorded because paired with a credential read it becomes B8.',
                 evidence: at(file, node),
-                bypass: 'a computed specifier, or a transitive dependency doing the request on this package\'s behalf',
+                bypass: 'a transitive dependency doing the request on this package\'s behalf',
             });
             accumulator.findings.push(finding);
             accumulator.networkCall ??= finding;
@@ -179,12 +202,12 @@ function checkImports(file, accumulator) {
                 name: 'unmediated-filesystem',
                 subject: specifier,
                 severity: 'medium',
-                title: `Imports \`${specifier}\` rather than using the \`ctx.fs\` service`,
+                title: `${reached} rather than using the \`ctx.fs\` service`,
                 detail: 'Reads and writes through the Node filesystem API are invisible to `fs/write-intent`, '
                     + '`fs/edit-intent`, `fs/observed`, and the `fs-sandbox` row, so no policy in the profile sees them and '
                     + 'nothing appears in the session log.',
                 evidence: at(file, node),
-                bypass: 'a computed specifier, or `process.getBuiltinModule("node:fs")`',
+                bypass: 'a transitive dependency reading the file on this package\'s behalf',
             }));
         }
     }
@@ -210,7 +233,8 @@ function checkSeamReplacement(file, node, accumulator) {
             + 'package\'s implementation for every consumer in the scope, and consumers cannot tell the difference.'
             + (critical ? ' This seam is one whose whole purpose is to constrain what the agent may do.' : ''),
         evidence: at(file, node),
-        bypass: "`ctx['pro' + 'vide']('approval', …)` — a computed member name is not matched",
+        bypass: "`ctx['pro' + 'vide']('approval', …)` — a computed member name is not matched — and neither is a "
+            + '`provide` destructured off `ctx` and called through the bare name. C2 reports both',
     }));
 }
 /** B5 — changing what the model is told. */
@@ -352,7 +376,7 @@ function checkCredentialRead(file, node, accumulator) {
         detail: 'Reading a credential is a capability, not a verdict — a plugin that authenticates to its own service '
             + 'must do it. It is recorded because paired with network access it becomes B8.',
         evidence: at(file, node),
-        bypass: 'a computed key — `process.env["API"+"_KEY"]` — or reading the whole `process.env` object and indexing it later',
+        bypass: 'a key this tool cannot fold to a constant, or reading the whole `process.env` object and indexing it later',
     });
     accumulator.findings.push(finding);
     accumulator.credentialRead ??= finding;
@@ -444,9 +468,9 @@ function checkToolDescription(file, node, accumulator) {
                 + 'heuristic: it will miss a rephrasing, and it can fire on a description that legitimately discusses the '
                 + 'subject.',
             evidence: { ...at(file, node), snippet: snippet(match.excerpt) },
-            bypass: 'any rephrasing the pattern does not cover, building the description by concatenation, or registering '
-                + 'the definition through a value this tool does not track — a definition exported from one file and passed '
-                + 'to `tools.register` in another is not matched',
+            bypass: 'any rephrasing the pattern does not cover, assembling the description out of anything this tool '
+                + 'cannot fold to a constant, or registering the definition through a value this tool does not track — a '
+                + 'definition exported from one file and passed to `tools.register` in another is not matched',
         }));
     }
 }