dsh-plugin-inspector 0.6.0 → 0.8.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

@@ -20,7 +20,7 @@ import { declaredPackages } from "../manifest.js";
  * whatever YAML that library happens to ship is inert bytes.
  */
 const PATCH_ROW_CHECKS = new Set([
-    'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10', 'A15', 'A17', 'A19', 'A23',
+    'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10', 'A15', 'A17', 'A19', 'A23', 'A26',
 ]);
 /** Loader builtins that are entry names but not resolvable npm packages. */
 const LOADER_BUILTINS = new Set([
@@ -725,6 +725,113 @@ 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 },
+    }));
+}
+/**
+ * A26 — a patch row that modifies a row this package neither ships nor shares
+ * with the harness.
+ *
+ * A2, A3, A5 and A19 all key on {@link CORE_ROWS}: an override whose `id` is
+ * not a row the shipped bundles define falls through every one of them and
+ * produces nothing. But the composed profile is not only the core rows. It also
+ * holds the rows the user wrote in their own layer and the rows every other
+ * installed plugin inserted, and `applyEntryPatches` matches by `id` alone with
+ * no notion of who owns the row. So `- id: some-other-plugin` / `disabled:
+ * true` in this package's layer switches that package off, and a `config:`
+ * override replaces its configuration wholesale, since a patch override is a
+ * shallow whole-value replacement rather than a merge.
+ *
+ * The check is a set difference, which is what keeps it decidable: an id that
+ * is neither a core row nor a row this same layer inserts belongs to somebody
+ * else. Two kinds of package legitimately rewrite rows they did not insert and
+ * are excluded — the harness's own bundles, which is what composing a surface
+ * bundle is, and a package that declares `dsh.profile.bundles`, which is a
+ * profile assembling other people's layers on purpose and is reported as such
+ * by A20.
+ */
+function checkForeignRows(input) {
+    if (isHarnessBundle(input))
+        return [];
+    if ((input.manifest.dsh.profile?.bundles ?? []).length > 0)
+        return [];
+    const findings = [];
+    for (const patch of input.patches) {
+        const own = new Set(patch.inserts.map(row => row.id).filter(id => id !== null));
+        for (const override of patch.overrides) {
+            if (override.overriddenKeys.length === 0)
+                continue;
+            if (CORE_ROWS.has(override.id) || own.has(override.id))
+                continue;
+            const switchedOff = override.overriddenKeys.includes('disabled') && Boolean(override.disabled);
+            const rewritten = override.overriddenKeys.filter(key => key !== 'disabled');
+            findings.push(tierA({
+                checkId: 'A26',
+                name: 'foreign-row-modified',
+                subject: override.id,
+                severity: 'high',
+                title: switchedOff
+                    ? `Patch layer disables the row "${override.id}", which this package does not ship`
+                    : `Patch layer rewrites ${rewritten.map(key => `\`${key}\``).join(', ')} on the row `
+                        + `"${override.id}", which this package does not ship`,
+                detail: `"${override.id}" is neither a row the shipped bundles define nor one this layer inserts, so it `
+                    + 'belongs to the user\'s own layer or to another installed plugin. `applyEntryPatches` matches rows by '
+                    + '`id` alone and has no notion of which layer owns one, so this patch reaches into that package\'s row '
+                    + 'and '
+                    + (switchedOff
+                        ? 'stops it running. Whatever that package contributed — a guard, a listener, an audit sink — is not '
+                            + 'composed into the profile, and the user\'s own configuration still says it is installed.'
+                        : 'replaces those keys. An override is a shallow whole-value replacement rather than a merge, so an '
+                            + 'overridden `config` discards every key that package shipped and keeps only what is written here.')
+                    + ' If the row id is not present in the composed profile the patch is simply inert, which is the benign '
+                    + 'reading and the one a reader should check first.',
+                evidence: {
+                    file: patch.file,
+                    path: switchedOff ? `${override.path}.disabled` : override.path,
+                    snippet: snippet(override.overriddenKeys.join(', ')),
+                },
+            }));
+        }
+    }
+    return findings;
+}
 /**
  * Run every Tier A check.
  *
@@ -741,6 +848,7 @@ export function runTierA(input) {
         ...checkNativeBuild(input),
         ...checkDisabledRows(input),
         ...checkOverriddenRows(input),
+        ...checkForeignRows(input),
         ...checkExpressions(input),
         ...checkPatchFailures(input),
         ...checkInsertedModules(input),
@@ -749,6 +857,7 @@ export function runTierA(input) {
         ...checkServiceRemapping(input),
         ...checkModelVisibleText(input),
         ...checkInjectionText(input),
+        ...checkProvenance(input),
     ];
     if (input.mountsAsBundle)
         return findings;