A comprehensive security tool for detecting compromised NPM packages and malicious code patterns in development projects. Recursively scans package.json, lockfiles, and installed packages to identify known security threats.
- Compromised Package Versions: Specific versions known to contain malicious code
- Malicious Code Patterns: Hidden malware signatures using regex patterns
- Multiple Package Formats: package.json, package-lock.json, yarn.lock, and node_modules
- Nested Dependencies: Deep scanning of dependency trees
- Scoped Packages: Full support for @scope/package naming
# Install from PyPI (when published)
pip install npm-security-scanner
# Or install from source
git clone https://github.com/reddcoin-project/npm-security-scanner.git
cd npm-security-scanner
pip install -e .# Scan current directory
npm-security-scanner .
# Scan specific project
npm-security-scanner /path/to/your/project
# Verbose output with debugging info
npm-security-scanner /path/to/project --verbose
# Generate JSON report
npm-security-scanner /path/to/project --report results.json
# Generate SARIF report for CI/CD
npm-security-scanner /path/to/project --sarif results.sarif- Package.json Analysis: Detects compromised packages in dependencies, devDependencies, peerDependencies, and optionalDependencies
- Lockfile Inspection: Supports both npm v6 and v7+ package-lock.json formats
- Yarn Support: Parses yarn.lock files for compromised packages
- Installed Package Verification: Directly inspects node_modules directories
- Nested Dependencies: Recursively scans nested node_modules up to configurable depth
The scanner currently detects these compromised package versions:
chalk@5.6.1- Malicious terminal styling packagedebug@4.4.2- Compromised debugging utilitystrip-ansi@7.1.1- Malicious ANSI string stripperansi-styles@6.2.2- Compromised ANSI styling- And 15+ more packages
Uses ripgrep to search for known malicious patterns:
_0x112fa8- Common obfuscation pattern used in NPM malware- Configurable pattern matching for new threats
- Real-time Progress Bar: Shows 0-100% completion with ETA
- Directory Counting: Pre-calculates total scope for accurate progress
- Performance Metrics: Displays scan time and directories processed
npm-security-scanner /path/to/project --report findings.jsonnpm-security-scanner /path/to/project --sarif results.sarifSARIF reports integrate with:
- GitHub Security Tab - Shows findings as security alerts
- Azure DevOps - Displays results in pull requests
- GitLab - Integrates with security dashboards
- VS Code - Shows inline warnings/errors
- Enterprise Security Platforms (Veracode, SonarQube, etc.)
npm-security-scanner [OPTIONS] ROOT_PATH
Arguments:
ROOT_PATH Root path to scan recursively
Options:
--version Show version and exit
--verbose, -v Enable verbose debug output
--report FILE, -r FILE Generate JSON report file
--sarif FILE, -s FILE Generate SARIF report for CI/CD integration
--max-depth DEPTH Maximum depth for nested node_modules (default: 10)
--help Show this message and exit
name: NPM Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install NPM Security Scanner
run: pip install npm-security-scanner
- name: Run Security Scan
run: npm-security-scanner . --sarif results.sarif
- name: Upload SARIF results
uses: github/codeql-action/upload-sarif@v2
if: always()
with:
sarif_file: results.sarif- task: UsePythonVersion@0
inputs:
versionSpec: '3.10'
- script: |
pip install npm-security-scanner
npm-security-scanner $(Build.SourcesDirectory) --sarif $(Agent.TempDirectory)/results.sarif
displayName: 'NPM Security Scan'
- task: PublishTestResults@2
inputs:
testResultsFormat: 'SARIF'
testResultsFiles: '$(Agent.TempDirectory)/results.sarif'# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=npm_security_scanner --cov-report=html
# Run specific test file
pytest tests/test_scanner.py -v# Format code
black npm_security_scanner tests
# Lint code
flake8 npm_security_scanner tests
# Type checking
mypy npm_security_scannerThe repository includes a test project with intentionally compromised packages:
# Test on example project (should find issues)
npm-security-scanner examples/test_project --verbose
# Should detect:
# - chalk@5.6.1 in package.json dependencies
# - debug@4.4.2 in installed packages
# - Multiple _0x112fa8 malicious code patternsfrom npm_security_scanner import NPMSecurityScanner
# Create scanner instance
scanner = NPMSecurityScanner("/path/to/project", verbose=True)
# Run scan
scanner.scan_recursive()
# Check results
if scanner.findings:
print(f"Found {len(scanner.findings)} security issues!")
# Generate reports
scanner.generate_report("findings.json")
scanner.generate_sarif_report("results.sarif")
else:
print("No security issues found!")This tool is designed for defensive security purposes only:
- ✅ Detecting compromised packages in existing codebases
- ✅ Analyzing potential security threats in dependencies
- ✅ Generating security reports for compliance
- ✅ Integrating with CI/CD pipelines for automated scanning
The tool helps developers and security teams proactively identify supply chain attacks targeting the NPM ecosystem.
0- No compromised packages found1- Compromised packages detected (security alert)
This allows easy integration with CI/CD pipelines that can fail builds when security issues are found.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Run the test suite (
pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
For security vulnerabilities, please email security@example.com instead of using the public issue tracker.
This project is licensed under the MIT License - see the LICENSE file for details.
- Built for the security community to combat NPM supply chain attacks
- Uses ripgrep for high-performance pattern matching
- Follows SARIF 2.1.0 specification for security reporting
- Inspired by the need for better NPM package security tooling