How It Works
Sandworm starts by parsing your app manifest (the content of your
package.jsonfile), as well as your lockfile (
pnpm-lock.yaml, depending on what package manager you use).
Make sure that Sandworm runs against the most recent lockfile for your app. The lockfile represents the source-of-truth for information about what packages and what versions are currently in 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 npm's registry API, but an offline alternative exists that's able to retrieve less info, but locally, from the
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 memoryerror while outputting the charts, your options are:
- Allocate more memory to the node process by exporting
- Reduce the depth of the tree represented by passing the
--max-depthoption to Sandworm - defaults to 7 layers of depth
- Use the
--skip-treeoption to skip building the tree
- Try another package manager
Sandworm retrieves CVE vulnerabilities via your package manager's command-line tool, by reading the results of
yarn audit, or
pnpm audit. Vulnerabilities come from GitHub's Advisory Database. The entire original advisory content is attached to each vulnerability that Sandworm outputs to the JSON report file.
Identified vulnerabilities might vary between different package managers.
Sandworm verifies dependency licenses to be:
- explicitly specified
- valid SPDX
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 license review process.
By default, Sandworm also issues:
- high severity issues for network protective and strongly protective licenses;
- moderate severity issues for weakly protective licenses.
You can also define a custom license policy for your app by specifying allowed licenses vs. licenses or categories that should trigger audit issues.
When identifying a package's license, Sandworm currently only looks at the
licensefield in the manifest file. Reading package
LICENSEfiles 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:
- packages with install scripts:
Sandworm is configurable to fail and exit with code
1after 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 configuring a fail policy.