How It Works
Last updated
Was this helpful?
Last updated
Was this helpful?
Sandworm starts by parsing your app manifest (the content of your package.json
file), as well as your lockfile (package-lock.json
, yarn.lock
, or pnpm-lock.yaml
, depending on what package manager you use).
Sandworm then builds a standardized dependency graph object, representing the hierarchical structure of all your dependencies, and adds package metadata on top. By default, Sandworm obtains metadata from , but an offline alternative exists that's able to retrieve less info, but locally, from the node_modules
directory.
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
Multiple types of issue scans are then performed - see for the full list.
Sandworm retrieves CVE vulnerabilities via your package manager's command-line tool, by reading the results of npm audit
, yarn audit
, or pnpm audit
. Vulnerabilities come from GitHub's . The entire original advisory content is attached to each vulnerability that Sandworm outputs to the JSON report file.
Sandworm verifies dependency licenses to be:
explicitly specified
valid SPDX
OSI-approved
non-deprecated
By default, Sandworm also issues:
high severity issues for network protective and strongly protective licenses;
moderate severity issues for weakly protective licenses.
When identifying a package's license, Sandworm currently only looks at the license
field in the manifest file. Reading package LICENSE
files is on the roadmap.
Dependency metadata is also verified against common indicators of risk or poor quality, such as
deprecated packages
packages with non-registry URLs: file:
, git:
, https:
packages with install scripts: preinstall
, postinstall
If possible, aim to use OSI-approved licenses. The goal of the OSI License Review Process is to ensure that licenses and software labeled as “open source” conform to existing community norms and expectations. Read more about the .
You can also define a custom for your app by specifying allowed licenses vs. licenses or categories that should trigger audit issues.
Sandworm is configurable to fail and exit with code 1
after performing the audit and writing audit artifacts, if specific types of issues are discovered. This allows you to configure a custom fail policy for your app, and enforce it within CI or Git hook workflows. Read more about .