feat(audit): add --include-attestations flag to output sigstore bundles (#9049)

mitchdenny · web-flow · commit 8eff5fb31afc · 2026-03-17T18:28:14.000-07:00
diff --git a/docs/lib/content/commands/npm-audit.md b/docs/lib/content/commands/npm-audit.md
@@ -42,6 +42,16 @@ The `audit signatures` command will also verify the provenance attestations of d
 Because provenance attestations are such a new feature, security features may be added to (or changed in) the attestation format over time.
 To ensure that you're always able to verify attestation signatures check that you're running the latest version of the npm CLI. Please note this often means updating npm beyond the version that ships with Node.js.
 
+To include the full sigstore attestation bundles in JSON output, use:
+
+```bash
+$ npm audit signatures --json --include-attestations
+```
+
+This adds a `verified` array to the JSON output containing the attestation
+bundles (DSSE envelopes, verification material, and transparency log entries)
+for each verified package.
+
 The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
 
 1. Signatures are provided in the package's `packument` in each published version within the `dist` object:
diff --git a/lib/commands/audit.js b/lib/commands/audit.js
@@ -19,6 +19,7 @@ class Audit extends ArboristWorkspaceCmd {
     'include',
     'foreground-scripts',
     'ignore-scripts',
+    'include-attestations',
     ...super.params,
   ]
 
diff --git a/lib/utils/verify-signatures.js b/lib/utils/verify-signatures.js
@@ -17,6 +17,7 @@ class VerifySignatures {
     this.invalid = []
     this.missing = []
     this.checkedPackages = new Set()
+    this.verified = []
     this.auditedWithKeysCount = 0
     this.verifiedSignatureCount = 0
     this.verifiedAttestationCount = 0
@@ -59,7 +60,11 @@ class VerifySignatures {
     }
 
     if (this.npm.config.get('json')) {
-      output.buffer({ invalid, missing })
+      const result = { invalid, missing }
+      if (this.npm.config.get('include-attestations')) {
+        result.verified = this.verified
+      }
+      output.buffer(result)
       return
     }
     const end = process.hrtime.bigint()
@@ -87,6 +92,9 @@ class VerifySignatures {
       } else {
         output.standard(`${this.verifiedAttestationCount} packages have ${verifiedBold} attestations`)
       }
+      if (!this.npm.config.get('include-attestations')) {
+        output.standard('(use --json --include-attestations to view attestation details)')
+      }
       output.standard()
     }
 
@@ -288,6 +296,7 @@ class VerifySignatures {
       _integrity: integrity,
       _signatures,
       _attestations,
+      _attestationBundles,
       _resolved: resolved,
     } = await pacote.manifest(`${name}@${version}`, {
       verifySignatures: true,
@@ -300,6 +309,7 @@ class VerifySignatures {
       integrity,
       signatures,
       attestations: _attestations,
+      attestationBundles: _attestationBundles,
       resolved,
     }
     return result
@@ -324,9 +334,8 @@ class VerifySignatures {
     }
 
     try {
-      const { integrity, signatures, attestations, resolved } = await this.verifySignatures(
-        name, version, registry
-      )
+      const { integrity, signatures, attestations, attestationBundles, resolved } =
+        await this.verifySignatures(name, version, registry)
 
       // Currently we only care about missing signatures on registries that provide a public key
       // We could make this configurable in the future with a strict/paranoid mode
@@ -346,6 +355,16 @@ class VerifySignatures {
       // Track verified attestations separately to registry signatures, as all packages on registries with signing keys are expected to have registry signatures, but not all packages have provenance and publish attestations.
       if (attestations) {
         this.verifiedAttestationCount += 1
+        if (this.npm.config.get('include-attestations')) {
+          this.verified.push({
+            name,
+            version,
+            location,
+            registry,
+            attestations,
+            attestationBundles,
+          })
+        }
       }
     } catch (e) {
       if (e.code === 'EINTEGRITYSIGNATURE' || e.code === 'EATTESTATIONVERIFY') {
diff --git a/tap-snapshots/test/lib/commands/audit.js.test.cjs b/tap-snapshots/test/lib/commands/audit.js.test.cjs
@@ -305,6 +305,7 @@ audited 1 package in xxx
 1 package has a verified registry signature
 
 1 package has a verified attestation
+(use --json --include-attestations to view attestation details)
 `
 
 exports[`test/lib/commands/audit.js TAP audit signatures with valid signatures > must match snapshot 1`] = `
diff --git a/tap-snapshots/test/lib/commands/config.js.test.cjs b/tap-snapshots/test/lib/commands/config.js.test.cjs
@@ -72,6 +72,7 @@ exports[`test/lib/commands/config.js TAP config list --json > output matches sna
   "include": [],
   "include-staged": false,
   "include-workspace-root": false,
+  "include-attestations": false,
   "init-author-email": "",
   "init-author-name": "",
   "init-author-url": "",
@@ -248,6 +249,7 @@ https-proxy = null
 if-present = false
 ignore-scripts = false
 include = []
+include-attestations = false
 include-staged = false
 include-workspace-root = false
 init-author-email = ""
diff --git a/tap-snapshots/test/lib/docs.js.test.cjs b/tap-snapshots/test/lib/docs.js.test.cjs
@@ -821,6 +821,18 @@ the order in which omit/include are specified on the command-line.
 
 
 
+#### \`include-attestations\`
+
+* Default: false
+* Type: Boolean
+
+When used with \`npm audit signatures --json\`, includes the full sigstore
+attestation bundles in the JSON output for each verified package. The
+bundles contain DSSE envelopes, verification material, and transparency log
+entries.
+
+
+
 #### \`include-staged\`
 
 * Default: false
@@ -2302,6 +2314,7 @@ Array [
   "include",
   "include-staged",
   "include-workspace-root",
+  "include-attestations",
   "init-author-email",
   "init-author-name",
   "init-author-url",
@@ -2476,6 +2489,7 @@ Array [
   "include",
   "include-staged",
   "include-workspace-root",
+  "include-attestations",
   "init-private",
   "install-links",
   "install-strategy",
@@ -2643,6 +2657,7 @@ Object {
   "httpsProxy": null,
   "ifPresent": false,
   "ignoreScripts": false,
+  "includeAttestations": false,
   "includeStaged": false,
   "includeWorkspaceRoot": false,
   "initPrivate": false,
@@ -2869,7 +2884,7 @@ Options:
 [--json] [--package-lock-only] [--no-package-lock]
 [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
 [--include <prod|dev|optional|peer> [--include <prod|dev|optional|peer> ...]]
-[--foreground-scripts] [--ignore-scripts]
+[--foreground-scripts] [--ignore-scripts] [--include-attestations]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 [--workspaces] [--include-workspace-root] [--install-links]
 
@@ -2903,6 +2918,9 @@ Options:
   --ignore-scripts
     If true, npm does not run scripts specified in package.json files.
 
+  --include-attestations
+    When used with \`npm audit signatures --json\`, includes the full
+
   -w|--workspace
     Enable running a command in the context of the configured workspaces of the
 
@@ -2932,6 +2950,7 @@ npm audit [fix|signatures]
 #### \`include\`
 #### \`foreground-scripts\`
 #### \`ignore-scripts\`
+#### \`include-attestations\`
 #### \`workspace\`
 #### \`workspaces\`
 #### \`include-workspace-root\`
diff --git a/test/lib/commands/audit.js b/test/lib/commands/audit.js
@@ -1850,9 +1850,99 @@ t.test('audit signatures', async t => {
 
     t.notOk(process.exitCode, 'should exit successfully')
     t.match(joinedOutput(), /1 package has a verified attestation/)
+    t.match(joinedOutput(), /use --json --include-attestations to view attestation details/)
     t.matchSnapshot(joinedOutput())
   })
 
+  t.test('with valid attestations and --include-attestations (human-readable)', async t => {
+    const { npm, joinedOutput } = await loadMockNpm(t, {
+      prefixDir: installWithValidAttestations,
+      config: {
+        'include-attestations': true,
+      },
+      mocks: {
+        pacote: t.mock('pacote', {
+          sigstore: { verify: async () => true },
+        }),
+      },
+    })
+    const registry = new MockRegistry({ tap: t, registry: npm.config.get('registry') })
+    await manifestWithValidAttestations({ registry })
+    const fixture = fs.readFileSync(
+      path.resolve(__dirname, '../../fixtures/sigstore/valid-sigstore-attestations.json'),
+      'utf8'
+    )
+    registry.nock.get('/-/npm/v1/attestations/sigstore@1.0.0').reply(200, fixture)
+    mockTUF({ npm, target: TUF_VALID_KEYS_TARGET })
+
+    await npm.exec('audit', ['signatures'])
+
+    t.notOk(process.exitCode, 'should exit successfully')
+    t.match(joinedOutput(), /1 package has a verified attestation/)
+    t.notMatch(joinedOutput(), /use --json --include-attestations to view attestation details/)
+  })
+
+  t.test('with valid attestations --json --include-attestations', async t => {
+    const { npm, joinedOutput } = await loadMockNpm(t, {
+      prefixDir: installWithValidAttestations,
+      config: {
+        json: true,
+        'include-attestations': true,
+      },
+      mocks: {
+        pacote: t.mock('pacote', {
+          sigstore: { verify: async () => true },
+        }),
+      },
+    })
+    const registry = new MockRegistry({ tap: t, registry: npm.config.get('registry') })
+    await manifestWithValidAttestations({ registry })
+    const fixture = fs.readFileSync(
+      path.resolve(__dirname, '../../fixtures/sigstore/valid-sigstore-attestations.json'),
+      'utf8'
+    )
+    registry.nock.get('/-/npm/v1/attestations/sigstore@1.0.0').reply(200, fixture)
+    mockTUF({ npm, target: TUF_VALID_KEYS_TARGET })
+
+    await npm.exec('audit', ['signatures'])
+
+    t.notOk(process.exitCode, 'should exit successfully')
+    const jsonOutput = JSON.parse(joinedOutput())
+    t.ok(jsonOutput.verified, 'should include verified array')
+    t.equal(jsonOutput.verified.length, 1, 'should have one verified package')
+    t.equal(jsonOutput.verified[0].name, 'sigstore', 'should have correct package name')
+    t.equal(jsonOutput.verified[0].version, '1.0.0', 'should have correct version')
+    t.ok(jsonOutput.verified[0].attestations, 'should include attestations')
+  })
+
+  t.test('with valid attestations --json without --include-attestations', async t => {
+    const { npm, joinedOutput } = await loadMockNpm(t, {
+      prefixDir: installWithValidAttestations,
+      config: {
+        json: true,
+      },
+      mocks: {
+        pacote: t.mock('pacote', {
+          sigstore: { verify: async () => true },
+        }),
+      },
+    })
+    const registry = new MockRegistry({ tap: t, registry: npm.config.get('registry') })
+    await manifestWithValidAttestations({ registry })
+    const fixture = fs.readFileSync(
+      path.resolve(__dirname, '../../fixtures/sigstore/valid-sigstore-attestations.json'),
+      'utf8'
+    )
+    registry.nock.get('/-/npm/v1/attestations/sigstore@1.0.0').reply(200, fixture)
+    mockTUF({ npm, target: TUF_VALID_KEYS_TARGET })
+
+    await npm.exec('audit', ['signatures'])
+
+    t.notOk(process.exitCode, 'should exit successfully')
+    const jsonOutput = JSON.parse(joinedOutput())
+    t.notOk(jsonOutput.verified, 'should not include verified array')
+  })
+
   t.test('with keyless attestations and no registry keys', async t => {
     const { npm, joinedOutput } = await loadMockNpm(t, {
       prefixDir: installWithValidAttestations,
diff --git a/workspaces/config/lib/definitions/definitions.js b/workspaces/config/lib/definitions/definitions.js
@@ -946,6 +946,17 @@ const definitions = {
     `,
     flatten,
   }),
+  'include-attestations': new Definition('include-attestations', {
+    default: false,
+    type: Boolean,
+    description: `
+      When used with \`npm audit signatures --json\`, includes the full
+      sigstore attestation bundles in the JSON output for each verified
+      package. The bundles contain DSSE envelopes, verification material,
+      and transparency log entries.
+    `,
+    flatten,
+  }),
   'init-author-email': new Definition('init-author-email', {
     default: '',
     hint: '<email>',
diff --git a/workspaces/config/tap-snapshots/test/type-description.js.test.cjs b/workspaces/config/tap-snapshots/test/type-description.js.test.cjs
@@ -221,6 +221,9 @@ Object {
     "optional",
     "peer",
   ],
+  "include-attestations": Array [
+    "boolean value (true or false)",
+  ],
   "include-staged": Array [
     "boolean value (true or false)",
   ],

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@ class Audit extends ArboristWorkspaceCmd {`
`19`	`19`	`'include',`
`20`	`20`	`'foreground-scripts',`
`21`	`21`	`'ignore-scripts',`
	`22`	`+ 'include-attestations',`
`22`	`23`	`...super.params,`
`23`	`24`	`]`
`24`	`25`
Original file line number	Diff line number	Diff line change
`@@ -305,6 +305,7 @@ audited 1 package in xxx`
`305`	`305`	`1 package has a verified registry signature`
`306`	`306`
`307`	`307`	`1 package has a verified attestation`
	`308`	`+(use --json --include-attestations to view attestation details)`
`308`	`309`	`
`309`	`310`
`310`	`311`	exports[`test/lib/commands/audit.js TAP audit signatures with valid signatures > must match snapshot 1`] = `