dsh-plugin-inspector 0.5.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)
@@ -84,8 +85,8 @@ Findings are tiered by how much you should trust them:
 intent is not. Every Tier B check has a one-line bypass, and the tool says so per finding rather
 than implying a completeness it does not have. What it does guarantee is that it never runs the
 code it analyses — asserted from outside the unit suite by a CI canary whose fixture writes
-sentinel files from `preinstall`, `postinstall`, `prepare`, `!!js` config and module top level. Any
-sentinel on disk after a full analysis is a release blocker.
+sentinel files from `preinstall`, `postinstall`, `prepare`, `!!js` config, `!!js` disabled, and
+module top level. Any sentinel on disk after a full analysis is a release blocker.
 
 [What is not statically decidable →](https://charlotten7.github.io/dsh-plugin-inspector/ceiling.html) ·
 [What it reports on the real ecosystem →](https://charlotten7.github.io/dsh-plugin-inspector/ecosystem.html)
@@ -100,8 +101,14 @@ pnpm run test:coverage
 pnpm run test:e2e
 ```
 
-Severity calibration is pinned against a corpus of published packages, so a change that starts
-firing on ordinary code fails CI rather than shipping.
+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

@@ -123,8 +123,12 @@ function checkDisabledRows(input) {
             // (vendor/loader/src/config/entry.ts). `null`, `0` and `""` therefore
             // leave the row running, and reporting them as a disabled row would be
             // confidently wrong about the one thing Tier A claims to be certain of.
-            // An expression node is an object, so it stays truthy here and is judged
-            // by what it can evaluate to rather than by its own shape.
+            // A `!!js` node is not that case. The loader evaluates the expression
+            // first and coerces its *result*, so `disabled: !!js false` also leaves
+            // the row running — which this tool cannot know without running the
+            // expression, and running it is the one thing it may never do. An
+            // expression is therefore read as what it could evaluate to, which
+            // raises the finding rather than dropping it.
             if (!override.disabled) {
                 const enabled = coreRowSeverity(override.id);
                 if (enabled === null)
@@ -643,7 +647,7 @@ function checkModelVisibleText(input) {
             detail: 'Skill and agent-instruction markdown reaches the model verbatim, unescaped and uncapped. Shipping it '
                 + 'in an npm package does not by itself put it in front of the model: it is discovered only when the plugin '
                 + 'registers it through ctx.skills, when a patch row redirects a skill root into this package (A15), or when '
-                + 'something copies it into the user\'s workspace. The text itself is scored separately by B10.',
+                + 'something copies it into the user\'s workspace. The text itself is scored separately by A21.',
             /* v8 ignore next -- the caller returns early on an empty list. */
             evidence: { file: input.modelVisibleFiles[0] ?? '', snippet: snippet(input.modelVisibleFiles.join(', ')) },
         })];
@@ -721,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.
  *
@@ -745,6 +789,7 @@ export function runTierA(input) {
         ...checkServiceRemapping(input),
         ...checkModelVisibleText(input),
         ...checkInjectionText(input),
+        ...checkProvenance(input),
     ];
     if (input.mountsAsBundle)
         return findings;