💀 DeadHunt

Hunt the Dead Code. Expose the Zombies.

An AI-powered forensic scanner that surgically detects dead code, zombie dependencies, and unused imports in Python repositories.

Features • Demo • Installation • Usage • How It Works • Contributing

🎯 Overview

DeadHunt is a sophisticated static analysis tool that combines AST parsing, dependency analysis, and AI-powered reasoning to identify dead code and zombie dependencies in Python projects. Unlike traditional linters, DeadHunt understands framework patterns (Django, Flask, FastAPI) and reduces false positives through intelligent context analysis.

Why DeadHunt?

🔍 Framework-Aware: Recognizes Django models, Flask routes, FastAPI endpoints, and other framework patterns
🧠 AI-Powered Analysis: Uses LLM reasoning to distinguish real dead code from framework-invoked code
📊 Comprehensive Reports: Beautiful, interactive HTML reports with actionable insights
🚀 Zero Configuration: Just paste a GitHub URL and scan
🎨 Modern UI: Cyberpunk-inspired terminal interface with real-time progress

✨ Features

🔬 Dead Code Detection

Identifies unused functions, classes, variables, and imports
AST-based analysis with cross-file reference tracking
Framework-specific whitelisting to avoid false positives
Confidence scoring for each finding

🧟 Zombie Dependency Hunting

Compares declared dependencies vs. actual imports
Detects packages installed but never used
Identifies bloated requirements.txt files
Suggests safe removal candidates

📈 Intelligent Reporting

Executive summary with health score
Risk-categorized findings (High/Medium/Low)
Actionable recommendations for each issue
PDF export and markdown copy functionality
Interactive table of contents with scroll spy

🎨 Beautiful Interface

Cyberpunk-themed terminal UI
Real-time scan progress
Animated particles and scanline effects
Responsive design for mobile and desktop

🎬 Demo

Landing Page

┌─────────────────────────────────────────┐
│  💀 DeadHunt                            │
│  Hunt The Dead Code.                    │
│                                         │
│  ❯ https://github.com/user/repo        │
│    [SCAN]                               │
└─────────────────────────────────────────┘

Analysis Report

Health Score: Visual ring chart showing codebase health (0-100)
Finding Cards: Color-coded cards with verdict badges
Sidebar TOC: Auto-generated navigation with active section highlighting
Export Options: PDF download and raw markdown copy

🚀 Installation

Prerequisites

Python 3.8 or higher
Git
pip

Quick Start

Clone the repository

git clone https://github.com/indiser/DeadHunt.git
cd DeadHunt

Install dependencies
```
pip install -r requirements.txt
```

Set up environment variables

# Create a .env file with your API keys
cp .env.example .env

Add your API keys to .env:

GEMINI_API_KEY=your_gemini_api_key_here
OPENROUTER_API_KEY=your_openrouter_key_here  
GROQ_API_KEY=your_groq_key_here              
CEREBRAS_API_KEY=your_cerebras_key_here

Run the application
```
python app.py
```
Open your browser
```
Navigate to http://localhost:5000
```

📖 Usage

Web Interface

Open DeadHunt in your browser
Paste a GitHub repository URL (e.g., https://github.com/user/repo)
Click SCAN
Wait for analysis to complete (typically 30-90 seconds)
Review the forensic report with findings and recommendations

Command Line (Advanced)

from enginex import analyze_repo

# Analyze a repository
report = analyze_repo("https://github.com/user/repo")
print(report)

🔧 How It Works

Phase 1: Clone & Parse

Repository → Shallow Clone → AST Parsing → Framework Detection

Clones the target repository (depth=1 for speed)
Parses all Python files into Abstract Syntax Trees
Detects framework architecture (Django/Flask/FastAPI/Generic)

Phase 2: Static Analysis

AST → Vulture Scanner → Cross-File References → Confidence Scoring

Uses Vulture for dead code detection
Performs cross-file reference analysis
Applies framework-specific whitelists
Assigns confidence scores (60-100%)

Phase 3: Dependency Analysis

requirements.txt → Import Extraction → Diff Analysis → Zombie Detection

Generates actual imports using pipreqs or manual AST scan
Compares declared vs. actual dependencies
Identifies unused packages

Phase 4: AI Reasoning

Findings → LLM Analysis → Verdict Assignment → Risk Categorization

Sends findings to AI model (Gemini/OpenRouter/Groq/Cerebras)
Applies framework pattern recognition
Distinguishes false positives from real issues
Generates actionable recommendations

🏗️ Architecture

DeadHunt/
├── app.py                 # Flask application & routing
├── enginex.py             # Core analysis engine
├── deadhunt_router.py     # Multi-provider LLM failover 
├── templates/
│   ├── index.html         # Landing page
│   └── report.html        # Analysis report UI
├── .env                   # API keys (not committed)
└── README.md              # This file

Key Components

app.py: Flask web server, handles routing and report rendering
enginex.py: Core scanning logic, AST parsing, Vulture integration, LLM communication
index.html: Cyberpunk-themed landing page with terminal input
report.html: Interactive forensic report with markdown rendering

🛡️ Framework Support

DeadHunt intelligently handles framework-specific patterns:

Framework	Supported Patterns
Django	Models, Meta classes, admin attributes, signals, middleware, AppConfig
Flask	Routes, blueprints, decorators, context processors
FastAPI	Path operations, dependencies, background tasks
Celery	Task decorators, worker-invoked functions
Pytest	Fixtures, test functions, conftest.py
SQLAlchemy	Model columns, relationships, event listeners

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Format code
black .

# Lint
flake8 .

📊 Roadmap

Support for JavaScript/TypeScript repositories
GitHub Actions integration
CLI tool for CI/CD pipelines
VS Code extension
Batch scanning for multiple repositories
Historical trend analysis
Custom rule configuration

🐛 Known Limitations

Python 2 Support: Limited AST parsing for Python 2 codebases
Dynamic Imports: Cannot detect runtime imports via importlib or exec()
Reflection Patterns: May flag metaprogramming patterns as dead code
Private Repositories: Requires public GitHub URLs (or manual cloning)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Vulture - Dead code detection
Marked.js - Markdown parsing
Highlight.js - Syntax highlighting
Google Gemini - AI-powered analysis
Flask - Web framework

📧 Contact

Project Maintainer: Indiser

GitHub: indiser
Email: indiser01@gmail.com

Built with 💀 by developers, for developers

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
presentation		presentation
static		static
templates		templates
Readme.md		Readme.md
app.py		app.py
deadhunt_router.py		deadhunt_router.py
enginex.py		enginex.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation