Skip to main content

npm Application Analysis

IQ evaluates JavaScript applications using Advanced Binary Fingerprinting (ABF) enhanced with metadata-assisted hash-based matching. This method analyzes package metadata (package.json and lock files) and the SHA-1 hashes of nearby JavaScript files to precisely identify npm components.

The result is a component inventory based on the actual files present in the application rather than just the declared dependency metadata. This helps reduce false positives and improves accuracy in both security and license reporting.

How IQ Identifies npm Components

IQ’s npm application analysis process is designed to do the following:

  • Distinguish between declared dependencies and the files that are truly included in the application

  • Provide high-confidence identification by verifying files against authoritative package data

  • Avoid reporting vulnerabilities for code that is not present in the scanned application

1 - Metadata Parsing

During a scan, IQ collects all package.json files present in the application. These files act as anchors for component identification.

For each package.json, IQ extracts the name and version. These coordinates define the package version that the scanner will attempt to match.

2 - Find Official Package Hashes

Using Sonatype’s proprietary data sources, the scanner determines the SHA-1 hashes associated with the package’s published files. This returns the definitive set of expected file hashes for that package version.

3 - Candidate File Discovery

For each dependency, the scanner reviews JavaScript files located near its package.json file. These files are evaluated to determine whether they belong to that dependency’s published package contents.

A note on which package.json files are used

The package.json files inside each dependency’s own directory (not the application’s root package.json) drive most identification. These dependency package.json files are created automatically when npm or yarn builds node_modules, and they provide the metadata that powers matching.

Only files that can be confidently associated with a dependency are included in the inventory.

4 - Hash Comparison

IQ computes the SHA-1 hash for each candidate file and compares it to the official hashes retrieved from Sonatype’s proprietary data in step 2.

If a file hash matches, the following happens:

  • The file is confirmed to be part of that npm package

  • IQ flags it as an identified component with exact-match confidence

  • Only the matching files are attached to that component’s analysis

Files that do not match known hashes are excluded from the component inventory, even if located near a dependency’s metadata. This ensures the analysis reflects only the code that is truly present and reduces noise in security and license reporting.

Advanced Binary Fingerprinting Behavior: JavaScript Files vs. Manifest Files

Scan behavior depends on which files are included in that scan:

When JavaScript files are included:

  • ABF is used, and JavaScript files act as the primary identification source.

  • Manifest entries without corresponding JavaScript files are ignored.

  • Use this mode when you want analysis of your actual shipped code.

When only manifest and lock files are included:

  • IQ performs manifest matching, evaluating dependences purely from metadata.

  • This identifies all declared dependencies (direct and transitive) based on the lock file’s contents.

  • Use this mode when analyzing SBOM metadata or when built artifacts are unavailable.

Supported Scan Targets

Supported scan targets include the following:

  • *.js

  • *.ts

  • *.tgz

  • package.json (requires package-lock.json)

  • package-lock.json

  • npm-shrinkwrap.json

  • yarn.lock

  • pnpm-lock.yaml

  • node_modules (after a clean production flag build)

Results include component identity, license data, and security findings.

For the most precise results, you should include a package.json, package-lock.json, and the node_modules folder.

Legacy A-Name Behavior (Sunset)

In earlier IQ versions, JavaScript files that could not be matched to an npm package were sometimes identified as A-name components. This legacy mechanism assigned authoritative names to individual files.

A-name matching has been sunset as of 2025-09-10:

  • Scanning loose *.js files no longer produces A-name matches.

  • These files now appear as unknown JavaScript files unless matched through metadata-assisted identification.

  • License data is still taken from the associated open-source package where applicable.

Unknown JavaScript files can be viewed by adding ?unknownjs to the end of the report URL.