A prescient scanner to detect and banish Shai Hulud malware from your dependencies.
npm install worm-sign
> "We have wormsign the likes of which even God has never seen."
Worm Sign is a specialized scanner designed to detect and block npm packages compromised by the Shai Hulud malware campaign. It scans your project's package.json and lockfiles against a curated list of 1,717 known compromised packages.
- Safe Static Analysis: Uses @npmcli/arborist to inspect the dependency tree without executing any lifecycle scripts, neutralizing the malware's "Dead Man's Switch".
- Detects Shai Hulud: Identifies 1,717 packages known to be compromised by the Shai Hulud malware.
- Hash-Based Detection: Detects compromised packages by their integrity hash (SHA-1/SHA-512), catching variants even if they are renamed or version-spoofed.
- Lockfile Required: Scans package-lock.json, yarn.lock, or pnpm-lock.yaml. A lockfile is required for analysis.
- API Integration: Fetches the latest banned list from a remote API (customizable).
- Smart Caching: Caches API responses locally for 1 hour to improve performance.
- Heuristic Analysis: Scans package.json scripts for suspicious patterns (e.g., curl | bash, rm -rf, reverse shells, obfuscated code).
- Entropy Analysis: Detects high-entropy files (potential obfuscated malware payloads) > 5MB.
- Behavioral Detection: Identifies destructive commands (shred, del) and known C2 signatures.
- SARIF Output: Generates SARIF reports for integration with GitHub Security.
- CI/CD Ready: Easily integrates into GitHub Actions or other CI pipelines.
Worm Sign includes advanced detection logic specifically for the Shai-Hulud 2.0 campaign:
- File Entropy: Analyzes large files (>5MB) for high entropy, a common indicator of packed/obfuscated malware payloads (e.g., bun_environment.js).
- Destructive Commands: Flags scripts containing system-wiping commands like shred -uvz -n 1 (Linux/macOS) and del /F /Q /S "%USERPROFILE%*" (Windows).
- Installation Vectors: Detects specific installation patterns used by the malware, such as irm bun.sh/install.ps1|iex (PowerShell Bun install).
- C2 Signatures: Scans for known Command & Control signatures like "Sha1-Hulud: The Second Coming".
Arborist.loadVirtual()) to build an in-memory dependency graph. It never runs npm install or executes preinstall/postinstall scripts during scanning, ensuring the malware is never given a chance to execute.src/generated/signatures.ts.``bash`
npm install -g worm-sign
Run the scanner in your project root. It uses the bundled list of banned packages by default.
`bash`
worm-sign
Fetch the latest list of vulnerable packages from configured remote sources (e.g., Datadog, Koi).
`bash`
worm-sign --fetch
Configured Remote Sources:
- Datadog: consolidated_iocs.csv
- Koi: export?format=csv
You can also fetch from a custom URL. You must specify the data format (json or csv).
JSON Format:
Expects an object with a packages array: { "packages": [ { "name": "pkg", "version": "1.0.0" } ] }.
`bash`
worm-sign --url "https://example.com/vulns.json" --data-format json
> Note: The scanner will attempt to fetch from this URL in addition to other configured sources. If the fetch fails, it will warn you but continue scanning with other available sources.
CSV Format:
Expects a CSV with name and version columns (headers are ignored if they don't look like package names, but standard format is name,version).
`bash`
worm-sign --url "https://example.com/vulns.csv" --data-format csv
Hash Support:
The CSV format also supports an optional integrity column (or hash, shasum). If provided, the scanner will verify the package integrity against your lockfile.
`csv`
name,version,integrity
safe-package,1.0.0,sha512-badhash...
Generate a SARIF report for security tools:
`bash`
worm-sign --format sarif > results.sarif
Install a pre-commit hook to automatically scan before every commit:
`bash`
worm-sign --install-hook
Disable caching if you need to force a fresh fetch:
`bash`
worm-sign --fetch --no-cache
Add this to your GitHub Actions workflow:
`yaml`
- name: Run Worm Sign
run: npx worm-sign --format sarif
By default, worm-sign will:
1. Load all local .csv package lists from the sources/ directory.sources/*.json
2. Fetch updates from any remote sources configured in (e.g., Datadog, Koi).
3. Fail the build if any banned packages are found (exit code 1).
You do not need to pass --fetch explicitly; the scanner automatically processes all configured sources.
Worm Sign fetches threat intelligence from the following public endpoints. Ensure your firewall allows outbound HTTPS (443) access to:
- Datadog: raw.githubusercontent.com
- Koi:
- HTTPS_PROXY (or https_proxy)HTTP_PROXY
- (or http_proxy)NO_PROXY
- (or no_proxy)
For large organizations or high-volume CI/CD environments, we recommend mirroring the data sources internally to avoid rate limiting or external dependency failures.
To avoid rate limiting or external dependency failures, you can host the data sources on an internal server (e.g., Artifactory, S3).
If using the npm package directly:
Use the --offline flag to disable default remote fetches, and provide your internal mirror URL via the --url flag.
CSV Example:
`bash`
npx worm-sign --offline --url "https://internal.example.com/compromised-packages.csv" --data-format csv
JSON Example:
`bash`
npx worm-sign --offline --url "https://internal.example.com/compromised-packages.json" --data-format json
Self-Signed Certificates:
If your internal server uses a self-signed certificate, use the --insecure flag to bypass SSL verification:
`bash`
npx worm-sign --offline --insecure --url "https://internal.example.com/compromised-packages.json" --data-format json
If maintaining a fork:
Update the sources/*.json files in your repository to point to your internal URLs. This allows you to distribute a pre-configured version of the scanner to your team.
If you prefer to rely solely on the bundled local CSVs (which are updated with each package release), you can disable remote fetching:
`bash`
npx worm-sign --offline
This will only scan against the local .csv files found in the sources/ directory.
---
| Option | Description | Default |
| ------------------------ | -------------------------------------------------- | ------- |
| -f, --fetch | Fetch the latest compromised packages from the API | false |-u, --url
| | Custom API URL to fetch compromised packages from | - |--data-format
| | Data format for custom URL (json, csv) | json |-p, --path
| | Path to the project to scan | . |--format
| | Output format (text, sarif) | text |--no-cache
| | Disable caching of API responses | false |--install-hook
| | Install a pre-commit hook to run worm-sign | false |--dry-run
| | Run scan but always exit with 0 (useful for CI) | false |--offline
| | Disable network requests (implies --no-fetch) | false |--insecure
| | Disable SSL certificate verification | false |--debug
| | Enable debug logging | false |
Scan a specific directory:
`bash`
worm-sign --path ./projects/my-app
Run in CI (Dry Run):
Use --dry-run to see what would be found without failing the build (exit code 0).
`bash`
worm-sign --dry-run
Debug Mode:
Enable verbose logging to troubleshoot issues.
`bash``
worm-sign --debug
---
The bundled data sources aggregate findings from various security research teams and community projects, including:
- DataDog Security Labs
- Aikido Security
- Socket.dev
- GitGuardian
- Wiz
- Cobenian/shai-hulud-detect
- Phylum
- Truesec
- IBM X-Force
This project is licensed under the MIT License - see the LICENSE file for details.