ankitrmishra01/OpenTrace

# 🔐 OpenTrace — AI 驱动的网络风险分析器     # 🔐 OpenTrace — AI 驱动的网络风险分析器 (简短描述) ## 📸 截图 ### 认证门户  ### 网络指挥中心  ### 情报扫描与风险分析  ## 💻 技术栈 | 层级 | 技术 | 用途 | | -------------- | ----------------------- | ---------------------------------------- | | **Frontend** | React 18 + Vite | 具有快速构建时间的现代 SPA | | **UI** | CSS3 (Cyberpunk theme) | 霓虹灯效果、故障文本、玻璃拟态 | | **API Client** | Axios | 带有自动 token 注入的 HTTP 请求 | | **Backend** | Node.js + Express | 可扩展的 REST API | | **Database** | MongoDB Atlas | 云端文档存储 | | **Auth** | JWT + bcrypt | 安全的身份验证与密码哈希 | | **OAuth** | Google Sign-In | 第三方身份验证 | | **AI** | Groq API (Mixtral 8x7b) | 用于风险分析的快速 LLM 推理 | | **Deployment** | Vercel + Render | 生产级托管 | ## 🚀 快速开始（5 分钟） ### 前置条件 - Node.js 18+ - MongoDB Atlas 账户（免费版即可） - Groq API 密钥（提供免费额度） - Google OAuth 凭证（可选，用于 Google 登录） ### 1. 克隆与安装 ``` cd OpenTrace npm run install:all ``` ### 2. 配置环境 **Backend** — `server/.env` ``` PORT=5000 MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/opentrace?retryWrites=true&w=majority JWT_SECRET=your_super_secret_jwt_key_here_change_in_production CLIENT_URL=http://localhost:5173 GROQ_API_KEY=gsk_xxxxx GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=xxxxx ``` **Frontend** — `frontend/.env` ``` VITE_API_URL=http://localhost:5000/api VITE_GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com ``` ### 3. 运行开发环境 ``` npm run dev ``` **Frontend**: http://localhost:5173 **Backend API**: http://localhost:5000 **Health Check**: http://localhost:5000/health ## 🔧 设置指南 ### MongoDB Atlas 设置（2 分钟） 1. 访问 https://www.mongodb.com/cloud/atlas 2. 创建免费集群 3. 添加 IP 到白名单（开发环境使用 0.0.0.0/0） 4. 创建数据库用户 5. 将连接字符串复制到 `server/.env` 中 ### Groq API 设置（1 分钟） 1. 访问 https://console.groq.com 2. 创建免费账户并获取 API 密钥 3. 作为 `GROQ_API_KEY` 添加到 `server/.env` 4. 免费额度包含每分钟 30 次请求（足以用于演示） ### Google OAuth 设置（可选，5 分钟） 1. 访问 https://console.cloud.google.com 2. 创建新项目 3. 启用 Google+ API 4. 创建 OAuth 2.0 凭证（Web 应用） 5. 添加授权的重定向 URI： - `http://localhost:5173` - `http://localhost:5000/api/auth/google/callback` 6. 将 Client ID 和 Secret 复制到 `.env` 文件中 ## 🏗️ 系统架构 ``` graph TD A[User Browser] --> B[React + Vite Frontend] B --> C[Express Backend API] C --> D[(MongoDB Atlas)] C --> E[Groq AI API] C --> F[Google OAuth] C --> G[GitHub API] C --> H[Reddit API] C --> I[Gravatar API] B --> J[Vercel Hosting] C --> K[Render Hosting] ``` ## 📁 项目结构 ``` opentrace/ ├── frontend/ # React + Vite │ ├── src/ │ │ ├── App.jsx # Main component (40KB - all-in-one) │ │ ├── main.jsx # Entry point with GoogleOAuthProvider │ │ ├── services/ │ │ │ └── api.js # Axios API client with interceptors │ │ └── assets/ │ ├── index.html │ ├── vite.config.js │ ├── package.json │ └── .env.example │ ├── server/ # Node.js + Express │ ├── models/ │ │ ├── User.js # User schema (JWT + Google OAuth) │ │ └── ScanResult.js # Scan data persistence │ ├── routes/ │ │ ├── auth.js # /auth endpoints │ │ └── scan.js # /scan endpoints │ ├── controllers/ │ │ ├── authController.js # Auth logic (register/login/google) │ │ └── scanController.js # Scan logic (start/analyze/history) │ ├── services/ │ │ ├── platformService.js # GitHub, Reddit, Gravatar API calls │ │ └── anthropicService.js # Anthropic AI integration │ ├── middleware/ │ │ ├── auth.js # JWT verification │ │ └── rateLimit.js # Rate limiting │ ├── utils/ │ │ ├── generateToken.js # JWT token generation │ │ └── riskScorer.js # Risk calculation algorithm │ ├── config/ │ │ └── db.js # MongoDB connection │ ├── server.js # Express app setup │ ├── package.json │ └── .env.example │ ├── package.json # Root scripts └── README.md ``` ## 🔐 认证流程 ### 本地注册/登录 ``` User Input → /auth/register or /auth/login ↓ Password hashed with bcrypt ↓ User stored in MongoDB ↓ JWT token generated (7-day expiry) ↓ Token stored in localStorage ↓ Subsequent requests include: Authorization: Bearer {token} ``` ### Google OAuth ``` Google Login Button → GoogleOAuthProvider wrapper ↓ Google authentication ↓ Credential token → /auth/google endpoint ↓ Token decoded, googleId extracted ↓ User created or linked in MongoDB ↓ JWT token issued ↓ Redirected to Dashboard ``` ## 🔍 API Endpoints ### 认证 ``` POST /api/auth/register Body: { email, password, name } Returns: { token, user } POST /api/auth/login Body: { email, password } Returns: { token, user } POST /api/auth/google Body: { googleId, email, name, picture } Returns: { token, user } GET /api/auth/user (Protected) Headers: Authorization: Bearer {token} Returns: { user } ``` ### 扫描 ``` POST /api/scan/start (Protected) Body: { username } Returns: { scan: { id, username, results, riskScore, platformsFound } } POST /api/scan/analyze (Protected) Body: { scanId } Returns: { analysis } GET /api/scan/history (Protected) Returns: { scans: [{id, username, riskScore, platformsFound, date}] } GET /api/scan/:scanId (Protected) Returns: { scan } ``` ## 🎯 已实现的功能 ✅ **用户认证** - 使用 bcrypt 哈希的电子邮件/密码注册 - 基于JWT 的登录（token 有效期为 7 天） - Google OAuth 集成 - 在 localStorage 中安全存储 token ✅ **平台扫描** - GitHub API（实时用户查找） - Reddit API（用于演示的模拟） - Gravatar MD5 哈希 - 头像获取与显示 ✅ **风险分析** - 可配置的风险评分算法 - 基于平台的权重计算 - 曝光率计算 - 实时分数生成 ✅ **AI 建议** - 集成 Groq API（闪电般的 LLM 推理） - 基于扫描结果的动态 prompt 生成 - 实时风险分析与建议 - Markdown 格式的输出 - API 不可用时的备用分析 ✅ **数据持久化** - 使用 MongoDB 存储用户 - 带有时间戳的扫描历史 - AI 分析缓存 - 用户仪表板 ✅ **UI/UX** - 带有霓虹灯效果的赛博朋克设计 - 故障文本动画 - Matrix 代码雨背景 - 玻璃拟态卡片 - 响应式布局 - 实时扫描动画 ## 🧪 端到端测试 ### 1. 注册新账户 ``` Go to http://localhost:5173 Click "ENTER SYSTEM" → "REGISTER" Fill in name, email, password Submit → Should redirect to Dashboard ``` ### 2. Google 登录（如果已配置） ``` On Auth page, click "SIGN IN WITH GOOGLE" Complete Google authentication Should redirect to Dashboard with user profile ``` ### 3. 运行用户名扫描 ``` Go to Dashboard → "INITIATE SCAN" Enter username (e.g., "github-username") Click "SCAN TARGET" Wait for GitHub/Reddit/Gravatar checks View results, risk score, and AI analysis ``` ### 4. 查看扫描历史 ``` Return to Dashboard Scroll down to "SCAN HISTORY LOG" Should show all previous scans with risk scores ``` ### 5. 验证数据库 ``` MongoDB Atlas → Collections opentrace database should have: - users collection (with your account) - scanresults collection (with scan history) ``` ## 🚢 部署指南 ### 在线演示 - **Frontend**: https://open-trace-six.vercel.app - **状态**: ✅ 生产环境就绪 ### Frontend 部署 (Vercel) #### 选项 1：自动部署（推荐） 1. 推送至 GitHub 2. 每次推送时 Vercel 都会自动部署 3. 完成！（部署时间 1-2 分钟） #### 选项 2：手动部署 ``` cd frontend vercel --prod ``` **Vercel Dashboard 中的环境变量：** - `VITE_API_URL` = Backend API URL（例如：https://opentrace-backend.onrender.com/api） - `VITE_GOOGLE_CLIENT_ID` = 你的 Google OAuth Client ID **Google Cloud Console 中的授权来源：** - `https://open-trace-six.vercel.app` - `http://localhost:5173`（用于本地开发） ### Backend 部署 (Render) 1. **创建 Render Web Service**： - 访问 https://render.com - New → Web Service - 连接 GitHub 仓库 2. **配置服务**： - Name: `opentrace-api` - Root Directory: `server/` - Runtime: Node - Build Command: `npm install` - Start Command: `npm start` - Plan: Free 或 Paid 3. **添加环境变量**： PORT=3000 MONGODB_URI=mongodb+srv://... JWT_SECRET=your_strong_secret_key GROQ_API_KEY=gsk_xxxxx CLIENT_URL=https://open-trace-six.vercel.app GOOGLE_CLIENT_ID=xxxxx GOOGLE_CLIENT_SECRET=xxxxx 4. **部署**：点击 "Deploy" 并等待 2-5 分钟 ### 部署故障排除 **Frontend 部署失败：** - 检查 `VITE_API_URL` 是否可访问 - 在 Vercel dashboard 中验证 `.env` 变量 - 检查构建日志：Vercel Dashboard → Deployments **Backend 部署失败：** - 确保 `server/` 目录中包含 package.json - 检查 MONGODB_URI 是否有效 - 验证所有必需的环境变量是否已在 Render 中设置 **Google OAuth 在生产环境中不起作用：** - 确保 Google Console 中包含 `https://open-trace-six.vercel.app` - 验证 `VITE_GOOGLE_CLIENT_ID` 与 frontend 匹配 - 检查 backend 中的 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET` ## ⚠️ 安全提示 - **切勿提交 `.env` 文件** — 请使用 `.env.example` - **在生产环境中更改 JWT_SECRET** — 使用强随机字符串 - 在生产环境中**仅使用 HTTPS** - 适当**设置 MongoDB IP 白名单** - 在认证 endpoint 上**启用速率限制**（15 分钟内 5 次尝试） - 使用 bcrypt 对**密码进行哈希处理**（10 次加盐轮次） - **Google OAuth** 需要安全的 callback URL ## 🎯 OpenTrace 与简单的用户名检查器的区别 简单的 OSINT 检查器只是查询数百个站点上字符串的存在情况。OpenTrace 提供了结构化的数字足迹感知能力： 1. **确定性的、可解释的风险模型**：完全消除了 `Math.random()`。以透明的细分方式评估跨平台关联性、PII 披露和足迹深度。 2. **身份关联置信度评分**：使用交叉链接的 handle、个人简介关联以及头像 pHash 匹配，区分属于不同个体的相同用户名与已确认的单一身份。 3. **统一身份合成**：将姓名、位置、社交链接和个人简介合成为一张高等级的身份卡片，标记用户最早的在线足迹。 4. **曝光变化监控**：将新的扫描结果与历史基线扫描进行 diff，以揭示随时间推移新创建的账户或停用情况。 5. **可操作的补救措施**：将检测到的曝光字段直接连接到确切的隐私设置深层链接（例如 GitHub 电子邮件隐私、Reddit 隐私设置）。 ## ⚠️ 已知限制与设计决策 - **LinkedIn 抓取**：放弃了自动抓取，因为 LinkedIn 会主动阻止未经身份验证的请求，且抓取违反了 ToS。替换为静态手动检查链接。 - **Twitter/X 与 Instagram**：由于反抓取措施会返回通用的备用页面，自动化的 HTML 解析已被弃用。已标记为需要手动验证。 - **感知图像哈希**：图像 pHash 在可用时利用 `sharp`；如果在 serverless 免费层级上受限于原生二进制文件，则会优雅地降级回 URL 匹配。 - **仅限自我的道德安全**：违规检查被严格限定在 `req.user.email` 范围内，以防被滥用为开放式侦察工具。密码在本地使用 K-Anonymity SHA-1 前缀进行测试（`api.pwnedpasswords.com/range/{first5}`）。 ## 📋 免责声明 OpenTrace 仅用于**教育和网络安全意识提升目的**。 它仅使用公共 API，不参与任何非法监视、抓取或数据收集行为。 请始终尊重平台的服务条款和隐私法律。 ## 🔧 故障排除 ### "无法找到模块 'mongoose'" ``` cd server && npm install ``` ### "MongoDB 连接失败" - 检查 `server/.env` 中的连接字符串 - 验证 MongoDB Atlas 中的 IP 白名单 - 确保数据库凭证正确 ### "Google OAuth 无法正常工作" - 验证 `VITE_GOOGLE_CLIENT_ID` 与配置匹配 - 检查 Google Cloud Console 中的已授权 JavaScript 来源 - origin URL 中**不要带末尾斜杠**：应为 `https://domain.com` 而非 `https://domain.com/` - 确保已加载 `.env` 文件（重启开发服务器） - 检查浏览器弹窗拦截设置（Chrome/Firefox） - 测试前清除浏览器缓存和 cookie ### "弹窗被浏览器拦截" - 这是浏览器的安全机制，不是代码问题 - Chrome：点击锁形图标 → 网站设置 → 弹出式窗口 → 允许 - Firefox：首选项 → 隐私 → 弹出窗口 → 例外 - 清除缓存并重试 ### "API 调用返回 401" - 检查 token 是否存储在 localStorage 中 - 验证 frontend 和 backend 之间的 JWT_SECRET 是否匹配 - 清除 localStorage 并重新登录 ## 📄 License MIT © 2026 OpenTrace ## 🤝 贡献 这是一个教育项目。欢迎出于目的自由进行复刻、修改和增强。 ## 📞 支持 如遇问题，请检查： 1. 环境变量是否设置正确 2. MongoDB Atlas 集群是否正在运行 3. Backend 是否可在 http://localhost:5000/health 访问 4. 端口 5000 和 5173 是否未被占用

标签：Express, MITM代理, MongoDB, React, Syscalls, Sysdig, Unix, 实时处理, 数字足迹, 网络安全, 自定义脚本, 隐私保护, 风险分析