This module is intended to be consumed by your favourite continuous integration tool to
halt execution if npm audit
or yarn audit
finds vulnerabilities at or above the specified
threshold while ignoring allowlisted advisories.
Note: Use our codemod to update to
audit-ci
v6.0.0
- Node >=12.x (Yarn Berry requires Node >=12.13.0)
- (Optional) Yarn ^1.12.3 || Yarn >=2.4.0
Install audit-ci
during your CI environment using npx
or as a devDependency.
npx audit-ci --moderate
Alternatively, for the devDependency approach with NPM:
npm install --save-dev audit-ci
or, using yarn
:
yarn add -D audit-ci
The next section gives examples using audit-ci
in various CI environments.
It assumes that medium, high, and critical severity vulnerabilities prevent build continuation.
For simplicity, the examples use npx
and do not use a config file.
steps:
- uses: actions/checkout@v2
- name: Audit for vulnerabilities
run: npx audit-ci --config ./audit-ci.jsonc
# ... excludes set up for job
steps:
- checkout
- run:
name: update-npm
command: "sudo npm install -g npm"
- restore_cache:
key: dependency-cache-{{ checksum "package.json" }}
- run:
name: install-npm
command: "npm install --no-audit"
# This should run immediately after installation to reduce
# the risk of executing a script from a compromised NPM package.
- run:
name: run-audit-ci
command: npx audit-ci --config ./audit-ci.jsonc
# If you use a pull-request-only workflow,
# it's better to not run audit-ci on `main` and only run it on pull requests.
# For more info: https://github.com/IBM/audit-ci/issues/69
# For a PR-only workflow, use the below command instead of the above command:
#
# command: if [[ ! -z $CIRCLE_PULL_REQUEST ]] ; then audit-ci --moderate ; fi
Auditing only on PR builds is recommended
scripts:
# This script should be the first that runs to reduce the risk of
# executing a script from a compromised NPM package.
- if [ "${TRAVIS_PULL_REQUEST}" != "false" ]; then npx audit-ci --moderate; fi
For Travis-CI
not using PR builds:
scripts:
- npx audit-ci --config ./audit-ci.jsonc
Args | Alias | Description |
---|---|---|
-l | --low | Prevents integration with low or higher vulnerabilities (default false ) |
-m | --moderate | Prevents integration with moderate or higher vulnerabilities (default false ) |
-h | --high | Prevents integration with high or critical vulnerabilities (default false ) |
-c | --critical | Prevents integration only with critical vulnerabilities (default false ) |
-p | --package-manager | Choose a package manager [choices: auto , npm , yarn ] (default auto ) |
-a | --allowlist | Vulnerable modules, advisories, and paths to allowlist from preventing integration (default none ) |
-o | --output-format | The format of the output of audit-ci [choices: text , json ] (default text ) |
-d | --directory | The directory containing the package.json to audit (default ./ ) |
--pass-enoaudit | Pass if no audit is performed due to the registry returning ENOAUDIT (default false ) |
|
--show-found | Show allowlisted advisories that are found (default true ) |
|
--show-not-found | Show allowlisted advisories that are not found (default true ) |
|
--registry | The registry to resolve packages by name and version (default to unspecified) | |
--report-type | Format for the audit report results [choices: important , summary , full ] (default important ) |
|
--retry-count | The number of attempts audit-ci calls an unavailable registry before failing (default 5 ) |
|
--config | Path to JSON config file | |
--skip-dev | Skip auditing devDependencies (default false ) |
A config file can manage auditing preferences audit-ci
. The config file's keys match the CLI arguments.
{
// Only use one of ["low": true, "moderate": true, "high": true, "critical": true]
"low": <boolean>, // [Optional] defaults `false`
"moderate": <boolean>, // [Optional] defaults `false`
"high": <boolean>, // [Optional] defaults `false`
"critical": <boolean>, // [Optional] defaults `false`
"allowlist": <string[]>, // [Optional] default `[]`
"report-type": <string>, // [Optional] defaults `important`
"package-manager": <string>, // [Optional] defaults `"auto"`
"output-format": <string>, // [Optional] defaults `"text"`
"pass-enoaudit": <boolean>, // [Optional] defaults `false`
"show-found": <boolean>, // [Optional] defaults `true`
"show-not-found": <boolean>, // [Optional] defaults `true`
"registry": <string>, // [Optional] defaults `undefined`
"retry-count": <number>, // [Optional] defaults 5
"skip-dev": <boolean>, // [Optional] defaults `false`
}
Review the examples section for an example of config file usage.
Refrain from using
"directory"
within the config file becausedirectory
is relative to where the command is run, rather than the directory where the config file exists.
npx audit-ci -m
Prevents build on any vulnerability except advisory "GHSA-38f5-ghc2-fcmv" and all of lodash and base64url, don't show allowlisted
npx audit-ci -l -a "GHSA-38f5-ghc2-fcmv" lodash base64url --show-found false
audit-ci --critical --report-type full
npx audit-ci --report-type summary
{
"low": true,
"package-manager": "auto",
"allowlist": [
"GHSA-333w-rxj3-f55r",
"GHSA-vfvf-mqq8-rwqc",
"example1",
"example2",
"GHSA-6354-6mhv-mvv5|example3",
"GHSA-42xw-2xvc-qx8m|example4",
"GHSA-42xw-2xvc-qx8m|example5>example4",
"*|example6>*"
],
"registry": "https://registry.npmjs.org"
}
npx audit-ci --directory test/npm-config-file --config test/npm-config-file/audit-ci.jsonc
npx @quinnturner/audit-ci-codemod
https://github.com/quinnturner/audit-ci-codemod
audit-ci
v6.0.0 changed the identifiers used for auditing from the NPM identifiers to GitHub identifiers.
NPM identifiers are considered unstable to rely on, as they frequently change.
Meanwhile, GitHub identifiers are stable.
To accommodate for a potentially tedious migration, a codemod is available to update your configuration in-place.
$ npx @quinnturner/audit-ci-codemod
Need to install the following packages:
@quinnturner/audit-ci-codemod
Ok to proceed? (y) y
? What's the path for the audit-ci config? audit-ci.jsonc
Performed migration from advisories, whitelist, and path-whitelist to allowlist
Performed migration from NPM advisories to GitHub advisories
If audit-ci
is run on the PR build and not on the push build, you can continue to push new code and create PRs parallel to the actual vulnerability fix. However, they can't be merged until the fix is implemented. Since audit-ci
performs the audit on the PR build, it will always have the most up-to-date dependencies vs. the push build, which would require a manual merge with main
before passing the audit.
The config option --pass-enoaudit
allows passing if no audit is performed due to the registry returning ENOAUDIT. It is false
by default to reduce the risk of merging in a vulnerable package. However, if the convenience of passing is more important for your project then you can add --pass-enoaudit
into the CLI or add it to the config.