Mo7ammedaga/Sentinel-Platform

# Sentinel 平台     一个由 AI 驱动的**用户行为分析 (UBA) 与内部威胁检测** 平台。员工在协作工作区中进行真实工作；每一个 有意义的操作都会转化为不可篡改的 **Event**；**AI Engine** 会根据*特定用户自身*的历史基准对 每个事件进行评分；安全 分析师审查生成的警报，并驱动完整的**事件响应 工作流** —— 从初次查看到记录在案、解决并归档的案例。 ``` Employee action → Event → AI Engine (per-user baseline) → Risk + Explanation → Alert → Investigation → Analyst verdict → Confirmed → Incident Response (severity · escalation · containment · remediation · evidence · resolution) → Closed, full audit trail ``` ## 截图 | | | |---|---| |  **安全仪表板** — 实时统计数据、风险趋势、90 天活动热力图 |  **警报** — 每个标记都附带有通俗易懂的*原因*解释 | |  **事件响应** — 严重程度、升级、响应时间线、证据，全部汇集于一条审计记录中 |  **事件** — SOC 案例管理视图，与原始警报收件箱分开 | |  **工作区** — 一个真正的看板；这里的每一个操作都是 AI 的行为信号 |  **团队聊天** — 私信、已读回执、在线状态 | |  **用户管理** — 最小权限角色分配 |  **我的账户** — 个人资料、安全、会话 | 更多：[登录](docs/screenshots/01-login.png) · [通知](docs/screenshots/11-notifications.png) · [工作区项目](docs/screenshots/07-workspace-projects.png) 分镜头演示脚本（用于录制您自己的演示视频）位于 [`docs/DEMO_SCRIPT.md`](docs/DEMO_SCRIPT.md)。 ## 这与带有图表的 CRUD 应用有何不同 - **AI 是核心产品，而非装饰。** 模型可见的每一个特征都是 针对不可变 `events` 表进行的确定性 SQL 聚合 —— 任何地方都没有合成或随机值。用户只会被拿来与 **他们自己**的历史进行比较：针对每个用户训练 Isolation Forest，风险评分则是根据该用户自身的异常分数分布计算出的稳健 z-score。 夜猫子在凌晨 2 点的正常活动对*他们自己*来说就是正常的； 而对于一个从未工作到晚上 6 点以后的人，同样的登录则会被标记出来 —— 因为这对*那个特定的人*来说是不寻常的，而不是因为硬编码的“工作时间”规则。 - **每个评分都是可解释且永久保存的。** 风险评分、置信度、 特征向量、人类可读的说明以及模型版本，都会在产生评分的那一刻被持久化 （`AIAnalysis`）—— 分析师随时可以询问 “为什么这会被标记？”并获得*最初的*答案，而不是重新生成的 猜测。 - **少于 50 个事件的用户会返回 `insufficient_data`，而不是“正常”。** 仪表板的基准覆盖率视图明确指出了这一点 —— “历史数据不足” 和“表现正常”绝不会被混为一谈。 - **AI 绝不采取行动。** 它只会引发警报。人类分析师会开启 调查并作出裁决。确认存在真实威胁并不会关闭 案例 —— 而是会在同一记录上开启完整的事件响应阶段： 严重程度、向管理员升级、遏制/补救措施、 证据上传，以及在案例归档前必须填写的解决摘要。每一步都会记录在同一条只能追加的审计记录中。 ## 功能导览 **AI Engine** 按用户划分的 Isolation Forest 基准 · 确定性特征提取（一天中的时间、 速度、连续不同操作突发、新 IP/设备、非基准时间） · 置信度 + 每个评分持久化的解释 · 分析师反馈循环（确认为真实威胁 vs. 误报， 按模型版本跟踪） · 风险趋势图 · 基准覆盖率透明度面板。 **警报 → 调查 → 事件响应** 幂等调查工作流（打开 → 确认 → 遏制中 → 已解决 → 已关闭） · 分析师分配的严重程度，与 AI 自身的严重程度区分开来 · 向管理员升级并附带通知 · 遏制/补救 操作日志 · 真实的文件证据上传/下载 · 归档已确认案例前必须填写的解决摘要 · 专属的事件案例管理视图。 **工作区** 项目、看板任务、笔记以及真实的文件上传/下载 —— 每一次变更 都会精确发出一个行为事件，因为这正是 AI 实际学习 的内容。支持针对所有内容的全文搜索，以及 Cmd+K 命令面板。 **团队聊天** 私信、已读回执、在线状态、真实头像。 **身份与访问** 带刷新的 JWT 认证，会话/设备管理（列出和撤销），在 四种角色（员工/经理、安全分析师、管理员）之间实施 RBAC，并在路由 层强制执行，支持头像上传和密码更改的账户资料。 **隐私与合规** 书面的监控通知、针对自身事件历史的主体访问数据导出、 数据保留清理工具，以及分析师操作审计 —— 参见 [`docs/15`]()。 **工程** 71 个后端测试 (pytest) + 17 个前端测试 (Jest/RTL)，GitHub Actions CI （每次 push/PR 时进行类型检查、Lint、测试、构建），针对每次 schema 变更的 Alembic 迁移，用于类生产环境运行的 Docker + docker-compose。 ## 架构 ``` flowchart LR subgraph Client FE["React 19 + TypeScript\nTailwind · Socket.IO client"] end subgraph Backend["Flask API (routes → services → models)"] RT["Routes\nRBAC · pydantic validation"] SV["Services\nbusiness logic"] AI["AI Engine\nscikit-learn Isolation Forest\nper-user baseline"] DB[(PostgreSQL / SQLite)] end FE <-->|REST /api/v1 + WebSocket| RT RT --> SV SV --> DB SV -->|events| AI AI -->|risk + explanation| SV SV -->|live alert push| FE ``` ``` flowchart LR A["Employee action"] --> B["Event\n(immutable)"] B --> C["AI Engine\nper-user baseline"] C --> D["Risk score + explanation"] D --> E["Alert"] E --> F["Investigation\n(analyst opens)"] F -->|false positive| G["Closed"] F -->|confirmed| H["Incident Response\nseverity · escalate · contain · remediate · evidence"] H --> I["Resolved"] I --> J["Closed\n(full audit trail)"] ``` 后端分层（文档 [`13`](), [`14`]())：**路由（薄层） → 服务（业务逻辑） → 模型 ← 扩展**。横切关注点：RBAC 装饰器，pydantic 请求验证，集中式错误处理， 分页，实时 WebSocket 警报。 | 组件 | 技术栈 | |-----------|-------| | **后端 API** | Flask 3, SQLAlchemy, Flask-Migrate (Alembic), Flask-SocketIO, JWT (PyJWT), bcrypt, pydantic, flask-limiter | | **AI Engine** | scikit-learn (Isolation Forest), 按用户划分的基准特征 | | **前端** | React 19 + TypeScript, Tailwind CSS, React Router, Socket.IO 客户端 | | **数据库** | PostgreSQL (生产环境) · SQLite (开发环境) | | **部署** | Docker + docker-compose, gunicorn + gevent-websocket | | **CI** | GitHub Actions — pytest+覆盖率, pyflakes, tsc, Jest, 生产环境构建 | ## 快速开始（开发环境） ``` # Backend cd backend python -m venv venv && source venv/bin/activate pip install -r requirements.txt cp .env.example .env # fill in local values export FLASK_APP=run.py flask db upgrade # provision the full schema (migration-driven) python run.py # http://localhost:5000 # 可选：生成确定性的开发历史记录，以便 AI 有内容可评分 python scripts/dev_behavior_generator.py --seed 42 --scenario bulk_download # Frontend（新终端） cd frontend npm install npm start # http://localhost:3000 ``` 在 `/signup` 注册账户 —— 新注册者总是从 **Employee** 开始； 直接在数据库中将某个用户提升为 **Admin** 以解锁用户管理， 或者一旦您拥有任何管理员账户，即可通过 `PATCH /api/v1/admin/users//role` 提升。 ### 测试 ``` # Backend — 71 个测试，每次测试运行使用独立的临时 SQLite cd backend && pytest -q # add --cov=app for coverage # Frontend — 17 个测试 cd frontend && npm test -- --watchAll=false npx tsc --noEmit # typecheck npm run build # production build ``` ### 类生产环境（Docker） ``` docker compose up --build # backend :5000 + PostgreSQL 16 ``` ## API 概览 (`/api/v1`) | 领域 | 端点 | |------|-----------| | 认证 | `POST /auth/register`, `/login`, `/refresh` · `GET/PATCH /auth/profile` · `POST /auth/change-password`, `/auth/avatar` · `GET/DELETE /auth/sessions` | | AI | `POST /ai/analyze` (分析师/管理员) | | 仪表板 | `GET /dashboard/stats`, `/recent-events`, `/users//activity` | | 安全 | `GET /security/alerts`, `/high-risk-users`, `/baseline-coverage`, `/model-performance`, `/risk-trend` · `POST /security/alerts//investigations` | | 事件响应 | `GET/PATCH /security/investigations/` · `GET /security/incidents` · `POST .../severity`, `.../escalate`, `.../actions`, `.../evidence` · `GET /security/evidence//download` · `GET /security/admins` | | 工作区 | 针对以下内容的 CRUD 操作：`workspaces`, `projects`, `tasks`, `files` (真实上传/下载), `notes`, `messages` — 每次变更都会发出一个 Event | | 通知 | `GET /notifications`, `/unread-count` · `POST /notifications//read`, `/read-all` | | 隐私 | `GET /privacy/notice` · `GET /me/events`, `/me/events/export` | | 管理员 | `GET /admin/users` · `PATCH /admin/users//role` · `POST /admin/retention/purge` | 所有错误共享一种格式 `{error, details?}`；列表端点返回 `{items, pagination}`。 ## 角色（最小权限 —— [`docs/04`](docs/04-User-Roles.md)) - **员工 / 经理** — 工作区、聊天，仅限拥有自己的账户/数据。 - **安全分析师** — 安全仪表板、警报、事件；无工作区访问权限（职责分离）。 - **管理员** — 拥有所有权限，包括角色分配、数据保留和升级目标。 ## 人为安全 参见 [`docs/15`]()。透明度 通知、主体访问/导出、分析师操作审计、保留及 证据保全，以及严格的**无自动化惩处 —— 由人类决定** 原则，通过上述事件响应工作流进行端到端的强制执行。 ## 文档 `docs/01`–`docs/15` — 愿景、架构、数据库、API、前端、AI 引擎、部署、后端配置/扩展/结构，以及人工审查/ 合规性。`PROJECT_CONTEXT.md` 是一份原始的开发日志，供那些好奇该系统实际上是如何一步步构建的人参考 —— 它不是必读内容，仅仅是开发过程的记录。 ## 许可证 [MIT](LICENSE) © 2026 Mohammed Alagha

标签：Python, React, Syscalls, 内部威胁检测, 安全运营, 异常检测, 扫描框架, 无后门, 测试用例, 用户行为分析, 请求拦截