Zero-friction supply chain security for npm. Protects humans and AI agents from malicious lifecycle scripts and dependency injection attacks.

When you run npm install, packages can execute hidden commands through lifecycle scripts (preinstall, postinstall). These scripts can steal tokens, delete files, install backdoors, or open reverse shells - silently, automatically. Worse, a legitimate package can be compromised to inject a malicious dependency that carries the payload (as happened with the axios supply-chain attack of March 2026).

npm-guard catches them before they run.

npm-guard setup     # One-time: wraps your npm command
npm install express  # npm-guard deep-scans automatically, then installs

npm-guard check express --deep --json   # Machine-readable deep scan
# AI agent parses JSON, decides whether to proceed

See AI_INSTRUCTIONS.md for the full AI integration protocol.

npm install -g npm-guard

npm-guard

Guided menu with explanations in plain language.

npm-guard check express              # Shallow check (lifecycle scripts only)
npm-guard check lodash axios react   # Check multiple packages
npm-guard check express --json       # JSON for machines
npm-guard check express --html       # HTML report

npm-guard check axios --deep         # Full dependency tree analysis
npm-guard check axios --deep --json  # Deep scan with JSON output
npm-guard check axios --deep --html  # Deep scan HTML report

The --deep flag enables:

• Recursive scanning of all transitive dependencies
• Detection of newly-injected dependencies vs. the previous version
• Package age verification (flags packages published < 7 days ago)
• Typosquatting name detection (e.g. plain-crypto-js mimicking crypto-js)

npm-guard scan                       # Current project
npm-guard scan /path/to/project      # Specific path
npm-guard scan --json --fail-on high # CI/CD pipeline

npm-guard setup      # Inject wrapper into .zshrc/.bashrc
npm-guard status     # Check if wrapper is active
npm-guard uninstall  # Remove wrapper

After setup, every npm install <package> is automatically deep-scanned. If threats are found, the installation is blocked.

The obfuscation rule goes beyond simple pattern matching with combinatorial analysis:

• Download + Execute: curl ... | bash detected as supply-chain attack
• Silent execution: > /dev/null 2>&1 flagged when hiding output
• Reverse shells: /dev/tcp connections detected
• Payload dropping: write hidden file + chmod +x + execute
• Heavy obfuscation: counts hex escape sequences, flags if > 10
• Persistence: crontab, systemctl, launchctl for backdoor installation

The dependency-risk rule, activated by the --deep flag, detects the exact attack pattern used in the axios compromise:

Example: if [email protected] adds plain-crypto-js (published 20 hours ago, name mimics crypto-js), npm-guard would flag it with 4+ findings at CRITICAL level and block the installation.

npm-guard is designed to be used as a security tool by AI coding agents.

# 1. Deep-check package before install
npm-guard check <package> --deep --json

# 2. Parse response
# summary.maxRiskLevel: "SICURO" | "BASSO" | "MEDIO" | "ALTO" | "CRITICO"
# results[].depRiskFindings: supply-chain specific alerts
# results[].suspiciousDependencies: transitive deps with dangerous scripts

# 3. Decision
# SICURO/BASSO -> install
# MEDIO -> install + inform user
# ALTO/CRITICO -> DO NOT install, warn user

Add to your project's CLAUDE.md:

Before running `npm install` for new packages, always run:
`npm-guard check <package> --deep --json`
If maxRiskLevel is ALTO or CRITICO, do not install.
Check depRiskFindings for supply-chain indicators.

Full protocol: AI_INSTRUCTIONS.md

Create .npmguardrc.json:

{
  "rules": {
    "shell-commands": true,
    "network-access": true,
    "file-system": true,
    "code-execution": true,
    "sensitive-files": true,
    "obfuscation": true,
    "dependency-risk": true
  },
  "ignore": ["trusted-package"],
  "failOn": "high",
  "format": "text"
}

See npmguard.config.example.js for all options.

Extend with custom rules, formatters, and safe patterns:

const { BaseRule } = require("npm-guard");

class MyRule extends BaseRule {
  get name() { return "my-rule"; }
  get description() { return "Custom check"; }
  get patterns() {
    return [{
      pattern: /suspicious/,
      id: "suspicious",
      severity: "high",
      title: "Suspicious pattern",
      description: "Why this is dangerous"
    }];
  }
}

module.exports = {
  name: "my-plugin",
  register(api) { api.addRule(new MyRule()); }
};

See Plugin Guide.

const { NpmGuardEngine } = require("npm-guard");

// Shallow scan
const engine = new NpmGuardEngine({ format: "json" });
const result = engine.scanPackage("express");
const output = JSON.parse(engine.formatResults([result]));

if (output.summary.maxRiskLevel === "CRITICO") {
  console.error("Blocked!");
}

// Deep scan (recommended)
const deep = engine.scanPackageDeep("axios");
const deepOutput = JSON.parse(engine.formatDeepResults([deep], { format: "json" }));

if (deepOutput.summary.maxRiskLevel === "CRITICO") {
  console.error("Supply-chain threat detected!");
  console.error("Alerts:", deep.depRiskFindings);
}

See API Reference.

npm-guard/
├── bin/cli.js              # CLI with subcommands
├── src/
│   ├── index.js            # Public API
│   ├── core/
│   │   ├── engine.js       # Orchestrator (shallow + deep scan)
│   │   ├── config.js       # Configuration
│   │   ├── registry.js     # npm registry + dependency tree resolver
│   │   └── wrapper.js      # Shell wrapper (setup/uninstall)
│   ├── rules/              # 7 rule groups (extensible)
│   │   ├── shell-commands.js
│   │   ├── network-access.js
│   │   ├── file-system.js
│   │   ├── code-execution.js
│   │   ├── sensitive-files.js
│   │   ├── obfuscation.js
│   │   └── dependency-risk.js
│   ├── formatters/         # text, json, html (extensible)
│   ├── plugins/            # Plugin loader
│   └── ui/                 # Interactive mode
├── AI_INSTRUCTIONS.md      # Protocol for AI agents
├── plugins/example-plugin/ # Example plugin
├── test/                   # 95 tests
└── docs/                   # Architecture, API, Plugins

See CONTRIBUTING.md.

MIT