npm Package Scanner

The npm package scanner automatically detects and extracts all third-party dependencies declared in your JavaScript and TypeScript projects that use npm as their package manager.

What It Does

Default file: package.json

When you enable the npm scanner during SBOM creation, CAST SBOM Manager will:

• Find all npm manifest files (package.json and package-lock.json) throughout your codebase
• Extract declared dependencies from package.json files
• Extract resolved dependencies with exact versions from package-lock.json files
• Support both lockfile formats - legacy npm 5/6 (lockfileVersion 1) and modern npm 7+ (lockfileVersion 2+)
• Handle version ranges and extract pinned versions where available
• Filter to direct dependencies when configured to exclude transitive dependencies

What Gets Detected

The npm scanner identifies dependencies from two types of files:

Package Manifest (package.json)

From package.json files, the scanner extracts:

• Direct dependencies declared in the dependencies section
• Package names and their version constraints
• Pinned versions (when exact versions like "1.2.3" are specified)

Version handling:

• Exact versions (e.g., "2.0.13") are captured as pinned versions
• Version ranges (e.g., "^2.0.0", "~1.5.0", ">=1.0.0 <2.0.0") are recognized but the package is recorded without a specific pinned version
• This allows you to see which dependencies are declared, even if their exact version will be resolved by npm

Lock Files (package-lock.json)

From package-lock.json files, the scanner extracts:

• All resolved dependencies with their exact installed versions
• Both direct and transitive dependencies (unless filtered)
• Precise version numbers as resolved by npm during installation

Format support:

• npm 5/6 lockfiles (lockfileVersion 1) - Reads from top-level dependencies object
• npm 7+ lockfiles (lockfileVersion 2+) - Reads from packages object with node_modules/ prefixed keys

How It Works

Package.json Processing

When scanning a package.json file, the scanner:

1. Parses the JSON structure
2. Locates the dependencies section
3. For each dependency:
   • Extracts the package name
   • Parses the version constraint using npm-style semver parsing
   • If the constraint is an exact version (single value with = semantics), stores it as the pinned version
   • If the constraint is a range, records the dependency without a specific version

Package-lock.json Processing

The scanner handles both npm lockfile formats:

Modern Format (npm 7+, lockfileVersion 2+):

1. Reads the packages object
2. Identifies the root package (key "") which contains direct dependencies
3. For each direct dependency, looks up its resolved version under node_modules/<package-name>
4. Extracts the exact version from the package entry

Legacy Format (npm 5/6, lockfileVersion 1):

1. Reads the top-level dependencies object
2. For each dependency entry, extracts the package name and exact version field
3. Builds the dependency list with resolved versions

What It Doesn't Detect

The npm scanner has different behavior depending on which file type it's processing:

When scanning package.json files:

• Development dependencies - Packages in devDependencies are not extracted
• Optional dependencies - Packages in optionalDependencies are not extracted
• Peer dependencies - Packages in peerDependencies are not extracted
• Only the dependencies section is processed

When scanning package-lock.json files:

• All resolved packages are extracted by default, regardless of whether they originated from dependencies, devDependencies, peerDependencies, or optionalDependencies
• When "direct dependencies only" filtering is enabled, the scanner includes packages from dependencies, devDependencies, and peerDependencies sections of the corresponding package.json

Neither file type detects:

• Manually copied JavaScript libraries not declared in package.json
• Embedded or copy-pasted code from open source projects
• CDN-loaded libraries referenced only in HTML files

For complete open source detection including undeclared components and copied code, enable the OSS Knowledge Base scanning option in the Scanners step, which analyzes actual file content to identify all open source usage.