npm-audit

Scan the project's dependencies for known vulnerabilities

$ npm audit

$ npm audit fix

$ npm audit fix [[-f|--force]]

$ npm audit fix --package-lock-only

$ npm audit fix --dry-run

$ npm audit --json

$ npm audit --audit-level [info|low|moderate|high|critical]

npm audit [fix] [options]

--audit-level=<level>
    Specify the minimum vulnerability level to display (info, low, moderate, high, critical). Defaults to 'info'.

--production
    Run the audit only on production dependencies (dependencies listed in `dependencies`, not `devDependencies`).

--json
    Output the audit report in JSON format.

--package-lock-only
    Forces `npm audit` to use `package-lock.json` (or `npm-shrinkwrap.json`) as the primary source of dependency information, rather than `node_modules`.

--force
    With npm audit fix, this option forces a fix, even if it introduces breaking changes or conflicts.

--legacy-peer-deps
    Allows the installation of packages with unmet peer dependencies in `npm audit fix`.

--dry-run
    With npm audit fix, show what changes would be made without actually applying them.

--omit=<type>
    Exclude specific dependency types from the audit. Can be `dev` or `peer`. Can be specified multiple times.

--include=<type>
    Explicitly include specific dependency types. Can be `dev` or `peer`. Can be specified multiple times. Conflicts with `--omit`.

npm-audit scans your project's dependency tree for known security vulnerabilities. It leverages a vulnerability database maintained by npm, which is populated by security researchers and companies. When you run npm audit, npm sends a description of your project's dependencies (from your package-lock.json file) to the default npm registry. The registry then responds with a report detailing any identified vulnerabilities.

The report provides information on the severity of the vulnerability, affected packages, and paths through the dependency tree. It also suggests remediation steps, often including updates to vulnerable packages. A common remediation is npm audit fix, which attempts to automatically resolve identified vulnerabilities by upgrading packages to non-vulnerable versions or by modifying the dependency tree. This command is crucial for maintaining the security posture of Node.js applications by proactively identifying and addressing potential security risks before they can be exploited.

While npm audit is a powerful tool, it's not foolproof. It relies on a known vulnerability database, meaning zero-day vulnerabilities might not be detected.

Using npm audit fix --force can sometimes introduce breaking changes to your project, as it might upgrade major versions of dependencies. Always test thoroughly after running `fix` commands, especially with `force`.

The audit results can sometimes include false positives or issues that are not exploitable in your specific context.

npm audit exits with code 0 if no vulnerabilities are found, and a non-zero exit code if any vulnerabilities are found. This makes it suitable for use in CI/CD pipelines to enforce security checks.

When run as npm audit fix, npm attempts to automatically resolve vulnerabilities by upgrading packages to non-vulnerable versions. It prioritizes non-breaking changes (patch and minor upgrades). If a major version upgrade is required to fix a vulnerability, it will be noted in the report but not automatically applied unless --force is used.

The npm audit command was introduced in npm version 6.0.0, released in April 2018. Its introduction marked a significant step in npm's focus on security, providing developers with an integrated tool to identify and mitigate known vulnerabilities directly within their development workflow. Before its introduction, developers relied on third-party tools or manual checks to perform similar security analyses.

npm(1), npm install(1), npm update(1), npm fund(1), npm ls(1)