Metadata-Version: 2.4
Name: npmsecure
Version: 0.1.0
Summary: 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
Author-email: Niccolas Munoz <niccolas@azomland.com>
License: MIT License
        
        Copyright (c) 2026 azomland
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/azomland/npmsecure
Project-URL: Repository, https://github.com/azomland/npmsecure
Project-URL: Issues, https://github.com/azomland/npmsecure/issues
Keywords: npm,security,supply-chain,malware,audit,cve,secrets,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: requests>=2.31
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install npmsecure
```

Or from source:

```bash
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

```bash
# 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 |

```bash
# 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

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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`:

```yaml
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

```bash
# 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

```yaml
# 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:

```bash
# 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:**

```bash
# 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

```bash
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
