npmsecure 0.1.0

npm security scanner, hardener, and malware detector: audit all your projects at once, fix unsafe npm defaults, quarantine malicious packages, and audit AI agent configs

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/azomland/npmsecure
cd 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