adhi-debug/The-Cyber-Sentinel-Saga-
GitHub: adhi-debug/The-Cyber-Sentinel-Saga-
一个基于规则与机器学习混合架构的实时 Web 日志威胁检测平台，通过 GeoIP 丰富与交互式仪表盘实现安全事件的自动发现与可视化。
Stars: 0 | Forks: 0
# 🎬 ** 赛博哨兵传奇**
## 🌌 概述
**The Cyber‑Sentinel Saga** 是一个**实时 AI 驱动的威胁检测引擎**，它能够接入 **Nginx access logs**，利用 **GeoIP** 智能丰富每一个请求，并运行一个**基于规则和机器学习模型的混合武器库**（Auto‑Encoder、Random‑Forest、Isolation‑Forest）。检测结果将流入 **PostgreSQL**，通过 **WebSocket** 进行广播，并在流畅的 **React + Vite** dashboard 上进行可视化展示。
```
Nginx Logs → Log Tailer → Parser → GeoIP Enrichment →
Rules + ML Models → Threat Score → PostgreSQL → WebSocket → Dashboard
```
## 🛠️ 前置条件 (Windows)
| 工具 | 最低版本 | 安装命令 |
|------|----------------|-----------------|
| **Python** | 3.12+ | 下载 |
## 🚀 快速开始 (无 Docker)
```
# 1️⃣ 克隆并导航
git clone https://github.com/adhi-debug/The-Cyber-Sentinel-Saga-.git
cd adi‑debug\backend
# 2️⃣ 创建并激活 virtual‑env
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # PowerShell
# .\.venv\Scripts\activate.bat # CMD
# 3️⃣ 安装 Python 依赖
pip install -U pip
pip install -e . # editable install pulls requirements
# 4️⃣ 准备 GeoIP DB（放置在 data 文件夹中）
mkdir ..\data\geoip
# 将 GeoLite2‑City.mmdb 复制到该文件夹中
# 5️⃣ 创建示例 Nginx log（或指向一个真实的 log）
mkdir ..\data\nginx
New-Item -Path ..\data\nginx\access.log -ItemType File
# 6️⃣ 配置环境变量（参见下方的 .env 示例）
Copy-Item .env.example .env
# 使用文本编辑器编辑 .env – 如有需要请调整路径
notepad .env
# 7️⃣ 启动 FastAPI 后端
python -m uvicorn app.main:app --reload
# → http://127.0.0.1:8000/health 应返回 {"status":"ok"}
# 8️⃣ 在一个*新*终端中，启动 UI
cd ..\frontend
npm install # first run only
npm run dev # → http://localhost:5173
```
### 📄 `.env` 示例 (节选)
```
ENV=development
DEBUG=true
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
PROJECT_ROOT=g:/PROJECT/temp/adi-debug
API_KEY=adi-debug-key
DATABASE_URL=
REDIS_URL=redis:
GEOIP_ACCOUNT_ID=
GEOIP_LICENSE_KEY=
GEOIP_DB_PATH=
NGINX_LOG_PATH=g:
MODEL_DIR=g:/PROJECT/temp/adi-debug/data/models
SKIP_AUTO_TRAIN=false
```
## 🧩 引擎内部机制
| 组件 | 用途 |
|-----------|---------|
| **LogTailer** | 异步跟踪 Nginx access log，将原始行输入到一个有界队列中。 |
| **Parser** | 提取 IP、HTTP method、URL、status code 和时间戳。 |
| **GeoIPService** | 使用 MaxMind DB 解析 IP → 国家/城市/ASN。 |
| **RuleEngine** | 快速、确定性的特征签名（例如，可疑的 URI 模式）。 |
| **InferenceEngine** *(可选)* | 加载 ONNX 模型 – Auto‑Encoder、Random‑Forest、Isolation‑Forest – 并对异常进行评分。 |
| **Pipeline** | 协调队列，应用丰富化处理，运行检测，并将警报推送给调度器。 |
| **AlertDispatcher** | 持久化威胁记录，将其写入 PostgreSQL，并通过 WebSocket 推送到 dashboard。 |
## 📚 模型重新训练 (1 秒魔法)
1. 将新的训练数据（CSV、Parquet 或 JSON）放入 `data/models/training/` 中。
2. 运行内置训练器：
cd backend
python -m app.scripts.retrain_models
3. 该脚本**会将 ONNX 产物重新导出**到 `data/models/` 中，并将 `skip_auto_train` 切换为 `false`。下一次推理周期会立即加载新的模型 —— 无需重启服务器。
## 🐞 常见陷阱与修复备忘录
| 症状 | 可能原因 | 修复方法 |
|---------|--------------|-----|
| **`ValidationError: project_root`** | `.env` 包含 `PROJECT_ROOT`，但 Settings 中没有对应的字段。 | 删除或注释掉该行，或者在 `config.py` 中添加 `project_root`。 |
| **后端已启动但 UI 为空** | 前端代理 URL 不匹配。 | 确保 `vite.config.ts` 指向 `http://localhost:8000`。 |
| **没有出现警报** | Log tailer 无法找到日志文件。 | 验证 `NGINX_LOG_PATH` 是否指向已存在的 `access.log`。 |
| **GeoIP 字段为空** | 缺少 `GeoLite2-City.mmdb`。 | 下载数据库，并将其放置在 `.env` 中定义的路径下。 |
| **模型未加载** | `data/models/` 为空或缺少 ONNX runtime。 | 安装 `onnxruntime`（`pip install onnxruntime`）并放置模型文件。 |
## 🏁 终局
随着 **adi‑debug** 的顺畅运行，你拥有了一个活跃的哨兵，它监视着每一个请求，为其描绘地理上下文，并瞬间对其威胁等级进行评分。扩展它、更换模型、添加自定义规则——你的安全故事只受限于想象力。
## 📜 许可证与致谢
- **许可证：** MIT – 详情请参阅 `LICENSE`。
- **作者：** **adhi‑debug** –
- **贡献者：** 开源社区，核心团队成员列于 `CONTRIBUTORS.md`。
*愿你的服务器保持安静，而你的警报响亮。*
winget install Python.Python.3.12 |
| **Node.js** | 20.x | winget install OpenJS.Nodejs |
| **npm** (内置) | — | — |
| **Docker Desktop** (可选) | 4.x | winget install Docker.DockerDesktop |
| **PostgreSQL** | 15.x | winget install PostgreSQL |
| **Redis** | 7.x | winget install Redis.Redis |
| **MaxMind GeoLite2** | – | 从 标签：AMSI绕过, Apex, 威胁检测, 安全, 搜索引擎查询, 机器学习, 测试用例, 请求拦截, 超时处理, 逆向工具