Recon-Scan

ReconScan 是一个开源的被动侦察扫描器，采用 FastAPI 后端、异步 worker 流水线和单页前端。你可以在 https://recon-scan.vercel.app/ 查看已部署的站点。

其核心在于快速信号：运行一次扫描，获取逐模块的发现结果，并获得一份 AI 摘要，该摘要现已可导出为精美的 PDF 报告。

该项目是什么（以及不是什么）

• 它是被动侦察。不会对端点进行暴力破解、模糊测试或运行主动利用逻辑。
• 它适用于态势快照、分类和报告。
• 它不能替代完整的渗透测试。

功能特性

• 13 个被动模块：
  • 安全头部
  • SSL/TLS
  • DNS + 邮件认证（SPF/DMARC/MX）
  • WHOIS
  • Robots/sitemap
  • 子域名枚举
  • 技术指纹识别
  • WAF 检测
  • CORS 检查
  • Cookie 安全检查
  • JS 暴露检查
  • 目录暴露检查
  • 信誉检查
• 使用 Redis + ARQ worker 实现异步执行。
• 若队列入队失败，则回退到进程内后台执行。
• 可选通过 OpenRouter / Anthropic / OpenAI 提供 AI 摘要。
• 从扫描结果 + AI 摘要生成 PDF 报告。
• 前端由 FastAPI 直接提供（一个 URL，一个应用）。

一键启动（本地开发）

如果你只想快速运行：

./start.sh

该脚本会执行以下操作：

• 如果缺少 .env，则从 .env.example 创建。
• 如果需要，创建 .venv。
• 从 requirements.txt 安装依赖。
• 在 http://localhost:8000 上以热重载方式启动 FastAPI。
• 强制设置 USE_ARQ_QUEUE=false，以便无 Redis 的本地启动更简单。

使用 Ctrl+C 停止。

一键启动（Docker）

./start-docker.sh

该脚本会执行以下操作：

• 如果缺少 .env，则从 .env.example 创建。
• 使用 Docker Compose 启动 API + worker + Redis。

Docker 启动（手动）

cp .env.example .env
docker compose up --build

本地开发（不使用 Docker）

1. 安装依赖：

pip install -r requirements.txt

2. 创建环境文件：

cp .env.example .env

3. 启动 API：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. 在另一个终端启动 worker（推荐）：

arq app.worker.WorkerSettings

5. 打开：

http://localhost:8000

运行测试

安装测试依赖：

pip install -r requirements-dev.txt

运行完整测试套件：

pytest -q

PDF 报告

扫描完成后，在界面中点击 Download PDF。

后端端点：

• GET /scans/{scan_id}/report.pdf

报告包括：

• 目标和扫描元数据
• AI 执行摘要（可用时包含简短版和完整叙述版）
• 严重性快照表
• 详细的逐模块发现结果

API

• GET /health
• POST /scans
  • body 示例：
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • 说明：
    • 除非 ALLOW_BYO_API_KEY=true，否则拒绝 byoapi_key
    • 阻止私有 / 环回 / 保留目标
    • user_id 为可选，保留以保持兼容
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

配置

来自 .env.example：

• DATABASE_URL（默认：sqlite:///./reconscan.db）
• REDIS_URL（默认：redis://localhost:6379）
• USE_ARQ_QUEUE（默认：true）
• RATE_LIMIT_PER_MINUTE（默认：10）
• RATE_LIMIT_PER_DAY（默认：200）
• ALLOWED_HOSTS（默认：localhost,127.0.0.1）
• CORS_ALLOWED_ORIGINS（默认：本地开发来源）
• ALLOW_BYO_API_KEY（默认：）

参与贡献

欢迎贡献，尤其是围绕被动侦察模块、报告、前端 UX 和测试覆盖方面。

在提交拉取请求之前，请阅读完整的贡献指南：

贡献指南

说明

• 如果未配置外部 AI 密钥，ReconScan 会存储本地回退摘要。
• 默认存储引擎为 SQLite，便于本地使用。
• 该仓库刻意保持轻量，且易于自托管。

许可证

MIT。参见 LICENSE。