npm-audit-report

npm audit security report

Given a response from the npm security api, render it into a variety of security reports

The response is an object that contains an output string (the report) and a suggested exitCode.

{
  report: 'string that contains the security report',
  exit: 1
}

Basic usage example

This is intended to be used along with @npmcli/arborist's AuditReport class.

'use strict'
const Report = require('npm-audit-report')
const options = {
  reporter: 'json'
}

const arb = new Arborist({ path: '/path/to/project' })
arb.audit().then(report => {
  const result = new Report(report, options)
  console.log(result.output)
  process.exitCode = result.exitCode
})

Break from Version 1

Version 5 and 6 of the npm CLI make a request to the registry endpoint at either the "Full Audit" endpoint at /-/npm/v1/security/audits or the "Quick Audit" endpoint at /-/npm/v1/security/audits/quick. The Full Audit endpoint calculates remediations necessary to correct problems based on the shape of the tree.

As of npm v7, the logic of how the cli manages trees is dramatically rearchitected, rendering much of the remediations no longer valid. Thus, it only fetches the advisory data from the Quick Audit endpoint, and uses @npmcli/arborist to calculate required remediations and affected nodes in the dependency graph. This data is serialized and provided as an "auditReportVersion": 2 object.

Version 2 of this module expects to receive an instance (or serialized JSON version of) the AuditReport class from Arborist, which is returned by arborist.audit() and stored on the instance as arborist.auditReport.

Eventually, a new endpoint may be added to move the @npmcli/arborist work to the server-side, in which case version 2 style audit reports may be provided directly.

options

option	values	default	description
reporter	install, detail, json, quiet	install	specify which output format you want to use
chalk	Chalk instance	required	a Chalk instance to use for colorizing strings. use new chalk.Instance({ level: 0 }) for no colors
unicode	true, false	true	indicates if unicode characters should be used
indent	Number or String	2	indentation for 'json' report
auditLevel	'info', 'low', 'moderate', 'high', 'critical', 'none'	low (ie, exit 0 if only info advisories are found)	level of vulnerability that will trigger a non-zero exit code (set to 'none' to always exit with a 0 status code)

Changelog

6.0.0 (2024-09-03)

⚠️ BREAKING CHANGES

• npm-audit-report now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• b9a071c #137 align to npm 10 node engine range (@hashtagchris)

Chores

• 6ae4785 #137 run template-oss-apply (@hashtagchris)
• d9a9b5a #135 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• 6a5ef6a #123 bump @npmcli/template-oss to 4.22.0 (@lukekarrys)
• 3dfcf02 #90 enable auto publish (#90) (@wraithgar)
• dfc6832 #136 postinstall for dependabot template-oss PR (@hashtagchris)
• ac3cfa2 #136 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])