indiser/DeadHunt

## 🎯 概述 **DeadHunt** 是一款精密的静态分析工具，它结合了 AST 解析、依赖分析和 AI 驱动的推理，用于识别 Python 项目中的死代码和僵尸依赖。与传统的 linter 不同，DeadHunt 能够理解框架模式（Django、Flask、FastAPI），并通过智能上下文分析来减少误报。 ### 为什么选择 DeadHunt？ - 🔍 **感知框架**：识别 Django 模型、Flask 路由、FastAPI endpoint 以及其他框架模式 - 🧠 **AI 驱动分析**：使用 LLM 推理来区分真正的死代码和框架调用的代码 - 📊 **综合报告**：生成美观且交互式 HTML 报告，并提供具有指导意义的洞察 - 🚀 **零配置**：只需粘贴 GitHub URL 即可开始扫描 - 🎨 **现代 UI**：具有赛博朋克风格的终端界面和实时进度显示 ## ✨ 功能 ### 🔬 死代码检测 - 识别未使用的函数、类、变量和导入 - 基于 AST 进行跨文件引用跟踪与分析 - 针对特定框架的白名单机制，以避免误报 - 为每项发现提供置信度评分 ### 🧟 僵尸依赖猎捕 - 将声明的依赖与实际导入进行比较 - 检测已安装但从未使用的包 - 找出冗余的 `requirements.txt` 文件 - 建议可以安全移除的候选项 ### 📈 智能报告 - 包含健康评分的执行摘要 - 按风险分类的发现项（高/中/低） - 针对每个问题提供具有指导意义的建议 - 支持 PDF 导出和 Markdown 复制功能 - 带有滚动监听的交互式目录 ### 🎨 精美界面 - 赛博朋克主题的终端 UI - 实时扫描进度 - 动态粒子和扫描线特效 - 适配移动端和桌面端的响应式设计 ## 🎬 演示 ### 首页 ``` ┌─────────────────────────────────────────┐ │ 💀 DeadHunt │ │ Hunt The Dead Code. │ │ │ │ ❯ https://github.com/user/repo │ │ [SCAN] │ └─────────────────────────────────────────┘ ``` ### 分析报告 - **健康评分**：显示代码库健康度（0-100）的环形图 - **发现卡片**：带有结论徽章的颜色编码卡片 - **侧边栏目录**：自动生成的导航栏，并具有当前部分高亮显示功能 - **导出选项**：支持 PDF 下载和原始 Markdown 复制 ## 🚀 安装说明 ### 前置条件 - Python 3.8 或更高版本 - Git - pip ### 快速开始 1. **克隆仓库** git clone https://github.com/indiser/DeadHunt.git cd DeadHunt 2. **安装依赖** pip install -r requirements.txt 3. **设置环境变量** # 创建一个 .env 文件并填入你的 API 密钥 cp .env.example .env 将你的 API 密钥添加到 `.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 4. **运行应用** python app.py 5. **打开浏览器** 访问 http://localhost:5000 ## 📖 使用方法 ### Web 界面 1. 在浏览器中打开 DeadHunt 2. 粘贴一个 GitHub 仓库 URL（例如 `https://github.com/user/repo`） 3. 点击 **SCAN** 4. 等待分析完成（通常需要 30-90 秒） 5. 查看包含发现问题和改进建议的取证报告 ### 命令行（高级） ``` from enginex import analyze_repo # 分析 repository report = analyze_repo("https://github.com/user/repo") print(report) ``` ## 🔧 工作原理 ### 阶段 1：克隆与解析 ``` Repository → Shallow Clone → AST Parsing → Framework Detection ``` - 克隆目标仓库（使用 depth=1 以提高速度） - 将所有 Python 文件解析为抽象语法树（AST） - 检测框架架构（Django/Flask/FastAPI/通用） ### 阶段 2：静态分析 ``` AST → Vulture Scanner → Cross-File References → Confidence Scoring ``` - 使用 [Vulture](https://github.com/jendrikseipp/vulture) 进行死代码检测 - 执行跨文件引用分析 - 应用针对特定框架的白名单 - 分配置信度评分（60-100%） ### 阶段 3：依赖分析 ``` requirements.txt → Import Extraction → Diff Analysis → Zombie Detection ``` - 使用 `pipreqs` 或手动 AST 扫描生成实际导入的依赖 - 对比声明依赖与实际依赖 - 找出未使用的包 ### 阶段 4：AI 推理 ``` Findings → LLM Analysis → Verdict Assignment → Risk Categorization ``` - 将分析发现发送至 AI 模型（Gemini/OpenRouter/Groq/Cerebras） - 应用框架模式识别 - 区分误报与实际问题 - 生成具有指导意义的建议 ## 🏗️ 架构 ``` 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 ``` ### 核心组件 - **app.py**：Flask Web 服务器，负责处理路由和报告渲染 - **enginex.py**：核心扫描逻辑、AST 解析、Vulture 集成以及 LLM 通信 - **index.html**：带有终端输入框的赛博朋克风格首页 - **report.html**：支持 Markdown 渲染的交互式取证报告 ## 🛡️ 框架支持 DeadHunt 能够智能处理特定框架的模式： | 框架 | 支持的模式 | |-----------|-------------------| | **Django** | 模型、Meta 类、admin 属性、信号、middleware、AppConfig | | **Flask** | 路由、蓝图、装饰器、上下文处理器 | | **FastAPI** | 路径操作、依赖项、后台任务 | | **Celery** | 任务装饰器、worker 调用的函数 | | **Pytest** | Fixture、测试函数、conftest.py | | **SQLAlchemy** | 模型列、关系、事件监听器 | ## 📊 路线图 - [ ] 支持 JavaScript/TypeScript 仓库 - [ ] GitHub Actions 集成 - [ ] 用于 CI/CD pipeline 的 CLI 工具 - [ ] VS Code 扩展 - [ ] 多仓库批量扫描 - [ ] 历史趋势分析 - [ ] 自定义规则配置 ## 🐛 已知限制 - **Python 2 支持**：对 Python 2 代码库的 AST 解析能力有限 - **动态导入**：无法检测通过 `importlib` 或 `exec()` 进行的运行时导入 - **反射模式**：可能会将元编程模式标记为死代码 - **私有仓库**：需要公开的 GitHub URL（或手动克隆） ## 📄 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。 ## 📧 联系方式 **项目维护者**：Indiser - GitHub：[indiser](https://github.com/indiser) - 邮箱：indiser01@gmail.com

标签：AST, Flask, Python, 云安全监控, 代码质量, 后端开发, 无后门, 死代码检测, 静态分析