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