ritiksah141/BreachLens

# BreachLens [](backend/tests/) [](frontend/src/app/) [](backend/htmlcov/) [](https://www.python.org/) [](https://angular.dev/) [](https://flask.palletsprojects.com/) [](https://www.mongodb.com/) **COM661 全栈开发 - 阿尔斯特大学** **课程作业 1**：后端 API 开发 ✅ **课程作业 2**：前端开发 ✅ ## 📋 目录 - [概述](#-overview) - [功能](#-features) - [技术栈](#-technology-stack) - [项目结构](#-project-structure) - [快速开始](#-quick-start) - [后端 API](#-backend-api) - [前端](#-frontend) - [文档](#-documentation) - [测试](#-testing) - [安全](#-security) - [贡献](#-contributing) ## 🎯 概述 BreachLens 是一个全面的网络威胁情报平台，旨在跟踪和分析来自暗网的数据泄露事件。该平台提供： - **泄露追踪**：监控和记录数据泄露事件及其详细元数据 - **地理空间映射**：以可视化方式呈现全球范围内的泄露起源和受影响地区 - **风险分析**：提供关于行业风险、严重性趋势和暴露指标的汇总洞察 - **受损监控**：跟踪受影响的账户、时间表和补救措施 - **基于角色的访问控制**：多层级访问控制（管理员、分析师、访客） 该系统采用 RESTful API 后端（Flask + MongoDB）构建，注重可扩展性和安全性，并配有用于数据可视化和用户交互的 Angular 前端。 ## ✨ 功能 ### **核心功能** - ✅ **65 个 REST API 端点** - 为泄露、用户和分析提供完整的 CRUD 操作 - ✅ **JWT 身份验证** - 带有功能性守卫的安全基于令牌的身份验证 - ✅ **基于角色的访问控制 (RBAC)** - 带有结构指令的管理员、分析师和访客角色 - ✅ **地理空间映射** - 使用 Leaflet-js 战术地图，支持 GeoJSON 遥测和地理定位 - ✅ **高级分析** - 11 个聚合端点，用于行业年度趋势和风险分布分析 - ✅ **暴露扫描器** - 实时身份和域暴露情报扫描器 - ✅ **暗色/亮色主题** - 带有 CSS 自定义属性的感知系统主题 - ✅ **综合测试** - 跨后端 (586) 和前端 (249) 共有 835 个测试 ### **安全功能** - 🔐 JWT 令牌身份验证，基于 MongoDB 的黑名单机制 - 🔐 登录失败后的账户锁定机制 - 🔐 BCrypt 密码哈希（12 轮） - 🔐 NoSQL 注入防护 - 🔐 XSS 净化 - 🔐 安全标头（CSP, X-Frame-Options） - 🔐 敏感端点的速率限制 - 🔐 安全事件的审计日志 ### **数据管理** - 📊 来自真实来源的 25 条以上初始泄露记录 - 📊 对泄露标题和描述的全文搜索 - 📊 分页和过滤支持 - 📊 用于地图集成的 GeoJSON 导出 - 📊 用于受影响账户和时间轴的子文档数组 ## 🛠 技术栈 ### **后端**（课程作业 1 - ✅ 已完成） - **框架**：Flask 3.0.3 - **数据库**：MongoDB 7.0 与 PyMongo 4.6.3 - **身份验证**：PyJWT（原生 JWT 库） - **测试**：pytest 8.2.2（586 个测试） - **API 文档**：Swagger/OpenAPI - **安全**：bcrypt, flask-limiter, bleach - **环境**：Python 3.11+ ### **前端**（课程作业 2 - ✅ 已完成） - **框架**：Angular 17.3（独立组件，信号） - **语言**：TypeScript 5.4 - **UI**：Bootstrap 5.3 与自定义 CSS 变量（暗色/亮色主题） - **地图**：Leaflet.js 1.9.4，包含 GeoJSON，Stadia Maps + OpenStreetMap 瓦片 - **图表**：Chart.js 4.4（6 种图表类型，响应主题） - **状态管理**：Angular Signals（signal, computed, effect） - **测试**：Jasmine 5.1 + Karma 6.4（249 个测试） ### **开发工具** - **API 测试**：Postman（69 个请求，115+ 个测试断言） - **代码质量**：pytest, coverage.py, 预提交钩子 - **安全扫描**：detect-secrets - **版本控制**：带有分支保护的 Git ## 📂 项目结构 ``` BreachLens/ ├── backend/ # Backend API (Flask) │ ├── app/ # Application package │ │ ├── routes/ # REST API endpoints (63 endpoints) │ │ ├── services/ # Business logic layer │ │ ├── models/ # Data validation schemas │ │ ├── middleware/ # Auth, logging, security │ │ └── utils/ # Helper functions │ ├── tests/ # Test suite (586 tests) │ ├── seed/ # Database seeding scripts │ ├── postman/ # API test collection │ ├── logs/ # Application logs │ ├── htmlcov/ # Coverage reports │ ├── run.py # Application entry point │ ├── requirements.txt # Python dependencies │ └── README.md # Backend documentation ├── docs/ # Project documentation │ ├── API_SPEC.md # Complete API reference │ ├── PRD.md # Product requirements │ ├── QA_STRATEGY.md # Testing strategy │ ├── SUBMISSION_CHECKLIST.md # Coursework checklist │ └── README.md # Documentation index ├── frontend/ # Frontend (Angular 17 SPA) │ ├── src/app/ # Application source │ │ ├── core/ # Guards, interceptors, resolvers, services for│ │ ├── features/ # Lazy-loaded feature components (16) │ │ └── shared/ # Pipes, directives, shared components │ ├── package.json # Node dependencies │ └── README.md # Frontend documentation ├── .pre-commit-config.yaml # Git hooks configuration ├── LICENSE # MIT License └── README.md # This file ``` **详细的模块结构**：有关完整的后端架构，请参阅 [backend/README.md](backend/README.md)。 ## 🚀 快速开始 ### **前置条件** - Python 3.11 或更高版本 - Node.js 18+ 和 npm - MongoDB 7.0（本地安装） - Git ### **1. 克隆仓库** ``` git clone https://github.com/yourusername/BreachLens.git cd BreachLens ``` ### **2. 设置后端** ``` # 创建虚拟环境 python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 cd backend pip install -r requirements.txt # 配置环境 cp .env.example .env # 使用你的 MongoDB URI 和 secrets 编辑 .env ``` ### **3. 启动 MongoDB** ``` # macOS (Homebrew) brew services start mongodb-community # 验证 MongoDB 是否正在运行 mongosh --eval "db.version()" ``` ### **4. 初始化数据库** ``` python seed/seed_data.py --reset # 植入 25+ 条泄露记录和默认用户 ``` ### **5. 运行后端 API** ``` python run.py # API 可用于：http://localhost:5001 # Swagger 文档：http://localhost:5001/api/docs ``` ### **6. 设置前端** ``` cd ../frontend npm install npm start # App：http://localhost:4200 ``` ### **7. 测试两者** ``` # 后端测试 cd backend && pytest tests/ -v # 预期：586 个通过，2 个跳过，14 个取消选择 # 前端测试 cd ../frontend && npx ng test --watch=false --browsers=ChromeHeadless # 预期：247 个通过 ``` ### **8. 使用 cURL 测试** ``` # 健康检查 curl http://localhost:5001/health # 登录（获取 JWT token） curl -X POST http://localhost:5001/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "admin@breachlens.io", "password": "Admin@123"}' # pragma: allowlist secret # 使用 token 进行身份验证请求 curl http://localhost:5001/api/v1/breaches \ -H "x-access-token: YOUR_TOKEN_HERE" ``` ## 🔌 后端 API ### **API 端点（共 63 个）** | 类别 | 端点数 | 描述 | |----------|-----------|-------------| | **身份验证** | 8 | 注册、登录、登出、个人资料 | | **泄露事件** | 32 | CRUD 操作、地理空间查询、子文档 | | **分析** | 10 | 风险评估、趋势、聚合 | | **用户** | 4 | 用户管理、个人资料更新 | | **管理员** | 6 | 系统统计、审计日志、缓存管理 | | **健康检查** | 3 | 健康检查、就绪状态、存活状态 | **基础 URL**：`http://localhost:5001/api/v1` ### **身份验证** ``` # 使用凭据登录 POST /auth/login { "email": "admin@breachlens.io", "password": "Admin@123" # pragma: allowlist secret } # 返回有效期 1 小时的 JWT token # 在 header 中使用：x-access-token: ``` ### **示例请求** **列出所有泄露事件**（分页，已过滤）： ``` GET /api/v1/breaches?page=1&limit=10&severity=Critical&status=Unresolved ``` **创建泄露事件**（分析师/管理员）： ``` POST /api/v1/breaches Content-Type: application/json x-access-token: YOUR_TOKEN { "title": "DataCorp Security Incident", "description": "Payment system breach", "severity": "Critical", "breach_date": "2026-01-15", "records_exposed": 500000, ... } ``` **地理空间搜索**： ``` GET /api/v1/breaches/geo/near?longitude=-0.1278&latitude=51.5074&max_distance=100000 ``` **分析仪表板**： ``` GET /api/v1/analytics/summary ``` 📖 **完整 API 文档**：[docs/API_SPEC.md](docs/API_SPEC.md) 📦 **Postman 集合**：[backend/postman/](backend/postman/) ### **默认测试账户** | 角色 | 电子邮件 | 密码 | 权限 | |------|-------|----------|-------------| | 管理员 | admin@breachlens.io | Admin@123 | 完全访问权限 | | 分析师 | priya@breachlens.io | Analyst@123 | 读取 + 创建/更新 | | 访客 | marcus@example.com | Guest@123 | 只读（受限） | ### **后端架构** 后端遵循**分层架构**： 1. **路由层**（`app/routes/`）- HTTP 请求处理和验证 2. **服务层**（`app/services/`）- 业务逻辑和 MongoDB 操作 3. **模型层**（`app/models/`）- 数据验证模式 4. **中间件层**（`app/middleware/`）- 身份验证、日志记录、安全 5. **工具层**（`app/utils/`）- 辅助函数和实用程序 **完整的后端文档**：请参阅 [backend/README.md](backend/README.md) ## 🎨 前端 ### **状态**：✅ 已完成（课程作业 2） Angular 17 单页应用程序，包含 **14 个独立组件**、**247 个通过的测试**，并完全集成了后端。 #### **核心功能** - 🖥️ **Angular 17 SPA** — 独立组件，signals，computed()，effect()，懒加载路由 - 🗺️ **交互式泄露地图** — Leaflet.js 结合 GeoJSON 标记、地理定位、严重性着色 - 📊 **分析仪表板** — 6 种 Chart.js 可视化图表（柱状图、折线图、圆环图、直方图） - 🔍 **高级搜索** — 多条件过滤、自动建议、子文档查询 - 📋 **泄露管理** — 包含子文档管理（时间轴、补救措施、警报、账户）的完整 CRUD 操作 - 👤 **管理员面板** — 用户管理、角色变更、批量操作、审计追踪 - 🔐 **身份验证** — JWT 登录/注册/重置、功能性守卫、HTTP 拦截器 - 🎨 **暗色/亮色主题** — 系统偏好检测、CSS 变量、主题响应式地图/图表 - 📱 **响应式设计** — Bootstrap 5 网格，对移动端友好的导航 - 🔒 **基于角色的 UI** — 自定义 `*appRequireRole` 结构指令，3 个路由守卫 #### **Angular 亮点** | 特性 | 数量 | |---------|-------| | 组件 | 14 (全部独立) | | 服务 | 7 | | 自定义管道 | 3 (TimeAgo, RiskLevel, CompactNumber) | | 自定义指令 | 2 (CopyClipboard, RequireRole) | | 路由守卫 | 3 (auth, admin, analyst) | | 路由解析器 | 1 (泄露详情预抓取) | | HTTP 拦截器 | 1 (JWT + 错误处理) | | 消耗的后端端点数 | 65 | | 测试 | 249 个通过 | **前端文档**：[frontend/README.md](frontend/README.md) ## 📚 文档 [`docs/`](docs/) 目录中提供了详尽的文档： | 文档 | 描述 | |----------|-------------| | [API_SPEC.md](docs/API_SPEC.md) | 完整的 API 参考，包含请求/响应示例 | | [PRD.md](docs/PRD.md) | 产品需求和功能规格 | | [QA_STRATEGY.md](docs/QA_STRATEGY.md) | 测试策略和质量保证计划 | | [SUBMISSION_CHECKLIST.md](docs/SUBMISSION_CHECKLIST.md) | 课程作业要求清单 | | [backend/README.md](backend/README.md) | 后端架构和开发指南 | | [frontend/README.md](frontend/README.md) | 前端架构、组件和测试 | **模块特定的 READMEs**： - [backend/app/README.md](backend/app/README.md) - 应用工厂和配置 - [backend/app/routes/README.md](backend/app/routes/README.md) - REST API 端点参考 - [backend/app/models/README.md](backend/app/models/README.md) - 数据验证模式 - [backend/app/services/README.md](backend/app/services/README.md) - 业务逻辑层 - [backend/app/middleware/README.md](backend/app/middleware/README.md) - 身份验证和安全 - [backend/app/utils/README.md](backend/app/utils/README.md) - 辅助函数 - [backend/tests/README.md](backend/tests/README.md) - 测试指南 - [backend/seed/README.md](backend/seed/README.md) - 数据库初始数据加载指南 - [backend/postman/README.md](backend/postman/README.md) - 使用 Postman 进行 API 测试 ## 🧪 测试 ### **测试覆盖率** 该项目在后端和前端均有全面的测试覆盖率：**共 833 个测试**。 #### **后端测试（586 个通过，88% 覆盖率）** | 测试模块 | 测试数 | 重点 | |-------------|-------|-------| | 身份验证 | 11 | 身份验证端点，JWT 验证 | | 泄露事件 CRUD | 21 | 创建、读取、更新、删除操作 | | 子文档 | 31 | 账户、时间轴、补救措施、警报 | | 安全 | 40 | NoSQL 注入XSS、速率限制、锁定 | | 分析 | ~10 | 聚合管道和报告 | | 泄露服务 | ~50 | 带有模拟的业务逻辑 | | 模型/验证 | ~140 | 模式验证和实用程序 | | 服务集成 | ~200 | 端到端服务层测试 | | 管理员路由 | ~25 | 管理员操作和 RBAC | | 用户管理 | ~30 | 用户资料和管理 | | 性能 | 14 | 基准测试（默认取消选择） | #### **前端测试（249 个通过）** | 测试模块 | 测试数 | 重点 | |-------------|-------|-------| | 自定义管道 | 83 | TimeAgo, RiskLevel, CompactNumber | | 自定义指令 | 25 | CopyClipboard, RequireRole | | 服务 | 33 | Auth, Breach, Notification, Theme | | 守卫和拦截器 | 19 | Auth 守卫信号，JWT 拦截器 | | 解析器 | 8 | 泄露详情预抓取 | | 组件 | 70 | Profile, Pagination, SeverityBadge, BreachList, Dashboard | | 集成 | 9 | 服务 HTTP 调用 | ### **运行测试** ``` # 后端测试 cd backend source ../venv/bin/activate pytest tests/ -v # 前端测试 cd frontend npx ng test --watch=false --browsers=ChromeHeadless # 后端覆盖率报告 cd backend pytest tests/ --cov=app --cov-report=html --cov-report=term open htmlcov/index.html # 前端覆盖率报告 cd frontend npx ng test --watch=false --browsers=ChromeHeadless --code-coverage open coverage/breachlens-frontend/index.html ``` ### **使用 Postman 进行 API 测试** [`backend/postman/`](backend/postman/) 目录包含一个完整的 Postman 集合，包含覆盖所有主要 API 端点的 **64 个请求**和 **108 个测试断言**。 ``` # 导入 collection backend/postman/BreachLens.postman_collection.json # 导入 environment backend/postman/BreachLens.postman_environment.json # 使用 Newman 运行 npm install -g newman newman run backend/postman/BreachLens.postman_collection.json \ -e backend/postman/BreachLens.postman_environment.json ``` **测试文档**：[backend/tests/README.md](backend/tests/README.md) ## 🛡️ 安全 BreachLens 实现了多层安全防护： ### **身份验证与授权** - ✅ 具有 1 小时有效期的 JWT 令牌 - ✅ 存储在 MongoDB 中的令牌黑名单（支持登出） - ✅ 基于角色的访问控制（管理员、分析师、访客） - ✅ 5 次登录尝试失败后的账户锁定 - ✅ 带有安全令牌流程的密码重置 ### **数据保护** - ✅ BCrypt 密码哈希（12 轮） - ✅ NoSQL 注入防护 - ✅ 使用 bleach 库进行 XSS 净化 - ✅ 所有端点的输入验证 - ✅ 查询参数净化 ### **基础设施安全** - ✅ 安全标头（CSP, X-Frame-Options, X-Content-Type-Options） - ✅ 针对不同环境的 CORS 配置 - ✅ 速率限制（身份验证端点 100 次请求/分钟） - ✅ 安全事件的审计日志 - ✅ 用于机密检测的 Git 预提交钩子 ### **安全测试** - ✅ 40 多个侧重于安全的测试 - ✅ NoSQL 注入测试覆盖 - ✅ XSS 攻击防护测试 - ✅ 速率限制验证 - ✅ 账户锁定测试 **安全文档**：[backend/README.md#security-features](backend/README.md#security-features) ## 🤝 贡献 ### **开发工作流** 1. **克隆并设置**： git clone https://github.com/yourusername/BreachLens.git cd BreachLens python3 -m venv venv source venv/bin/activate cd backend && pip install -r requirements.txt 2. **创建功能分支**： git checkout -b feature/your-feature-name 3. **进行修改并测试**： pytest tests/ -v 4. **使用常规提交**： git commit -m "feat: add new analytics endpoint" git commit -m "fix: resolve authentication issue" git commit -m "docs: update API documentation" 5. **推送并创建 PR**： git push origin feature/your-feature-name ### **预提交钩子** 该仓库使用预提交钩子来保证代码质量： - ✅ 大文件检测 - ✅ JSON/YAML 验证 - ✅ 机密检测 - ✅ Python 语法验证 - ✅ 去除行尾空格 - ✅ 分支保护（仅限主分支） 安装钩子： ``` pip install pre-commit pre-commit install ``` ### **编码规范** - Python 代码遵循 PEP 8 规范 - 为新功能编写单元测试 - 针对变更更新 API 文档 - 为所有函数添加文档字符串 - 在适当的地方使用类型提示 ## 📝 许可证 本项目基于 **MIT 许可证**授权。详情请参阅 [LICENSE](LICENSE)。 ## 👥 作者 **Ritik Sah** 学号：B00925357 课程：COM661 全栈开发 机构：阿尔斯特大学 ## 📞 支持 如有问题或疑虑： - 📧 电子邮件：[your.email@study.beds.ac.uk] - 📖 文档：[docs/](docs/) - 🐛 议题：[GitHub Issues](https://github.com/yourusername/BreachLens/issues) ## 🗓️ 项目状态 | 组件 | 状态 | 完成度 | |-----------|--------|------------| | 后端 API | ✅ 已完成 | 100%（课程作业 1） | | 前端 SPA | ✅ 已完成 | 100%（课程作业 2） | | API 文档 | ✅ 已完成 | 100% | | 后端测试 | ✅ 已完成 | 586 个测试，88% 覆盖率 | | 前端测试 | ✅ 已完成 | 跨 16 个组件共 249 个测试 | **最后更新**：2026 年 4 月 **版本**：v2.0.0（全栈） **为 COM661 全栈开发而构建**

标签：Angular, Flask, Grype, MongoDB, Python, RBAC, RESTful API, 前后端分离, 受损凭证, 地理空间分析, 威胁情报, 开发者工具, 情报平台, 提示词优化, 无后门, 暗网监控, 测绘与可视化, 网络安全, 网络攻击追踪, 角色访问控制, 资产监控, 逆向工具, 隐私保护, 风险分析, 高等教育课程设计