It depends on the flags. The npm docs list workspace options that target selected workspaces, all workspaces, and whether the root project is included. Know which combination your CI job uses, because a flag can quietly remove the root project from the check.
The three options
The npm documentation for audit lists these configuration options:
- workspace limits a command to selected workspaces, by name or by path. A path to a parent directory selects all workspaces inside it.
- workspaces runs the command in the context of all configured workspaces.
- include-workspace-root defaults to false. Without it, naming workspaces means npm operates on the specified workspaces and not on the root project.
The third point is the surprise. If you add a workspace selector to an audit command, the root package.json is skipped unless you ask for it.
npm audit --workspaces --include-workspace-root
What each choice means
| Command shape | Covers | Misses |
|---|---|---|
| Plain audit at root | The project as npm resolves it | Nothing by design, but read the output carefully |
| Audit with a workspace selector | Chosen workspaces | The root, unless included |
| Audit across all workspaces plus root | Everything | Nothing, but the output is long |
Check the output against your package list. If you expect twelve packages and the report names nine, find the difference before you trust a clean result.
Prod versus dev
The docs also describe an omit option. Omitted dependencies are still resolved and kept in the lockfile, and for audit the docs say they are left out of the submitted payload as appropriate. Decide on purpose whether your gate checks development dependencies, and see do dev dependencies matter for how to think about it.
Failing the build
The audit level option sets the lowest severity that produces a non zero exit code. The docs are explicit that it does not filter the report. It only changes the failure threshold. A job set to high will still print low findings, and will pass if none is high or above.
- Pick a level for the gate, for example high.
- Keep the full report as a build artifact.
- Review the lower findings on a schedule, not on every pull request.
Limits to remember
npm audit works from the dependency tree and advisory data. It does not tell you whether a vulnerable function is called, and it does not read non npm parts of a polyglot repo. For Python or Java folders you need a different tool or a scanner that covers several ecosystems.
Safeguard scans npm lockfiles along with other ecosystems and applies reachability analysis to prioritise results. The free scan at https://gold.safeguard.sh/scan covers one project.
Try it yourself
In the demo, sort findings and look at how severity and fix availability help you decide what to gate on.
Click through it at your own pace, or open it full screen.
Quick check
Does naming a workspace include the root project?
No. The docs say the root is left out unless you set include-workspace-root.
Does the audit level filter the report?
No. It changes only the exit code threshold.
Sources
Last reviewed: 19 October 2026.
