nabz0r/Xpose
GitHub: nabz0r/Xpose
一个生产级的 OSINT SaaS 平台，能够并行调度八个开源情报工具对邮箱或用户名进行聚合调查，并生成带置信度评分的统一报告。
Stars: 0 | Forks: 0
# Xpose — OSINT 调查平台
一个生产级 SaaS Web 应用程序，可针对电子邮件或用户名目标并行运行 8 个 OSINT 工具，通过跨工具去重和置信度评分汇总结果，并显示具有暗色网络主题 UI 的统一调查报告。
## 目录
- [快速入门（交互式安装程序）](#quick-start-interactive-installer)
- [架构概览](#architecture-overview)
- [技术栈](#tech-stack)
- [集成的 OSINT 工具](#osint-tools-integrated)
- [安装指南](#installation-guide)
- [前置条件](#prerequisites)
- [交互式安装程序（推荐）](#interactive-installer-recommended)
- [手动 Docker 部署](#manual-docker-deployment)
- [本地开发设置](#local-development-setup)
- [配置](#configuration)
- [使用](#usage)
- [安全与认证](#security--authentication)
- [两步验证 (2FA)](#two-factor-authentication-2fa)
- [单点登录 (SSO)](#single-sign-on-sso)
- [扫描工作流](#scan-workflow)
- [API 参考](#api-reference)
- [前端页面](#frontend-pages)
- [Token 与定价模型](#token--pricing-model)
- [GHunt 补丁](#ghunt-patch)
- [项目结构](#project-structure)
- [故障排除](#troubleshooting)
## 架构概览
```
┌─────────────────────────────────────────────────────────────────┐
│ CLIENT BROWSER │
│ (React + Tailwind CSS) │
│ Landing │ Dashboard │ Scan Results │ Admin │ Settings │ Auth │
└──────────────────┬─────────────────────┬────────────────────────┘
│ REST API (HTTPS) │ WebSocket (WSS)
┌──────────────────▼─────────────────────▼────────────────────────┐
│ NGINX REVERSE PROXY │
│ Serves frontend static files │
│ Proxies /api/* → backend:8000 │
│ Upgrades WebSocket connections │
└──────────────────┬─────────────────────┬────────────────────────┘
│ │
┌──────────────────▼─────────────────────▼────────────────────────┐
│ BACKEND (FastAPI) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ Auth API │ │Scans API │ │Admin API │ │ WebSocket Handler │ │
│ │ JWT+SSO │ │CRUD+Export│ │Stats+Mgmt│ │ Live scan updates │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ Token management · Scan orchestration · Result dedup │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ SQLAlchemy ORM (Async) + Pydantic Schemas │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────┬─────────────────────────────┬─────────────────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────────────────┐
│ PostgreSQL 16 │ │ Redis 7 │
│ │ │ │
│ users │ │ Celery broker (task queue) │
│ scans │ │ Celery backend (result store) │
│ scan_results │ │ Rate limiting cache │
│ accounts │ │ Session cache │
│ token_transactions │ │ │
│ api_keys │ └──────────┬──────────────────────┘
└─────────────────────┘ │
│ Task dispatch
┌──────────────────────────▼──────────────────────┐
│ CELERY WORKERS │
│ │
│ Orchestrator: run_full_scan() │
│ ┌─────────────────────────────────────────────┐ │
│ │ Parallel tool execution (8 concurrent) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ │
│ │ │ GHunt │ │ Holehe │ │ Maigret │ │ │
│ │ │(patched)│ │(120+ ▓▓)│ │(2600+ ▓▓)│ │ │
│ │ └─────────┘ └─────────┘ └──────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ │
│ │ │ h8mail │ │ Mosint │ │Blackbird │ │ │
│ │ │(breaches│ │(Go bin) │ │(600+ ▓▓▓)│ │ │
│ │ └─────────┘ └─────────┘ └──────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │Sherlock │ │ HIBP │ │ │
│ │ │(300+ ▓▓)│ │(API) │ │ │
│ │ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ Deduplicator: deduplicate_accounts() │
│ Scheduler: reset_free_tokens() (daily) │
└──────────────────────────────────────────────────┘
```
### 数据流
1. 用户通过前端提交电子邮件/用户名
2. 后端验证请求，扣除 token，创建扫描记录
3. Celery 编排器分发 8 个并行工具任务
4. 每个工具独立运行，将结果保存到 PostgreSQL
5. 前端通过 WebSocket 接收实时进度（每 2 秒轮询一次）
6. 当所有工具完成后，去重器汇总并对结果进行评分
7. 用户查看带有置信度评分账户的统一报告
## 技术栈
| 层级 | 技术 | 版本 | 用途 |
|-------|-----------|---------|---------|
| **Frontend** | React | 18.3 | UI 框架 |
| | Tailwind CSS | 3.4 | 实用优先的样式 |
| | Framer Motion | 11.15 | 动画 |
| | Recharts | 2.15 | 仪表板图表 |
| | Axios | 1.7 | HTTP 客户端 |
| | Lucide React | 0.468 | 图标库 |
| **Backend** | FastAPI | 0.115 | REST API 框架 |
| | SQLAlchemy | 2.0 | 异步 ORM |
| | Pydantic | 2.10 | 数据验证 |
| | python-jose | 3.3 | JWT token |
| | Passlib + bcrypt | 1.7 | 密码哈希 |
| | Authlib | 1.4 | OAuth (Google, GitHub) |
| | pyotp | latest | TOTP 两步验证 |
| | qrcode | latest | 用于 2FA 设置的二维码生成 |
| | WeasyPrint | 63.1 | PDF 报告生成 |
| **Workers** | Celery | 5.4 | 任务队列 |
| | Redis | 7 | Broker + 缓存 |
| **Database** | PostgreSQL | 16 | 主数据存储 |
| **Infrastructure** | Docker Compose | 3.8 | 容器编排 |
| | Nginx | Alpine | 反向代理 |
## 集成的 OSINT 工具
| 工具 | 输入 | 站点/来源 | 发现内容 | 方法 |
|------|-------|---------------|---------------|--------|
| **GHunt** (已修补) | email | Google 服务 | Gaia ID, 个人资料照片, 地图评论, 日历, 云端硬盘, Play Games | Python 库 + gpsoauth |
| **Holehe** | email | 120+ 站点 | 邮箱是否在 Twitter, Snapchat, Instagram, Deliveroo 等注册 | Python 库 (异步) |
| **Maigret** | username | 2600+ 站点 | 社交媒体、论坛、平台上的用户名归属 | CLI 子进程 |
| **h8mail** | email | 泄露数据库 | 数据泄露和凭证泄露 (HIBP, Scylla 等) | CLI 子进程 → JSON |
| **Mosint** | email | 多种来源 | 泄露检查, 社交媒体, DNS 记录, Google dorking | Go 二进制 |
| **Blackbird** | email/username | 600+ 站点 | 通过 WhatsMyName 项目数据库检查账户是否存在 | Python 子进程 |
| **Sherlock** | username | 300+ 站点 | 社交媒体账户发现 | CLI 子进程 → JSON |
| **HIBP API** | email | Have I Been Pwned | 数据泄露及泄露日期、受影响的数据类别 | REST API (需要密钥) |
### 衍生情报
除了原始工具输出外，Xpose 还会自动执行：
- **用户名提取** — 提取电子邮件的本地部分（`@` 之前）并将其输入给基于用户名的工具（Maigret, Sherlock, Blackbird）
- **跨工具去重** — 多个工具发现的同一平台被合并为一个条目
- **置信度评分** — 如果 2 个以上工具确认则为 `HIGH`，如果 1 个工具则为 `MEDIUM`，不确定的匹配为 `LOW`
- **反向图片搜索链接** — 如果 GHunt 返回个人资料照片 URL，则会生成指向 Yandex/TinEye 的链接
## 快速入门（交互式安装程序）
部署 Xpose 的最快方式 —— 一条命令搞定一切：
```
git clone https://github.com/nabz0r/Xpose.git
cd Xpose
./setup
```
安装程序会引导您完成配置，构建所有容器，并显示实时进度部署完整技术栈。有关详细信息，请参阅 [交互式安装程序](#interactive-installer-recommended)。
## 安装指南
### 前置条件
| 要求 | 最低版本 | 检查命令 |
|-------------|----------------|---------------|
| **Docker** | 20.10+ | `docker --version` |
| **Docker Compose** | 2.0+ (v2 插件) | `docker compose version` |
| **Git** | 2.30+ | `git --version` |
| **磁盘空间** | 5 GB 可用空间 | `df -h` |
| **RAM** | 4 GB 最低 (推荐 8 GB) | `free -h` |
对于本地开发（不使用 Docker）：
| 要求 | 版本 | 检查命令 |
|-------------|---------|---------------|
| **Python** | 3.11+ | `python3 --version` |
| **Node.js** | 20+ | `node --version` |
| **npm** | 9+ | `npm --version` |
| **Go** | 1.21+ (用于 Mosint) | `go version` |
| **PostgreSQL** | 16+ | `psql --version` |
| **Redis** | 7+ | `redis-server --version` |
### 交互式安装程序（推荐）
Xpose 包含一个完整的终端 UI 安装程序，可在单个引导流程中处理整个部署 —— 从配置到运行服务。
#### 运行
```
./setup
# 或
./install.sh
```
#### 安装程序的功能
安装程序按顺序运行 5 个屏幕：
```
┌─────────────────────────────────────────────────────────────┐
│ │
│ ██╗ ██╗██████╗ ██████╗ ███████╗███████╗ │
│ ╚██╗██╔╝██╔══██╗██╔══██╗██╔════╝██╔════╝ │
│ ╚███╔╝ ██████╔╝██║ ██║███████╗█████╗ │
│ ██╔██╗ ██╔═══╝ ██║ ██║╚════██║██╔══╝ │
│ ██╔╝ ██╗██║ ╚█████╔╝███████║███████╗ │
│ ╚═╝ ╚═╝╚═╝ ╚════╝ ╚══════╝╚══════╝ │
│ │
│ OSINT Investigation Platform │
│ │
└─────────────────────────────────────────────────────────────┘
```
**屏幕 1 — 预检检查**
在开始之前自动验证您的系统：
```
PREFLIGHT CHECKS
✓ Docker v27.3.1
✓ Docker Compose v2.30.3
✓ Docker daemon running
✓ Git 2.43.0
✓ Disk space 42GB available
✓ Memory 16GB RAM
✓ Port 3000 available
✓ Port 8000 available
✓ Port 5432 available
✓ Port 6379 available
✓ All checks passed
```
如果缺少任何要求，安装程序会准确告诉您需要修复什么并退出。
**屏幕 2 — 配置**
所有设置的交互式提示。安全默认值是自动生成的 —— 只需按 Enter 接受：
```
CONFIGURATION
─── Security (auto-generated — press Enter to accept) ───
▸ Secret key [a1b2c3d4e5f6...]: ↵
▸ Database password: ••••••••••
─── Ports ───
▸ Frontend port [3000]: ↵
▸ Backend port [8000]: ↵
─── Admin account ───
▸ Admin email: admin@example.com
▸ Admin password: ••••••••••
─── API keys (optional — press Enter to skip) ───
▸ HIBP API key: ••••••••••
▸ GHunt master token: ↵
▸ Configure OAuth (Google/GitHub login)? [y/N]: ↵
```
- **密钥 & 数据库密码** — 加密生成，只需按 Enter
- **管理员账户** — 可选，如果提供则自动创建并分配管理员角色
- **API 密钥** — 均为可选，按 Enter 跳过
- **OAuth** — 仅在您选择加入时提示
**屏幕 3 — 审核**
显示配置摘要，密钥已掩码：
```
REVIEW
│ Secret Key a1b2c3d4••••••••
│ DB Password ••••••••••••••••
│ Frontend http://localhost:3000
│ Backend API http://localhost:8000
│ Admin admin@example.com
│ HIBP API configured
│ GHunt skipped
│ Google OAuth skipped
│ GitHub OAuth skipped
▸ Proceed with installation? [Y/n]:
```
**屏幕 4 — 部署**
8 步部署，带有实时进度条和微调器：
```
DEPLOYING
████████████████████████████████████████████░░░░░░░░░░ 75%
✓ Environment file created
✓ Base images pulled
✓ Backend image built
✓ Frontend image built
✓ PostgreSQL & Redis healthy
✓ API server running
⣾ Starting Celery workers & scheduler...
```
每个步骤在继续之前都会等待健康检查：
1. 根据您的配置生成 `.env` 文件
2. 拉取基础 Docker 镜像
3. 构建后端镜像（FastAPI + 所有 OSINT 工具）
4. 构建前端镜像（React → Nginx）
5. 启动 PostgreSQL & Redis，等待直到健康
6. 启动 API 服务器，等待直到 `/api/health` 响应
7. 启动 Celery workers & Beat 调度器
8. 启动前端 Nginx 容器
如果配置了管理员电子邮件，安装程序会自动注册该账户并将其提升为管理员角色。
**屏幕 5 — 完成**
服务状态仪表板和访问信息：
```
═══════ INSTALLATION COMPLETE ═══════
SERVICE STATUS
● PostgreSQL :5432
● Redis :6379
● API Server :8000
● Workers
● Scheduler
● Frontend :3000
Access Your Instance
│ App http://localhost:3000
│ API http://localhost:8000
│ API Docs http://localhost:8000/docs
│ Admin Login admin@example.com
Commands
│ View logs docker compose logs -f
│ Stop docker compose down
│ Restart docker compose restart
│ Rebuild docker compose up -d --build
│ Reset DB docker compose down -v
```
#### 安装程序命令
| 命令 | 描述 |
|---------|-------------|
| `./setup` 或 `./install.sh` | 完整的交互式安装 |
| `./install.sh --status` | 显示当前服务状态（彩色健康指示器） |
| `./install.sh --uninstall` | 停止所有容器，删除镜像和卷 |
| `./install.sh --help` | 显示使用信息 |
#### 错误处理
- 如果 Docker 构建失败，安装程序会显示构建日志的最后 10 行
- 所有输出都记录到 `.install.log` 以供调试
- 安装程序在 Ctrl+C 时干净地退出（恢复光标，无孤立进程）
- 失败的预检检查会准确告诉您需要安装什么以及在哪里
### 手动 Docker 部署
如果您更喜欢手动配置所有内容而不是使用交互式安装程序。
#### 步骤 1：克隆仓库
```
git clone https://github.com/nabz0r/Xpose.git
cd Xpose
```
#### 步骤 2：创建环境文件
```
cp .env.example .env
```
#### 步骤 3：配置环境变量
在编辑器中打开 `.env` 并设置所需的值：
```
# 必填 — 在生产环境中更改此项
SECRET_KEY=your-random-secret-key-min-32-chars # Generate with: openssl rand -hex 32
DB_PASSWORD=your-secure-database-password # PostgreSQL password
# 可选 — 用于增强结果的 API keys
HIBP_API_KEY=your-hibp-api-key # https://haveibeenpwned.com/API/Key
GHUNT_MASTER_TOKEN=your-google-master-token # Required for GHunt to work
# 可选 — OAuth (用于 Google/GitHub 登录)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
```
#### 步骤 4：构建并启动所有服务
```
# 构建镜像并在后台启动
docker compose up -d --build
# 查看构建进度
docker compose logs -f
```
这将启动 6 个服务：
- `frontend` — 通过 Nginx 在端口 3000 上提供的 React 应用
- `backend` — 端口 8000 上的 FastAPI 服务器
- `worker` — Celery worker（4 个并发工具执行）
- `scheduler` — Celery Beat（每日 token 重置 cron）
- `postgres` — PostgreSQL 16 数据库
- `redis` — Redis 7 消息 broker
#### 步骤 5：验证所有服务正在运行
```
docker compose ps
```
预期输出：
```
NAME SERVICE STATUS
xpose-frontend-1 frontend running (healthy)
xpose-backend-1 backend running
xpose-worker-1 worker running
xpose-scheduler-1 scheduler running
xpose-postgres-1 postgres running (healthy)
xpose-redis-1 redis running (healthy)
```
#### 步骤 6：验证后端健康
```
curl http://localhost:8000/api/health
# 预期: {"status":"ok","app":"Xpose"}
```
#### 步骤 7：访问应用程序
| 服务 | URL | 用途 |
|---------|-----|---------|
| **Frontend** | http://localhost:3000 | 主 Web 应用程序 |
| **API** | http://localhost:8000 | REST API |
| **API 文档** | http://localhost:8000/docs | Swagger UI（交互式） |
| **API 文档** | http://localhost:8000/redoc | ReDoc（可读） |
#### 步骤 8：创建您的第一个管理员用户
通过 UI 在 http://localhost:3000 注册，然后提升为管理员：
```
# 连接到数据库
docker compose exec postgres psql -U xpose -d xpose
# 将用户提升为管理员 (替换 email)
UPDATE users SET role = 'admin' WHERE email = 'your@email.com';
# 验证
SELECT email, role, plan FROM users;
# 退出
\q
```
#### 可选：启用 PgAdmin
```
docker compose --profile admin up -d
# 访问地址 http://localhost:5050
# 登录: admin@xpose.local / (您在 .env 中设置的 PGADMIN_PASSWORD)
```
### 本地开发设置
用于在前端和后端都启用热重载的开发。
#### 步骤 1：启动数据库服务
您仍然需要 PostgreSQL 和 Redis。最简单的方法是 Docker：
```
# 仅启动数据服务
docker compose up -d postgres redis
```
或原生安装：
```
# macOS
brew install postgresql@16 redis
brew services start postgresql@16
brew services start redis
# Ubuntu/Debian
sudo apt install postgresql-16 redis-server
sudo systemctl start postgresql redis
```
#### 步骤 2：创建数据库
```
# 如果使用 Docker:
docker compose exec postgres psql -U xpose -c "SELECT 1;"
# 如果使用原生 PostgreSQL:
createdb xpose
psql -d xpose -c "CREATE USER xpose WITH PASSWORD 'xpose_secret';"
psql -d xpose -c "GRANT ALL PRIVILEGES ON DATABASE xpose TO xpose;"
```
#### 步骤 3：设置后端
```
cd backend
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装 Python 依赖
pip install -r requirements.txt
# 为本地开发创建 .env (位于 backend/ 目录)
cat > .env << 'EOF'
DATABASE_URL=postgresql+asyncpg://xpose:xpose_secret@localhost:5432/xpose
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=dev-secret-key-change-in-production
FRONTEND_URL=http://localhost:3000
EOF
# 应用 GHunt 补丁 (如果已安装 ghunt)
python patches/ghunt_auth_patch.py
# 启动带热重载的 API server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
后端将在首次启动时自动创建所有数据库表。
#### 步骤 4：启动 Celery Workers
打开一个新终端：
```
cd backend
source venv/bin/activate
# 启动具有 4 个并发线程的 worker
celery -A app.workers.celery_app worker --loglevel=info --concurrency=4
```
打开另一个终端用于调度器：
```
cd backend
source venv/bin/activate
# 启动 beat 调度器 (每日 token 重置)
celery -A app.workers.celery_app beat --loglevel=info
```
#### 步骤 5：安装 OSINT 工具（用于 workers）
```
# Python tools (已在 requirements.txt 中)
pip install holehe maigret h8mail sherlock-project gpsoauth
# Go tool (Mosint)
go install github.com/alpkeskin/mosint/v3/cmd/mosint@latest
# Blackbird (克隆)
git clone https://github.com/p1ngul1n0/blackbird.git /opt/blackbird
```
#### 步骤 6：设置前端
打开一个新终端：
```
cd frontend
# 安装依赖
npm install
# 启动带热重载的开发服务器
npm start
```
前端将位于 http://localhost:3000 并将 API 请求代理到后端。
#### 步骤 7：验证一切正常
```
# 检查 backend
curl http://localhost:8000/api/health
# 检查 frontend
curl -s http://localhost:3000 | head -5
# 检查 Celery worker
celery -A app.workers.celery_app inspect ping
```
## 配置
### 环境变量参考
#### 必需
| 变量 | 描述 | 示例 |
|----------|-------------|---------|
| `SECRET_KEY` | JWT 签名密钥。必须是随机的，最少 32 个字符。 | `a1b2c3d4...` (64 个十六进制字符) |
| `DB_PASSWORD` | PostgreSQL 密码 | `strong-password-here` |
| `DATABASE_URL` | 完整的异步数据库连接字符串 | `postgresql+asyncpg://pose:pass@postgres:5432/xpose` |
| `REDIS_URL` | Redis 连接字符串 | `redis://redis:6379/0` |
#### 认证
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `JWT_ALGORITHM` | Token 签名算法 | `HS256` |
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | 访问 token 有效期 | `60` |
| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | 刷新 token 有效期 | `30` |
| `GOOGLE_CLIENT_ID` | Google OAuth 2.0 客户端 ID | (空) |
| `GOOGLE_CLIENT_SECRET` | Google OAuth 2.0 客户端密钥 | (空) |
| `GITHUB_CLIENT_ID` | GitHub OAuth 应用客户端 ID | (空) |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth 应用客户端密钥 | (空) |
#### 外部 API 密钥
| 变量 | 描述 | 是否必需？ |
|----------|-------------|-----------|
| `HIBP_API_KEY` | Have I Been Pwned API 密钥 ($3.50/月) | 可选 —— 没有它 HIBP 工具将跳过 |
| `HUNTER_API_KEY` | Hunter.io 电子邮件验证 | 可选 |
| `INTELX_API_KEY` | Intelligence X 搜索 API | 可选 |
| `GHUNT_MASTER_TOKEN` | 用于 GHunt 的 Google 主身份验证 token | 可选 —— 没有它 GHunt 将无法运行 |
#### 应用程序设置
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `APP_NAME` | 应用程序显示名称 | `Xpose` |
| `DEBUG` | 启用调试模式 | `False` |
| `FRONTEND_URL` | 前端来源，用于 CORS | `http://localhost:3000` |
| `FREE_DAILY_TOKENS` | 每日授予免费用户的 token | `5` |
| `PRO_MONTHLY_TOKENS` | Pro 计划的每月 token | `100` |
| `ENTERPRISE_MONTHLY_TOKENS` | Enterprise 计划的每月 token | `500` |
## 使用
### 运行扫描
1. 在 http://localhost:3000 **注册/登录**
2. 在仪表板的扫描输入框中**输入目标电子邮件**
3. **点击 "Start Scan"** — 这会消耗 1 个 token
4. **观看实时进度** — 每个工具通过 WebSocket 报告状态
5. **查看结果** — 查看确认的账户、泄露、工具详情
6. **导出** — 下载为 JSON、HTML 或 PDF（Pro+ 计划）
### 使用 API
```
# 1. 注册
curl -X POST http://localhost:8000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "securepass123"}'
# 响应: {"access_token": "eyJ...", "refresh_token": "eyJ...", "token_type": "bearer"}
# 2. 开始扫描
curl -X POST http://localhost:8000/api/scans \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target_email": "target@example.com"}'
# 响应: {"id": "uuid", "status": "pending", "progress": 0, ...}
# 3. 检查扫描状态
curl http://localhost:8000/api/scans/SCAN_ID \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# 4. 导出结果
curl http://localhost:8000/api/scans/SCAN_ID/export/json \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## 安全与认证
### 两步验证 (2FA)
Xpose 支持基于 TOTP 的两步验证，兼容任何身份验证器应用（Google Authenticator, Authy, 1Password 等）。
**设置流程：**
1. 导航至 **Settings → Two-Factor Authentication**
2. 点击 **Enable 2FA** — 显示二维码和手动密钥
3. 使用您的身份验证器应用扫描二维码
4. 输入 6 位代码进行验证和激活
**使用 2FA 登录：**
1. 像往常一样输入电子邮件和密码
2. 如果启用了 2FA，系统将提示您输入 6 位 TOTP 代码
3. 输入来自身份验证器应用的代码以完成登录
**禁用 2FA：**
- 前往 Settings → Two-Factor Authentication → Disable
- 输入当前的 TOTP 代码以确认
### 单点登录 (SSO)
Xpose 支持使用 Google 和 GitHub 进行 OAuth 2.0 登录。在 `.env` 中或通过交互式安装程序配置您的 OAuth 凭证。
**Google OAuth 设置：**
1. 前往 [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. 创建一个 OAuth 2.0 客户端 ID（Web 应用程序）
3. 将授权重定向 URI 设置为 `http://your-domain/api/auth/sso/google/callback`
4. 将 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET` 添加到 `.env`
**GitHub OAuth 设置：**
1. 前往 [GitHub Developer Settings](https://github.com/settings/developers)
2. 创建一个新的 OAuth App
3. 将授权回调 URL 设置为 `http://your-domain/api/auth/sso/github/callback`
4. 将 `GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET` 添加到 `.env`
SSO 用户在首次登录时自动创建。他们可以稍后选择设置密码，以启用除 SSO 之外的本地登录。
## 扫描工作流
```
User submits email
│
▼
┌─────────────────┐
│ Validate input │──→ Check token balance ──→ 402 if insufficient
│ Deduct 1 token │──→ Check concurrent limit ──→ 429 if exceeded
└────────┬────────┘
│
▼
┌─────────────────┐
│ Create scan │ status: "pending"
│ Create 8 result │ one per tool, all status: "pending"
│ entries │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Dispatch to │ Celery: run_full_scan.delay(scan_id, email, username)
│ task queue │
└────────┬────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PARALLEL TOOL EXECUTION │
│ │
│ Email-based: Username-based: │
│ ├── GHunt (Google) ├── Maigret (2600+ sites) │
│ ├── Holehe (120+) ├── Sherlock (300+ sites) │
│ ├── h8mail (breaches) └── Blackbird (username mode) │
│ ├── Mosint (multi) │
│ ├── Blackbird (email) │
│ └── HIBP (API) │
│ │
│ Each tool: │
│ 1. Sets status → "running" │
│ 2. Executes tool (library call or subprocess) │
│ 3. Normalizes output to {platform, url, exists} │
│ 4. Saves results + metadata to scan_results │
│ 5. Sets status → "completed" or "error" │
│ 6. Updates scan progress (N/8 × 100%) │
└────────────────────────┬────────────────────────────────┘
│
▼ (when progress reaches 100%)
┌─────────────────────────────────────────────────────────┐
│ DEDUPLICATION & SCORING │
│ │
│ 1. Gather all accounts_found from completed tools │
│ 2. Group by platform name (case-insensitive) │
│ 3. Merge URLs and metadata across sources │
│ 4. Score confidence: │
│ └── 2+ tools found it → HIGH │
│ └── 1 tool found it → MEDIUM │
│ └── Uncertain match → LOW │
│ 5. Insert into accounts table │
└────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────┐
│ Scan complete │ status: "completed", progress: 100
│ completed_at │ set to current timestamp
└─────────────────┘
```
## API 参考
### 认证
| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| `POST` | `/api/auth/register` | 注册新账户 | 否 |
| `POST` | `/api/auth/login` | 使用邮箱/密码登录（+ 可选 TOTP 代码） | 否 |
| `POST` | `/api/auth/refresh` | 刷新访问 token | 否 |
| `GET` | `/api/auth/me` | 获取当前用户资料 | 是 |
| `POST` | `/api/auth/logout` | 登出 | 是 |
| `POST` | `/api/auth/2fa/setup` | 生成 TOTP 密钥 + 二维码 | 是 |
| `POST` | `/api/auth/2fa/verify` | 验证代码并启用 2FA | 是 |
| `POST` | `/api/auth/2fa/disable` | 禁用 2FA（需要当前代码） | 是 |
| `GET` | `/api/auth/sso/google` | 重定向到 Google OAuth | 否 |
| `GET` | `/api/auth/sso/google/callback` | Google OAuth 回调 | 否 |
| `GET` | `/api/auth/sso/github` | 重定向到 GitHub OAuth | 否 |
| `GET` | `/api/auth/sso/github/callback` | GitHub OAuth 回调 | 否 |
### 扫描
| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| `POST` | `/api/scans` | 创建新扫描（消耗 1 个 token） | 是 |
| `GET` | `/api/scans` | 列出用户的扫描（分页） | 是 |
| `GET` | `/api/scans/:id` | 获取扫描结果 + 账户 | 是 |
| `DELETE` | `/api/scans/:id` | 删除扫描 | 是 |
| `GET` | `/api/scans/:id/export/:format` | 导出 | 是 |
| `WS` | `/api/scans/:id/live` | 用于实时进度的 WebSocket | 否 |
### Token
| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| `GET` | `/api/tokens/balance` | 获取 token 余额 + 计划信息 | 是 |
| `GET` | `/api/tokens/history` | 获取 token 交易历史 | 是 |
### 管理员（需要 `role: admin`）
| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| `GET` | `/api/admin/stats` | 系统范围统计（每日/每周/每月） | Admin |
| `GET` | `/api/admin/users` | 列出用户（搜索，按计划/角色筛选，分页） | Admin |
| `GET` | `/api/admin/users/:id` | 详细用户信息及扫描 + 交易 | Admin |
| `PATCH` | `/api/admin/users/:id` | 更新用户姓名/角色/计划/token | Admin |
| `DELETE` | `/api/admin/users/:id` | 删除用户 | Admin |
| `GET` | `/api/admin/scans` | 列出所有扫描（搜索，按状态筛选） | Admin |
| `POST` | `/api/admin/tokens/grant` | 向用户授予 token | Admin |
| `GET` | `/api/admin/tokens/history` | 全局 token 交易历史 | Admin |
| `GET` | `/api/admin/db/stats` | 数据库统计（大小，连接数，表） | Admin |
| `GET` | `/api/admin/workers/health` | Worker 健康状况，活动任务，已注册任务 | Admin |
### API 密钥（Pro+ 计划）
| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| `POST` | `/api/keys` | 创建新 API 密钥 | 是 |
| `GET` | `/api/keys` | 列出用户的 API 密钥 | 是 |
| `DELETE` | `/api/keys/:id` | 删除 API 密钥 | 是 |
## 前端页面
| 页面 | 路由 | 访问权限 | 描述 |
|------|-------|--------|-------------|
| **Landing** | `/` | 公开 | 带有扫描 CTA、8 工具功能网格、定价卡片、页脚 |
| **Login** | `/login` | 公开 | 邮箱/密码表单及注册切换，Google/GitHub SSO 按钮，TOTP 2FA 代码输入 |
| **Dashboard** | `/dashboard` | 需认证 | 快速扫描输入（邮箱 + 用户名），token 计数器，活动图表，最近扫描列表 |
| **Scan Results** | `/scan/:id` | 需认证 | 选项卡式界面（Overview/Accounts/Tools/Timeline），实时进度，平台卡片，导出按钮 |
| **Admin** | `/admin` | Admin | 5 标签仪表板：概览统计，用户管理（搜索/筛选/编辑/删除），扫描，数据库统计，Worker 监控 |
| **Settings** | `/settings` | 需认证 | 个人资料信息，2FA 设置/禁用及二维码，计划管理，API 密钥 CRUD (Pro+)，危险区域 |
### UI 组件
| 组件 | 描述 |
|-----------|-------------|
| `Navbar` | 顶部导航栏，带有 logo，dashboard/admin 链接，token 计数器，用户下拉菜单 |
| `ScanProgress` | 总体进度条 + 每个工具的状态卡片，带有微调器/勾选/错误图标 |
| `ToolResultCard` | 每个工具的可展开卡片，显示发现的账户、元数据、执行时间 |
| `AccountTable` | 可排序的去重账户表格，带有置信度徽章和来源归属 |
| `TokenCounter` | 动画 token 余额，带有计划徽章和进度环 |
| `StatsCard` | 可重用的指标卡片，带有图标、数值、标签和趋势指示器 |
| `ScanTimeline` | 垂直扫描执行时间轴，带有工具状态图标和时间 |
| `PlatformCard` | 丰富的账户卡片，带有类别检测、置信度徽章和元数据 |
### 设计系统
- **背景**: 深黑色 `#0a0a0f` 带有微妙的径向渐变覆盖
- **强调色**: 霓虹绿 `#00ff88` 用于主要操作、边框和高光
- **次要色**: 霓虹蓝 `#00d4ff` 用于链接和次要元素
- **排版**: JetBrains Mono 用于数据/代码，Inter 用于 UI 文本
- **卡片**: 玻璃态，带有 `backdrop-blur-xl` 和半透明背景
- **动画**: Framer Motion 用于页面过渡、交错显示、展开/折叠
## Token 与定价模型
| 功能 | Free | Pro ($19/月) | Enterprise ($99/月) |
|---------|------|-------------|---------------------|
| **Token** | 每天 5 个（UTC 午夜自动重置） | 每月 100 个 | 每月 500 个 |
| **并发扫描** | 1 | 3 | 10 |
| **每次扫描工具数** | 全部 8 个 | 全部 8 个 | 全部 8 个 |
| **结果存储** | 7 天 | 永久 | 永久 |
| **导出格式** | 无 | JSON, HTML, PDF | JSON, HTML, PDF |
| **API 访问** | 否 | 是 (REST) | 是 (REST) |
| **Webhooks** | 否 | 否 | 是 |
### Token 机制
- **1 次扫描 = 1 个 token**，无论运行多少个工具
- 免费层通过 Celery Beat 计划任务在 UTC 午夜每日重置
- Token 交易记录在案以供审计（`token_transactions` 表）
- 管理员可以通过管理仪表板向任何用户授予 token
## GHunt 补丁
### 背景
GHunt 的 `android_master_auth()` 函数对**全球所有人**都已失效。Google 的 DroidGuard 认证拒绝了 GHunt 发送到 `android.googleapis.com/auth` 的原始 POST 请求。
### 修复方案
位于 `backend/patches/ghunt_auth_patch.py`，该补丁用 `gpsoauth.exchange_token()` 替失效的身份验证，后者能正确处理 DroidGuard 认证。
**补丁的作用：**
1. 定位 GHunt 安装 (`ghunt/helpers/auth.py`)
2. 检查是否已打补丁（幂等）
3. 将 `android_master_auth()` 函数替换为：
```
async def android_master_auth(as_client, oauth_token):
import gpsoauth
from uuid import getnode as getmac
android_id = hex(getmac())[2:]
resp = gpsoauth.exchange_token(
email=None,
token=oauth_token,
android_id=android_id
)
for keyword in ["Token", "Email", "services", "firstName", "lastName"]:
if keyword not in resp:
raise GHuntAndroidMasterAuthError(...)
return resp["Token"], resp["services"].split(","), resp["Email"], \
f'{resp["firstName"]} {resp["lastName"]}'
```
**关键依赖:** `pip install gpsoauth`
该补丁在 Docker 镜像构建期间自动应用。对于本地开发，请手动运行：
```
python backend/patches/ghunt_auth_patch.py
```
## 项目结构
```
Xpose/
├── install.sh # Interactive installer with terminal UI
├── setup # Shortcut → install.sh
├── docker-compose.yml # All services: frontend, backend, worker, postgres, redis
├── .env.example # Environment variable template
├── .gitignore
├── README.md # This file
├── docs/
│ ├── ARCHITECTURE.md # Deep-dive architecture documentation
│ └── API.md # Complete API reference with examples
│
├── backend/
│ ├── Dockerfile # Python 3.11 + Go + OSINT tools
│ ├── requirements.txt # Python dependencies
│ ├── alembic.ini # Alembic migration configuration
│ ├── alembic/
│ │ ├── env.py # Migration environment (imports all models)
│ │ ├── script.py.mako # Migration template
│ │ └── versions/ # Migration scripts
│ │ └── 001_add_totp_2fa_columns.py
│ ├── patches/
│ │ └── ghunt_auth_patch.py # GHunt DroidGuard attestation bypass
│ └── app/
│ ├── main.py # FastAPI app entry point, CORS, route registration
│ ├── core/
│ │ ├── config.py # Settings from env vars (Pydantic BaseSettings)
│ │ ├── database.py # Async SQLAlchemy engine + session factory
│ │ └── security.py # JWT create/decode, bcrypt hash/verify
│ ├── models/
│ │ ├── user.py # User model (auth, plan, tokens)
│ │ ├── scan.py # Scan, ScanResult, Account models
│ │ └── token.py # TokenTransaction, ApiKey models
│ ├── schemas/
│ │ ├── auth.py # Register/Login/2FA request, Token/User response
│ │ ├── scan.py # CreateScan request, Scan/Result/Account response
│ │ └── admin.py # AdminStats, UpdateUser, GrantTokens, DBStats
│ ├── api/
│ │ ├── deps.py # get_current_user, require_admin dependencies
│ │ ├── auth.py # /api/auth/* routes (login, register, 2FA, SSO)
│ │ ├── scans.py # /api/scans/* routes + export
│ │ ├── tokens.py # /api/tokens/* routes
│ │ ├── admin.py # /api/admin/* routes (stats, users, DB, workers)
│ │ ├── keys.py # /api/keys/* routes
│ │ └── websocket.py # WebSocket /api/scans/:id/live
│ ├── services/ # Business logic (extensible)
│ └── workers/
│ ├── __init__.py # Celery app config, beat schedule
│ ├── orchestrator.py # run_full_scan, deduplicate_accounts
│ ├── tools.py # 8 individual tool tasks
│ ├── helpers.py # DB helpers (sync), progress tracking
│ └── token_reset.py # Daily free tier token reset
│
└── frontend/
├── Dockerfile # Node 20 build → Nginx serve
├── nginx.conf # Reverse proxy + WebSocket upgrade
├── package.json
├── tailwind.config.js # Custom colors, fonts, animations
├── postcss.config.js
├── public/
│ └── index.html # HTML shell with Google Fonts
└── src/
├── index.js # React entry point
├── App.jsx # Router: public, private, admin routes
├── styles/
│ └── index.css # Tailwind layers + custom components
├── services/
│ └── api.js # Axios client + interceptors
├── hooks/
│ ├── useAuth.js # Auth context (user, login, register, logout)
│ └── useScanSocket.js # WebSocket hook for live scan progress
├── components/
│ ├── Navbar.jsx # Top navigation bar
│ ├── ScanProgress.jsx # Real-time scan progress display
│ ├── ToolResultCard.jsx # Expandable tool result card
│ ├── AccountTable.jsx # Sortable discovered accounts table
│ ├── TokenCounter.jsx # Animated token balance display
│ ├── StatsCard.jsx # Dashboard metric card
│ ├── ScanTimeline.jsx # Vertical timeline of scan execution
│ └── PlatformCard.jsx # Rich account card with category detection
└── pages/
├── Landing.jsx # Public landing page
├── Login.jsx # Auth (login/register + SSO)
├── Dashboard.jsx # User dashboard
├── ScanResults.jsx # Scan results report
├── Admin.jsx # Admin dashboard
└── Settings.jsx # User settings
```
## 数据库 Schema
```
┌──────────────────┐ ┌──────────────────┐
│ users │ │ scans │
├──────────────────┤ ├──────────────────┤
│ id (UUID, PK) │──┐ │ id (UUID, PK) │
│ email │ │ │ user_id (FK) │──→ users.id
│ password_hash │ │ │ target_email │
│ name │ │ │ target_username │
│ avatar_url │ │ │ status │
│ provider │ │ │ progress (0-100) │
│ provider_id │ │ │ tokens_cost │
│ totp_secret │ │ │ started_at │
│ totp_enabled │ │ │ completed_at │
│ role │ │ │ created_at │
│ plan │ │ └────────┬─────────┘
│ tokens_balance │ │ │
│ tokens_last_reset│ │ │ 1:N
│ created_at │ │
│ updated_at │ │
└──────────────────┘ │ ┌────────▼─────────┐ ┌──────────────────┐
│ │ scan_results │ │ accounts │
│ ├──────────────────┤ ├──────────────────┤
│ │ id (UUID, PK) │ │ id (UUID, PK) │
│ │ scan_id (FK) │ │ scan_id (FK) │──→ scans.id
│ │ tool_name │ │ platform │
│ │ status │ │ url │
│ │ raw_output (JSON)│ │ username │
│ │ accounts_found │ │ exists │
│ │ metadata (JSON) │ │ confidence │
│ │ execution_time_ms│ │ sources (array) │
│ │ error_message │ │ metadata (JSON) │
│ │ created_at │ │ created_at │
│ └──────────────────┘ └──────────────────┘
│
│ ┌──────────────────┐ ┌──────────────────┐
│ │token_transactions│ │ api_keys │
│ ├──────────────────┤ ├──────────────────┤
└──→ │ id (UUID, PK) │ │ id (UUID, PK) │
│ user_id (FK) │ │ user_id (FK) │──→ users.id
│ amount (+/-) │ │ key_hash │
│ reason │ │ name │
│ scan_id (FK) │ │ last_used_at │
│ created_at │ │ created_at │
└──────────────────┘ └──────────────────┘
```
## 故障排除
### 快速诊断
```
# 快速检查服务健康状态
./install.sh --status
# 如果部署失败，查看安装日志
cat .install.log
# 完全卸载并全新重装
./install.sh --uninstall
./setup
```
### 服务无法启动
```
# 查看特定服务的日志
docker compose logs backend
docker compose logs worker
# 从头构建
docker compose down -v
docker compose up -d --build
# 或者使用安装程序进行全新部署
./install.sh --uninstall
./setup
```
### 数据库连接错误
```
# 验证 PostgreSQL 健康状态
docker compose exec postgres pg_isready -U xpose
# 检查 .env 中的 DATABASE_URL 是否与 postgres 服务配置匹配
# Docker: postgresql+asyncpg://xpose:PASSWORD@postgres:5432/xpose
# 本地: postgresql+asyncpg://xpose:PASSWORD@localhost:5432/xpose
```
### 数据库迁移（现有安装）
如果您正在升级现有的 Xpose 安装，请运行 Alembic 迁移以添加新的 2FA 列：
```
# 通过 Docker
docker compose exec backend alembic upgrade head
# 本地开发
cd backend
alembic upgrade head
```
### Worker 未处理扫描
```
# 检查 worker 日志
docker compose logs worker
# 验证 Redis 正在运行
docker compose exec redis redis-cli ping
# 预期: PONG
# 检查 Celery worker 状态
docker compose exec worker celery -A app.workers.celery_app inspect ping
```
### 扫描卡在 "pending"
1. 检查 worker 是否正在运行: `docker compose ps worker`
2. 检查 Redis 连接: `docker compose exec redis redis-cli ping`
3. 检查 worker 日志是否有错误: `docker compose logs worker --tail=50`
4. 重启 worker: `docker compose restart worker`
### GHunt 不工作
1. 确保在 `.env` 中设置了 `GHUNT_MASTER_TOKEN`
2. 验证补丁是否已应用: `docker compose exec worker python -c "import ghunt; print('OK')"`
3. GHunt 需要有效的 Google 会话 token —— 这些会定期过期
### 前端显示空白页
```
# 检查 frontend 构建
docker compose logs frontend
# 重新构建 frontend
docker compose build frontend
docker compose up -d frontend
```
### 端口冲突
如果端口 3000、8000、5432 或 6379 被占用：
```
# 查找占用端口的进程
lsof -i :3000
# 交互式安装程序允许您选择自定义端口:
./setup
# → 当提示输入 "Frontend port" 时，输入一个可用端口 (例如, 3001)
# → 当提示输入 "Backend port" 时，输入一个可用端口 (例如, 8001)
```
对于手动设置，更改 `docker-compose.yml` 中的端口：
```
# 例如, "3001:80" 而不是 "3000:80"
```
### 安装日志
交互式安装程序将所有 Docker 输出记录到 `.install.log`。如果构建失败：
```
# 查看完整日志
cat .install.log
# 仅查看最后的错误
tail -50 .install.log
```
标签：2FA, CTF工具, DInvoke, Docker, ESC4, Flask, OSINT, Python, React, SaaS, SSO, Syscalls, 威胁情报, 安全防御评估, 开发者工具, 开源网络情报, 情报分析, 情报搜集, 搜索引擎查询, 数据去重, 无后门, 测试用例, 漏洞搜索, 用户名追踪, 用户画像, 网络安全, 网络探针, 网络诊断, 网络调查, 聚合平台, 自动化侦查, 自定义脚本, 请求拦截, 逆向工具, 邮箱侦查, 隐私保护