npm-scanner

Command Reference

Synopsis

npm-scanner.sh <command> [options]

Commands

Command	Description
init	Download required data files (run once after install)
refresh	Update data files to latest versions
scan	Scan installed packages or project dependencies
validate	Check a package before installation
list-iocs	Display all current indicators of compromise
cache	Manage the npm metadata cache
help	Show help message
version	Show version information

---

init

Download required data files for enhanced detection.

npm-scanner.sh init

Downloads:

• Disposable email domain list (~3000 domains)
• Tranco top 100k domain rankings

Data is stored in ~/.npm-scanner/data/.

---

refresh

Update data files to latest versions.

npm-scanner.sh refresh

Run periodically (monthly recommended) to keep detection data current.

---

scan

Scan installed packages or project dependencies for security issues.

Usage

npm-scanner.sh scan [options] [path]

Scan Modes

Option	Description
-g, --global	Scan globally installed packages
-l, --local	Scan node_modules directories under path
-p, --project	Scan packages declared in package.json files

Common Options

Option	Description
-o, --output DIR	Output directory (default: reports/packages-TIMESTAMP)
-n, --limit N	Limit scan to first N items (0 = no limit)
-r, --random	Randomly sample instead of sequential order
-v, --verbose	Show detailed IOC checks during scan
--yes	Skip confirmation prompt
-h, --help	Show help

Scan-Specific Options

Option	Applies To	Description
-d, --depth N	--global, --local	Maximum depth in node_modules (default: 10)
-e, --exclude DIR	--project	Exclude directories from scan (repeatable)
--parallel	--project	Run audits in parallel
-s, --summary	--project	One-line output per project

Exit Codes

Code	Meaning
0	No issues found
1	Issues found (check report)
2	Error during scan

---

validate

Check a package before installation.

Usage

npm-scanner.sh validate <package-name>

Checks Performed

• Package age and creation date
• Maintainer count and identity
• Download statistics
• Typosquatting potential (Levenshtein distance to popular packages)
• Known malicious indicators
• Disposable email detection
• Email domain reputation

---

list-iocs

Display all current indicators of compromise (IOCs) being checked.

npm-scanner.sh list-iocs

Shows:

• Malicious domains
• Malicious IP addresses
• Attacker username/email patterns
• Typosquatting target packages

---

cache

Manage the npm metadata cache.

Usage

npm-scanner.sh cache [options]

Options

Option	Description
--status	Show cache statistics (default)
--clear	Clear all cached data
--clear-expired	Clear only expired cache entries

Environment Variables

Variable	Default	Description
NPM_SCANNER_CACHE_MAX_SIZE_MB	200	Maximum cache size in MB
NPM_SCANNER_CACHE_MAX_AGE_DAYS	3	Cache expiration in days

---

Files and Directories

Path	Description
~/.npm-scanner/	Scanner data directory
~/.npm-scanner/data/	Downloaded data files
~/.npm-scanner/cache/	npm metadata cache
reports/	Default output directory for scan results

This site is open source. Improve this page.