Youness-Harrizi/recon-dashboard-yh

# recon-dashboard-yh         ## 快速开始 ``` git clone https://github.com/Youness-Harrizi/recon-dashboard-yh.git cd recon-dashboard-yh cp .env.example .env docker compose up --build ``` 然后打开： - **Web UI:** http://localhost:3000 - **API 文档:** http://localhost:8000/docs - **健康检查:** http://localhost:8000/health 提交 `example.com` —— 你会看到七个模块卡片从 `pending → running → done` 过渡，随着结果不断流入。 ## 侦察模块 | 模块 | 功能描述 | 来源 | |---------|-------------------------------------------------------------------|---------------------------------------------| | `dns` | A/AAAA/MX/NS/TXT/CNAME/SOA 记录；标记缺失 SPF / DMARC | `dnspython` | | `whois` | RDAP：注册商、注册/过期时间、名称服务器、状态 | `rdap.org` → 权威 RDAP 服务器 | | `crtsh` | 从证书透明度日志中枚举子域名 | `crt.sh` | | `tls` | 443 握手、证书解析、基于过期时间的严重性分级 | stdlib `ssl` | | `http` | GET `/`，检查头部，标记缺失的安全头部 | 直接 HTTPS | | `wayback` | 历史 URL | `web.archive.org` CDX API | | `shodan` | 被动 DNS（子域名、记录）+ 暴露服务（可选） | Shodan API — 需要 `SHODAN_API_KEY` | | `github` | 公开代码中提及该域名（可选 — 需要 `GITHUB_TOKEN`） | GitHub 代码搜索 API | 模块实现一个微型协议 ([backend/app/recon/base.py](backend/app/recon/base.py)) 并在 [registry.py](backend/app/recon/registry.py) 中注册。新增一个模块大约需要 30 行代码。 ## 架构 ``` flowchart LR subgraph Browser UI["Next.js UI
EventSource"] end subgraph API["FastAPI (async)"] POST["POST /scans
(rate-limited)"] SSE["GET /stream
(SSE)"] EXPORT["GET /export.{html,xlsx,csv,md,json}"] end DB[("PostgreSQL 16
scans · findings · module_runs · cache")] REDIS[("Redis 7
Celery broker
pub/sub channel")] subgraph Worker["Celery worker"] DISPATCH["chord header"] M1["dns"] M2["whois"] M3["crtsh"] M4["tls"] M5["http"] M6["wayback"] M7["shodan"] M8["github"] FIN["finalize_scan"] end UI -->|POST domain| POST POST -->|insert Scan + ModuleRuns| DB POST -->|enqueue chord| REDIS REDIS --> DISPATCH DISPATCH --> M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 -->|emit Finding| DB M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 -->|publish event| REDIS M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 --> FIN FIN -->|status=done| DB FIN -->|publish end| REDIS REDIS -->|subscribe| SSE SSE -->|stream events| UI UI -->|click export| EXPORT EXPORT -->|read| DB ``` **关键流程：** - **提交。** `POST /api/v1/scans` 验证域名（SSRF 防护），插入一条 `Scan` 和每个模块的一条 `ModuleRun`，触发 Celery 和弦（chord），返回 201。 - **执行。** 每个工作线程检查 `domain_cache` 表；命中则重放缓存结果，未命中则运行模块，将每个 `Finding` 持久化，并在缓存中按模块 TTL 存储批次结果。 - **流式。** 每个状态变化（`module_run`、`finding`、`scan`）通过 `scan:` 发布到 Redis。SSE 端点订阅并发送初始快照，随后转发事件直到 `end`。浏览器使用 `EventSource`；失败时回退到轮询。 - **完成。** 和弦回调将 `Scan.status` 翻转为 `done`/`failed` 并发布终止事件。 ## API ``` POST /api/v1/scans { "domain": "example.com" } → Scan (10/min/IP) GET /api/v1/scans → Scan[] (most recent first) GET /api/v1/scans/{id} → ScanDetail (findings + module_runs) GET /api/v1/scans/{id}/stream → SSE: snapshot, module_run, finding, scan, end GET /api/v1/scans/{id}/export.html → self-contained HTML report (printable to PDF) GET /api/v1/scans/{id}/export.xlsx → Excel workbook (Overview / Findings / Modules sheets) GET /api/v1/scans/{id}/export.csv → flat findings table (UTF-8 BOM, opens in Excel) GET /api/v1/scans/{id}/export.md → Markdown report GET /api/v1/scans/{id}/export.json → raw JSON GET /health → dependency status ``` 完整的 OpenAPI 规范位于 http://localhost:8000/docs。 ## 安全与伦理 **范围。** 本工具执行 **被动式** 侦察：公共 DNS 查询、RDAP、证书透明度查询、Wayback 机器、单个 TLS 握手以及对根页面的一次 HTTP GET。 **它不会** 端口扫描、暴力破解子域名、爬取或探测漏洞。 **内置的滥用防护：** - 输入验证器拒绝 IP 地址、`localhost` 及保留 TLD（`.local`、`.internal`、`.arpa` 等）——参见 [domain_validator.py](backend/app/services/domain_validator.py)。 - `POST /scans` 通过 slowapi 限制为 10 次/分钟/IP。 - HTTP 模块不会跟随重定向到内部主机（httpx 默认设置 + 显式 HTTPS 方案）。 - 若没有令牌，GitHub 模块会优雅跳过，而不是静默失败。 **仅对您拥有或明确授权评估的域名使用本工具。** 本项目旨在展示工程能力，而非协助未经授权的测试。 ## 开发 ### 运行测试套件 ``` docker compose exec backend pytest ``` 完全隔离（hermetic）：模拟 `dns.resolver`，无需网络/数据库。覆盖域名验证器（接受/拒绝矩阵 + IDN punycode）、注册表不变量以及 DNS 模块。 ### 项目结构 ``` backend/ app/ api/ routes_scans.py, routes_stream.py recon/ base.py, registry.py, dns_records.py, whois_rdap.py, … services/ domain_validator.py, orchestrator.py, events.py, cache.py, exporters.py workers/ celery_app.py, tasks.py models/ scan.py, finding.py, module_run.py, cache.py schemas/ (Pydantic) tests/ test_domain_validator.py, test_registry.py, test_dns_module.py alembic/ versions/0001_initial.py web/ src/app/ page.tsx, scan/[id]/page.tsx, scan/[id]/FindingData.tsx src/lib/api.ts typed API client docker-compose.yml ``` ### 新增侦察模块 1. 在 `backend/app/recon/my_module.py` 中添加： ```python class MyModule: name = "mymodule" passive = True def run(self, ctx: Context) -> None: ctx.emit(FindingDraft(module=self.name, title="hello", data={})) ``` 2. 在 [registry.py](backend/app/recon/registry.py) 中注册它。 3. （可选）在 [cache.py](backend/app/services/cache.py) 的 `MODULE_TTL` 中添加缓存过期时间。 ### 数据库迁移 Alembic 在后端容器启动时运行 `upgrade head`。要新增迁移： ``` docker compose exec backend alembic revision --autogenerate -m "describe change" ``` ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。 基于个人作品集项目构建。欢迎反馈与提问 —— 可新建 Issue。

标签：AV绕过, CDN识别, Celery, DNS查询, Docker Compose, ESC4, Excel导出, FastAPI, HTML导出, JSON导出, Live Dashboard, Markdown导出, OSINT, PostgreSQL, Python, Redis, REST, Stream, TLS检测, Web API, Whois查询, 后台任务, 域名侦察, 多模块并发, 威胁情报, 子域名枚举, 安全工具库, 实时仪表盘, 工作流, 开发者工具, 搜索引擎查询, 数据导出, 无后门, 流式UI, 测试用例, 消息队列, 系统安全, 自托管, 被动侦察, 证书透明度, 请求拦截, 逆向工具