{"_id":"@corsaroblue/npm-guard","_rev":"2-6c7bd1b72232210a19afed66cdb4ce1b","name":"@corsaroblue/npm-guard","dist-tags":{"latest":"2.1.0"},"versions":{"2.0.0":{"name":"@corsaroblue/npm-guard","version":"2.0.0","keywords":["npm","security","audit","lifecycle-scripts","supply-chain","scanner","malware","preinstall","postinstall"],"author":{"name":"Conradlog"},"license":"MIT","_id":"@corsaroblue/npm-guard@2.0.0","maintainers":[{"name":"corsaroblue","email":"tapognani.corrado96@gmail.com"}],"homepage":"https://github.com/Conradlog/npm-guard#readme","bugs":{"url":"https://github.com/Conradlog/npm-guard/issues"},"bin":{"npm-guard":"bin/cli.js"},"dist":{"shasum":"55f05b7db938b2846f09ab907911b58852b25e4b","tarball":"https://registry.npmjs.org/@corsaroblue/npm-guard/-/npm-guard-2.0.0.tgz","fileCount":32,"integrity":"sha512-vCMAEanpMV4d58S9HMYjZ/LJGNUJM9OlRlhZGQX1sNJCJ2xxXIANQf3GO4fVHC5OvK5+pkydDtamz9uLtgSbFg==","signatures":[{"sig":"MEUCIQCujjPC4gFXfqhDv20bHLcCYhZJ8e+A/0ZqXgoQi67qNwIgb90PU3U5woazCmvhpY9f6byjvcpfVNG+d9BS2XCBJiA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":145721},"main":"src/index.js","engines":{"node":">=16.0.0"},"gitHead":"8073b02715e93d56845492f30d3c0c624a0dccdd","scripts":{"lint":"eslint src/ bin/ test/","test":"node test/core/engine.test.js && node test/rules/rules.test.js && node test/rules/dependency-risk.test.js && node test/core/deep-scan.test.js && node test/formatters/formatters.test.js && node test/core/wrapper.test.js","start":"node bin/cli.js","test:rules":"node test/rules/rules.test.js","test:engine":"node test/core/engine.test.js","test:wrapper":"node test/core/wrapper.test.js","test:formatters":"node test/formatters/formatters.test.js"},"_npmUser":{"name":"corsaroblue","email":"tapognani.corrado96@gmail.com"},"repository":{"url":"git+https://github.com/Conradlog/npm-guard.git","type":"git"},"_npmVersion":"10.9.2","description":"Scan npm packages for malicious lifecycle scripts before installing them","directories":{},"_nodeVersion":"22.17.1","dependencies":{"chalk":"^4.1.2"},"_hasShrinkwrap":false,"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/npm-guard_2.0.0_1774995383217_0.7789906561130575","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@corsaroblue/npm-guard","version":"2.1.0","description":"Scan npm packages for malicious lifecycle scripts before installing them","main":"src/index.js","bin":{"npm-guard":"bin/cli.js"},"scripts":{"test":"node test/core/engine.test.js && node test/rules/rules.test.js && node test/rules/dependency-risk.test.js && node test/core/deep-scan.test.js && node test/formatters/formatters.test.js && node test/core/wrapper.test.js","test:engine":"node test/core/engine.test.js","test:rules":"node test/rules/rules.test.js","test:formatters":"node test/formatters/formatters.test.js","test:wrapper":"node test/core/wrapper.test.js","lint":"eslint src/ bin/ test/","start":"node bin/cli.js"},"keywords":["npm","security","audit","lifecycle-scripts","supply-chain","scanner","malware","preinstall","postinstall"],"author":{"name":"Conradlog"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Conradlog/npm-guard.git"},"bugs":{"url":"https://github.com/Conradlog/npm-guard/issues"},"homepage":"https://github.com/Conradlog/npm-guard#readme","engines":{"node":">=16.0.0"},"dependencies":{"chalk":"^4.1.2"},"devDependencies":{},"_id":"@corsaroblue/npm-guard@2.1.0","gitHead":"f50ee7608bcf29c07b97a19efad7c5b29c14a199","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-E8BUq8WouodlTfkTH97i0XXjibpRaS+UvNCkphCUIZafo2gMYK9UCKgkOdCpR8eYHJFXdEc8SQF673ltIk2fPQ==","shasum":"bff73d72debe3d534d68deab3a58b053e045a047","tarball":"https://registry.npmjs.org/@corsaroblue/npm-guard/-/npm-guard-2.1.0.tgz","fileCount":32,"unpackedSize":144619,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC+X49hG+rx3hpP719Tjh0AF2Xs4EYY1fMt/FBp7uN3VwIgGhjmRnXvjehKgIS5OM7iUyQhU9hvz2WxYTgJCTQXj3I="}]},"_npmUser":{"name":"corsaroblue","email":"tapognani.corrado96@gmail.com"},"directories":{},"maintainers":[{"name":"corsaroblue","email":"tapognani.corrado96@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/npm-guard_2.1.0_1774996808881_0.1703288156351026"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T22:16:23.108Z","modified":"2026-03-31T22:40:09.165Z","2.0.0":"2026-03-31T22:16:23.380Z","2.1.0":"2026-03-31T22:40:09.040Z"},"bugs":{"url":"https://github.com/Conradlog/npm-guard/issues"},"author":{"name":"Conradlog"},"license":"MIT","homepage":"https://github.com/Conradlog/npm-guard#readme","keywords":["npm","security","audit","lifecycle-scripts","supply-chain","scanner","malware","preinstall","postinstall"],"repository":{"type":"git","url":"git+https://github.com/Conradlog/npm-guard.git"},"description":"Scan npm packages for malicious lifecycle scripts before installing them","maintainers":[{"name":"corsaroblue","email":"tapognani.corrado96@gmail.com"}],"readme":"# npm-guard\n\n> Zero-friction supply chain security for npm. Protects humans and AI agents from malicious lifecycle scripts and dependency injection attacks.\n\nWhen 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](https://thehackernews.com/2026/03/axios-supply-chain-attack-pushes-cross.html)).\n\n**npm-guard** catches them **before** they run.\n\n## Two Modes, One Engine\n\n### For Humans: Transparent Wrapper\n```bash\nnpm-guard setup     # One-time: wraps your npm command\nnpm install express  # npm-guard deep-scans automatically, then installs\n```\n\n### For AI Agents: Explicit Check\n```bash\nnpm-guard check express --deep --json   # Machine-readable deep scan\n# AI agent parses JSON, decides whether to proceed\n```\n\nSee [`AI_INSTRUCTIONS.md`](./AI_INSTRUCTIONS.md) for the full AI integration protocol.\n\n---\n\n## Install\n\n```bash\nnpm install -g npm-guard\n```\n\n## Quick Start\n\n### Interactive Mode (beginners)\n\n```bash\nnpm-guard\n```\n\nGuided menu with explanations in plain language.\n\n### Check Mode (experts, CI, AI agents)\n\n```bash\nnpm-guard check express              # Shallow check (lifecycle scripts only)\nnpm-guard check lodash axios react   # Check multiple packages\nnpm-guard check express --json       # JSON for machines\nnpm-guard check express --html       # HTML report\n```\n\n### Deep Scan Mode (supply-chain protection)\n\n```bash\nnpm-guard check axios --deep         # Full dependency tree analysis\nnpm-guard check axios --deep --json  # Deep scan with JSON output\nnpm-guard check axios --deep --html  # Deep scan HTML report\n```\n\nThe `--deep` flag enables:\n- Recursive scanning of all transitive dependencies\n- Detection of newly-injected dependencies vs. the previous version\n- Package age verification (flags packages published < 7 days ago)\n- Typosquatting name detection (e.g. `plain-crypto-js` mimicking `crypto-js`)\n\n### Scan Mode (entire project)\n\n```bash\nnpm-guard scan                       # Current project\nnpm-guard scan /path/to/project      # Specific path\nnpm-guard scan --json --fail-on high # CI/CD pipeline\n```\n\n### Wrapper Mode (transparent protection)\n\n```bash\nnpm-guard setup      # Inject wrapper into .zshrc/.bashrc\nnpm-guard status     # Check if wrapper is active\nnpm-guard uninstall  # Remove wrapper\n```\n\nAfter setup, every `npm install <package>` is automatically deep-scanned. If threats are found, the installation is blocked.\n\n---\n\n## What It Detects\n\n### 7 Rule Groups (all pluggable)\n\n| Rule Group | What it catches | Examples |\n|------------|----------------|----------|\n| **shell-commands** | File/system manipulation | `rm -rf`, `sudo`, `chmod`, `touch` |\n| **network-access** | Unauthorized network calls | `curl`, `wget`, `netcat`, pipe to `sh` |\n| **file-system** | Access to sensitive paths | `.npmrc`, `.ssh`, `.env`, `.aws`, `/etc/passwd` |\n| **code-execution** | Dynamic/obfuscated execution | `eval`, `base64`, `node -e`, `PowerShell` |\n| **sensitive-files** | Credential theft + exfiltration | `.pem`, `.key`, `id_rsa` + `cat \\| curl` combo |\n| **obfuscation** | Supply-chain attack patterns | `/dev/tcp`, hex strings, `Buffer.from(base64)`, `crontab`, `launchctl`, silent execution |\n| **dependency-risk** | Dependency injection attacks | New deps vs. previous version, young packages, typosquatting names |\n\n### Advanced Detection (obfuscation rule)\n\nThe obfuscation rule goes beyond simple pattern matching with **combinatorial analysis**:\n\n- **Download + Execute**: `curl ... | bash` detected as supply-chain attack\n- **Silent execution**: `> /dev/null 2>&1` flagged when hiding output\n- **Reverse shells**: `/dev/tcp` connections detected\n- **Payload dropping**: write hidden file + `chmod +x` + execute\n- **Heavy obfuscation**: counts hex escape sequences, flags if > 10\n- **Persistence**: `crontab`, `systemctl`, `launchctl` for backdoor installation\n\n### Supply-Chain Attack Detection (dependency-risk rule, `--deep`)\n\nThe dependency-risk rule, activated by the `--deep` flag, detects the exact attack pattern used in the axios compromise:\n\n| Detection | Severity | What it catches |\n|-----------|----------|-----------------|\n| **New dependency** | HIGH | A dependency was added that didn't exist in the previous version |\n| **Young package** | HIGH/CRITICAL | A dependency was published less than 7 days ago (CRITICAL if < 24h) |\n| **Injected + young** | CRITICAL | New dependency AND recently published (strongest signal of compromise) |\n| **Suspicious name** | HIGH | Name mimics a well-known library with prefix/suffix (e.g. `plain-crypto-js`) |\n\n**Example**: if `axios@1.14.1` 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.\n\n---\n\n## AI Agent Integration\n\nnpm-guard is designed to be used as a **security tool by AI coding agents**.\n\n### Protocol\n\n```bash\n# 1. Deep-check package before install\nnpm-guard check <package> --deep --json\n\n# 2. Parse response\n# summary.maxRiskLevel: \"SICURO\" | \"BASSO\" | \"MEDIO\" | \"ALTO\" | \"CRITICO\"\n# results[].depRiskFindings: supply-chain specific alerts\n# results[].suspiciousDependencies: transitive deps with dangerous scripts\n\n# 3. Decision\n# SICURO/BASSO -> install\n# MEDIO -> install + inform user\n# ALTO/CRITICO -> DO NOT install, warn user\n```\n\n### Claude Code\n\nAdd to your project's `CLAUDE.md`:\n\n```markdown\nBefore running `npm install` for new packages, always run:\n`npm-guard check <package> --deep --json`\nIf maxRiskLevel is ALTO or CRITICO, do not install.\nCheck depRiskFindings for supply-chain indicators.\n```\n\nFull protocol: [`AI_INSTRUCTIONS.md`](./AI_INSTRUCTIONS.md)\n\n---\n\n## Configuration\n\nCreate `.npmguardrc.json`:\n\n```json\n{\n  \"rules\": {\n    \"shell-commands\": true,\n    \"network-access\": true,\n    \"file-system\": true,\n    \"code-execution\": true,\n    \"sensitive-files\": true,\n    \"obfuscation\": true,\n    \"dependency-risk\": true\n  },\n  \"ignore\": [\"trusted-package\"],\n  \"failOn\": \"high\",\n  \"format\": \"text\"\n}\n```\n\nSee [`npmguard.config.example.js`](./npmguard.config.example.js) for all options.\n\n## Plugins\n\nExtend with custom rules, formatters, and safe patterns:\n\n```js\nconst { BaseRule } = require(\"npm-guard\");\n\nclass MyRule extends BaseRule {\n  get name() { return \"my-rule\"; }\n  get description() { return \"Custom check\"; }\n  get patterns() {\n    return [{\n      pattern: /suspicious/,\n      id: \"suspicious\",\n      severity: \"high\",\n      title: \"Suspicious pattern\",\n      description: \"Why this is dangerous\"\n    }];\n  }\n}\n\nmodule.exports = {\n  name: \"my-plugin\",\n  register(api) { api.addRule(new MyRule()); }\n};\n```\n\nSee [Plugin Guide](./docs/PLUGINS.md).\n\n## Use as Library\n\n```js\nconst { NpmGuardEngine } = require(\"npm-guard\");\n\n// Shallow scan\nconst engine = new NpmGuardEngine({ format: \"json\" });\nconst result = engine.scanPackage(\"express\");\nconst output = JSON.parse(engine.formatResults([result]));\n\nif (output.summary.maxRiskLevel === \"CRITICO\") {\n  console.error(\"Blocked!\");\n}\n\n// Deep scan (recommended)\nconst deep = engine.scanPackageDeep(\"axios\");\nconst deepOutput = JSON.parse(engine.formatDeepResults([deep], { format: \"json\" }));\n\nif (deepOutput.summary.maxRiskLevel === \"CRITICO\") {\n  console.error(\"Supply-chain threat detected!\");\n  console.error(\"Alerts:\", deep.depRiskFindings);\n}\n```\n\nSee [API Reference](./docs/API.md).\n\n## Project Structure\n\n```\nnpm-guard/\n├── bin/cli.js              # CLI with subcommands\n├── src/\n│   ├── index.js            # Public API\n│   ├── core/\n│   │   ├── engine.js       # Orchestrator (shallow + deep scan)\n│   │   ├── config.js       # Configuration\n│   │   ├── registry.js     # npm registry + dependency tree resolver\n│   │   └── wrapper.js      # Shell wrapper (setup/uninstall)\n│   ├── rules/              # 7 rule groups (extensible)\n│   │   ├── shell-commands.js\n│   │   ├── network-access.js\n│   │   ├── file-system.js\n│   │   ├── code-execution.js\n│   │   ├── sensitive-files.js\n│   │   ├── obfuscation.js\n│   │   └── dependency-risk.js\n│   ├── formatters/         # text, json, html (extensible)\n│   ├── plugins/            # Plugin loader\n│   └── ui/                 # Interactive mode\n├── AI_INSTRUCTIONS.md      # Protocol for AI agents\n├── plugins/example-plugin/ # Example plugin\n├── test/                   # 95 tests\n└── docs/                   # Architecture, API, Plugins\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}