yashcanbuild/social_shield

# 🛡️ Social Shield - 高级邮件情感分析平台 ## 📚 目录 - [🌟 功能](#-features) - [🏗️ 架构](#️-architecture) - [⚡ 快速开始](#-quick-start) - [🛠️ 安装](#️-installation) - [🔧 配置](#-configuration) - [🚀 用法](#-usage) - [📖 API 文档](#-api-documentation) - [🤖 AI 模型](#-ai-models) - [🔒 安全](#-security) - [🌐 部署](#-deployment) - [🤝 贡献](#-contributing) - [📄 许可证](#-license) - [🙏 致谢](#-acknowledgments) ## 🌟 功能 ### 🛡️ 高级邮件安全 - **钓鱼检测**：利用 AI 驱动的分析识别可疑邮件 - **情感分析**：实时检测邮件中的情感基调 - **风险评分**：基于百分比的全面威胁评估 - **Gmail 集成**：通过 OAuth 2.0 与 Gmail 账户无缝连接 ### 📊 分析与洞察 - **交互式仪表盘**：带有图表和指标的可视化分析 - **历史分析**：随时间追踪邮件模式 - **导出功能**：生成详细的 PDF 和 CSV 报告 - **书签系统**：保存和分类重要邮件 ### 🎯 用户体验 - **现代化 UI**：简洁、响应式的设计，支持深色/浅色主题 - **移动端优先**：针对所有设备尺寸进行优化 - **实时更新**：实时分析结果和通知 - **游戏化**：用于学习的交互式评分系统 ### 🔧 开发者友好 - **模块化架构**：基于微服务的设计 - **RESTful APIs**：文档完善的 endpoint - **基于环境的配置**：安全的凭证管理 - **Docker 支持**：随时可用于容器化部署 ## 🏗️ 架构 ``` graph TB A[React Frontend] -->|REST API| B[Node.js Backend] B -->|OAuth 2.0| C[Gmail API] B -->|Store Data| D[MongoDB] B -->|AI Analysis| E[Flask ML Service] E -->|Models| F[Hugging Face/Gemini] subgraph Frontend["Frontend Port 5173"] A1[Authentication] A2[Dashboard] A3[Email Analysis] A4[Reports] end subgraph Backend["Backend Services"] B1[Express API Port 5000] E1[Flask ML Port 3000] end subgraph Data["Data Layer"] D1[User Data] D2[Email Analysis] D3[Game Scores] end ``` ### 🗂️ 项目结构 ``` social-shield/ ├── 📁 mern-frontend/ # React Frontend (Vite + Tailwind) │ ├── 📁 src/ │ │ ├── 📁 components/ # Reusable UI components │ │ ├── 📁 pages/ # Application pages │ │ ├── 📁 contexts/ # React context providers │ │ ├── 📁 utils/ # Helper functions │ │ └── 📁 styles/ # CSS and animations │ └── 📄 package.json ├── 📁 mern-backend/ # Node.js API Server │ ├── 📁 controllers/ # Request handlers │ ├── 📁 models/ # Database schemas │ ├── 📁 routes/ # API endpoints │ ├── 📁 middleware/ # Auth & validation │ └── 📄 package.json ├── 📁 flask-backend/ # Python ML Service │ ├── 📄 app.py # Flask application │ ├── 📄 requirements.txt # Python dependencies │ └── 📁 models/ # ML model files ├── 📄 README.md # This file ├── 📄 LICENSE # MIT License └── 📄 CONTRIBUTING.md # Contribution guidelines ``` ## ⚡ 快速开始 让 Social Shield 在 5 分钟内运行起来： ``` # 1. Clone the repository git clone https://github.com/yourusername/social-shield.git cd social-shield # 2. 快速设置脚本（处理所有依赖项） chmod +x scripts/quick-start.sh ./scripts/quick-start.sh # 3. 打开浏览器 # 4. Frontend: http://localhost:5173 # 5. Backend: http://localhost:5000 ``` ## 🛠️ 安装 ### 前置条件 请确保已安装以下软件： - **Node.js** 18+ 和 npm 9+ ([下载](https://nodejs.org/)) - **Python** 3.9+ 和 pip ([下载](https://python.org/)) - **MongoDB** Community Edition ([下载](https://mongodb.com/try/download/community)) - **Git** ([下载](https://git-scm.com/)) ### 分步安装 #### 1. 克隆并导航 ``` git clone https://github.com/yourusername/social-shield.git cd social-shield ``` #### 2. 安装前端依赖 ``` cd mern-frontend npm install cd .. ``` #### 3. 安装后端依赖 ``` cd mern-backend npm install cd .. ``` #### 4. 安装 Python 依赖 ``` cd flask-backend pip install -r requirements.txt cd .. ``` #### 5. 环境设置 ``` # 6. 复制环境模板 cp mern-frontend/.env.example mern-frontend/.env cp mern-backend/.env.example mern-backend/.env cp flask-backend/.env.example flask-backend/.env # 7. 使用您的凭据编辑每个 .env 文件 ``` ## 🔧 配置 ### 环境变量 #### 前端配置 (`mern-frontend/.env`) ``` # 8. API Endpoints VITE_API_URL=http://localhost:5000 VITE_FLASK_API_URL=http://localhost:3000 # 9. Google OAuth VITE_GOOGLE_CLIENT_ID=your_google_client_id VITE_REDIRECT_URI=http://localhost:5000/api/auth/google/callback # 10. 开发 VITE_NODE_ENV=development VITE_DEBUG_MODE=true ``` #### 后端配置 (`mern-backend/.env`) ``` # 11. 数据库 MONGODB_URI=mongodb://localhost:27017/social-shield # 12. Google OAuth GOOGLE_CLIENT_ID=your_google_client_id GOOGLE_CLIENT_SECRET=your_google_client_secret REDIRECT_URI=http://localhost:5000/api/auth/google/callback # 13. 安全 JWT_SECRET=your_super_secure_jwt_secret_minimum_32_characters SESSION_SECRET=your_session_secret # 14. AI Services GEMINI_API_KEY=your_gemini_api_key # 15. 服务 FRONTEND_URL=http://localhost:5173 FLASK_API_URL=http://localhost:3000 PORT=5000 NODE_ENV=development ``` #### Flask ML 服务配置 (`flask-backend/.env`) ``` # 16. AI Models HUGGINGFACE_API_TOKEN=your_huggingface_token LOCAL_MODEL_PATH=./models USE_LOCAL_MODEL=true # 17. 开发 FLASK_ENV=development PORT=3000 DEBUG=true ``` ### 🔑 API 密钥设置 #### 1. Google OAuth（必需） 1. 访问 [Google Cloud Console](https://console.cloud.google.com/) 2. 创建新项目或选择现有项目 3. 启用 **Gmail API** 和 **Google+ API** 4. 创建 **OAuth 2.0 Client ID** 凭证 5. 添加授权重定向 URI：`http://localhost:5000/api/auth/google/callback` #### 2. Google Gemini API（必需） 1. 前往 [Google AI Studio](https://makersuite.google.com/app/apikey) 2. 创建新的 API 密钥 3. 将密钥复制到后端的 `.env` 文件中的 `GEMINI_API_KEY` #### 3. Hugging Face（可选） 1. 在 [Hugging Face](https://huggingface.co/) 注册 2. 前往 [Settings → Tokens](https://huggingface.co/settings/tokens) 3. 创建具有 **read** 权限的新 token 4. 将其添加到 Flask `.env` 文件中的 `HUGGINGFACE_API_TOKEN` ### 🗄️ 数据库设置 #### 选项 1：本地 MongoDB ``` # 18. Install MongoDB Community Edition # 19. 启动 MongoDB service mongod --dbpath /path/to/your/data/directory # 20. 创建数据库 mongo > use social-shield > db.createCollection("users") > db.createCollection("scores") ``` #### 选项 2：MongoDB Atlas（云端） 1. 在 [MongoDB Atlas](https://cloud.mongodb.com/) 创建账户 2. 创建免费集群 (M0 Sandbox) 3. 添加数据库用户并设置 IP 白名单 4. 获取连接字符串并更新 `MONGODB_URI` ## 🚀 用法 ### 启动开发环境 #### 终端 1：后端 API ``` cd mern-backend npm run dev # 21. Server 运行于 http://localhost:5000 ``` #### 终端 2：Flask ML 服务 ``` cd flask-backend python app.py # 22. ML service 运行于 http://localhost:3000 ``` #### 终端 3：前端 ``` cd mern-frontend npm run dev # 23. Frontend 运行于 http://localhost:5173 ``` ### 使用应用程序 #### 1. **身份验证** - 访问 `http://localhost:5173` - 点击“使用 Google 登录” - 授予 Gmail 访问权限 - 重定向到仪表盘 #### 2. **邮件分析** - 导航至“邮件分析”页面 - 点击“分析邮件” - 查看实时分析结果 - 检查情感评分和风险评估 #### 3. **仪表盘功能** - **分析**：查看邮件统计信息和趋势 - **书签**：保存重要邮件以便快速访问 - **导出**：生成 PDF/CSV 报告 - **设置**：配置首选项和主题 #### 4. **游戏模式** - 访问“LLM 模拟”进行交互式学习 - 练习识别钓鱼邮件 - 追踪您的安全意识得分 ## 📖 API 文档 ### 身份验证 Endpoint #### 24. POST `/api/auth/google-login` 使用 Google OAuth 代码对用户进行身份验证。 ``` curl -X POST http://localhost:5000/api/auth/google-login \ -H "Content-Type: application/json" \ -d '{"code": "google_oauth_code"}' ``` **响应：** ``` { "token": "jwt_token", "user": { "id": "user_id", "name": "John Doe", "email": "john@example.com" } } ``` ### 邮件分析 Endpoint #### 25. GET `/api/gmail/emails` 获取用户的 Gmail 邮件。 ``` curl -X GET "http://localhost:5000/api/gmail/emails?limit=10" \ -H "Authorization: Bearer jwt_token" ``` #### 26. POST `/api/analyze/sentiment` 分析邮件情感和安全性。 ``` curl -X POST http://localhost:3000/api/analyze \ -H "Content-Type: application/json" \ -d '{ "text": "Email content to analyze", "subject": "Email subject", "sender": "sender@example.com" }' ``` **响应：** ``` { "sentiment": "positive", "confidence": 0.95, "suspicion_score": 0.1, "prediction": "Safe", "analysis": { "phishing_indicators": [], "sentiment_breakdown": { "positive": 0.8, "neutral": 0.15, "negative": 0.05 } } } ``` ### 用户数据 Endpoint #### 27. GET `/api/scores` 获取用户的分析得分。 ``` curl -X GET "http://localhost:5000/api/scores?email=user@example.com" \ -H "Authorization: Bearer jwt_token" ``` #### 28. POST `/api/scores` 保存分析得分。 ``` curl -X POST http://localhost:5000/api/scores \ -H "Content-Type: application/json" \ -H "Authorization: Bearer jwt_token" \ -d '{"email": "user@example.com", "score": 85}' ``` 完整的 API 文档，请参阅 [API 参考](./docs/api.md)。 ## 🤖 AI 模型 ### 情感分析模型 #### 主要模型：RoBERTa (Hugging Face) - **模型**：`cardiffnlp/twitter-roberta-base-sentiment-latest` - **准确率**：在测试数据集上为 94.2% - **语言**：英语（主要），计划支持多语言 - **推理时间**：每封邮件约 200ms #### 备用模型：Google Gemini - **用例**：复杂的邮件和边缘情况 - **功能**：上下文感知分析，多模态理解 - **速率限制**：60 次请求/分钟（免费版） ### 钓鱼检测 #### 基于规则的分析 - **URL 扫描**：可疑链接检测 - **标头分析**：发件人验证 - **内容模式**：钓鱼关键词匹配 - **附件扫描**：文件类型验证 #### 增强型机器学习检测 - **特征工程**：提取了 47 个独特特征 - **算法**：Gradient Boosting Classifier - **训练数据**：50K+ 标记的钓鱼邮件 - **准确率**：96.8% 精确率，94.1% 召回率 ### 模型性能 | 模型 | 准确率 | 精确率 | 召回率 | F1-Score | 推理时间 | | ------------------ | -------- | --------- | ------ | -------- | -------------- | | Sentiment Analysis | 94.2% | 93.8% | 94.6% | 94.2% | 180ms | | Phishing Detection | 95.5% | 96.8% | 94.1% | 95.4% | 120ms | | Combined Analysis | 94.8% | 95.1% | 94.3% | 94.7% | 300ms | ## 🔒 安全 ### 数据保护 - **加密**：静态和传输中的所有数据均已加密 - **JWT 身份验证**：安全的基于 token 的身份验证 - **OAuth 2.0**：业界标准的 Google 身份验证 - **CORS 保护**：为生产环境配置 - **速率限制**：防止 API 滥用 ### 隐私措施 - **最少数据存储**：仅存储基本的邮件元数据 - **用户控制**：完整的数据删除功能 - **不存储邮件内容**：仅存储分析结果，不存储邮件内容 - **GDPR 合规**：支持数据可携带权和删除权 ### 安全最佳实践 - **环境变量**：无硬编码凭证 - **输入验证**：所有输入均已清理和验证 - **SQL 注入预防**：MongoDB 使用参数化查询 - **XSS 保护**：内容安全策略标头 - **仅限 HTTPS**：生产环境中使用 TLS 1.3 ### 漏洞报告 发现安全问题？请负责任地报告： - 邮箱：security@social-shield.com - 使用我们的[安全政策](.github/SECURITY.md) - GPG 密钥：可应要求提供 ## 🌐 部署 ### 生产环境变量 ``` # 29. Frontend (Vercel/Netlify) VITE_API_URL=https://api.yourdomain.com VITE_FLASK_API_URL=https://ml.yourdomain.com VITE_REDIRECT_URI=https://api.yourdomain.com/api/auth/google/callback # 30. Backend (Render/Railway) FRONTEND_URL=https://yourdomain.com NODE_ENV=production MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/production # 31. Flask (Render/PythonAnywhere) FLASK_ENV=production ``` ### 部署指南 #### Vercel（前端） ``` # 32. Install Vercel CLI npm i -g vercel # 33. 部署 cd mern-frontend vercel --prod ``` #### Render（后端服务） 1. 连接 GitHub 仓库 2. 为 Node.js 后端创建 **Web Service** 3. 为 Flask ML 服务创建 **Web Service** 4. 在仪表盘中设置环境变量 5. 推送时自动部署 #### 34. MongoDB Atlas 1. 创建生产集群 2. 配置网络访问 3. 创建数据库用户 4. 启用备份和监控 ### Docker 部署 #### 使用 Docker Compose ``` # 35. 构建并启动所有服务 docker-compose up -d # 36. 查看日志 docker-compose logs -f # 37. 停止服务 docker-compose down ``` #### 单独服务 ``` # 38. Backend docker build -t social-shield-backend ./mern-backend docker run -p 5000:5000 --env-file .env social-shield-backend # 39. Frontend docker build -t social-shield-frontend ./mern-frontend docker run -p 5173:5173 social-shield-frontend # 40. Flask ML docker build -t social-shield-ml ./flask-backend docker run -p 3000:3000 --env-file .env social-shield-ml ``` ### 性能优化 #### 前端 - **代码拆分**：懒加载以提升性能 - **CDN 集成**：通过 CDN 提供静态资源 - **图片优化**：使用 WebP 格式并提供后备 - **Bundle 分析**：集成 Webpack Bundle Analyzer #### 后端 - **数据库索引**：优化的 MongoDB 查询 - **缓存**：为频繁访问的数据集成 Redis - **负载均衡**：支持多实例 - **监控**：应用程序性能监控 ## 🤝 贡献 我们欢迎社区的贡献！以下是您可以提供帮助的方式： ### 开发流程 1. **Fork** 该仓库 2. 在本地 **Clone** 您的 fork 3. **创建** 功能分支 4. **进行** 更改 5. 全面**测试** 6. **提交** Pull Request ``` # 41. Fork 并 clone git clone https://github.com/yourusername/social-shield.git cd social-shield # 42. 创建功能分支 git checkout -b feature/amazing-new-feature # 43. 进行更改并提交 git add . git commit -m "Add amazing new feature" # 44. 推送并创建 PR git push origin feature/amazing-new-feature ``` ### 贡献指南 #### 代码规范 - **ESLint**：遵循现有的代码风格 - **Prettier**：提交前格式化代码 - **注释**：为复杂的逻辑编写文档 - **测试**：为新功能包含测试 **TypeScript**：正逐步迁移至 TypeScript #### 提交信息格式 ``` type(scope): description [optional body] [optional footer] ``` **类型**：`feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` **示例**： ``` feat(auth): add two-factor authentication fix(api): resolve email parsing bug docs(readme): update installation instructions ``` #### Pull Request 检查清单 - [ ] 代码遵循项目风格指南 - [ ] 完成更改的自我审查 - [ ] 为新功能添加了测试 - [ ] 更新了文档 - [ ] 无合并冲突 - [ ] CI/CD 检查通过 ### 贡献领域 #### 🎯 高优先级 - **多语言支持**：国际化 (i18n) - **移动应用**：React Native 或 Flutter 实现 - **高级 ML 模型**：提高检测准确率 - **性能优化**：减少加载时间 #### 🛠️ 中优先级 - **深色模式改进**：增强的主题系统 - **无障碍访问**：符合 WCAG 2.1 标准 - **测试覆盖率**：提高到 90% 以上 - **文档**：改进 API 文档 #### 🌟 期望拥有 - **浏览器扩展**：Chrome/Firefox 扩展 - **Slack 集成**：团队协作功能 - **高级分析**：商业智能仪表盘 - **白标解决方案**：可定制的品牌 ### 获取帮助 - **GitHub Discussions**：用于提问和想法 - **Discord Server**：实时社区聊天 - **Issues**：Bug 报告和功能请求 - **Wiki**：详细的开发指南 ## 📄 许可证 该项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ### MIT 许可证摘要 - ✅ 商业用途 - ✅ 修改 - ✅ 分发 - ✅ 私人使用 - ❌ 责任 - ❌ 担保 ## 🙏 致谢 ### 核心技术 - **[React](https://reactjs.org/)** - 用于构建用户界面的 UI 库 - **[Node.js](https://nodejs.org/)** - 用于后端服务的 JavaScript runtime - **[MongoDB](https://mongodb.com/)** - 用于数据存储的 NoSQL 数据库 - **[Flask](https://flask.palletsprojects.com/)** - 用于 ML 服务的 Python Web 框架 ### AI 与 ML 服务 - **[Google Gemini](https://ai.google.dev/)** - 用于分析的高级语言模型 - **[Hugging Face](https://huggingface.co/)** - 预训练 transformer 模型 - **[Transformers](https://huggingface.co/transformers/)** - 最先进的 NLP 库 ### UI 与设计 - **[Tailwind CSS](https://tailwindcss.com/)** - 实用优先的 CSS 框架 - **[Lucide Icons](https://lucide.dev/)** - 美观且一致的图标包 - **[Framer Motion](https://framer.com/motion/)** - React 的动画库 ### 开发工具 - **[Vite](https://vitejs.dev/)** - 快速的构建工具和开发服务器 - **[ESLint](https://eslint.org/)** - JavaScript linting 实用程序 - **[Prettier](https://prettier.io/)** - 代码格式化工具 ### 托管与基础设施 - **[Vercel](https://vercel.com/)** - 前端部署平台 - **[Render](https://render.com/)** - 后端服务托管 - **[MongoDB Atlas](https://cloud.mongodb.com/)** - 云数据库服务 ### 社区与支持 - **贡献者**：感谢我们所有了不起的贡献者！ - **Beta 测试员**：提供宝贵反馈的早期用户 - **安全研究员**：负责的漏洞披露贡献者

标签：Gmail集成, GNU通用公共许可证, MITM代理, Node.js, Python, React, Syscalls, 情感分析, 无后门, 自定义脚本, 请求拦截, 逆向工具, 邮件安全, 钓鱼检测