npm-scanner

Architecture Reference

System Structure

┌─────────────────────────────────────────────────────────────────┐
│                         npm-scanner.sh                          │
│                        (Main Entry Point)                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Commands:                                                      │
│  ├─ init / refresh     → Data file management                  │
│  ├─ scan               → audit-installed-packages.sh           │
│  ├─ validate           → package-validator.sh                  │
│  ├─ list-iocs          → Display IOC definitions               │
│  └─ cache              → Cache management                      │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Core Scripts (scripts/):                                       │
│  ├─ audit-installed-packages.sh   (Unified scanner)            │
│  ├─ npm-security-audit.sh         (Single project scanner)     │
│  ├─ npm-audit-lib.sh              (Shared library)             │
│  └─ package-validator.sh          (Pre-install validation)     │
│                                                                 │
│  Automation Scripts:                                            │
│  ├─ scheduled-audit-script.sh     (Cron/scheduling)            │
│  └─ generate-summary-report.sh    (Report aggregation)         │
│                                                                 │
│  Response Scripts:                                              │
│  ├─ credential-rotation-script.sh (Incident response)          │
│  └─ npmrc-security-config.sh      (Hardening)                  │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Data Layer:                                                    │
│  ├─ ~/.npm-scanner/data/          (Downloaded lists)           │
│  │   ├─ disposable-email-domains.txt                           │
│  │   └─ tranco-top-100k.csv                                    │
│  └─ ~/.npm-scanner/cache/         (npm registry cache)         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

File Structure

npm-scanner/
├── npm-scanner.sh              # Main entry point
├── VERSION                     # Version and release date
├── scripts/
│   ├── npm-audit-lib.sh        # Shared library
│   ├── audit-installed-packages.sh
│   ├── npm-security-audit.sh
│   ├── package-validator.sh
│   ├── scheduled-audit-script.sh
│   ├── generate-summary-report.sh
│   ├── credential-rotation-script.sh
│   └── npmrc-security-config.sh
├── docs/                       # Documentation
├── templates/                  # Report templates
└── reports/                    # Scan output (gitignored)

Components

npm-scanner.sh

Main entry point and command router.

• Parses commands and options
• Manages data file lifecycle (init/refresh)
• Routes to appropriate scripts
• Provides unified help system

npm-audit-lib.sh

Shared library sourced by other scripts.

• IOC definitions (malicious domains, IPs, attacker patterns)
• Typosquatting targets list
• Cache functions for npm registry metadata
• Common utility functions

audit-installed-packages.sh

Unified scanning tool supporting three modes:

Mode	Flag	Scans
Global	--global	npm list -g packages
Local	--local	node_modules directories
Project	--project	package.json dependencies

npm-security-audit.sh

Single-project scanner used internally by audit-installed-packages.sh.

• HTTP URL dependency detection
• Lifecycle script analysis
• npm registry metadata fetching
• Risk score calculation

package-validator.sh

Pre-installation validation tool.

• Package existence and metadata
• Age and creation date
• Maintainer analysis
• Download statistics
• Typosquatting detection (Levenshtein distance)
• Disposable email detection
• Email domain reputation

Data Flow

Scan Flow

npm-scanner.sh scan --project ~/code
        │
        ▼
audit-installed-packages.sh
        │
        ▼
Find all package.json files
        │
        ▼
For each project: npm-security-audit.sh
        │
        ▼
Fetch npm registry metadata ◄── Cache layer
        │
        ▼
Check IOCs (domains, IPs, patterns, URLs, scripts)
        │
        ▼
Calculate risk score
        │
        ▼
Generate reports in reports/

Validation Flow

npm-scanner.sh validate some-package
        │
        ▼
package-validator.sh
        │
        ▼
Fetch npm registry metadata
        │
        ▼
Analyze (age, maintainers, downloads, emails)
        │
        ▼
Check typosquatting against 28 targets
        │
        ▼
Output risk assessment

Caching

npm Registry Cache

Location: ~/.npm-scanner/cache/

Setting	Default	Environment Variable
Max size	200 MB	NPM_SCANNER_CACHE_MAX_SIZE_MB
Max age	3 days	NPM_SCANNER_CACHE_MAX_AGE_DAYS

Package List Cache

Caches directory listings of node_modules. Invalidated when directory modification time changes.

Risk Scoring

Finding	Points	Severity
Known malicious domain	+100	CRITICAL
Known malicious IP	+100	CRITICAL
Attacker pattern match	+100	CRITICAL
HTTP URL dependency	+50	CRITICAL
Typosquatting match	+30	HIGH
Lifecycle scripts	+10-30	MEDIUM-HIGH
Recently created (<30 days)	+20	MEDIUM
Low downloads (<1000/week)	+15	MEDIUM
Single maintainer	+10	LOW
Disposable email	+25	HIGH

Risk levels:

• 0-25: LOW
• 26-50: MEDIUM
• 51-75: HIGH
• 76+: CRITICAL

Report Templates

Location: templates/

• templates/common/ - Shared template components
• templates/packages/ - Package scan templates
• templates/projects/ - Project scan templates

This site is open source. Improve this page.