stack-guardian/HiveRecon

面向 Bug Bounty Hunting 的 AI 驱动侦察框架

功能 | 快速开始 | 架构 | API | 结构 | 开发

## 概述 HiveRecon 自动化了完整的安全侦察流程——从子域名枚举到漏洞扫描——使用由 Groq 驱动的中央 AI 协调器编排五个专门的代理。该系统提供了一个基于 React 的 Web 仪表板，由单个 FastAPI 容器提供服务，使用 SQLite 进行数据持久化，并提供全面的审计日志记录以符合法律合规性。 ## 功能 - **自动化侦察流程** —— 将子域名发现、端口扫描、端点发现和漏洞扫描串联成单一工作流 - **AI 编排** —— Groq AI 优先处理目标，选择扫描候选对象，关联发现结果并生成执行摘要 - **五个专门的代理** —— 子域名、端口扫描、端点发现、漏洞扫描 和 MCP 服务器 - **法律优先设计** —— 范围验证、审计日志记录和边界执行确保仅扫描授权目标 - **发现结果关联** —— 跨工具分析可减少误报并将相关发现分组 - **教育性输出** —— 针对每个发现提供初学者友好的解释和修复指导 - **Web 仪表板** —— React SPA，包含扫描管理、发现浏览器、实时监控和设置 - **报告生成** —— 每次扫描生成 PDF 和 Markdown 报告 - **MCP 服务器** —— 用于外部 AI 代理集成的模型上下文协议接口 - **单容器部署** —— 所有内容在端口 8000 的单个 Docker 容器中运行 ## 截图

Welcome Screen

Legal Disclaimer — Authorization Acknowledgment

Scope Configuration — Define In/Out of Scope Targets

Scan Monitor — Real-Time Progress Tracking

Findings — Vulnerability Results Browser

New Scan — Target Configuration

Dashboard — Statistics & Overview

## 技术栈 | 组件 | 技术 | |-----------|------------| | 语言 | Python 3.14 | | 后端 | FastAPI (async) | | AI/LLM | Groq API (llama-3.1-8b-instant) | | 数据库 | SQLite + SQLAlchemy (async) | | 前端 | React 19 + Vite + shadcn/ui | | 容器 | Docker + Docker Compose | | 侦察工具 | subfinder, nmap, katana, nuclei, amass, ffuf | ## 快速开始 ### 前置条件 - Docker 和 Docker Compose - 一个 Groq API 密钥（可在 [console.groq.com](https://console.groq.com) 免费获取） ### Docker 部署 ``` git clone https://github.com/stack-guardian/HiveRecon.git cd HiveRecon ``` 在 `docker-compose.yml` 中设置您的 Groq API 密钥： ``` environment: GROQ_API_KEY: "gsk_your_key_here" ``` 构建并启动： ``` docker compose build --no-cache app docker compose up -d ``` 验证部署： ``` curl http://localhost:8000/health # {"status":"healthy","version":"0.1.0","groq_configured":true} ``` 打开仪表板： ``` http://localhost:8000/app/ ``` ### 手动安装 ``` # 安装 Python 依赖 pip install -r requirements.txt # 初始化数据库 python -c "from hiverecon.database import init_db; from hiverecon.config import get_config; import asyncio; asyncio.run(init_db(get_config().get_database_url()))" # 启动 API 服务器 uvicorn hiverecon.api.server:app --host 0.0.0.0 --port 8000 ``` ## 架构 ``` Incoming Request (port 8000) | v FastAPI Server (uvicorn) | +-- API Routes (/health, /scans, /findings, /stats) | | | v | SQLite Database (aiosqlite) | | | v | HiveMindCoordinator | | | +-- Groq API (cloud, llama-3.1-8b-instant) | +-- Recon Agents (subfinder, nmap, katana, nuclei) | +-- Parsers, Correlation, Audit Logger | +-- Static Files (/app/, /assets/, /favicon.svg) | v React SPA (Vite production build) ``` ### 扫描流程 ``` subfinder --> AI Prioritize --> nmap --> AI Select --> katana --> AI Select --> nuclei (subdomains) (rank hosts) (ports) (top hosts) (crawl) (endpoints) (vulnscan) | | +---------------------------> AI Summary <------------------------------+ | v Executive Report ``` ## API 端点 | 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/` | API 根信息 | | GET | `/health` | 健康检查（含 Groq 状态） | | POST | `/scans` | 创建新的侦察扫描 | | GET | `/scans` | 列出所有扫描（支持过滤） | | GET | `/scans/{id}` | 获取扫描详情 | | GET | `/scans/{id}/summary` | 获取 AI 生成的摘要 | | GET | `/scans/{id}/findings` | 获取特定扫描的发现结果 | | DELETE | `/scans/{id}` | 取消正在运行的扫描 | | GET | `/findings` | 列出所有扫描的发现结果 | | GET | `/stats` | 总体统计数据 | | GET | `/app/` | React 仪表板 SPA | | GET | `/api/v1/reports/{id}/markdown` | 下载 Markdown 报告 | ## 项目结构 ``` hiverecon/ ├── hiverecon/ # Python package (backend core) │ ├── agents/ # 5 recon agents (subfinder, nmap, katana, nuclei, MCP) │ ├── core/ # HiveMindCoordinator, parsers, correlation, audit │ ├── api/ # FastAPI server and report endpoints │ ├── config.py # Pydantic configuration system │ ├── database.py # SQLAlchemy ORM models │ └── cli.py # Command-line interface ├── dashboard/ # React frontend │ └── src/ │ ├── pages/ # 8 dashboard pages │ ├── components/ # shadcn/ui components │ └── api.js # API client ├── config/ # YAML configuration ├── docs/ # Extended documentation ├── scripts/ # Utility scripts ├── docker-compose.yml # Single-service deployment ├── Dockerfile # Container build definition └── ARCHITECTURE.md # Complete technical documentation ``` ## 仪表板页面 | 页面 | 用途 | |------|---------| | 仪表板 | 统计卡片、扫描状态图表、近期扫描 | | 新建扫描 | 目标输入、范围配置、扫描启动 | | 扫描监控 | 实时扫描进度追踪 | | 发现结果 | 可过滤的漏洞发现表格 | | 范围配置 | 范围内/范围外域名管理 | | 设置 | Groq API 密钥、模型选择器 | | 法律 | 条款确认 | | 欢迎 | 新用户引导 | ## 配置 ### 环境变量 | 变量 | 用途 | 默认值 | |----------|---------|---------| | `GROQ_API_KEY` | Groq API 认证 | （必填） | | `DATABASE_URL` | 数据库连接字符串 | `sqlite+aiosqlite:///./hiverecon.db` | | `AI_MODEL` | 覆盖 AI 模型 | `llama-3.1-8b-instant` | ### 可用的 AI 模型 - `llama-3.1-8b-instant`（默认，快速） - `llama-3.3-70b-versatile`（质量更高） - `mixtral-8x7b-32768`（大上下文） - `gemma-7b-it`（轻量级） ## 开发 ### 运行测试 ``` pytest tests/ -v ``` ### 构建仪表板 ``` cd dashboard npm install --legacy-peer-deps npm run build ``` ### 代码风格 ``` # 格式化 black hiverecon/ # Linting ruff check hiverecon/ # Type checking mypy hiverecon/ ``` ## 文档 - [ARCHITECTURE.md](ARCHITECTURE.md) —— 完整的技术架构（872 行） - [docs/README.md](docs/README.md) —— 扩展设置和故障排除指南 - [QUICKSTART.md](QUICKSTART.md) —— 快速入门指南 - [DOCKER.md](DOCKER.md) —— Docker 部署详情 - [PROJECT_STATUS.md](PROJECT_STATUS.md) —— 功能完成跟踪器 - [ROADMAP.md](ROADMAP.md) —— 未来开发计划 ## 已知限制 - **Subfinder 配置警告** —— 子域名枚举期间的非阻塞权限警告。不影响功能。 - **SQLite 并发性** —— 并发写入支持有限。足以满足单用户部署。建议在生产环境多用户场景中使用 PostgreSQL。 - **无身份验证** —— 仪表板没有用户身份验证。在网络暴露部署前请添加 JWT 身份验证。 ## 许可证 MIT 许可证 —— 详情请参阅 [LICENSE](LICENSE)。 ## 作者 **Vibhor Prasad** ([@stack-guardian](https://github.com/stack-guardian))

标签：AV绕过, Bug Bounty, Docker, FastAPI, GitHub, Google, Nmap, Nuclei, React, Syscalls, WSL, 人工智能, 协调器, 可自定义解析器, 大模型安全, 子域名枚举, 安全合规, 安全扫描, 安全防御评估, 密码管理, 密钥管理, 插件系统, 数据统计, 时序注入, 用户模式Hook绕过, 白盒审计, 端口扫描, 系统安全, 网络代理, 网络安全, 自动化侦察, 自动化渗透, 虚拟驱动器, 请求拦截, 逆向工具, 隐私保护