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

Add a new --include-attestations flag for `npm audit signatures` that
includes the full sigstore attestation bundles in JSON output. This
enables downstream tooling to consume and further process attestation
data (e.g. for policy engines, SBOMs, or custom verification).

When used with `npm audit signatures --json --include-attestations`,
the JSON output includes a `verified` array containing each package's
name, version, and attestation bundles.

Depends on npm/pacote#457 to expose the fetched attestation bundles
on the manifest's _attestations property.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Mitch Denny

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:

lib/commands/audit.js

@@ -19,6 +19,7 @@ class Audit extends ArboristWorkspaceCmd {
     'include',
     'foreground-scripts',
     'ignore-scripts',
+    'include-attestations',
     ...super.params,
   ]
 

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
@@ -60,7 +61,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()
@@ -88,6 +93,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()
     }
 
@@ -350,6 +358,15 @@ class VerifySignatures {
       // 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,
+          })
+        }
       }
     } catch (e) {
       if (e.code === 'EINTEGRITYSIGNATURE' || e.code === 'EATTESTATIONVERIFY') {

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`] = `

test/lib/commands/audit.js

@@ -1850,9 +1850,71 @@ 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 --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,

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>',