Getting Started


Sandworm Audit requires Node 14.19+.
When using npm, Sandworm Audit supports lockfile versions 2 and 3 (npm 7+).
Install sandworm-audit globally via your favorite package manager:
npm install -g @sandworm/audit
# or yarn global add @sandworm/audit
# or pnpm add -g @sandworm/audit
You can also directly run without installing via:
npx @sandworm/audit@latest
# or yarn dlx -p @sandworm/audit sandworm
# or pnpm --package=@sandworm/audit dlx sandworm

Run Sandworm in the terminal

To use Sandworm Audit as a command-line tool, simply run sandworm-audit or npx @sandworm/audit@latest in the root directory of your app, or use the -p option to point to the root dir.
The app root directory should contain a manifest file (package.json) and a lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml).
If you use workspaces, make sure to run Sandworm in the directory of the package you want to audit.
You can use a configuration file, or you can pass configuration options directly to the command-line tool. Here are the available options, that you can also list by running sandworm-audit --help:
-v, --version Show version number [boolean]
--help Show help [boolean]
-o, --output-path The path of the output directory, relative to the
application path [string] [default: "sandworm"]
-d, --include-dev Include dev dependencies[boolean] [default: false]
--sv, --show-versions Show package versions in chart names
[boolean] [default: false]
-p, --path The path to the application to audit [string]
--md, --max-depth Max depth to represent in charts [number]
--ms, --min-severity Min issue severity to represent in charts [string]
--lp, --license-policy Custom license policy JSON string [string]
-f, --from Load data from "registry" or "disk"
[string] [default: "registry"]
--fo, --fail-on Fail policy JSON string [string] [default: "[]"]
-s, --summary Print a summary of the audit results to the
console [boolean] [default: true]
--root-vulnerabilites Include vulnerabilities for the root project
[boolean] [default: false]
--skip-license-issues Skip scanning for license issues
[boolean] [default: false]
--skip-meta-issues Skip scanning for meta issues
[boolean] [default: false]
--skip-tree Don't output the dependency tree chart
[boolean] [default: false]
--force-tree Force build large dependency tree charts
[boolean] [default: false]
--skip-treemap Don't output the dependency treemap chart
[boolean] [default: false]
--skip-csv Don't output the dependency csv file
[boolean] [default: false]
--skip-report Don't output the report json file
[boolean] [default: false]
--skip-all Don't output any file [boolean] [default: false]
--show-tips Show usage tips [boolean] [default: true]
Generating a report can sometimes take a while, depending on how many direct and transient dependencies your app has in total. Sandworm fetches details about each individual dependency from the registry, so network conditions and registry availability are factors that can influence the total audit duration.
Dense, convoluted dependency graphs may require a lot of memory to render into the SVG trees that Sandworm produces. If the auditing process crashes with a heap out of memory error while outputting the charts, your options are:
  • Allocate more memory to the node process by exporting NODE_OPTIONS="--max-old-space-size=16384"
  • Reduce the depth of the tree represented by passing the --max-depth option to Sandworm - defaults to 7 layers of depth
  • Use the --skip-tree option to skip building the tree
  • Try another package manager
After completing a report, Sandworm: