Sandworm
HomepageGitHub
  • Sandworm Audit
    • Getting Started
    • How It Works
    • Configuration
    • Issue Types
    • Resolved Issues
    • License Policies
    • Fail Policies
    • Custom Registries
    • Chart Info
  • Sandworm Guard
    • Overview
    • Getting Started
    • Supported Methods
    • Enforcing Permissions
    • Describing Permissions
    • Caller Module Paths
    • Configuration
    • Bundlers & Sourcemaps
  • Snapshot Testing
  • Contributing
    • Code of Conduct
    • Security Policy
Powered by GitBook
On this page
  • CVE vulnerabilities
  • Licenses
  • Package metadata
  • Conditionally failing the audit

Was this helpful?

Edit on GitHub
  1. Sandworm Audit

How It Works

PreviousGetting StartedNextConfiguration

Last updated 2 years ago

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).

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 , 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.

CVE vulnerabilities

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.

Identified vulnerabilities might vary between different package managers.

Licenses

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.

Package metadata

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

Conditionally failing the audit

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 .

npm's registry API
detected issue types
Advisory Database
license review process
license policy
configuring a fail policy