Scan npm packages for malicious preinstall/postinstall scripts before they execute
npm install preinstall-guardiannpm install. By the time you notice something's wrong, your credentials may already be stolen.
bash
npm install -g preinstall-guardian
`
Or use without installing:
`bash
npx preinstall-guardian check
`
Usage
$3
`bash
preinstall-guardian check
`
Scans your package.json and node_modules for suspicious scripts.
$3
`bash
preinstall-guardian scan package.json
`
$3
`bash
preinstall-guardian scan node_modules
`
$3
`bash
pig check # Same as preinstall-guardian check
`
Example Output
`
Preinstall Guardian
Protect your project from malicious install scripts
suspicious-package@1.2.3
Risk Level: CRITICAL
Total Matches: 7
Findings:
• postinstall script detected with 7 suspicious pattern(s)
- Combines network access with environment variable reading
- Uses code obfuscation techniques
Suspicious patterns found:
→ fetch(
→ process.env
→ eval(
→ child_process
Summary:
──────────────────────────────────────────────────
Total packages scanned: 1
CRITICAL: 1
──────────────────────────────────────────────────
WARNING: High-risk packages detected!
Review these packages immediately before continuing.
`
What It Detects
Preinstall Guardian looks for patterns commonly used in malicious packages:
$3
- HTTP requests (fetch, axios, webhooks)
- Connections to suspicious domains
$3
- Writing/deleting files
- Accessing SSH keys, AWS credentials
- Home directory manipulation
$3
- Running system commands
- Spawning child processes
$3
- Environment variable access
- GitHub/npm token patterns
- Cloud provider credentials (AWS, GCP, Azure)
$3
- eval() usage
- Base64 encoding
- Dynamic code execution
$3
- Bun runtime files (Shai-Hulud 2.0)
- Crypto wallet manipulation
- Specific malware patterns
CI/CD Integration
Add to your CI pipeline to block malicious packages:
`yaml
.github/workflows/security.yml
name: Security Check
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install dependencies
run: npm ci
- name: Scan for malicious scripts
run: npx preinstall-guardian check
`
The command exits with code 1 if CRITICAL or HIGH risk packages are found.
Use as a Library
`javascript
const PreinstallGuardian = require('preinstall-guardian');
const guardian = new PreinstallGuardian();
// Scan a single package.json
const result = guardian.scanPackageJson('./package.json');
console.log(Risk: ${result.overallRisk});
console.log(Findings: ${result.findings.length});
// Scan all packages in node_modules
const results = guardian.scanNodeModules('./node_modules');
const critical = results.filter(r => r.overallRisk === 'CRITICAL');
console.log(Found ${critical.length} critical packages);
`
When to Use
- ✅ Before running npm install in a new project
- ✅ After adding new dependencies
- ✅ In CI/CD pipelines before deployment
- ✅ Regular security audits of existing projects
- ✅ When suspicious activity is detected in the npm ecosystem
Limitations
- Does not execute code (static analysis only)
- May have false positives for legitimate use cases
- Cannot detect all obfuscation techniques
- Complements but doesn't replace tools like Socket, Snyk
Best Practices
1. Use with npm audit: npm audit && preinstall-guardian check`