Three npm features change what is really installed: overrides replace a package anywhere in the tree, aliases install a package under another name, and optional dependencies may be skipped. A scan of package.json alone can misreport all three. Scan the lockfile or the installed tree instead.
What each feature does
Overrides. The npm documentation says they "provide a way to replace a package in your dependency tree with another version, or another package entirely." Setting "foo": "1.0.0" pins every copy of foo in the tree to that version. Overrides are only considered in the root package.json.
Aliases. The syntax "kpg": "npm:pkg@1.0.0" installs pkg@1.0.0 under the name kpg. The folder and import name say one thing and the real package says another.
Optional dependencies. Build failures do not cause installation to fail, and installing with the omit optional setting skips them entirely. The docs say it is still your program's job to handle the absence.
What can go wrong in a scan
| Feature | Naive scan mistake |
|---|---|
| Override to a fixed version | Reports the old version declared by a parent package |
| Override to a different package | Looks up advisories for the wrong name |
| Alias | Searches for the alias name and finds no record |
| Optional dependency | Reports a package that never installed, or misses one that did |
The lockfile records what npm resolved, including these substitutions, so a lockfile aware tool is far less likely to be wrong. This is also why an override is a legitimate way to fix a transitive vulnerability, but only if the scan confirms the result. See pinning versus ranges and its trade offs for the trade offs of pinning.
Verify an override worked
- Record the scan result before the change.
- Add the override to the root package.json and reinstall to refresh the lockfile.
- Run the scan against the new lockfile and confirm the finding is gone.
- Run your tests, since an override can break a parent package that expected the old range.
- Re-check after each parent update, because the override may become unnecessary or conflict.
Verify aliases are understood
Create a test project with an alias to a package version that has a known advisory. Scan it. If the tool reports nothing, it is reading the alias name and not the real one. Report that to the maker and add the alias list to your manual review.
Safeguard's dependency scanning works from resolved dependency data, and you can try a lockfile at https://gold.safeguard.sh/scan.
Quick check
Does an override in a dependency's own package.json apply?
No. The npm documentation says overrides are only considered in the root package.json of a project.
Why might a scanner miss an aliased package?
It may look up the alias name instead of the real package name, so no advisory matches.
Sources
Last reviewed: 19 October 2026.
