Malicious Package Detection
Relevant source files
The following files were used as context for generating this wiki page:
Malicious Package Detection is a core security capability of the Unified Security Scanner designed to protect the software supply chain. It identifies risks associated with third-party dependencies, including typosquatting, dependency confusion, and the presence of malicious scripts within package configurations. This system operates as part of a multi-phase scanning strategy, combining traditional SAST filters with targeted deep dives into dependency metadata and installation scripts.
The module focuses on identifying "Critical Priority" threats such as data exfiltration, backdoors, and obfuscation. By analyzing package manifests and registry metadata, it prevents developers from accidentally introducing compromised or fraudulent code into their environments.
Sources: README.md:28-33, README.md:43-46, CHANGELOG.md:15-16
Architecture and Data Flow
The detection system is integrated into the core scanning engine and is orchestrated through specialized analyzers. It primarily targets package manifest files (e.g., package.json) to inspect dependency trees and lifecycle scripts.
Detection Logic Flow
The following diagram illustrates how the scanner identifies a potential malicious package during a scan session.
The scanner processes files to identify dependency-related risks by comparing package names against known legitimate libraries and scanning scripts for dangerous patterns like network requests during installation.
Sources: SECURITY_REVIEW.md:154-159, rules/npm/security.yml:1-10, README.md:150-160
Key Detection Mechanisms
Typosquatting Detection
The scanner identifies packages that mimic popular libraries by calculating the Levenshtein distance between dependency names. A distance of 2 or less relative to a high-traffic package triggers an alert. The system is designed to distinguish between legitimate variations (e.g., jest vs next) and malicious clones by optionally incorporating package popularity data.
| Component | Logic/Threshold | Description |
|---|---|---|
| Distance Metric | Levenshtein <= 2 | Measures character substitutions/omissions between names. |
| Whitelist | Popular Pairs | Prevents false positives for known legitimate packages like react and preact. |
| Popularity Check | < 1000 Downloads | Flags low-download packages that resemble high-profile ones. |
Sources: SECURITY_REVIEW.md:154-177, README.md:43-46
Installation Script Analysis
The scanner utilizes Semgrep-based rules to inspect package.json for suspicious lifecycle scripts. It specifically monitors postinstall and other execution hooks for patterns indicating potential compromise.
- Network Requests: Detection of
curl,wget, orfetchin scripts that may download secondary payloads. - Environment Leaks: Monitoring access to
npm_*environment variables which could contain sensitive authentication tokens. - Code Injection: Identifying the use of
eval()within scripts to execute obfuscated code.
# Example Rule: Detecting network access in postinstall
id: npm-postinstall-network-request
patterns:
- pattern-inside: |
{ "scripts": { "postinstall": "$SCRIPT" } }
- metavariable-pattern:
metavariable: $SCRIPT
patterns:
- pattern-regex: .*(curl|wget|fetch|http|https).*
Sources: rules/npm/security.yml:1-40, CHANGELOG.md:15-16
Configuration and Implementation
Malicious package detection is managed via the customScanners and semgrep tool configurations. Users can exclude specific directories or define custom rules for their organization's tech stack.
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
tools.customScanners.enabled | Boolean | true | Enables the malicious package analyzer module. |
scan.exclude | Array | ["**/node_modules/**"] | Directories to ignore during the file-level scan. |
falsePositives.patterns | Array | [] | Suppression rules for known-safe package name collisions. |
Sources: configs/default.json:1-30, CONTRIBUTING.md:20-30
Technical Debt Integration
The malicious package detection system works alongside technical debt tracking to identify End-of-Life (EOL) dependencies. While not always inherently "malicious," unmaintained packages are frequently targeted for supply chain takeovers.
The orchestrator coordinates between analyzing for active malice and identifying passive risks like outdated or unmaintained dependencies.
Sources: CHANGELOG.md:15-18, SECURITY_REVIEW.md:184-190, src/index.ts:7-10
Conclusion
Malicious Package Detection in the Unified Security Scanner provides a multi-layered defense against supply chain attacks. By combining name-similarity analysis (typosquatting) with behavioral script inspection, the system identifies high-risk dependencies before they can compromise the development lifecycle. This module is essential for maintaining compliance and preventing data exfiltration in modern, dependency-heavy projects.