npmsecure

npm security scanner, hardener, and malware detector for your projects.

npm audit only runs on one project at a time, only checks the npm advisory database, and does nothing about the unsafe defaults npm ships with. npmsecure fixes that — and goes further: secret exposure, AI agent auditing, supply chain threat feeds, and incident response actions.

---

What it does

Command	What
npmsecure scan [path]	Discover all npm projects recursively, run audit, report by severity
npmsecure scan --fix	Same + run npm audit fix to patch safe upgrades automatically
npmsecure harden	Detect and fix the 6 npm config defaults that are unsafe
npmsecure locks [path] [--fix]	Check package-lock.json health across all projects
npmsecure malware [path]	Scan node_modules for known malicious packages and suspicious code
npmsecure malware --quarantine	Same + move infected packages out of node_modules immediately
npmsecure install <pkg>	Pre-install check: block risky packages before npm runs
npmsecure gitcheck [--history]	Detect exposed secrets and unprotected .env files
npmsecure threat-feed	Real-time supply chain advisory feed (GitHub Advisory + OSV)
npmsecure agents	Audit AI agent configs (Claude Code, Cursor, Cline, Windsurf…)
npmsecure policy-check	Validate project against .npmsecure.yml policy for CI
npmsecure doctor [--deep]	Full health check in one pass

---

Install

pip install npmsecure

Or from source:

git clone https://github.com/yourname/personnn-npmsecure
cd personnn-npmsecure
pip install -e .

Requires Python ≥ 3.10 and npm in your PATH.

---

Usage

scan — audit all your npm projects at once

# Scan current directory (finds all nested package.json)
npmsecure scan

# Scan a specific path
npmsecure scan ~/dev/myprojects

# Only show high and critical
npmsecure scan --min-severity high

# Cross-reference against OSV CVE database (slower, more thorough)
npmsecure scan --cve

# Auto-fix safe patches after reporting (runs npm audit fix)
npmsecure scan --fix

# Force-fix including major version bumps (review package.json after!)
npmsecure scan --force-fix

# SARIF output for GitHub / GitLab Code Scanning
npmsecure scan --sarif results.sarif

# JSON output for CI pipelines
npmsecure scan --json

# Exit codes: 0 = clean, 1 = high vulns, 2 = critical vulns

harden — fix unsafe npm defaults

npm ships with dangerous defaults. This command detects and fixes them:

Setting	Default	Safe value	Why
ignore-scripts	false	true	Prevents postinstall scripts from running arbitrary code
audit-level	not set	moderate	Fails npm install on moderate+ vulnerabilities
save-exact	false	true	Pins exact versions instead of ^ ranges
package-lock	true	true	Always generates lock file
fund	true	false	Hides funding noise that can obscure security warnings
update-notifier	true	false	Disables background outbound requests

# Preview what would change (safe, no side effects)
npmsecure harden --dry-run

# Apply hardening
npmsecure harden

Note: After setting ignore-scripts=true, packages that need to compile native binaries (e.g. bcrypt, node-gyp) require npm install --ignore-scripts=false for that specific install.

locks — package-lock health

# Check all projects
npmsecure locks ~/dev

# Auto-generate missing lock files
npmsecure locks --fix

Flags:

• Missing package-lock.json (allows installing different versions on each machine)
• Unsafe ranges (^1.2.3, ~1.2.3, *) that can silently install vulnerable versions
• Dependencies present in package.json but missing from the lock file

malware — supply chain attack detection

Scans node_modules for known malicious packages and suspicious code patterns.

# Report only
npmsecure malware
npmsecure malware ~/dev/myproject

# Report + quarantine infected packages
npmsecure malware --quarantine

When critical malware is detected, npmsecure shows a panic mode panel with immediate response steps:

1. Rotate ALL secrets (assume credentials are compromised)
2. Audit egress logs for unexpected outbound connections
3. Rebuild from a clean environment
4. Run with --quarantine to isolate packages

--quarantine mode:

• Moves the infected package directory from node_modules/ to .npmsecure_quarantine/<pkg>@<version>
• Records the blocked package at ~/.npmsecure/blocked.json
• After quarantine: run npm install to restore clean versions from the registry

Known malicious packages detected: flatmap-stream, node-ipc, ua-parser-js, coa, rc, eslint-scope, and 15+ more historical incidents.

Suspicious patterns detected:

• curl/wget downloading and executing remote code in postinstall scripts
• eval(Buffer.from(..., 'base64')) — base64 obfuscated payloads
• Long hex-encoded strings — obfuscation red flag
• process.env values being sent to external HTTP endpoints
• .npmrc file access — auth token theft
• Discord webhook exfiltration
• Crypto miner signatures (stratum+tcp, cryptonight, monero)
• System fingerprinting (os.hostname(), os.userInfo())

Exit codes: 0 = clean, 1 = suspicious patterns, 2 = critical / known malware.

install — pre-install security interceptor

# Check before installing
npmsecure install lodash

# Skip confirmation prompt
npmsecure install lodash --yes

# Pass extra npm flags through
npmsecure install lodash --save-dev

# Force install despite risks (not recommended)
npmsecure install risky-pkg --force

Checks each package for:

• Known malicious package name
• CVEs from OSV database
• Package age (blocks packages < 3 days old)
• Typosquatting (Levenshtein distance ≤ 2 vs 60 popular packages)
• No repository field + single maintainer

gitcheck — secret exposure scan

# Scan working tree for secrets and unprotected .env files
npmsecure gitcheck

# Also scan git commit history (catches deleted secrets that remain in log)
npmsecure gitcheck --history

Detects:

• .env files not listed in .gitignore
• Hardcoded API keys (OpenAI, Anthropic, Stripe, AWS, GitHub, Slack…)
• .npmrc files with auth tokens
• JWT tokens, private keys, database URLs, Supabase service keys

threat-feed — real-time advisory feed

# Latest 24h of npm supply chain advisories
npmsecure threat-feed

# Cross-reference against your installed packages
npmsecure threat-feed ~/dev/myproject

# Extend window to 72 hours
npmsecure threat-feed --hours 72

# Force refresh (ignore 24h cache)
npmsecure threat-feed --force

Pulls from GitHub Advisory Database + OSV. Updates automatically every 24h on first use.

agents — AI agent security audit

npmsecure agents
npmsecure agents --json

Audits configurations for: Claude Code, Cursor, Cline, Continue.dev, Windsurf, Aider.

Checks:

• MCP server sources (unknown, unofficial, local code)
• Broad filesystem path access (/, ~)
• Sensitive environment variables exposed to MCP
• Shell commands wired as MCP servers
• Prompt injection patterns in skills/instructions

policy-check — CI policy enforcement

# Create default policy file
npmsecure policy-check --init

# Validate against policy
npmsecure policy-check

# JSON output for CI
npmsecure policy-check --json

Configure rules in .npmsecure.yml:

version: 1
rules:
  max_severity: moderate
  require_lock_file: true
  no_unsafe_ranges: false
  allow_install_scripts: true
  blocked_packages:
    - event-stream
    - flatmap-stream
  ignored_advisories: []

doctor — full health check

# Fast mode: npm config + secrets + lock files
npmsecure doctor

# Deep mode: + git history + malware scan + live advisory feed
npmsecure doctor --deep

# JSON output for dashboards / CI
npmsecure doctor --json

---

CI integration

# GitHub Actions
- name: npm security scan
  run: |
    pip install npmsecure
    npmsecure scan --min-severity high --sarif results.sarif
    npmsecure malware
    npmsecure policy-check

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

---

Whitelist

Suppress false positives from known-safe packages that trigger pattern detection:

# List all whitelisted packages
npmsecure whitelist list

# Add a package
npmsecure whitelist add postcss --reason "source maps use base64 legitimately"

# Remove a user-added entry
npmsecure whitelist remove mypackage

Built-in whitelist covers: postcss, vite, webpack, esbuild, rollup, three, typescript, jest, babel, next, sharp, bcrypt, canvas, node-gyp, fsevents, node-sass, puppeteer, playwright, cypress.

---

How it compares

Feature	npm audit	Snyk	socket.dev	npmsecure
Multi-project scan	❌	Partial	❌	✅
Auto-fix (--fix)	Basic	✅	❌	✅
Malware / supply chain	❌	Partial	✅	✅
Quarantine infected packages	❌	❌	❌	✅
Panic mode / incident response	❌	❌	❌	✅
npm config hardening	❌	❌	❌	✅
Lock file health	Basic	❌	❌	✅
Secret / .env exposure	❌	❌	❌	✅
AI agent / MCP audit	❌	❌	❌	✅
Real-time advisory feed	❌	✅	✅	✅
Policy engine (.yml)	❌	✅	❌	✅
SARIF output (GitHub/GitLab)	❌	✅	❌	✅
Pre-install interceptor	❌	❌	Partial	✅
Open source	✅	❌	❌	✅
Free	✅	Limited	Limited	✅

---

Incident playbook: the @cap-js supply chain attack (2025)

In May 2025, malicious versions of @cap-js/sqlite, @cap-js/postgres, and @cap-js/db-service were published to npm with embedded malware.

How npmsecure would have caught it:

# 1. threat-feed catches it within 24h of GitHub Advisory publication
npmsecure threat-feed
# → CRITICAL: Supply chain compromise via malicious package versions (@cap-js/...)

# 2. malware scanner finds the payload before it runs
npmsecure malware
# → CRITICAL base64-decode-exec in @cap-js/sqlite/index.js
# → SECURITY INCIDENT panel with immediate response steps

# 3. quarantine isolates the package immediately
npmsecure malware --quarantine
# → Quarantined @cap-js/sqlite@1.x.x → .npmsecure_quarantine/

# 4. pre-install interceptor blocks future installs
npmsecure install @cap-js/sqlite
# → CRITICAL: CVE MAL-2025-xxxxx detected
# Proceed with npm install? [y/N]: N

---

Tests

pip install -e ".[dev]"
pytest

58 tests covering scanner, hardener, lock checker, malware detector, interceptor, and whitelist.

---

Roadmap

• yarn and pnpm lockfile support (read-only audit)
• HTML report with executive summary and vulnerability timeline
• SBOM export (CycloneDX / SPDX)
• Baseline mode (--since-baseline — only show new vulns)
• Maintainer trust score (release history, hijack signals)
• Monorepo workspace detection (Lerna/Turbo/Nx)
• Remote blocklist auto-update (signed JSON, fetched on run)
• IoC export (npmsecure ioc --format json) for firewall/XDR ingestion

---

License

MIT