jest-package-audit

Filter and retry yarn/npm audit command with Jest.

The yarn audit, and npm audit commands are useful for detecting packages in use that have vulnerabilites. But they don't allow specific package filtering. For example you may have a vulnerability in a package you are only using in development, and the nature of that vulnerability is more often than not only unsafe when used in production. Updating the dependency to fix the vulnerability may break things. That is where jest-package-audit comes in, it wraps the yarn audit and npm audit commands and checks each vulnerabilty they flag against an array of allowed vulnerability names e.g. ['puppeteer'].

Another added benefit of jest-package-audit is the ability to retry tests if they fail. This is useful as the audit endpoints can sometimes timeout out or randomly give 503 HTTP Status codes back. Using jest.retryTimes you can overcome this by retrying say 5 times.

Usage

Important: jest-package-audit only works with Jest >= 23 as it depends on async matchers.

Install jest-package-audit:

yarn add jest-package-audit --dev
# or
npm install jest-package-audit --save-dev

Create a new test file for package auditing:

// audit.test.js
import { toPassPackageAudit } from 'jest-package-audit';
expect.extend({ toPassPackageAudit });

jest.retryTimes(5); // Optional
jest.setTimeout(15000); // The audit command can take a while...

test('packages do not have vunerabilities', async () => {
  await expect({/* Input options */}).toPassPackageAudit({ allow: ['puppeteer'] /* Output options */ });
});

test('packages do not have vunerabilities using predicate function', async () => {
  await expect({/* Input options */}).toPassPackageAudit({ allow: (options) => {
    if (options.packageName === 'puppeteer' && options.packageSeverity === 'low') {
      return true;
    } else {
      return false;
    }
  } /* Output options */ });
});

Options

Input Options

Input options should be passed to the expect function when using toPassPackageAudit, they define how the actual yarn audit or npm audit command is run.

Name	Description	Default
`cwd: (String)`	Current working directory to run the audit command in.	The closest folder with a `package.json` above `jest-package-audit`.
`packageManager ('npm' or 'yarn' or 'pnpm')`	Which package manager to use, this will be auto-detected if not specified, also it will determine how the audit output is parsed when using `command`.	Based on relevant lockfile existance
`level: ('info' or 'low' or 'moderate' or 'high' or 'critical')`	Limit the vulnerabilities to the given level and above. (Note: npm and pnpm does not support `info`, so it will not be passed forward)
`dependencyType: ('dependencies' or 'devDependencies')`	Limit the vulnerabilities to the projects development or production dependencies.
`command (String)`	Custom command to use. This will override the `yarn`, `level` and `dependencyType` options. Use this with caution!

Note: level and dependencyType are passed forward to yarn and npm in their respective formats. Unless, command is specified,

Output Options

Output options should be passed to the toPassPackageAudit function, they define how the output of yarn audit or npm audit is processed.

Name	Description	Default
`allow: (String[] \| (vulnerability: {packageName: string; packageSeverity: string; packageData: Object}) => boolean)`	An array of package names to allow if they have vulnerabilities or a single callback predicate function.	`[]`

Disclaimer

Please be aware that we provide no liability for any security issues, or any other issues for that matter, encountered when using this package. It is provided as open-source software under the MIT license. So please read the source code and make sure you understand the implications of allowing vulnerable modules to pass through the audit commands!