fyshdhszs/web-vulnerability-scanner

# 授权目标 Web 漏洞检测与报告系统 这是一个面向课程大作业的 Web 安全检测报告系统。系统提供登录、白名单管理、授权扫描、漏洞结果展示和 HTML/PDF 报告导出。 系统只用于： - 本地靶场 - 自有域名 - 老师明确授权目标 - 明确允许测试的课程/演示靶场 系统不是公网任意 URL 扫描器。 ## 技术栈 - FastAPI - Jinja2 - SQLite / SQLAlchemy - OWASP ZAP sidecar container - Docker Compose - ReportLab ## 功能 - 管理员登录后才能使用系统。 - 只允许扫描启用状态的白名单目标。 - 创建扫描任务前会做目标连通性预检查。 - 默认扫描模式：Spider + Passive。 - 增强扫描模式：Spider + Passive + Active，仅显式选择时启用。 - 增强扫描已有边界控制、进度显示、超时停止和部分结果保存。 - 支持扫描取消，并尝试调用 ZAP stop API 停止底层 spider/ascan。 - 支持 HTML/PDF 报告导出。 ## 当前演示与部署状态 当前项目已经完成本地演示环境和 Google Cloud VPS 部署。 生产访问地址： https://scanner.fyshdhszs.com 帮助页和教师使用说明： https://scanner.fyshdhszs.com/help https://scanner.fyshdhszs.com/help/download.pdf 当前关键提交： 74c7e8b Polish UI, help page, and report guide 生产部署策略： - VPS 使用 `docker-compose.prod.yml`。 - Nginx 监听公网 `80/443`。 - FastAPI app 仅绑定到 `127.0.0.1:8000`。 - ZAP 仅在 Docker 内部网络暴露 `8080/tcp`。 - VPS 初始部署保持 `ENABLE_ENHANCED_SCAN=false`。 - 本地演示环境可开启 `ENABLE_ENHANCED_SCAN=true` 展示增强检测能力。 如果生产页面文字已更新但颜色或布局仍像旧版本，通常是浏览器缓存了旧的 `/static/css/style.css`。使用 `Ctrl + F5` 强制刷新即可。 ## 本地 Docker 运行 复制配置： Copy-Item .env.example .env 本地演示可使用： ADMIN_USERNAME=admin ADMIN_PASSWORD=admin123 SESSION_SECRET=change-this-to-a-long-random-string ALLOW_PRIVATE_TARGETS=true ENABLE_ENHANCED_SCAN=true 启动： docker compose up --build -d 访问： http://127.0.0.1:8000 查看状态： docker compose ps docker compose logs --tail=100 app docker compose logs --tail=100 zap 停止： docker compose down ## 增强扫描运行策略 早期实现的扫描封装只适合被动扫描。增强模式直接加入后，会把 spider、passive、active 共用一个总 timeout，并同步等待整站递归 active scan 完整结束，导致任务长时间 `running` 后失败。 当前实现已经修复： - Spider / Passive / Active 使用分阶段超时。 - Spider 默认限制深度、子节点数和最长运行时间。 - Active scan 默认不递归整站。 - Active scan 使用 LOW attack strength、MEDIUM alert threshold。 - Active scan 有总时长限制和单规则时长限制。 - Active scan 超时会调用 ZAP stop API。 - 超时前已发现的 alerts 会继续保存并生成报告。 - 任务详情页显示 ZAP 阶段、进度、spider ID、active scan ID。 相关配置： ZAP_SCAN_TIMEOUT_SECONDS=600 ZAP_SPIDER_TIMEOUT_SECONDS=120 ZAP_PASSIVE_TIMEOUT_SECONDS=60 ZAP_ACTIVE_TIMEOUT_SECONDS=300 ZAP_SPIDER_MAX_DEPTH=2 ZAP_SPIDER_MAX_CHILDREN=30 ZAP_SPIDER_MAX_DURATION_MINUTES=2 ZAP_ACTIVE_RECURSE=false ZAP_ACTIVE_MAX_SCAN_DURATION_MINUTES=5 ZAP_ACTIVE_MAX_RULE_DURATION_MINUTES=1 ZAP_ACTIVE_ATTACK_STRENGTH=LOW ZAP_ACTIVE_ALERT_THRESHOLD=MEDIUM 本机 `.env` 为了演示更快，当前使用： ZAP_ACTIVE_TIMEOUT_SECONDS=180 ZAP_ACTIVE_MAX_SCAN_DURATION_MINUTES=3 ## 演示流程 1. 打开 `http://127.0.0.1:8000`。 2. 使用 `.env` 中的管理员账号登录。 3. 进入白名单页，确认目标已启用。 4. 在控制台输入白名单内目标 URL。 5. 自有域名建议先用默认被动扫描。 6. 本地靶场或授权靶场可选择增强扫描。 7. 在扫描详情页查看阶段、进度和结果。 8. 下载 HTML/PDF 报告。 ## 安全边界 - 不允许扫描非白名单目标。 - 不删除登录限制。 - 不暴露 ZAP API 到公网。 - 默认不执行 active scan。 - 增强扫描必须显式选择，且目标仍必须命中白名单。 - 云服务器部署时建议设置 `ALLOW_PRIVATE_TARGETS=false`。 - ZAP API 在 Compose 中供内部网络使用；本机映射 `127.0.0.1:8090` 仅用于调试。 ## 非 Docker 开发运行 需要本机 Python 3.11+，并单独运行 ZAP daemon： python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt Copy-Item .env.example .env uvicorn backend.app.main:app --reload 如果 ZAP 在宿主机： ZAP_API_URL=http://127.0.0.1:8090 ## Google Cloud 迁移建议 完整步骤见： deployment/scanner-fyshdhszs-com-deployment-plan.md 部署完成后的追溯和常用命令见： WORK_LOG_2026-05-07_DEPLOYMENT_SUMMARY.md deployment/vps-operations-runbook.md 云端部署前修改： ADMIN_PASSWORD= ADMIN_PASSWORD_HASH= SESSION_SECRET= SESSION_COOKIE_SECURE=true ENABLE_ENHANCED_SCAN=false ALLOW_PRIVATE_TARGETS=false SEED_ALLOWLIST_ENABLED=false VPS 上优先使用生产模板和生产 Compose： cp deployment/env.production.example .env nano .env python3 scripts/preflight_check.py --env .env docker compose -f docker-compose.prod.yml up -d --build 部署建议： - 只开放反向代理后的 Web 端口。 - 不要开放 ZAP API 端口。 - 白名单只添加自有域名、老师授权目标或云端内部靶场。 - VPS 初始部署建议关闭种子白名单，上线后登录后台手动添加授权目标。 ## 目录结构 web-vulnerability-scanner/ ├── backend/app/ # FastAPI 应用 ├── data/ # SQLite 数据库目录 ├── reports/ # 扫描报告和 ZAP 原始 JSON ├── scripts/ # 辅助脚本和部署前自检 ├── deployment/ # VPS 部署计划和生产环境变量模板 ├── docker-compose.yml ├── docker-compose.prod.yml ├── Dockerfile ├── requirements.txt ├── PROJECT_PLAN.md ├── AGENT.md └── README.md