Dep-Hallucinator

Security scanner that detects AI-generated dependency confusion vulnerabilities in software projects.

Problem

AI code assistants sometimes suggest packages that don't exist. Attackers can register these hallucinated package names with malicious code. When developers install the suggested dependency, they execute the attacker's payload.

Solution

Dep-Hallucinator detects these non-existent packages and suspicious packages that may be malicious registrations.

Features

• Registry scanning: Checks PyPI, npm, Maven Central, Crates.io, and Go Modules
• ML detection: Identifies AI-generated naming patterns
• Heuristic analysis: Analyzes package age, downloads, and metadata
• Risk classification: CRITICAL/HIGH/MEDIUM/LOW risk levels with explanations
• Multi-language support: Python, JavaScript, Java, Rust, Go
• SBOM generation: Creates Software Bill of Materials (SPDX and CycloneDX)
• CI/CD integration: Exit codes and JSON output

Supported Ecosystems

Language	Registry	File Types
Python	PyPI	requirements.txt, poetry.lock, Pipfile.lock
JavaScript	npm	package.json, yarn.lock
Java	Maven Central	pom.xml, build.gradle, build.gradle.kts
Rust	Crates.io	Cargo.toml, Cargo.lock
Go	Go Modules	go.mod, go.sum

Installation

pip install dep-hallucinator

Usage

# Basic scan
dep-hallucinator scan requirements.txt

# With options
dep-hallucinator scan requirements.txt --rate-limit 5.0 --max-concurrent 10

# JSON output
dep-hallucinator scan requirements.txt --output-format json

# Generate SBOM
dep-hallucinator scan requirements.txt --generate-sbom

# Batch scan
dep-hallucinator batch requirements.txt package.json pom.xml

Example Output

🔍 Scanning 8 dependencies...

📊 Scan Summary           
🚨 CRITICAL │   2   │ VULNERABLE
🔶 HIGH     │   1   │ SUSPICIOUS  
✅ LOW      │   5   │     OK     

🚨 CRITICAL VULNERABILITIES

📦 ai-powered-data-processor (==1.0.0)
   Suspicion Score: 100% (CRITICAL) | ML: 95%
   Reasons:
   • Package does not exist in the registry
   • Vulnerable to dependency confusion attacks
   • ML models indicate high probability of AI generation
   Recommendations:
   → Do not install this package
   → Check if this was generated by an AI assistant

Developer Workflow Integration

For immediate, in-workflow feedback, we recommend integrating dep-hallucinator as a Git pre-commit hook. This provides simple, local security checks before code is committed, helping developers catch issues early.

Git Pre-commit Hook Guide

1. Ensure dep-hallucinator is installed:

   pip install dep-hallucinator

2. Create a pre-commit script in your project's .git/hooks/pre-commit file (ensure it is executable, chmod +x).

3. Add the following logic to scan your dependency files and prevent the commit on critical findings:

   #!/bin/bash
   
   # --- dep-hallucinator pre-commit hook ---
   
   # Files to check (adjust as needed for your project)
   DEP_FILES="requirements.txt package.json"
   
   CRITICAL_FOUND=0
   
   for FILE in $DEP_FILES; do
     if [ -f "$FILE" ]; then
       echo "🔍 Scanning $FILE..."
       # Use quiet mode to suppress normal output, and rely on the exit code
       dep-hallucinator scan "$FILE" --quiet
       
       EXIT_CODE=$?
       
       # Exit code 1 indicates Critical vulnerabilities found
       if [ $EXIT_CODE -eq 1 ]; then
         echo "❌ CRITICAL VULNERABILITY FOUND in $FILE. Commit aborted."
         CRITICAL_FOUND=1
       elif [ $EXIT_CODE -ne 0 ]; then
         echo "⚠️  Scan failed or found HIGH risk packages in $FILE. Review before pushing."
       fi
     fi
   done
   
   if [ $CRITICAL_FOUND -eq 1 ]; then
     exit 1  # Abort commit
   else
     exit 0  # Allow commit
   fi

Configuration

Create .dep-hallucinator.json:

{
  "scan": {
    "rate_limit": 10.0,
    "max_concurrent": 20,
    "timeout_seconds": 30
  },
  "security": {
    "max_file_size_mb": 10
  }
}

Development

git clone https://github.com/serhanwbahar/dep-hallucinator.git
cd dep-hallucinator
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"
make test

Exit Codes

• 0: No critical vulnerabilities
• 1: Critical vulnerabilities found
• 130: Scan interrupted

Documentation

• Complete Documentation - Comprehensive usage guide
• Security Policy - Vulnerability reporting
• Contributing - Development guidelines
• Deployment - Production deployment

License

MIT License. See LICENSE file.