ciaudit
Wrapper for npm audit to allow configurable severity levels and support ignore lists for specific advisories.
Install
To install into a project:
$ npm install --save-dev @lennym/ciaudit
If installed in a project then the recommended usage is to add a line to the scripts
section of package.json:
"scripts": {
...
"audit": "ciaudit"
}
and then run:
$ npm run audit
Basic usage
Define a base severity level by passing a flag of --low
, --moderate
, --high
or --critical
. Default: low
# as an installed module
$ ciaudit [--moderate | --high | --critical]
# with npx
$ npx @lennym/ciaudit [--moderate | --high | --critical]
This process will output a JSON formatted report and will exit with a non-zero exit code if any non-ignored advisories are detected.
Other options
--production
- ignore dev dependencies when running audit (Default:false
)
Note: --production
will be inherited from npm CLI, so if running via an npm script npm run audit --production
will be equivalent to npm run audit -- --production
--ignorefile
- use specified file to load ignore list (Default:./.auditignore
)
By default an installed version of @npmcli/arborist
is used to perform the audit, and so is not dependent on the locally installed npm runtime. However, this can be overridden by passing a --local
flag.
--local
- use locally installed npm version to perform audit (Default:false
)
Ignore file
Advisories can be ignore by listing in an ignore file - default .auditignore
.
Entries in the ignore file can be defined based on source, module name, and install path. Install paths are separated by >
and can include wildcards (*
).
# ignore advisory with source id 1005560
1005560
# ignore advisories relating to package `node-fetch`
node-fetch
# ignore advisories in child/descendant dependencies of `webpack`
webpack>*
Advanced usage
Ignore file entries can be combined by using a &&
separator. In this case all conditions must be met for the advisory to be ignored.
In the following example, advisory 1006947 (related to the glob-parent
module) is ignored only when it appears as a descendant of webpack
.
# ignore 1006947 as a descendant of webpack
1006947 && webpack>*
Note on path matching
Due to a bug in npm
at time of writing, some reported install paths may be incomplete and not include a complete set of ancestor dependencies where a module with an advisory has multiple install paths with a common ancestor.
Updating from v1.x
v2.0.0 is a total ground-up rewrite of the module to solve a different set of problems that have emerged as npm audit
has developed and matured.
As such it should be considered a complete breaking change, and a from-scratch reimplementation is recommended.