The guardian of your dependencies

A security CLI for Node.js developers. Scan for malicious packages, detect typosquatting, monitor outbound connections, enforce license compliance, and audit your supply chain — 100% local, no data ever leaves your machine.

Installation | Commands | Detection | Policy (.wardenrc) | Docs | Roadmap

English docs | Documentacion en espanol

---

Why warden?

The npm ecosystem has a growing supply-chain attack problem:

• Typosquatting — packages with names similar to popular ones (lodashs, expres)
• Postinstall scripts — arbitrary code execution the moment you run npm install
• Credential exfiltration — packages that read process.env and send tokens to external servers
• Code obfuscation — eval(), Function(), hex-encoded payloads hidden in dependencies
• Compromised maintainers — legitimate packages that get hijacked

warden gives you visibility and control through static analysis, runtime monitoring, license compliance, and enforceable policies — all running 100% locally.

---

Installation

npm install -g warden-cli

Requirements: Node.js >= 18, npm >= 8

warden --version   # 0.2.0
warden doctor      # health check + security score

---

Commands

Command	Description
warden check [path]	Pre-install gate — blocks npm install if dangerous versions detected
warden scan [path]	Static analysis of node_modules — 11 detection categories
warden audit [path]	npm audit with readable, grouped output
warden fix [path]	Apply vulnerability fixes (dry-run by default)
warden monitor	Real-time outbound connection monitor
warden config	Manage npm security settings across Node versions
warden update [path]	Interactive dependency updater with backup
warden license [path]	License compliance scanner with allow/deny lists
warden doctor	Environment health check with security score (0-100)
warden report [path]	Generate JSON/Markdown security reports
warden versions	Manage known-dangerous package versions list

---

warden check [path]

Pre-install gate. Reads package.json + package-lock.json and blocks installation if a dangerous version is detected. Add to your preinstall script to make it automatic:

{
  "scripts": {
    "preinstall": "warden check"
  }
}

warden check              # check current directory
warden check ./my-project

warden scan [path]

Path is optional — defaults to the current directory.

warden scan                              # scan current directory
warden scan ./my-project
warden scan ./my-project --only-dangerous
warden scan ./my-project --output json > report.json

Options: --only-dangerous --verbose --output json

warden audit [path]

warden audit ./my-project --level high

Options: --level <critical|high|moderate|low|info>

warden fix [path]

warden fix ./my-project              # dry-run (preview)
warden fix ./my-project --apply      # apply safe fixes
warden fix ./my-project --apply --force  # include breaking changes

warden monitor

warden monitor --interval 2 --alert
warden monitor --pid 9832

warden license [path]

warden license ./my-project
warden license ./my-project --deny GPL-3.0,AGPL-3.0
warden license ./my-project --allow MIT,ISC,Apache-2.0 --fail-on-unknown
warden license ./my-project --output json

warden update [path]

warden update ./my-project --patch-only

warden doctor

warden doctor

warden versions

warden versions                                              # list all known dangerous versions
warden versions add event-stream@3.3.6 --reason "..."       # add to your local list
warden versions add pkg@1.0.0 --reason "..." --source "url" --severity high
warden versions remove event-stream@3.3.6                   # remove from your local list

warden report [path]

warden report . --format markdown --out security-report.md

---

Detection

Warden scans every package in node_modules across 12 detection categories:

Category	What it detects	Severity
Dangerous Version	Exact match against 63 known-malicious name@version entries	High
Typosquatting	Names similar to popular packages (Levenshtein distance)	High
Obfuscation	eval(), new Function(), XOR cipher, Buffer.from('base64'), hex/Base64 payloads, string reversal, dynamic require()	High
Anti-Forensic	Self-deletion (unlinkSync(__filename)), evidence tampering (write to own package.json), file swap	High
Lifecycle Scripts	preinstall, postinstall, prepare in package.json	High
System Execution	exec(), spawn(), child_process, shelljs, execa	High
Filesystem Access	Read/write to .ssh, .env, .aws/credentials, /etc/passwd	High
Env Exfiltration	process.env.TOKEN, SECRET, AWS_*, GITHUB_TOKEN	High
Crypto Operations	crypto.createCipher(), encryption that may indicate ransomware	Medium
Network Calls	fetch(), http.request(), WebSocket, axios, got	Medium
Native Binaries	.node, .so, .dll, .exe files (unauditable code)	Medium
Git Dependencies	git+https://, github: — bypass npm registry checks	Medium

Risk Classification

Level	Condition
DANGEROUS	Known dangerous version; OR typosquat; OR anti-forensic + obfuscation/exec/lifecycle; OR obfuscation + network; OR exec + network/env; OR lifecycle + exec/obfuscation/network; OR filesystem + exec; OR crypto + network
SUSPICIOUS	Any single risk signal
CLEAN	No findings

Full detection documentation: docs/en/detection.md

---

Policy

Create a .wardenrc file in your project root to enforce security policies:

{
  "scan": {
    "ignorePackages": ["esbuild", "rollup"],
    "failOnRisk": "DANGEROUS",
    "maxSuspicious": 20,
    "blockDangerousVersions": true
  },
  "audit": {
    "failOnSeverity": "high"
  },
  "license": {
    "deny": ["GPL-3.0", "AGPL-3.0", "SSPL-1.0"],
    "allow": ["MIT", "ISC", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause"],
    "failOnUnknown": true
  },
  "policy": {
    "bannedPackages": ["request", "colors"]
  }
}

Exit Codes

Code	Meaning
0	Success
1	Policy violation (banned package, max suspicious)
2	DANGEROUS package found
3	Vulnerability threshold exceeded
4	License violation
99	Error

Full policy documentation: docs/en/policy.md

---

CI/CD Integration

# GitHub Actions
- run: npm install -g warden-cli
- run: warden scan .
- run: warden audit . --level high
- run: warden license .
- run: warden report . --format markdown --out security-report.md

Full CI/CD guide: docs/en/ci-cd.md

---

Data Files

Detection data is stored in editable JSON files — no code changes needed to contribute:

File	Purpose	How to contribute
src/data/popular-packages.json	150+ packages for typosquatting detection	Add a package name to the array
src/data/licenses.json	SPDX license classifications	Add an identifier to the right category
src/data/dangerous-versions.json	63 known-malicious name@version entries	Add an entry or use warden versions add

User-specific entries go to ~/.warden/dangerous-versions.json and are merged at runtime with the bundled list. Incidents covered include event-stream (2018), ua-parser-js (2021), node-ipc (2022), the Shai-Hulud Attack (Sept 2025, 40+ packages), and the Axios RAT Attack (March 2026).

---

Architecture

src/
├── index.ts              # CLI entry point
├── data/                 # Editable JSON (popular packages, licenses)
├── types/                # Domain types (as const enums, zero any)
├── constants/            # Detection patterns, thresholds, features
├── services/             # Business logic (no CLI knowledge)
│   ├── AstAnalyzer.ts        PackageScanner.ts     RiskCalculator.ts
│   ├── NpmrcManager.ts       AuditRunner.ts        NetworkMonitor.ts
│   ├── DependencyAnalyzer.ts  PolicyLoader.ts       LicenseScanner.ts
│   ├── TyposquatDetector.ts  DangerousVersionsChecker.ts
├── commands/             # Thin CLI handlers (10 commands)
└── utils/                # display, prompt, fs helpers

Full architecture docs: docs/en/architecture.md

---

Tech Stack

Dependency	Purpose
acorn	JavaScript AST parser
commander	CLI framework
chalk	Terminal colors
ora	Spinners
cli-table3	Tables

Zero runtime dependencies beyond these five. No API calls. No telemetry.

---

Security Guarantees

• 100% local — no data ever leaves your machine
• No root required — lsof/ss work as a regular user
• Read-only by default — scan, audit, doctor, license, report never modify files
• Explicit confirmation for destructive ops (fix, config disable)
• Automatic backups before any file modification (fix, update)

---

Documentation

Language	Link
English	docs/en/
Espanol	docs/es/

Includes: Getting started, command reference, detection patterns, policy configuration, architecture, CI/CD integration, and contributing guide.

---

Roadmap

• Unit test suite (vitest)
• warden sbom — Software Bill of Materials (CycloneDX/SPDX)
• warden diff — Compare security profiles between two snapshots
• SARIF output for GitHub Code Scanning
• Windows support for warden monitor
• GitHub Actions reusable action
• VS Code extension
• Supply-chain risk scoring (package age, maintainer count, download trends)

---

Contributing

Contributions welcome! Start here:

• Add detection patterns — edit src/constants/patterns.ts
• Add popular packages — edit src/data/popular-packages.json
• Add license identifiers — edit src/data/licenses.json
• Report a dangerous version — edit src/data/dangerous-versions.json or run warden versions add
• Write tests — RiskCalculator.ts and TyposquatDetector.ts are pure functions, ideal for unit tests

Full contributing guide: docs/en/contributing.md

---

License

MIT

---

_{Built for the Node.js community. If warden helped you catch something, consider giving it a star.}