indiser/DeadHunt

# 💀 DeadHunt **Hunt the Dead Code. Expose the Zombies.** [](https://www.python.org/downloads/) [](https://flask.palletsprojects.com/) [](LICENSE) [](https://github.com/psf/black) *An AI-powered forensic scanner that surgically detects dead code, zombie dependencies, and unused imports in Python repositories.* [Features](#-features) • [Demo](#-demo) • [Installation](#-installation) • [Usage](#-usage) • [How It Works](#-how-it-works) • [Contributing](#-contributing) ## 🎯 概述 **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. ### 为什么选择 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 ## ✨ 功能 ### 🔬 死代码检测 - 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 ### 🧟 僵尸依赖狩猎 - Compares declared dependencies vs. actual imports - Detects packages installed but never used - Identifies bloated `requirements.txt` files - Suggests safe removal candidates ### 📈 智能报告 - 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 ### 🎨 美观界面 - Cyberpunk-themed terminal UI - Real-time scan progress - Animated particles and scanline effects - Responsive design for mobile and desktop ## 🎬 演示 ### 着陆页 ``` ┌─────────────────────────────────────────┐ │ 💀 DeadHunt │ │ Hunt The Dead Code. │ │ │ │ ❯ https://github.com/user/repo │ │ [SCAN] │ └─────────────────────────────────────────┘ ``` ### 分析报告 - **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 ## 🚀 安装 ### 先决条件 - Python 3.8 or higher - Git - pip ### 快速开始 1. **Clone the repository** git clone https://github.com/yourusername/DeadHunt.git cd DeadHunt 2. **Install dependencies** pip install -r requirements.txt 3. **Set up environment variables** # 使用您的 API 密钥创建 .env 文件 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 # Optional GROQ_API_KEY=your_groq_key_here # Optional CEREBRAS_API_KEY=your_cerebras_key_here # Optional 4. **Run the application** python app.py 5. **Open your browser** Navigate to http://localhost:5000 ## 📖 使用说明 ### 网页界面 1. Open DeadHunt in your browser 2. Paste a GitHub repository URL (e.g., `https://github.com/user/repo`) 3. Click **SCAN** 4. Wait for analysis to complete (typically 30-90 seconds) 5. Review the forensic report with findings and recommendations ### 命令行（高级） ``` from enginex import analyze_repo # 分析仓库 report = analyze_repo("https://github.com/user/repo") print(report) ``` ## 🔧 工作原理 ### 阶段 1：克隆与解析 ``` 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) ### 阶段 2：静态分析 ``` AST → Vulture Scanner → Cross-File References → Confidence Scoring ``` - Uses [Vulture](https://github.com/jendrikseipp/vulture) for dead code detection - Performs cross-file reference analysis - Applies framework-specific whitelists - Assigns confidence scores (60-100%) ### 阶段 3：依赖分析 ``` 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 ### 阶段 4：AI 推理 ``` 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 ## 🏗️ 架构 ``` DeadHunt/ ├── app.py # Flask application & routing ├── enginex.py # Core analysis engine ├── deadhunt_router.py # Multi-provider LLM failover (if exists) ├── templates/ │ ├── index.html # Landing page │ └── report.html # Analysis report UI ├── .env # API keys (not committed) └── README.md # This file ``` ### 关键组件 - **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 ## 🛡️ 框架支持 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 | ## 🤝 贡献 Contributions are welcome! Here's how you can help: 1. **Fork the repository** 2. **Create a feature branch** (`git checkout -b feature/amazing-feature`) 3. **Commit your changes** (`git commit -m 'Add amazing feature'`) 4. **Push to the branch** (`git push origin feature/amazing-feature`) 5. **Open a Pull Request** ### 开发环境设置 ``` # 安装开发依赖 pip install -r requirements-dev.txt # 运行测试 pytest tests/ # 格式化代码 black . # 代码检查 flake8 . ``` ## 📊 路线图 - [ ] 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 ## 🐛 已知限制 - **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) ## 📄 许可证 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 致谢 - [Vulture](https://github.com/jendrikseipp/vulture) - Dead code detection - [Marked.js](https://marked.js.org/) - Markdown parsing - [Highlight.js](https://highlightjs.org/) - Syntax highlighting - [Google Gemini](https://ai.google.dev/) - AI-powered analysis - [Flask](https://flask.palletsprojects.com/) - Web framework ## 📧 联系方式 **Project Maintainer**: [Your Name] - GitHub: [@yourusername](https://github.com/yourusername) - Email: your.email@example.com - Twitter: [@yourhandle](https://twitter.com/yourhandle)

标签：AI静态分析, AST解析, AV绕过, C2, Django, FastAPI, Flask, GitHub集成, HTML报告, Python静态分析, SEO:DeadHunt, SEO:Python代码分析, SEO:僵尸依赖, SEO:死代码扫描, WebSocket, 依赖分析, 僵尸依赖, 后端开发, 安全扫描, 开源扫描工具, 时序注入, 未使用导入, 框架感知分析, 死代码检测, 终端界面, 逆向工具, 零配置