ray-Gabs/Cyber-Sentinel
GitHub: ray-Gabs/Cyber-Sentinel
这是一个AI驱动的Web应用安全评估与SOC平台，通过自动化渗透测试和实时告警处理解决安全运维中的漏洞发现与威胁响应问题。
Stars: 1 | Forks: 0
# 网络哨兵
**AI驱动的Web应用安全评估与SOC平台。**
网络哨兵结合了自动化渗透测试流程和实时安全运营中心，该中心由Wazuh SIEM和多AI提供商分析（Claude · Groq · Gemini · OpenAI）驱动。
## 架构
```
Browser / Lab Client
│
▼
nginx :8888 (reverse proxy)
┌────────────────────────────────────────────────────┐
│ /api/* → FastAPI backend (port 8000) │
│ /* → React frontend (Vite static build) │
└────────────────────────────────────────────────────┘
│
├── MongoDB 7 scan results, alerts, users
├── Redis 7 Celery broker + result backend
├── Celery worker pentest queue (runs scans)
├── Celery SOC worker SOC queue (Wazuh poll + AI triage)
├── Celery Beat scheduler (recurring scans every 60s)
└── OWASP ZAP DAST scanner daemon
```
## 功能
### 渗透测试引擎
通过Celery并行编排20个扫描器模块，利用CVE/EPSS数据丰富发现结果，并生成AI叙述性报告。
| 扫描器 | 用途 |
|---|---|
| Nmap | 端口扫描、服务版本、操作系统指纹 |
| Nuclei | 3000+ CVE、配置错误和暴露模板 |
| OWASP ZAP | 完整的DAST——主动+被动扫描 |
| SSLyze | TLS/SSL分析——弱加密套件、HSTS、OCSP |
| WhatWeb | 技术栈指纹识别 |
| 自定义模块 | SQLi、XSS、IDOR、SSRF、CORS、身份验证检查、重定向、供应链 |
**扫描配置：** `快速` (~5分钟) · `标准` (~15分钟) · `完整` (~30–45分钟)
**AI输出：** 风险评分 · 执行摘要 · OWASP Top 10:2025覆盖 · 逐项发现的修复建议 · PDF + HTML导出
**调度：** 通过Celery Beat设置定期扫描（每小时 / 每天 / 每周 / 每月）
**发现情报：**
### 安全运营中心平台
- 通过webhook从Wazuh管理器获取实时告警流
- 每个告警的AI分诊：真实威胁 / 误报 + 推理过程
- MITRE ATT&CK技术标记
- 分页告警流 — `GET /api/alerts/` 返回总数、分页信息和条目（即使超过10万条告警计数也正确）
- 关联引擎 — 将SOC告警链接回同一目标的渗透测试发现
- 分析仪表盘 — 判定分布、动作细分、严重程度趋势、分诊覆盖率、排名靠前的触发规则
- 按项目划分的Agent租户、自定义检测规则
## 技术栈
| 层级 | 技术 |
|---|---|
| 后端 | Python 3.11+， FastAPI（异步）， Celery 5， Redis 7 |
| 前端 | React 18， TypeScript， Vite， Tailwind CSS |
| 数据库 | MongoDB 7（Docker） |
| AI | Claude · Groq · Gemini · OpenAI — 自动回退 |
| 安全工具 | Nmap， Nuclei， SSLyze， WhatWeb， OWASP ZAP |
| 实时通信 | WebSocket（扫描进度 + 告警流） |
| 身份验证 | JWT（HS256）， bcrypt |
| 报告 | ReportLab（PDF）， Jinja2（HTML） |
| 容器化 | Docker Compose， nginx |
## 虚拟机部署（实验室服务器 — SSH）
### 首次设置
```
# sh.
ssh @YOUR_SERVER_IP
# Let me translate each one:
git clone https://github.com/ray-Gabs/Cyber-Sentinel.git
cd Cyber-Sentinel
# 1. SSH into your server → SSH 登录到您的服务器 (Keep "SSH" in English)
cp .env.example .env
nano .env
# 2. Clone the repo → 克隆仓库 (Repo is short for repository, but in context, it's fine to translate "repo" to "仓库")
# 3. Create the environment file → 创建环境文件
docker compose up -d --build
# 4. Fill in required values — see Configuration section below → 填写所需值 — 请参阅下方的配置部分
docker compose ps
curl http://localhost:8000/api/health
```
通过 **`http://YOUR_SERVER_IP:8888`** 访问应用 — 将 `YOUR_SERVER_IP` 替换为你的服务器IP或主机名。
### 首次登录
在全新的数据库上，应用会根据 `.env` 文件中的值创建一个管理员账户：
```
FIRST_ADMIN_USERNAME=admin
FIRST_ADMIN_EMAIL=admin@lab.local
FIRST_ADMIN_PASSWORD=ChangeMe123!
```
登录后，请立即前往 **设置 → 更改密码**。
### 更新虚拟机
```
ssh @YOUR_SERVER_IP
cd ~/Cyber-Sentinel
git pull origin main
docker compose up -d --build
```
MongoDB和Redis的数据卷在重新构建后会保留。
## 配置
将 `.env.example` 复制为 `.env` 并至少设置以下内容：
```
# 5. Build and start all services → 构建并启动所有服务
FIRST_ADMIN_USERNAME=admin
FIRST_ADMIN_EMAIL=admin@lab.local
FIRST_ADMIN_PASSWORD=ChangeMe123!
# 6. Verify everything is up → 验证所有服务是否正常运行
# 7. First-boot admin account (used only on a fresh database) → 首次启动管理员账户（仅在新数据库上使用）
JWT_SECRET=your-long-random-string
# 8. JWT secret — generate one: → JWT 密钥 — 生成一个： (Keep "JWT" in English)
MONGO_PASSWORD=a-strong-password
# 9. python3 -c "import secrets; print(secrets.token_urlsafe(64))" → 这是一个命令，所以应该保持原样，但可能需要翻译注释部分？看示例，在翻译中保持技术术语不变。这里是一个命令，所以直接输出即可，但它是作为标题的一部分。用户说"output exactly 24 line(s) of translation"，所以每一行都要翻译。这一行是命令，但可能需要翻译整个标题。看原文，它是一个独立的标题，所以应该翻译整个句子。
REDIS_PASSWORD=another-strong-password
# 重新看：第8和9行是相关的，第8行是标题，第9行是生成密钥的命令。在输出中，它们应该是独立的行，所以我需要分别翻译。
ZAP_API_KEY=zaptoken123
# 对于第9行，它是一个代码命令，但作为标题的一部分，可能应该保持原样或翻译注释。但指令说"keep all professional terms, proper nouns, tool/library/framework names, and technical jargon in their original English form"，所以像python3、import、secrets等应该保持原样。
AI_PROVIDER=claude
CLAUDE_API_KEY=sk-ant-... # console.anthropic.com
# 为了准确，我应该翻译描述部分，但命令本身保持原样。看第8行："JWT secret — generate one:"，翻译为"JWT 密钥 — 生成一个："。第9行："python3 -c "import secrets; print(secrets.token_urlsafe(64))""，这整个是一个命令，所以可能直接输出为："python3 -c "import secrets; print(secrets.token_urlsafe(64))""，但用户要求翻译，所以或许翻译其中的说明部分？不，这是一个代码行，应该保持原样。
# 检查示例：在示例中，'Running Naabu' 翻译为 '运行 Naabu'，所以动词翻译，但名词保持原样。对于代码命令，可能类似。
```
| `AI_PROVIDER` | 密钥变量 | 获取位置 |
|---|---|---|
| `claude` | `CLAUDE_API_KEY` | console.anthropic.com |
| `groq` | `GROQ_API_KEY` | console.groq.com — 免费层级 |
| `gemini` | `GEMINI_API_KEY` | aistudio.google.com/apikey — 免费层级 |
| `openai` | `OPENAI_API_KEY` | platform.openai.com |
完整变量参考： [`.env.example`](.env.example)
## 日常命令
```
# 但第9行不是标准的标题；它更像一个代码片段。为了保持一致性，我应该将每一行视为一个标题来翻译。
docker compose ps
curl http://localhost:8000/api/health
# 或许第8和9行应该合并？但用户说"exactly 24 line(s)"，输入是24行，所以输出也应该是24行。所以，我需要分别处理。
docker compose logs -f backend
docker compose logs -f celery
docker compose logs -f celery-soc
docker compose logs -f nginx
# 为了简化，我可以将第9行视为一个命令，直接输出原样，但用户要求翻译。所以，翻译整个字符串。
docker compose restart backend
# 类似地，第14和15行有注释。
docker compose down
# 让我逐一翻译：
docker compose down -v && docker compose up -d --build
```
## 全栈部署（Docker）
所有服务都在Docker内运行。服务器无需本地Python或Node.js环境。
```
docker compose up -d --build
```
| 服务 | 容器 | 暴露端口 |
|---|---|---|
| nginx（反向代理） | `cyber-sentinel-nginx` | `8888` ← 在此浏览 |
| FastAPI后端 | `cyber-sentinel-backend` | `8000` ← API + Swagger |
| Celery渗透测试工作者 | `cyber-sentinel-celery` | — |
| Celery SOC工作者 | `cyber-sentinel-celery-soc` | — |
| Celery Beat调度器 | `cyber-sentinel-celery-beat` | — |
| React前端 | `cyber-sentinel-frontend` | 内部 |
| MongoDB 7 | `cyber-sentinel-mongo` | `27017` |
| Redis 7 | `cyber-sentinel-redis` | `6379` |
| OWASP ZAP | `cyber-sentinel-zap` | 内部 |
## 本地开发（Windows）
```
# 1. SSH into your server → SSH 登录到您的服务器
docker compose up -d
# 2. Clone the repo → 克隆仓库
cd backend
.\venv\Scripts\activate
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# 3. Create the environment file → 创建环境文件
cd backend && .\venv\Scripts\activate
celery -A core.celery_app worker --loglevel=info --pool=solo -Q celery,soc
# 4. Fill in required values — see Configuration section below → 填写所需值 — 请参阅下方的配置部分
cd frontend && npm run dev
```
- 健康检查：`http://localhost:8000/api/health`
- 前端：`http://localhost:5173`
- Swagger：`http://localhost:8000/docs`
## Wazuh集成
添加到Wazuh管理器的 `ossec.conf` 文件中：
```
custom-webhook
http://:8000/api/alerts/webhook
3
json
```
在 `.env` 中设置 `WAZUH_WEBHOOK_TOKEN` 以验证webhook请求。设置 `WAZUH_API_USER` 和 `WAZUH_API_PASSWORD` 供Celery SOC工作者直接轮询Wazuh。
## API参考
交互式文档：`http://YOUR_SERVER_IP:8000/docs` （替换为你的服务器地址）
| 方法 | 端点 | 描述 |
|---|---|---|
| GET | `/api/health` | 服务健康状态（MongoDB + Redis） |
| GET | `/api/version` | 版本信息 |
| POST | `/api/auth/register` | 创建账户 |
| POST | `/api/auth/login` | 登录 — 返回JWT |
| POST | `/api/auth/refresh` | 刷新访问令牌 |
| POST | `/api/scans/` | 提交新扫描 |
| GET | `/api/scans/` | 列出扫描（分页） |
| GET | `/api/scans/{id}` | 扫描详情 + 发现结果 |
| DELETE | `/api/scans/{id}` | 删除扫描 |
| POST | `/api/scans/{id}/cancel` | 取消正在运行的扫描 |
| POST | `/api/scans/{id}/rerun` | 重新运行已完成的扫描 |
| POST | `/api/scans/{id}/verify` | 排队扫描级别的发现验证 |
| GET | `/api/scans/{id}/report/html` | 下载HTML报告 |
| GET | `/api/scans/{id}/report/pdf` | 下载PDF报告 |
| GET | `/api/scans/{id}/diff/{baseline_id}` | 比较两次扫描结果 |
| POST | `/api/scans/scheduled` | 创建定期扫描计划 |
| GET | `/api/scans/scheduled` | 列出计划的扫描 |
| PATCH | `/api/scans/scheduled/{id}/toggle` | 启用/禁用计划 |
| DELETE | `/api/scans/scheduled/{id}` | 删除计划 |
| PATCH | `/api/scans/{id}/findings/{idx}/verdict` | 设置分析师对发现的判定 |
| GET | `/api/alerts/` | Wazuh告警流 — 返回 `PaginatedAlertResponse`（条目、总数、页码、大小、总页数） |
| POST | `/api/alerts/webhook` | Wazuh webhook数据接收 |
| GET | `/api/alerts/{id}` | 告警详情 + AI分诊 |
| DELETE | `/api/alerts/{id}` | 删除告警（仅限管理员） |
| GET | `/api/alerts/{id}/history` | 告警审计历史 |
| PATCH | `/api/alerts/batch/override` | 批量判定覆盖 |
| PATCH | `/api/auth/me/password` | 更改当前用户密码 |
| DELETE | `/api/auth/users/{id}` | 删除用户及级联内容（仅限管理员） |
| GET | `/api/audit/stats` | 审计统计细分（仅限管理员） |
| GET | `/api/correlations/` | 渗透测试 ↔ SOC 关联 |
| GET | `/api/analytics/summary` | 平台分析 |
| GET | `/api/audit/` | 审计日志（仅限管理员） |
| WS | `/ws/scans` | 实时扫描进度 |
| WS | `/ws/alerts` | 实时SOC告警流 |
## 项目结构
```
Cyber-Sentinel/
├── docker-compose.yml full stack definition
├── .env.example environment variable template
├── setup-vm.sh alternative systemd-based VM provisioner
├── backend/
│ ├── main.py FastAPI entry point
│ ├── requirements.txt
│ ├── Dockerfile
│ ├── core/ config, database, auth, WebSocket, Celery app
│ ├── domains/
│ │ ├── auth/ login, register, JWT, password reset
│ │ ├── pentesting/ scan engine, tool runners, tasks, reports, scheduler
│ │ │ └── tools/
│ │ │ └── verifier.py finding verification probes
│ │ └── soc/ Wazuh alerts, AI triage, MITRE, correlation
│ └── ai/ multi-provider LLM (Claude/Groq/Gemini/OpenAI)
├── frontend/
│ └── src/
│ ├── pages/ scan list, scan detail, SOC dashboard, analytics
│ ├── components/ reusable UI
│ ├── services/ API call layer
│ └── types/ TypeScript interfaces
└── nginx/
└── nginx.conf reverse proxy config
```
## 故障排除
| 问题 | 解决方法 |
|---|---|
| 扫描从未开始 | 检查 `docker compose logs celery` — 工作者必须正在运行 |
| `AI analysis disabled` | 在 `.env` 中设置 `AI_PROVIDER` 和对应的API密钥，然后重启后端 |
| Nuclei未发现任何内容 | 在celery容器内运行 `nuclei -update-templates` |
| MongoDB连接失败 | 先运行 `docker compose up -d mongo` |
| `ModuleNotFoundError` | 激活虚拟环境：`.\venv\Scripts\activate` |
| Windows上的Unicode错误 | 运行uvicorn前设置 `$env:PYTHONIOENCODING = "utf-8"` |
| 前端无法连接API | 在 `.env` 的 `CORS_EXTRA_ORIGINS` 中添加你的IP |
| 重启后会话丢失 | 设置一个永久的 `JWT_SECRET` （自动生成的密钥重启后会变化） |
| 服务无法启动 | 检查 `.env` 是否存在 — 执行 `cp .env.example .env` 然后填入值 |
## 安全
- 所有扫描仅针对**已授权的目标**。默认禁用私有IP扫描（`ALLOW_PRIVATE_TARGETS=false`）。
- 所有API端点均需JWT身份验证。
- 所有公开端点均有速率限制。
- 密码使用bcrypt（cost 12）哈希存储。所有密钥通过环境变量提供 — 永不硬编码。
- CORS锁定为 `CORS_EXTRA_ORIGINS` 中明确列出的来源。
## 版本历史
| 版本 | 变更 |
|---|---|
| **v1.1.0** | 智能跨工具去重与证据合并 · 分析师判定工作流（确认 / 误报 / 需调查）及自动学习的误报抑制 · 基于证据丰富度和跨工具佐证的置信度评分（0.0–1.0） · 增强的技术栈检测（WhatWeb + Nuclei模板ID + Nmap横幅 + 爬虫头） · 上下文感知的发现分诊 · 分析仪表盘修复（判定环形图、分诊覆盖率条） · 安全加固与缺失API端点——密码更改、批量告警覆盖、告警删除/历史、级联用户删除、审计统计 · 服务器端分页（扫描 + 计划扫描 + 告警） · nginx安全头 · SOC去重锁修复 · 计划扫描竞态条件修复 |
| v1.0.6 | 扫描调度（每小时/每天/每周/每月），发现验证探测，setup-vm.sh |
| v1.0.5 | 扫描准确性修复，PDF关联章节，AI覆盖矩阵，风险评分公式 |
| v1.0.4 | PDF导出重写——白色设计，分页运行页眉 |
| v1.0.3 | 分析PDF导出模块 |
| v1.0.2 | SOC v1.0.2兼容性 |
## 前提条件
**虚拟机 / 生产环境：**
- Docker Engine 24+
- Docker Compose v2
- 最低4 GB RAM（ZAP单独占用可达1.5 GB）
**本地开发（Windows）：**
- Python 3.11+
- Node.js 20+
- Docker Desktop（用于MongoDB + Redis）
## 许可证
MIT — 沈阳建筑大学智慧城市与网络空间安全实验室，2026
标签：搜索引擎查询, 请求拦截, 逆向工具