# DNetX [V10]
## 自主安全编排与响应平台
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://docs.docker.com/compose/)
[](https://suricata.io/)
[](https://wazuh.com/)
[](https://attack.mitre.org/)
[](LICENSE)
[](#testing)
### 平台概览仪表板
## 核心亮点
- **自主 SOAR 平台** — 自动化响应剧本 (`block_ip`, `isolate_host`, `notify_analyst`)，具备模拟模式和持久化审计日志
- **多源威胁关联** — 跨网络 IDS (Suricata)、端点 EDR (Wazuh)、Sysmon、Zeek 和通用 SIEM 源的实时遥测数据关联
- **签名 + 行为 + ML 检测** — 结合签名规则、行为基线、统计异常评分和 ML 风险回归的多层检测 pipeline
- **在线机器学习** — 内置 MLOps pipeline，采用在线随机梯度下降 (SGD)，根据分析师反馈实时进行模型重训练
- **MITRE ATT&CK 映射** — 为每个告警和关联事件自动标注技术、战术和 kill-chain 阶段
- **可解释 AI** — 类线性 SHAP 的特征归因，为透明的分析师分类提供前 3 大风险驱动因素
- **调查自动化** — 通过 GPT-4o 或 Gemini 1.5 Flash 生成 AI 威胁叙述、攻击时间线和补救建议
- **基于 Docker 的部署** — 8 容器微服务拓扑，可通过单个 `docker compose up` 命令进行部署
- **REST + WebSocket API** — 包含 40 多个端点的综合 REST API，具备三层 RBAC 和 2 秒实时的 WebSocket 实时流
- **实时仪表板** — 交互式浏览器 SPA，包含图表小部件、告警源、调查工作室和 MITRE ATT&CK 热力图
## 目录
- [概述](#overview)
- [平台架构](#platform-architecture)
- [检测 Pipeline](#detection-pipeline)
- [机器学习 Pipeline](#machine-learning-pipeline)
- [Docker 部署](#docker-deployment)
- [仪表板预览](#dashboard-gallery)
- [功能矩阵](#feature-matrix)
- [技术栈](#technology-stack)
- [目录结构](#directory-structure)
- [快速开始](#quick-start)
- [安装](#installation)
- [配置](#configuration)
- [API 概览](#api-overview)
- [安全模型](#security-model)
- [性能](#performance)
- [测试](#testing)
- [路线图](#roadmap)
- [贡献](#contributing)
- [许可证](#license)
- [致谢](#acknowledgements)
## 概述
### 问题所在
现代安全运营中心 (SOC) 面临着关键的工具悖论。企业级 SIEM 和 XDR 平台（Splunk、Elastic Security、Microsoft Sentinel、CrowdStrike）昂贵且不透明。开源替代方案——Suricata、Wazuh、MISP——以**孤岛**形式存在。安全分析师需跨多个仪表板手动关联事件，对成千上万条低质量告警进行分类，并手工编写调查报告。这导致了：
- **告警疲劳** — 成千上万条未关联的告警，缺乏优先级事件视图
- **MTTD 以天计**，而不是分钟
- **零预测能力** — 无法预测攻击者的下一步行动
- **人工调查瓶颈** — 分析师需从原始日志中创建报告
- **无闭环学习** — 检测模型从未根据分析师反馈进行改进
### DNetX 解决方案
DNetX 是位于原始检测工具之上的**统一智能层**：
1. 从所有来源**摄取、规范化和关联**事件，将其汇聚为统一的 `CanonicalEvent` schema
2. **应用多层检测** — 同时执行签名、行为基线、ML 评分和链式关联
3. 通过在 14 阶段 MITRE ATT&CK kill-chain 图上的马尔可夫链模型**预测攻击者的下一步行动**
4. 通过 GPT-4o 或 Gemini 1.5 Flash **自动生成调查报告**
5. 对关联的事件执行 **SOAR 剧本** (阻断 IP、隔离主机、通知 SOC)
6. **闭合学习环** — 分析师的反馈会实时训练 ML 引擎
## 平台架构
DNetX 采用高吞吐量、事件驱动的架构，旨在实时处理、丰富和关联安全事件。核心引擎围绕内部基于 SQLite 的 pub/sub 消息总线构建，在统一的操作环境中编排摄取、多层威胁检测、在线机器学习、攻击路径预测和自动化响应。
DNetX 是一个由 Docker Compose 编排的**事件驱动微服务网格**。核心智能在单个 Python 进程 (`sentrix-core`) 内运行，作为并发后台线程，通过内部 SQLite pub/sub 事件总线进行通信 — 无需外部 broker。
### 内部事件总线 Topic
| Topic | 发布者 | 订阅者 |
|---|---|---|
| `events.raw` | 摄取路由 | 威胁引擎 |
| `events.alerts` | 威胁引擎 | 关联引擎、预测引擎 |
| `incidents.correlated` | 关联引擎 | 调查工作室、SOAR 引擎、ML 引擎 |
| `soar.trigger` | SOAR 引擎 | SOAR Worker 池 (4 个线程) |
## 检测 Pipeline
进入 DNetX 的事件将经历严格的 6 阶段生命周期 — 从原始遥测摄取和 schema 验证到规范化、丰富、多层检测以及自动化告警发布。大容量告警在滑动时间窗口内进行关联，以构建可操作的事件图。
每个入站事件都会在 `SentrixThreatEngine` 中经过六个连续阶段的处理：
```
STAGE 1 - RAW INGEST
Collector POSTs raw log to /api/v1/threat/events/ingest
Source type auto-detected (suricata | wazuh | generic)
Collector health heartbeat updated in events.db
STAGE 2 - SCHEMA VALIDATION
TelemetryValidator checks required fields and types
Invalid events routed to Dead Letter Queue (DLQ)
Audit log entry written for every rejected event
STAGE 3 - CANONICAL NORMALISATION
Source-specific plugin normalises to CanonicalEvent Pydantic schema
Supported sources: Wazuh, Suricata, Sysmon, Zeek, Generic SIEM
All 17 typed fields populated (source, destination, user, process, etc.)
STAGE 4 - ENRICHMENT
MITRE technique ID mapped to tactic and kill-chain stage
Threat intel connectors queried (AbuseIPDB, VirusTotal, GeoIP, Shodan)
IOC repository cross-referenced for known malicious indicators
STAGE 5 - THREAT DETECTION
Suppression check (IP whitelist / maintenance window)
Signature rule evaluation (equals, contains, greater_than, regex, sequence)
Behavioural detector evaluates baseline deviation
Anomaly detector scores statistical outliers
ML Engine: 26-feature extraction -> risk score + threat category + explainability
Threshold engine: time-windowed count-based alert correlation
Sequence engine: ordered event sequence matching
Attack chain engine: multi-source incident correlation
STAGE 6 - ALERT GENERATION AND PUBLICATION
Alert written to events.db alerts table
Alert published to EventBus on events.alerts topic
Subscribers triggered: PredictionEngine, CorrelationEngine
```
### 关联与事件提升
当满足以下条件时，`CorrelationEngine` 会将告警桶提升为关联事件：
- 在 5 分钟的滑动窗口内，来自同一源 IP 的告警数量 >= 3，或
- 同一攻击者发出的 Suricata + Wazuh 告警出现在同一个桶中（多源关联）
提升的事件将触发：ML 引擎丰富、AI 调查工作室和 SOAR 引擎。
## 机器学习 Pipeline
DNetX 包含一个连续的、内置的 MLOps pipeline，具备实时风险评分、威胁类别分类和在线模型更新功能。通过利用实时随机梯度下降 (SGD) 和事件解决时的分析师反馈，检测模型能够通过自动化的漂移监控和检查点回滚功能动态适应新的威胁向量。
DNetX 实现了带有在线学习的内置 MLOps pipeline。无需批处理作业、无需数据湖、无需外部 MLflow 服务器。
### 特征工程 (26 个特征)
```
Severity Features : severity_score (normalised 0.0-1.0)
Protocol Features : is_tcp, is_udp, is_icmp, is_http (one-hot encoded)
Network Features : src_port_normalized, dst_port_normalized
Asset Features : asset_criticality (from enrichment metadata)
Historical Features : historical_alert_count, average_historical_risk
Reputation Features : reputation_score (from AbuseIPDB / VirusTotal)
MITRE Tactic Flags : tactic_Reconnaissance ... tactic_Impact (14 binary flags)
```
### 模型架构
| 模型 | 算法 | 输出 |
|---|---|---|
| 风险评分器 | 在线 Ridge SGD 回归 | 风险评分 0-100 |
| 威胁分类器 | 在线 Logistic SGD 多分类 | 威胁类别标签 |
| 异常检测器 | 在线统计流检测器 | 异常评分 |
| 攻击预测器 | 马尔可夫链转换模型 | 下一 kill-chain 阶段 |
### MLOps 生命周期
```
Model bootstrapped at v1.0.0 on first startup
|
v
Live events -> Feature extraction -> Inference -> Results to UI + explainability
|
v
Analyst closes incident -> Labeled sample submitted to learning queue
|
v
OnlineLearningWorker (background thread) dequeues sample
|
+-- Clone active model state (serialised deep copy)
+-- Apply SGD weight update (train_step)
+-- Evaluate on validation cache (last 200 samples)
+-- If accuracy improves: promote candidate, write checkpoint
+-- If accuracy drops: rollback to previous checkpoint
```
所有版本均注册在 `registry.db` 中，包含算法、特征 schema 哈希、准确性指标、检查点路径、部署状态和提升审计追踪。
## Docker 部署
平台通过 Docker Compose 容器化为 8 服务拓扑，旨在实现模块化隔离和安全性。目标攻击环境和漏洞扫描程序在具有严格通信边界的专用 bridge 网络上运行，在保护内部平台服务的同时确保无缝的遥测收集。
### 容器拓扑
| 容器 | 镜像 | 用途 | 端口 |
|---|---|---|---|
| `sentrix-dvwa-db` | `mysql:5.7` | DVWA 数据库（隔离网络） | 内部 |
| `sentrix-dvwa` | `ghcr.io/digininja/dvwa:latest` | 易受攻击的 Web 攻击目标 | 8080 |
| `sentrix-suricata` | `jasonish/suricata:latest` | DVWA namespace 上的被动 IDS sidecar | — |
| `sentrix-wazuh` | `wazuh/wazuh-manager:4.7.5` | EDR 事件聚合 | 55000 |
| `sentrix-core` | `sentrix-core:v10` | FastAPI SOC 智能平台 | 8000 |
| `sentrix-suricata-collector` | `sentrix-core:v10` | 跟踪 eve.json 并转发至核心 | — |
| `sentrix-wazuh-collector` | `sentrix-core:v10` | 跟踪 alerts.json 并转发至核心 | — |
| `sentrix-dashboard` | `nginx:alpine` | 仪表板 UI 和 API 反向代理 | 80 |
### 网络隔离
```
dvwa-net (172.21.0.0/16) -- DVWA app and MySQL (isolated from SOC)
sentrix-net (172.20.0.0/16) -- Core, collectors, Wazuh, Nginx
```
Suricata 共享 DVWA 网络 namespace (`network_mode: service:dvwa`)，无需 host 网络模式即可捕获所有目标流量。
### 内存限制
| 容器 | 限制 |
|---|---|
| `sentrix-core` | 2 GB |
| `sentrix-wazuh` | 1 GB |
| `sentrix-dvwa-db` | 512 MB |
| 所有 collector 和仪表板 | 各 256 MB |
### 密钥管理
凭据在容器运行时通过 Docker Compose Secrets 从 `secrets/` 挂载到每个容器内的 `/run/secrets/` 中。环境变量定义、Dockerfile 层或镜像构建历史中均不会出现任何密钥。
```
docker compose ps # View container status
docker compose logs -f sentrix-core # Follow core engine logs
docker compose down -v # Stop and remove volumes
```
### 预置扩展
compose 文件包含了 Prometheus、Grafana、Elasticsearch、Kibana 和 Zeek 等随时可取消注释的定义。
## 仪表板预览
## 功能矩阵
### 核心检测引擎
| 功能 | 描述 |
|---|---|
| 多源摄取 | 为 Suricata、Wazuh、Sysmon、Zeek 和通用 SIEM payload 提供统一的 HTTP 摄取 |
| 规范化归一 | 基于插件的正则化器将所有源映射到强类型的 `CanonicalEvent` Pydantic schema |
| Schema 验证 + DLQ | 入站遥测验证，并为被拒绝的事件提供 Dead Letter Queue |
| 基于签名的检测 | JSON 规则定义，支持字段匹配、阈值条件和序列模式 |
| 行为检测 | 跨源 IP 行为配置文件的统计基线偏差检测 |
| 异常检测 | 针对异常网络遥测数据的流式统计异常评分 |
| 攻击链关联 | 5 分钟滑动窗口内的多源告警关联 |
| MITRE ATT&CK 映射 | 为每个告警自动标注技术 (T-ID -> 战术 -> 阶段) |
| IOC 库 | 包含 IP、domain、hash 的 IOC 数据库，支持实时丰富查询 |
| 告警抑制 | IP/CIDR 白名单、主机抑制、规则抑制和维护窗口 |
| 规则热重载 | 通过 watchdog 文件系统监视器实现零停机规则重载 |
| 危机模式 | 用于活跃事件响应的检测灵敏度提升模式 |
### 机器学习引擎
| 功能 | 描述 |
|---|---|
| 26 特征 Pipeline | 严重性、协议、端口、资产关键性、历史上下文、MITRE 战术标志 |
| 在线风险评分器 | Ridge SGD 回归 — 0-100 风险评分，根据分析师反馈进行更新 |
| 威胁分类器 | 用于威胁类别标记的在线 Logistic SGD 多类分类器 |
| 异常检测器 | 具有可配置灵敏度的在线流式异常检测器 |
| 漂移检测 | 基于 PSI 的模型漂移监视器，带有自动回滚触发器 |
| 版本化模型注册表 | 具有 candidate/active/retired 生命周期状态的 SQLite 注册表 |
| 原子检查点 | 带有特征 schema 版本哈希的序列化点写入 |
| 分析师反馈循环 | 事件解决触发带标签的 SGD 权重更新 |
| 可解释性 | 线性类 SHAP 归因 — 将前 3 大贡献特征返回给 UI |
| 攻击预测器 | 用于 kill-chain 阶段预测的在线马尔可夫转换预测器 |
### 预测引擎
| 功能 | 描述 |
|---|---|
| 14 阶段攻击图 | 完整的 MITRE ATT&CK kill-chain 有向转换图 |
| 马尔可夫链预测 | 根据攻击者当前位置进行概率性的下一阶段预测 |
| 攻击路径跟踪 | 每个攻击者 IP 的注册表，跟踪所有观察到的 kill-chain 阶段 |
| 活动分类 | 将多阶段活动映射到活动原型的启发式分类器 |
| 沦陷概率 | 每个活跃攻击者的综合沦陷概率得分 |
### 调查与响应
| 功能 | 描述 |
|---|---|
| AI 调查报告 | 威胁叙述、攻击时间线和补救建议 (GPT-4o 或 Gemini) |
| PDF 和 JSON 导出 | ReportLab PDF 导出和结构化的 JSON 调查报告输出 |
| 案例管理 | 完整的 CRUD 工单生命周期 (打开 -> 进行中 -> 已解决) 并带有分析师分配功能 |
| 证据图 | 基于 SQLite 的证据关系图，将告警链接到事件 |
| SOAR 引擎 | 4-Worker 异步剧本队列：`block_ip`, `isolate_host`, `notify_analyst` |
| 模拟模式 | SOAR 操作默认处于模拟状态 — 防止意外对网络产生实际更改 |
| 完整审计追踪 | 每个 SOAR 操作都记录有时间戳、目标、状态和模式 |
### 平台与可观测性
| 功能 | 描述 |
|---|---|
| 实时仪表板 | 基于 Web 浏览器的 SOC 仪表板，带有图表小部件、告警源和 MITRE 热力图 |
| WebSocket 实时推送 | `/ws/live` 每 2 秒向连接的浏览器推送事件、告警和 KPI |
| 连接器框架 | 用于 AbuseIPDB、VirusTotal、Shodan、GeoIP 和自定义源推送的插件架构 |
| 规则工作室 API | 用于自定义检测规则的 REST CRUD，具备测试触发功能 |
| Pipeline 追踪 | `/api/v1/trace/{event_id}` 返回任何事件的完整生命周期追踪 |
| 安全知识库 | 内置剧本、MITRE 战术索引、严重性分类器和建议 |
| Metrics 端点 | `/metrics` 返回实时的规则延迟、无效事件计数和连接器健康状况 |
## 技术栈
### 后端
| 组件 | 技术 | 用途 |
|---|---|---|
| API 框架 | FastAPI 0.111 + Uvicorn 0.30 | 异步 HTTP 和 WebSocket 服务器 |
| 数据模型 | Pydantic v2 + Pydantic-Settings | 强类型 schema 和环境配置 |
| 身份验证 | python-jose (JWT HS256) + API Key | 具有三层 RBAC 的双模式身份验证 |
| PDF 报告 | ReportLab 4.2 | 调查报告 PDF 生成 |
| 持久化 | SQLite (WAL 模式，30 秒 busy-timeout) | 全部 6 个平台数据库 |
| ML 与数值计算 | NumPy >= 1.26 | 在线 SGD 权重向量和特征数组 |
| 文件监视 | Watchdog 4.0 | 规则热重载文件系统事件监视 |
| HTTP 客户端 | Requests 2.32 | 威胁情报丰富 API 调用 |
| YAML | PyYAML 6.0 | Suricata 配置和知识库数据 |
### AI 集成
| 提供商 | 模型 | 激活方式 |
|---|---|---|
| OpenAI | GPT-4o (temperature 0.3) | 设置 `OPENAI_API_KEY` |
| Google | Gemini 1.5 Flash | 设置 `GEMINI_API_KEY` |
| 模拟 | 基于模板的 mock | 当不存在 AI 密钥时自动激活 |
即使没有 AI 密钥，平台也能完全运行。所有检测、ML 评分和 SOAR 功能均不受 AI 提供商可用性的影响。
### 基础设施
| 组件 | 技术 | 用途 |
|---|---|---|
| 容器运行时 | Docker + Docker Compose v2 | 8 服务编排 |
| IDS | Suricata (jasonish/suricata:latest) | 网络数据包检查 |
| EDR | Wazuh Manager 4.7.5 | 端点检测与响应 |
| 攻击目标 | DVWA (ghcr.io/digininja/dvwa) | 真实的易受攻击的 Web 应用程序 |
| 前端服务器 | Nginx Alpine | 静态资源服务和 API 反向代理 |
| DVWA 数据库 | MySQL 5.7 | 隔离的 DVWA 应用程序数据库 |
| 密钥 | Docker Compose Secrets (文件支持) | API 密钥、JWT 密钥、数据库密码 |
## 目录结构
```
mini-soc-defense-platform/
|
+-- main.py <- FastAPI entrypoint and engine lifecycle
+-- docker-compose.yml <- 8-container orchestration definition
+-- Dockerfile <- Python 3.14-slim container image
+-- requirements.txt <- Pinned production dependencies
+-- .env.example <- Environment variable template
|
+-- dashboard/ <- Frontend served by Nginx
| +-- index.html <- Full-featured SOC dashboard SPA
| +-- nginx.conf <- API and WebSocket reverse proxy config
|
+-- suricata/ <- Network IDS configuration
| +-- suricata.yaml <- Suricata sniffer configuration
| +-- rules/
| +-- 01_local.rules <- Custom local signatures
| +-- 02_web.rules <- HTTP vulnerability detection
| +-- 03_recon.rules <- Port scan detection
| +-- 04_exploit.rules <- RCE and injection signatures
| +-- 05_malware.rules <- Malware payload patterns
| +-- 06_bruteforce.rules <- SSH/FTP credential stuffing
| +-- 07_dns.rules <- DNS tunneling detection
| +-- 08_tls.rules <- TLS handshake anomalies
| +-- 09_protocol.rules <- Protocol abuse detection
| +-- 10_c2.rules <- Command and Control beacon signatures
|
+-- validation/ <- Integration and validation tests
| +-- test_sentrix_v8.py <- 22-test core validation suite
| +-- test_e2e_pipeline.py <- End-to-end ingest to incident test
| +-- test_sentrix_v7.py <- Live endpoint regression tests
| +-- test_soar_engine.py <- SOAR playbook audit tests
| +-- test_queue_retry.py <- DLQ and retry logic tests
| +-- test_correlation_persist.py <- Correlation chain DB persistence
| +-- test_asset_context.py <- Asset risk profiling tests
|
+-- scripts/
| +-- generate_certs.py <- TLS certificate generation utility
| +-- inspect_db.py <- Database inspection helper
|
+-- sentrix_core/ <- Core platform Python package
+-- ai_layer/ <- AI provider factory (GPT-4o/Gemini/Dummy)
+-- api/ <- FastAPI route handlers (14 routers)
+-- case_management/ <- Ticket CRUD and lifecycle management
+-- collectors/ <- Suricata and Wazuh log tail agents
+-- config/ <- Centralised pydantic-settings configuration
+-- connector_framework/ <- Plugin framework plus 8 enrichment connectors
+-- enrichment/ <- MITRE mapping and threat intel enricher
+-- event_bus/ <- SQLite pub/sub broker and DLQ worker
+-- investigation_engine/ <- AI report builder, job queue, case exporter
+-- knowledge/ <- Security knowledge base (playbooks, MITRE)
+-- metrics/ <- Latency and count telemetry collector
+-- ml_engine/ <- Full MLOps pipeline (25 modules)
+-- normalization/ <- Multi-source canonical normalisation plugins
+-- prediction_engine/ <- Markov attack path and campaign classifier
+-- prediction_intelligence/ <- Knowledge-enriched prediction layer
+-- reporting/ <- PDF and JSON report renderer
+-- response_engine/ <- SOAR playbook engine (4-worker async)
+-- rule_define_studio/ <- Rule CRUD, default pack, hot-reload watcher
+-- security/ <- JWT auth, API key auth, RBAC
+-- storage/ <- EventStore (central SQLite helper, 17 tables)
+-- suppression/ <- Alert suppression (IP, host, rule, window)
+-- threat_engine/ <- Primary detection orchestrator (15 sub-modules)
+-- threat_intel/ <- IOC repository
```
## 快速开始
### 前置条件
- Docker >= 24.0 和 Docker Compose v2
- 最少 4 GB 内存（推荐 8 GB）
- 可用的端口 80、8000、8080 和 55000
### 1. 克隆并配置
```
git clone https://github.com/your-org/dnetx-platform.git
cd dnetx-platform
cp .env.example .env
```
### 2. 创建密钥
```
mkdir -p secrets
echo "your-strong-api-key-here" > secrets/sentrix_api_key.txt
echo "your-jwt-secret-32chars+" > secrets/jwt_secret_key.txt
echo "rootpassword" > secrets/db_root_password.txt
echo "dvwapassword" > secrets/db_password.txt
echo "wazuh-api-password" > secrets/wazuh_api_password.txt
```
### 3. 启动平台
```
docker compose up -d
```
所有 8 个容器启动。请等待约 60 秒让 Wazuh 初始化。
### 4. 打开仪表板
导航至 **http://localhost** — SOC 仪表板会显示实时事件源、告警表、MITRE 热力图、预测小部件和调查报告。
### 5. 访问 API
```
curl http://localhost:8000/ready
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/dashboard/alerts
# 交互式 API 文档位于 http://localhost:8000/docs
```
## 安装
### 本地开发（不使用 Docker）
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export SENTRIX_API_KEY="dev-key"
export JWT_SECRET_KEY="dev-secret-32-chars-minimum!!"
export DATA_DIR="./data"
export SENTRIX_AUTH_ENABLED="false"
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
### 可选的 AI 提供商依赖
```
pip install openai # GPT-4o investigation reports
pip install google-generativeai # Gemini 1.5 Flash reports
```
## 配置
将 `.env.example` 复制到 `.env`。关键变量：
### 平台安全
| 变量 | 必需 | 描述 |
|---|---|---|
| `SENTRIX_API_KEY` | 是 | 用于 collector 和外部身份验证的主 API 密钥 |
| `JWT_SECRET_KEY` | 是 | JWT HS256 签名密钥（最少 32 个字符） |
| `SENTRIX_AUTH_ENABLED` | 否 | 全局身份验证执行开关（默认：`true`） |
### AI 集成
| 变量 | 描述 |
|---|---|
| `OPENAI_API_KEY` | 用于 GPT-4o 调查报告的 OpenAI API 密钥 |
| `GEMINI_API_KEY` | 用于 Gemini 1.5 Flash 报告的 Google AI API 密钥 |
### 威胁情报连接器
| 变量 | 描述 |
|---|---|
| `VIRUSTOTAL_API_KEY` | VirusTotal IOC 丰富 |
| `ABUSEIPDB_API_KEY` | AbuseIPDB IP 信誉评分 |
| `SHODAN_API_KEY` | Shodan 主机情报 |
| `GEOIP_API_KEY` | 地理 IP 解析 |
| `CUSTOM_FEED_URL` | 自定义 JSON 威胁情报源 URL |
### 基础设施
| 变量 | 默认值 | 描述 |
|---|---|---|
| `DATA_DIR` | `/data` | 用于所有持久化数据库的容器路径 |
| `LOG_LEVEL` | `INFO` | 应用程序日志详细程度 |
| `HOST` | `0.0.0.0` | Uvicorn 绑定地址 |
| `PORT` | `8000` | Uvicorn 监听端口 |
## API 概览
平台在 `/api/v1/` 暴露版本化的 REST API，并在 `/ws/live` 提供 WebSocket 推送。
### 身份验证
```
GET /api/v1/dashboard/alerts
X-API-Key: your-sentrix-api-key
GET /api/v1/dashboard/alerts
Authorization: Bearer eyJhbGci...
```
### 基于角色的访问控制
| 角色 | 权限 |
|---|---|
| `read_only` | 仪表板读取端点 |
| `soc_analyst` | 仪表板 + SOAR 触发 + 关闭事件 |
| `admin` | 完全访问权限，包括管理员和连接器管理 |
### 端点参考
**威胁与摄取**
| 方法 | 路径 | 描述 |
|---|---|---|
| POST | `/api/v1/threat/events/ingest` | 摄取原始事件 payload |
| GET | `/api/v1/threat/alerts` | 列出所有生成的告警 |
| GET | `/api/v1/threat/iocs` | 查询 IOC 库 |
**仪表板**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/v1/dashboard/alerts` | 带有分页和严重性过滤器的告警源 |
| GET | `/api/v1/dashboard/incidents` | 关联事件列表 |
| GET | `/api/v1/dashboard/top-attackers` | 按告警量排名的前列攻击 IP |
| GET | `/api/v1/dashboard/mitre-heatmap` | MITRE ATT&CK 技术频率热力图 |
| GET | `/api/v1/dashboard/predictions` | 攻击路径预测源 |
| GET | `/api/v1/dashboard/events` | 带有过滤的原始事件流 |
| GET | `/api/v1/dashboard/metrics` | KPI 摘要小部件数据 |
| GET | `/api/v1/dashboard/investigation-reports` | AI 生成的调查报告 |
| GET | `/api/v1/dashboard/search` | 跨事件和告警的全文搜索 |
**事件**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/v1/incidents` | 列出所有事件 |
| POST | `/api/v1/incidents/{id}/close` | 根据分析师反馈标签关闭事件 |
| POST | `/api/v1/incidents/{id}/assign` | 将事件分配给分析师 |
| GET | `/api/v1/incidents/{id}/export` | 将事件导出为 JSON |
**SOAR**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/v1/soar/` | SOAR 引擎状态和队列深度 |
| GET | `/api/v1/soar/audit` | 按时间顺序排列的 SOAR 操作审计日志 |
| POST | `/api/v1/soar/execute` | 手动触发 SOAR 剧本操作 |
**规则与抑制**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/v1/rules` | 列出所有检测规则 |
| POST | `/api/v1/rules` | 创建自定义检测规则 |
| DELETE | `/api/v1/rules/{id}` | 删除自定义规则 |
| POST | `/api/v1/rules/{id}/test` | 针对样本 payload 测试触发规则 |
| GET | `/api/v1/suppression` | 列出抑制规则 |
| POST | `/api/v1/suppression` | 添加抑制条目 |
**预测与知识**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/v1/predictions/history` | 历史预测记录 |
| GET | `/api/v1/predictions/attack-path/{ip}` | 特定攻击者 IP 的攻击路径 |
| GET | `/api/v1/investigations` | 列出调查报告 |
| POST | `/api/v1/investigations/trigger/{id}` | 手动触发 AI 调查 |
| GET | `/api/v1/knowledge/attacks` | 查询安全知识库 |
| GET | `/api/v1/knowledge/playbooks/{technique_id}` | 获取针对特定技术的补救剧本 |
**可观测性**
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/ready` | 平台就绪探针 |
| GET | `/metrics` | 实时平台 KPI |
| GET | `/api/v1/trace/{event_id}` | 任何事件的完整 pipeline 追踪 |
| GET | `/api/v1/connectors/health` | Collector 健康状态 |
| GET | `/api/v1/ingest/metrics` | 摄取队列和 SQLite 锁指标 |
| GET | `/api/v1/audit/logs` | 平台审计追踪 |
**WebSocket**
```
WS /ws/live
Server pushes every 2 seconds:
{
"type": "update",
"events": [...], new raw events since last push
"alerts": [...], new triggered alerts since last push
"metrics": {...}, current KPI snapshot
"timestamp": "ISO8601"
}
```
运行时可在 `http://localhost:8000/docs` 获取交互式 API 文档。
## 安全模型
### 身份验证层
| 调用方 | 机制 |
|---|---|
| Collector | X-API-Key 标头（挂载的 Docker Secret） |
浏览器 API 调用 | X-API-Key 或 Bearer JWT (HS256) |
| Admin 路由 | `require_admin()` FastAPI 依赖项 |
| SOAR 路由 | `require_soc_analyst()` FastAPI 依赖项 |
### 角色层级
```
read_only (0) -> soc_analyst (1) -> admin (2)
```
### 容器加固
每个容器都应用了 `no-new-privileges:true`。Suricata 仅被授予 `NET_ADMIN` 和 `NET_RAW` Linux capabilities，并在 DVWA 网络 namespace 中运行 — 绝不使用 host 网络模式。
### 网络隔离
DVWA 和 MySQL 隔离在 `dvwa-net` (172.21.0.0/16) 上。SOC 核心、collector、Wazuh 和 Nginx 在 `sentrix-net` (172.20.0.0/16) 上运行。网络之间无法进行直接通信。
## 性能
### 基准测试
| 指标 | 值 |
|---|---|
| 平均规则执行延迟 | < 每事件 5 ms |
| ML 推理延迟 | < 每事件 2 ms (进程内，无网络) |
| 事件摄取吞吐量 | ~200 个事件/秒（单核） |
| WebSocket 推送间隔 | 2 秒 |
| SOAR 入队延迟 | < 1 ms (内存队列) |
### SQLite 性能配置
所有数据库均使用：WAL journal 模式、30 秒 busy timeout、NORMAL synchronous 模式，以及针对频繁查询列的索引访问路径。
### 扩展路径
```
Current: SQLite event bus -> Single sentrix-core process
Phase 1: Redis pub/sub -> Single sentrix-core process
Phase 2: Redis pub/sub -> N sentrix-core replicas (load-balanced)
Phase 3: Kafka + PostgreSQL -> Distributed engine cluster
```
## 测试
```
python validation/test_sentrix_v8.py # Full 22-test integration suite
python validation/test_sentrix_v7.py # Live endpoint regression (server required)
python validation/test_e2e_pipeline.py # End-to-end ingest pipeline
python validation/test_soar_engine.py # SOAR playbook tests
python validation/test_correlation_persist.py # Correlation DB persistence
python validation/test_queue_retry.py # DLQ and retry logic
```
### V8 套件结果 (22/22 通过)
```
[PASS] 1. Settings and Paths
[PASS] 2. Default Pack Generation
[PASS] 3. Normalisation - Sysmon Process
[PASS] 4. Normalisation - Sysmon Network
[PASS] 5. Normalisation - Wazuh Alerts
[PASS] 6. Normalisation - Suricata Alerts
[PASS] 7. Normalisation - Zeek Network Connection
[PASS] 8. Normalisation - SIEM Generic
[PASS] 9. MITRE Mapping Enrichment
[PASS] 10. Threat Intel Enrichment
[PASS] 11. Signature-based Threat Ingestion
[PASS] 12. Anomaly / Behavioural Detection
[PASS] 13. Rule Hot Reloading
[PASS] 14. Suppression - IP Whitelist
[PASS] 15. Suppression - Rule ID Suppression
[PASS] 16. Suppression - Maintenance Window
[PASS] 17. SOAR Response Engine
[PASS] 18. Metrics Collector Increments
[PASS] 19. Metrics Persistence Snapshots
[PASS] 20. Case Management CRUD
[PASS] 21. Prediction Engine Forecasting
[PASS] 22. Investigation Studio Queueing
22/22 passed in 2.432s
```
ML 引擎单元测试：**7/7 通过**。
## 路线图
### v10.1
- Prometheus + Grafana 指标（compose 已预置）
- Elasticsearch + Kibana 日志分析（compose 已预置）
- Zeek L4/L7 网络监视器（compose 已预置）
- STIX/TAXII 威胁源消费者
- 具有每团队数据隔离的多租户 RBAC
### v11.0
- Redis pub/sub 事件总线（替代 SQLite 总线）
- PostgreSQL 主数据存储迁移
- Kubernetes 部署清单（Helm chart）
- D3.js 证据关系图 UI
- Zeek JA3/JA3S TLS 指纹检测
### v12.0+
- 分布式威胁引擎集群（多节点）
- 主动式 SOAR（真实的防火墙和 EDR API 集成）
- 通过模型注册表 API 上传自定义 ML 模型
- SOAR 工作流构建器（可视化剧本设计器）
- SAML/SSO 身份验证集成
## 贡献
### 开发设置
```
git clone https://github.com/your-org/dnetx-platform.git
cd dnetx-platform
pip install -r requirements.txt
pip install pytest pytest-asyncio httpx
python validation/test_sentrix_v8.py # Must pass before making changes
```
### 贡献领域
| 领域 | 位置 |
|---|---|
| 正则化插件 | `sentrix_core/normalization/plugins.py` |
| 检测规则 | `sentrix_core/rule_define_studio/default_pack.py` |
| 丰富连接器 | `sentrix_core/connector_framework/connectors/` |
| SOAR 剧本 | `sentrix_core/knowledge/playbooks/` |
| ML 改进 | `sentrix_core/ml_engine/` |
| Suricata 签名 | `suricata/rules/` |
### Pull Request 流程
1. `git checkout -b feature/your-feature-name`
2. 确保所有 22 项验证测试通过
3. 在 `validation/` 中为新功能添加或更新测试
4. 如果适用，更新 `SYSTEM_MAP.md` 或 `API_REFERENCE.md`
5. 提交带有清晰描述和动机的 Pull Request
## 许可证
MIT 许可证。有关完整文本，请参阅 [LICENSE](LICENSE)。
## 致谢
- [Suricata](https://suricata.io/) 由 Open Information Security Foundation 提供
- [Wazuh](https://wazuh.com/) — 开源 XDR 和 SIEM 平台
- [FastAPI](https://fastapi.tiangolo.com/) 由 Sebastián Ramírez 提供
- [DVWA](https://dvwa.co.uk/) — Damn Vulnerable Web Application，由 Robin Wood 提供
- [MITRE ATT&CK](https://attack.mitre.org/) — 对手战术和技术知识库
- [python-jose](https://github.com/mpdavis/python-jose) — 适用于 Python 的 JWT
- [ReportLab](https://www.reportlab.com/) — PDF 生成
- [Pydantic](https://docs.pydantic.dev/) — 使用 Python 类型提示进行数据验证
- [NumPy](https://numpy.org/) — 用于 ML 特征 pipeline 的科学计算
- [Watchdog](https://github.com/gorakhargosh/watchdog) — 文件系统事件监视
*DNetX [V10] — 由 Sentrix Core 提供支持的自主安全编排与响应平台*