omarbabba779xx/CyberTwin-SOC

## 📖 目录

**🎯 概览** - [为什么选择 CyberTwin SOC？](#-why-cybertwin-soc) - [v3.2.0 中的新功能](#-whats-new-in-v320) - [项目概览](#-project-at-a-glance) - [验证状态](#-validation-status)

**🏗 工程** - [架构](#-architecture) - [功能](#-features) - [实时 OCSF 接入](#-live-telemetry-ingestion-ocsf) - [检测覆盖中心](#-detection-coverage-center) - [SOC 工作流](#-soc-workflow)

**🔐 运维** - [快速开始](#-quick-start) - [安全态势](#-security-posture) - [CI/CD 流水线](#-cicd-pipeline) - [可观测性与指标](#-observability--metrics) - [生产部署](#-production-deployment) - [质量与测试](#-quality--testing)

## 🎯 为什么选择 CyberTwin SOC？ CyberTwin SOC **不是** SIEM，不是 SOAR，也不是又一个仪表板。它是一个**安全运营中心的数字孪生**，闭环了每个成熟 SOC 所需的四个循环： ``` flowchart LR A["SIMULATE
11 scenarios
28 attack techniques
Custom Sigma"] B["DETECT
46 rules + Sigma
622 MITRE techniques
OCSF normalisation"] C["RESPOND
SOC cases · SLA
SOAR · Suppressions · Feedback"] D["MEASURE
Coverage Center
NIST CSF + CIS
Benchmarks"] A --> B --> C --> D D -. continuous improvement .-> A classDef sim fill:#fef3c7,stroke:#f59e0b,color:#78350f classDef det fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a classDef resp fill:#fee2e2,stroke:#ef4444,color:#7f1d1d classDef mes fill:#d1fae5,stroke:#10b981,color:#064e3b class A sim class B det class C resp class D mes ``` 它用具体的数字——而非简单的要点——回答了每位 CISO 和检测工程师最终都会提出的问题： | 问题 | 答案所在之处 | |----------|------------------------| | *在 622 个已发布的 ATT&CK 技术中，我的 SOC 今天实际能检测到哪些？* | **检测覆盖中心** — 8 种真实状态（已验证 / 失败 / 未测试 / 仅规则 / 未覆盖 / ……） | | *过去 30 天内，我检测规则的误报率是多少？* | **SOC 工作流** — 针对每个警报的分析师反馈循环 | | *如果今天发生类似 Solorigate 的供应链攻击，我们能在数据外泄之前抓住它吗？* | 运行 `scenario apt_campaign` 并阅读报告 | | *我的日志源是否足以检测凭据转储？* | 每项技术的 `required_logs` × 每个主机组的 `available_logs` | | *分析师能多快进行分类？SLA 违约率是多少？* | SOC 案例存储了 SLA、状态转换和关闭时间 | | *检测工程师的哪次更改破坏了检测？* | 版本化规则存储 + 基准比较 | ## 🆕 v3.2.0 中的新功能

🏢 多租户与认证	🔐 安全与合规	📊 可观测性与运维	⚡ 企业功能
- **JWT** payload 中的 `tenant_id` - **TenantScopeMiddleware** - **TenantRepository** 模式 - 基于 **tenant:user** 的速率限制 - **OIDC/SSO**（Entra ID、Okta、Keycloak） - **会话治理**（并发限制） - ORM 优先的数据库（开发环境回退至 SQLite）	- **防篡改审计**（SHA-256 链） - **AES-256-GCM** 字段加密（基于每个租户的 HKDF） - 带有 CASCADE 的 **FK 约束**（3 次迁移） - **数据保留**清除作业（感知 GDPR） - **SOC 2** Type II 就绪映射 - **ISO 27001:2022** 附录 A 评估 - **GDPR** 数据处理文档	- **OpenTelemetry** 追踪（OTLP 导出器） - FastAPI + SQLAlchemy + Redis 遥测 - 所有响应上的 `X-API-Version: v1` - **备份/DR** 脚本 + 专业运维手册 - **前端测试套件**（Vitest + RTL） - **真正的 Arq worker**（Redis broker，独立容器）	- 数据库中每租户的 **动态 RBAC** - 连接器上的 **熔断器** - 带有 `@with_retry` 的指数重试 - **Redis Streams** 接入缓冲 - 统一的 **错误信封** + 全局处理器 - 完整的 **健康检查**（每个组件的延迟） - **高管仪表板**（MTTD/MTTR/SLA KPI）

v3.1.0 — 强化版本（点击展开）

- 通过 Redis 实现 JWT **jti 拒绝列表** · **刷新令牌轮换**（1h / 7d） · 严格的 CORS · **nginx-unprivileged** - `main.py` **1561 → 135 LoC** · **14 个路由模块** · **Arq 形式的任务** + `/api/tasks` - **SQLAlchemy 2.0** ORM · **Alembic** · **PostgreSQL CI 冒烟测试** · 10 个 ORM 模型 · 19 个索引 - **30+ 项 AI 安全测试** · **Checkov** IaC · **Lighthouse CI** · `quality-gate`（9 个作业）

### 📦 v3.2.0 — 企业就绪（5 个阶段，22 项交付物） | 阶段 | 标题 | 关键交付物 | |------:|-------|-----------------| | **1** | 运维可靠性 | 真正的 **Arq worker**（Redis broker + 独立容器） · **Redis Streams** 缓冲（持久化 5 万个事件） · 统一的 **错误信封** · 完整的 **健康检查**（Redis PING、PG、每个组件的延迟） | | **2** | 端到端多租户 | **JWT** 中的 `tenant_id` · `TenantScopeMiddleware` · `TenantRepository` 模式 · ORM 优先的数据库（开发环境回退至 SQLite） · 基于 **tenant:user** 的速率限制 | | **3** | 安全与合规 | **防篡改审计**（SHA-256 链 + PostgreSQL） · **OIDC/SSO**（Entra ID、Okta、Keycloak） · **会话治理**（并发限制 + 强制登出） · 带有 CASCADE 的 FK 约束 · **数据保留** + GDPR 文档 | | **4** | 可观测性与运维 | **OpenTelemetry** 追踪（OTLP + FastAPI/SQLAlchemy/Redis 遥测） · `X-API-Version: v1` 请求头 · **备份/DR** 脚本 + 运维手册 · **前端测试套件**（Vitest + RTL） | | **5** | 企业差异化功能 | 数据库中每租户的 **动态 RBAC** · 连接器上的 **熔断器** · **AES-256-GCM** 字段加密（基于每个租户的 HKDF） · **高管仪表板**（MTTD/MTTR/SLA KPI） · **SOC 2 / ISO 27001** 就绪文档 | ``` gantt title CyberTwin SOC — release timeline dateFormat YYYY-MM-DD axisFormat %b %d section v3.0.x · stabilised Live OCSF ingestion :done, a1, 2026-04-19, 1d Helm chart + 6-job CI :done, a2, 2026-04-20, 1d Senior architect audit :done, a3, 2026-04-25, 1d section v3.1.0 · hardening JWT jti + refresh rotation :done, b1, 2026-04-27, 1d nginx-unprivileged · CORS strict :done, b2, 2026-04-27, 1d Split 13 routers · AI sec tests :done, b3, 2026-04-27, 1d SQLAlchemy + Alembic + tenant_id :done, b4, 2026-04-27, 1d quality-gate CI · Checkov · 64-char :done, b5, 2026-04-27, 1d section v3.2.0 · enterprise readiness Phase 1 — Arq worker + Redis Streams :done, d1, 2026-04-28, 1d Phase 2 — Multi-tenancy runtime :done, d2, 2026-04-28, 1d Phase 3 — OIDC + audit chain + sessions :done, d3, 2026-04-28, 1d Phase 4 — OpenTelemetry + backup/DR :done, d4, 2026-04-28, 1d Phase 5 — RBAC + encryption + exec dash :done, d5, 2026-04-28, 1d ``` ## 📊 项目概览 ``` flowchart TB ROOT(("CyberTwin SOC v3.2")) BE["Backend"] FE["Frontend"] DET["Detection"] SOC["SOC"] OPS["Ops"] ENT["Enterprise"] ROOT --> BE & FE & DET & SOC & OPS & ENT BE --- BE1["Python 3.12
18+ packages · Arq worker"] BE --- BE2["80+ endpoints · 855 pytest · 867 automated QA ✅"] FE --- FE1["React 18 + Vite
27 pages · Vitest"] FE --- FE2["Recharts + ReactFlow"] DET --- DET1["46 rules + Sigma loader"] DET --- DET2["622 MITRE techniques · 14 tactics"] DET --- DET3["OCSF 1.0"] SOC --- SOC1["Cases · SLA
Feedback · Suppressions"] SOC --- SOC2["AI analyst · ML anomaly"] OPS --- OPS1["Docker Compose · Helm · Arq worker"] OPS --- OPS2["Prometheus + OpenTelemetry"] OPS --- OPS3["Backup/DR · 9-job CI"] ENT --- ENT1["Multi-tenancy · OIDC/SSO"] ENT --- ENT2["AES-256-GCM · Audit chain"] ENT --- ENT3["Dynamic RBAC · Circuit breaker"] classDef root fill:#1e293b,stroke:#0f172a,color:#fff classDef cat fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a classDef item fill:#f8fafc,stroke:#cbd5e1,color:#334155 class ROOT root class BE,FE,DET,SOC,OPS,ENT cat class BE1,BE2,FE1,FE2,DET1,DET2,DET3,SOC1,SOC2,OPS1,OPS2,OPS3,ENT1,ENT2,ENT3 item ``` | 指标 | 数量 | 备注 | |-------------------------------------|--------:|---------------------------------------------------------------------------| | **后端 Python** | 18 000+ | 20+ 个包 — `api`、`detection`、`soc`、`ingestion`、`db`、`auth`、`crypto`、`middleware`、`observability`、… | | **前端 React/JSX** | 13 000+ | 27 个页面（包含高管仪表板），Vitest 测试套件，Recharts | | **单元与集成测试** | 867 | 后端：pytest (855) · Vitest RTL (10) · Playwright 冒烟测试 (2) · 参见 [`docs/proof/test-report-v3.2.md`](docs/proof/test-report-v3.2.md) | | **REST + WebSocket 端点** | 80+ | 按租户:用户限制速率，RBAC 范围控制，`X-API-Version: v1` 请求头 | | **MITRE ATT&CK 技术** | 622 | 完整的企业矩阵 · 14 种战术 · TAXII 2.1 同步 | | **内置检测规则** | 46 | 14 个平台 · 按严重程度分层 · 运行时 Sigma 上传 | | **攻击场景** | 11 | Solorigate、ProxyShell、Log4Shell、内部威胁、勒索软件、… | | **RBAC 角色 / 范围权限** | 12 / 30+ | 3 个旧版 + 9 个企业级 + **数据库中按租户的动态角色** | | **连接器（可扩展）** | 15 (**5** 个生产级) | Splunk、Sentinel (Log Analytics)、TheHive、**Jira**、**MISP** — REST + 重试 + 熔断器 + `mock_mode` 测试；其余 10 个存根共享相同的强化攻击面 | | **依赖项中已知的 CVE** | 0 | 由 `pip-audit --strict` 和 `npm audit` 验证 | | **数据库** | 11+ 张表 | Alembic 迁移 `0001`–`0005` · FK 约束 · ORM 优先（开发环境回退至 SQLite） | | **企业功能** | 22 | 多租户 · OIDC/SSO · AES-256-GCM 加密 · OTel · 会话治理 · 审计链 · 备份/DR | ##⚖ 范围、诚实度与局限性 CyberTwin SOC 是为那些希望拥有一个由可复制的工件支持的**可信 SOC 孪生**的团队而构建的 — **而不是**一个交钥匙的商业 SIEM 替代品。有用的框架： | 主题 | 坦诚的回答 | |------|-----------------| | **测试数量** | **867** 次自动化运行（**855** 次 `pytest` + **10** 次 Vitest + **2** 次 Playwright）。权威证明：[`docs/proof/test-report-v3.2.md`](docs/proof/test-report-v3.2.md)。 | | **MITRE 规则映射** | **40 / 622 (6.43 %)** ([`docs/proof/mitre-coverage-snapshot.md`](docs/proof/mitre-coverage-snapshot.md))。对于 POC 基准测试来说是诚实的；远未达到全面的企业检测覆盖率。 | | **前端质量** | Vitest RTL（`frontend-tests-report`）+ CI 中的 Playwright **`frontend/e2e/`** 冒烟测试 — 扩展的 login→case 流程仍在待办列表中 ([`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md))。 | | **连接器** | **15** 个接口面；**5** 个生产级集成（Splunk、Sentinel、TheHive、Jira、MISP）+ **10** 个具有相同强化接口的存根 ([连接器框架图](#connector-framework))。 | | **演示视觉材料** | 仓库内暂**无**二进制 GIF — 故事板位于 [`docs/demo/README.md`](docs/demo/README.md)。 | | **源代码布局** | 关键入口点（**例如** [`backend/api/main.py`](backend/api/main.py)、[`backend/detection/engine.py`](backend/detection/engine.py)）是标准的 PEP 8 模块。如果 GitHub 上的“raw”或 diff 看起来像是一个超长单行，请重新打开格式化视图或在本地克隆 — 该代码库本身是以可维护性为导向的。 | ## ✅ 验证状态 | 领域 | 状态 | 证据 | |---------------------------|-------------------------------------------------------|----------| | **后端测试** | ✅ 855 项通过 | [`docs/proof/test-report-v3.2.md`](docs/proof/test-report-v3.2.md) | | **前端测试** | ✅ 10 项通过（Vitest + RTL 冒烟测试） | [`docs/proof/frontend-tests-report.md`](docs/proof/frontend-tests-report.md) | | **Playwright E2E** | ✅ 2 项冒烟测试通过（Chromium） | [`frontend/e2e/`](frontend/e2e/) | | **综合自动化 QA** | ✅ **867** (855 + 10 + 2) | 上方的证明文件 | | **代码覆盖率** | ✅ ~72 %（门控：≥ **71** %，**目标 80 %+**) | `pytest --cov=backend --cov-fail-under=71` | | **前端构建** | ✅ 通过 | GitHub Actions `Frontend Build` 作业 | | **Docker 构建** | ✅ 对 `/api/health` 和 `/health` 进行重试循环健康检查 | [`docs/proof/docker-validation.md`](docs/proof/docker-validation.md) | | **Helm chart** | ✅ 在 CI 中进行 Lint + 渲染 | `helm-lint` 作业 + 上传的 `helm-rendered-{sha}` 制品 | | **Compose 配置** | ✅ default + `soar` | [`docs/proof/docker-validation.md`](docs/proof/docker-validation.md) | | **代码质量** | ✅ flake8 = 0 个错误 | `Code Quality` CI 作业 | | **安全门禁** | ✅ `pip-audit`、`npm audit`、`gitleaks` — **阻塞式** | [`docs/proof/security-scan-summary.md`](docs/proof/security-scan-summary.md) | | **已知 CVE** | ✅ **0** | [`docs/proof/security-scan-summary.md`](docs/proof/security-scan-summary.md) | | **MITRE 覆盖率** | 📊 **40 / 622** 规则映射 (6.43 %) — 真实 | [`docs/proof/mitre-coverage-snapshot.md`](docs/proof/mitre-coverage-snapshot.md) | | **流水线基准测试** | 📊 3 个场景 × 3 次运行 · 端到端 4–13 秒 | [`docs/proof/benchmark-results.md`](docs/proof/benchmark-results.md) | | **审计报告（深度）** | 📋 7 个领域评分 · 修复了 4 个关键问题 | [`docs/proof/audit-report.md`](docs/proof/audit-report.md) | | **SOC 2 就绪度** | 📋 已映射 CC1–CC9 · 差距分析 | [`docs/compliance/soc2-readiness.md`](docs/compliance/soc2-readiness.md) | | **ISO 27001 就绪度** | 📋 附录 A 控制映射 | [`docs/compliance/iso27001-readiness.md`](docs/compliance/iso27001-readiness.md) | | **GDPR 数据处理** | 📋 数据类别、保留期限、主体权利 | [`docs/compliance/gdpr-data-processing.md`](docs/compliance/gdpr-data-processing.md) | | **备份/DR 运维手册** | 📋 PostgreSQL + Redis + 验证 | [`docs/operations/backup-recovery.md`](docs/operations/backup-recovery.md) | 图例：✅ 绿色，持续执行 · 📊 已测量的快照 · 📋 叙述性报告 · ⏳ 进行中的工作。 ## 🏗 架构 ### 高层组件图 ``` flowchart TB subgraph Client["👤 Client tier"] UI["🖥️ React 18 + Vite SPA
26 pages · Recharts · ReactFlow"] end subgraph Edge["🌐 Edge"] NX["nginx-unprivileged (uid 101)
CSP · HSTS · X-Frame-Options"] end subgraph API["⚙️ API tier — FastAPI 0.136"] MW["Middleware
RequestID · Metrics · Audit · CORS · RateLimit · CSP"] ROUT["14 Routers
health · auth · simulation · results · ingestion · scenarios
coverage · soc · soar · mitre · environment · history"] DEPS["Shared deps
JWT (jti+refresh) · 12-role scoped RBAC · slowapi"] end subgraph Core["🧠 Core domain"] SIM["🎭 Simulation
11 scenarios · 28 techniques"] TEL["📡 Telemetry
LogEvent → OCSF"] DET["🔍 Detection engine
46 rules + Sigma loader"] COR["🧩 Correlation
Alerts → Incidents"] SCO["🏆 Scoring
NIST CSF + CIS"] AI["🤖 AI Analyst
Ollama + NLG fallback
PII redaction · prompt sanitise"] ANO["📈 ML Anomaly
IsolationForest · UEBA"] SOC["🚨 SOC Workflow
Cases · SLA · Feedback · Suppressions"] COV["🎯 Coverage Center
8-state machine"] end subgraph Data["💾 Data tier"] DB[("PostgreSQL / SQLite
11+ ORM tables · 5 migrations
SQLAlchemy 2.0 + Alembic")] REDIS[("Redis
cache · jti · rate-limit
Streams · sessions · jobs")] BUF["Redis Streams
50 k events
(deque fallback)"] end subgraph Obs["📊 Observability"] PROM["Prometheus
/api/metrics"] OTEL["OpenTelemetry
OTLP traces"] LOG["JSON logs
W3C trace context"] end subgraph Ext["🔌 External"] SOAR["SOAR
TheHive 5 + Cortex 3"] TAXII["TAXII 2.1
MITRE ATT&CK"] CONN["Connectors
Splunk · Sentinel · Elastic · Defender · Jira · ServiceNow · MISP …"] end UI -->|HTTPS + JWT| NX --> MW --> ROUT --> DEPS DEPS --> SIM & DET & SOC & COV & AI & ANO SIM --> TEL --> DET --> COR --> SCO --> AI DET --> SOC BUF --> DET SOC <--> DB DET --> COV SOC <--> REDIS DET <--> REDIS DEPS --> PROM & OTEL & LOG SOC <--> SOAR COV <--> TAXII SOC <--> CONN DET <--> CONN classDef client fill:#fef3c7,stroke:#f59e0b,color:#78350f classDef api fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a classDef core fill:#e0e7ff,stroke:#6366f1,color:#312e81 classDef data fill:#dcfce7,stroke:#22c55e,color:#14532d classDef obs fill:#f3e8ff,stroke:#a855f7,color:#581c87 classDef ext fill:#fee2e2,stroke:#ef4444,color:#7f1d1d class UI client class NX,MW,ROUT,DEPS api class SIM,TEL,DET,COR,SCO,AI,ANO,SOC,COV core class DB,REDIS,BUF data class PROM,OTEL,LOG obs class SOAR,TAXII,CONN ext ``` ### 🔐 令牌生命周期 (v3.2.0) ``` sequenceDiagram autonumber participant U as User participant API as FastAPI participant CACHE as "Redis — jti denylist" participant DB as audit_log rect rgb(220, 252, 231) Note over U,DB: LOGIN U->>API: POST /api/auth/login {user, pass} API->>API: bcrypt verify · sign access (1h, jti_1) + refresh (7d, jti_2) API->>DB: log LOGIN API-->>U: {access_token, refresh_token, expires_in: 3600} end rect rgb(219, 234, 254) Note over U,DB: NORMAL CALL U->>API: GET /api/anything (Bearer jti_1) API->>CACHE: GET revoked_jti:jti_1 CACHE-->>API: nil (still valid) API-->>U: 200 OK end rect rgb(254, 252, 232) Note over U,DB: REFRESH U->>API: POST /api/auth/refresh (refresh_token jti_2) API->>CACHE: SET revoked_jti:jti_2 TTL=remaining API->>API: sign new access (jti_3) + refresh (jti_4) API-->>U: {access_token, refresh_token} end rect rgb(254, 226, 226) Note over U,DB: LOGOUT U->>API: POST /api/auth/logout (Bearer jti_3) API->>CACHE: SET revoked_jti:jti_3 TTL=remaining API->>DB: log LOGOUT API-->>U: 200 {status: "logged_out"} Note over CACHE: Subsequent calls with jti_3 return 401 end ``` ### 端到端模拟流水线 ``` sequenceDiagram autonumber participant U as 🧑 Analyst participant API as ⚙️ FastAPI participant ORC as 🎼 Orchestrator participant ENV as 🏢 Environment participant ATK as 🎭 AttackEngine participant TEL as 📡 Telemetry participant DET as 🔍 Detection participant SCO as 🏆 Scoring participant AI as 🤖 AI Analyst participant WS as 🔌 WebSocket U->>API: POST /api/simulate {scenario_id} API->>ORC: run_pipeline() ORC->>ENV: load_assets() / load_users() ORC->>ATK: execute(scenario) ATK-->>ORC: attack events (28 techniques) ORC->>TEL: generate(events + benign noise) TEL-->>ORC: log events (OCSF) ORC->>DET: run(rules + sigma) DET-->>ORC: alerts + incidents ORC->>SCO: compute(alerts, incidents) SCO-->>ORC: NIST CSF + CIS scores ORC->>AI: analyse_with_evidence(report) AI-->>ORC: narrative + IOCs + recommendations ORC-->>API: final_report API-->>WS: progress · phase · alerts (live) API-->>U: 200 + report URL ``` ### 实时 SOC 接入 (OCSF) ``` flowchart LR subgraph Sources["🛰 Sources"] W["Windows EventLog
4624 · 4625 · 4688 · …"] S["Sysmon
1 · 3 · 7 · 8 · …"] SY["Syslog 3164 / 5424"] CT["AWS CloudTrail"] JS["Generic JSON"] end subgraph Norm["🔄 Normaliser"] M["mappers.py
→ OCSF 1.0"] end subgraph Ingest["📥 Ingestion API · 9 endpoints"] E1["/event"] E2["/batch ≤ 5000"] E3["/syslog"] E4["/upload NDJSON ≤ 25 MB"] E5["/detect"] end subgraph Buf["💾 Redis Streams buffer"] B["50 000 events
persistent · MAXLEN
(deque fallback)"] end subgraph Det["🧠 Same Detection brain"] R["46 rules + Sigma uploads"] end Sources --> Norm --> Ingest --> Buf --> Det Det -->|alerts| SOC["🚨 SOC Workflow"] Det -->|metrics| Prom["📊 Prometheus"] classDef src fill:#fef3c7,stroke:#f59e0b classDef nrm fill:#dbeafe,stroke:#3b82f6 classDef ing fill:#e0e7ff,stroke:#6366f1 classDef buf fill:#dcfce7,stroke:#22c55e classDef det fill:#fee2e2,stroke:#ef4444 class W,S,SY,CT,JS src class M nrm class E1,E2,E3,E4,E5 ing class B buf class R det ``` ### 后端模块依赖图 ``` flowchart TB api["📡 api/
(routes + deps)"] auth["🔑 auth/
JWT · OIDC · RBAC · sessions"] audit["📋 audit.py
SHA-256 chain"] cache["🔴 cache.py
(Redis · in-mem)"] db["🗄️ db/
SQLAlchemy ORM
TenantRepository"] crypto["🔒 crypto/
AES-256-GCM"] mw["🔄 middleware/
TenantScope"] sim["🎭 simulation/"] tel["📡 telemetry/"] det["🔍 detection/"] cov["🎯 coverage/"] soc["🚨 soc/"] ing["📥 ingestion/"] norm["🔄 normalization/"] mitre["🎯 mitre/"] ai["🤖 ai_analyst.py"] llm["💬 llm_analyst.py"] orch["🎼 orchestrator.py"] score["🏆 scoring/"] obs["📊 observability/"] rep["📄 reports/"] soar["🤝 soar/"] conn["🔌 connectors/"] api --> auth & audit & cache api --> sim & det & cov & soc & ing & mitre & soar auth --> cache sim --> tel & orch det --> norm & mitre ing --> norm & det soc --> db api --> mw & crypto cov --> det & mitre orch --> sim & det & score & ai & rep ai --> llm soar --> conn classDef pl fill:#dbeafe,stroke:#3b82f6 classDef dom fill:#e0e7ff,stroke:#6366f1 classDef data fill:#dcfce7,stroke:#22c55e classDef ai fill:#f3e8ff,stroke:#a855f7 classDef ops fill:#fef3c7,stroke:#f59e0b class api,auth,audit,cache pl class sim,tel,det,cov,soc,ing,norm,mitre dom class db,crypto,mw data class ai,llm,orch,score ai class obs,rep,soar,conn ops ``` ## 🚀 功能 ### 🎭 对手模拟引擎 - **11 个交钥匙场景** — Solorigate、ProxyShell、Log4Shell、内部威胁、横向移动、加密挖矿、水坑攻击、就地取材、勒索软件、云攻击、DDoS 基础设施 - **28 种内置攻击技术**，每个事件上都有 MITRE ATT&CK ID - **路径遍历防护的场景构建器**，带有严格的 ID 验证 - **逼真的时间线生成器**，将良性用户活动与对抗行动交错混合 ### 🔍 多源检测引擎 - **46 条内置规则** — Windows EID、Sysmon、Linux audit、Web 访问、DNS、网络、AWS CloudTrail、Azure 活动、Office 365 - **Sigma 加载器** — 在运行时上传 `*.yml` 规则，**防 ReDoS 强化**（`re.escape` + `fullmatch`，256 KB 正文上限） - **严重性分层** + 置信度加权 + 战术多样性奖励 - **事件关联** — 警报 → 事件（杀伤链阶段聚合，多主机枢轴检测） ### 🎯 MITRE ATT&CK 覆盖中心 *(真实的，而非纸上谈兵)* ``` stateDiagram-v2 direction LR [*] --> NOT_COVERED NOT_COVERED --> RULE_EXISTS: enable rule RULE_EXISTS --> RULE_UNTESTED: rule loaded RULE_UNTESTED --> TESTED_DETECTED: scenario triggers rule ✅ RULE_UNTESTED --> TESTED_FAILED: scenario fails to trigger ❌ TESTED_DETECTED --> LOG_MISSING: required log absent RULE_EXISTS --> MUTED: noisy → suppressed RULE_EXISTS --> DEPRECATED: replaced TESTED_FAILED --> RULE_UNTESTED: re-test note right of TESTED_DETECTED: Validated (time-to-detect measured) note right of TESTED_FAILED: Regression (blocks merge) ``` 8 种真实状态（`NOT_COVERED`、`RULE_EXISTS`、`RULE_UNTESTED`、`TESTED_DETECTED`、`TESTED_FAILED`、`LOG_MISSING`、`MUTED`、`DEPRECATED`），带有**检测时间**、**按严重性加权的置信度**以及**按战术的风险评分**，权重倾向于初始访问、权限提升和数据外泄。 ### 🤖 AI 分析师（LLM + 确定性回退） - 兼容 Ollama（Llama 3、Mistral、Qwen），可自动回退到**完全确定性的 NLG 模板**，因此总能生成报告 - **证据优先**的叙述 — 每个主张都以警报 ID 或日志时间戳为依据 - **经过提示注入强化的** — `_sanitise()` 会编辑 AWS/GCP/JWT/PEM 密钥、电子邮件、密码、信用卡，中和注入标记，将提示硬性限制在 32 KB - IOC 提取器 — 外部/内部 IP、域名、URL、**MD5/SHA1/SHA256 哈希**、**电子邮件**、受损账户 - `tests/test_ai_analyst.py` 中有 **30 多项对抗性测试**，涵盖提示注入、PII 编辑、APT 归因防护和 IOC 完整性 ### 📈 ML 异常检测与 UEBA - 在良性遥测数据上训练的 IsolationForest 基线 - 每个用户的行为漂移评分 - 可配置的污染率；在重新训练时热启动 ### 🚨 SOC 工作流（警报 → 案例 → SLA） ``` flowchart LR AL[("🛎 Alert")] --> CA{Case
auto/manual} CA -->|new| NEW["📝 NEW"] NEW -->|assign| IP["🛠 IN_PROGRESS"] IP -->|resolved| RES["✅ RESOLVED"] IP -->|false-positive| FP["🟡 FALSE_POSITIVE"] RES -->|verify| CL["🔒 CLOSED"] FP -->|verify| CL IP -. comment / evidence .-> IP IP -. SLA timer by severity hrs .-> IP FP -- updates rule confidence --> RULE["📊 Rule confidence"] FP -- suggests --> SUP["🤫 Suppression w/ TTL"] classDef state fill:#dbeafe,stroke:#3b82f6 classDef done fill:#dcfce7,stroke:#22c55e classDef fp fill:#fef3c7,stroke:#f59e0b class NEW,IP state class RES,CL done class FP fp ``` - PostgreSQL 支持的案例存储（开发环境可回退至 SQLite） · 状态转换 · 评论 · 证据附件 · 按严重性划分的 SLA 时数 · 带有 CASCADE 的 FK 约束 - 分析师反馈（`true_positive` / `false_positive`）会反馈到规则置信度中 - 带有 TTL 的范围化抑制，以针对每个主机/用户静默已知的噪音规则 - **经过 SQL 注入强化的** UPDATE 构建器（列允许列表 + 标识符正则表达式，双重防御） ### 🤝 SOAR 集成 - docker-compose 中的可选 `--profile soar` - **TheHive 5** — 自动创建案例，附加 observables - **Cortex 3** — 运行分析器，丰富 IOC - 双向 webhook 进出 ### 🧪 合规性基准测试 - 将每个检测能力映射到 **NIST CSF v1.1** 子类别（`DE.AE-2`、`DE.CM-7`、…）和 **CIS Controls v8**（CIS 8.11、CIS 13.6、…） - 生成每次模拟的合规性评分 - 用于态势改进的趋势仪表板 ### 🏷 企业 RBAC — 12 个静态角色 × 30+ 种范围权限 + 每租户的动态角色 ``` flowchart TB subgraph L["⚪ Legacy roles"] ADM["🔴 admin"] ANA["🟢 analyst"] VIE["🔵 viewer"] end subgraph T["🟠 Tier-1 ops"] T1["tier1_analyst"] SE["senior_analyst"] SM["soc_manager"] end subgraph E["🟣 Engineering"] DE["detection_engineer"] TH["threat_hunter"] end subgraph R["🟡 Read-only / audit"] AU["auditor"] RX["read_executive"] SA["service_account"] end subgraph P["⚫ Platform"] PA["platform_admin"] end classDef leg fill:#f1f5f9,stroke:#64748b classDef tier fill:#fed7aa,stroke:#f97316 classDef eng fill:#e9d5ff,stroke:#a855f7 classDef ro fill:#fef3c7,stroke:#f59e0b classDef plat fill:#1e293b,stroke:#0f172a,color:#fff class ADM,ANA,VIE leg class T1,SE,SM tier class DE,TH eng class AU,RX,SA ro class PA plat ``` | 权限范围 | analyst | tier1 | senior | manager | det_eng | hunter | auditor | platform_admin | |---------------------|:-------:|:-----:|:------:|:-------:|:-------:|:------:|:-------:|:--------------:| | `simulation:run` | ✅ | | ✅ | ✅ | ✅ | ✅ | | ✅ | | `case:read/write` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 👁️ | ✅ | | `case:assign` | ✅ | | ✅ | ✅ | | | | ✅ | | `case:close` | ✅ | | ✅ | ✅ | | | | ✅ | | `rule:create` | | | | | ✅ | | | ✅ | | `rule:approve` | | | ✅ | ✅ | ✅ | | | ✅ | | `rule:deploy` | | | | | ✅ | | | ✅ | | `ingestion:write` | ✅ | | ✅ | ✅ | | ✅ | | ✅ | | `ingestion:read` | ✅ | ✅ | ✅ | ✅ | | ✅ | 👁️ | ✅ | | `ai:evidence` | ✅ | ✅ | ✅ | ✅ | | ✅ | | ✅ | | `suppression:create`| | | ✅ | ✅ | | | | ✅ | | `audit:read/export` | | | | ✅ | | | ✅ | ✅ | ✅ = 已授权 · 👁️ = 只读 · 空 = 已拒绝。权限是**范围化的**（`resource:action`） — 绝不是一揽子管理员权限。来源：[`backend/auth/`](backend/auth/)。租户可以使用存储在 `_roles` 数据库表中的**动态角色**进行覆盖。 ### 🔌 连接器框架 ``` classDiagram direction LR class BaseConnector { <> +name +health() bool } class SIEMConnector { +query(qs) } class SOARConnector { +create_case(data) } class EDRConnector { +contain_host(id) } class ITSMConnector { +open_ticket(data) } class TIConnector { +lookup_ioc(ioc) } BaseConnector <|-- SIEMConnector BaseConnector <|-- SOARConnector BaseConnector <|-- EDRConnector BaseConnector <|-- ITSMConnector BaseConnector <|-- TIConnector SIEMConnector <|.. SplunkStub SIEMConnector <|.. SentinelStub SIEMConnector <|.. ElasticStub SOARConnector <|.. TheHiveStub EDRConnector <|.. CrowdStrikeStub EDRConnector <|.. DefenderStub ITSMConnector <|.. JiraStub ITSMConnector <|.. ServiceNowStub TIConnector <|.. MISPStub TIConnector <|.. OpenCTIStub class SplunkStub class SentinelStub class ElasticStub class TheHiveStub class CrowdStrikeStub class DefenderStub class JiraStub class ServiceNowStub class MISPStub class OpenCTIStub ``` ## ⚡ 快速开始 ### 选项 A — Docker Compose（推荐） ``` git clone https://github.com/omarbabba779xx/CyberTwin-SOC.git cd CyberTwin-SOC # 首次运行前设置强 Secrets cp .env.example .env # 编辑 .env：设置 JWT_SECRET (生产环境 >= 64 字符) + AUTH_*_PASSWORD docker compose up -d ``` | 服务 | URL | 备注 | |----------------|---------------------------------------------|----------------------------------------------| | 前端 | | nginx-unprivileged，端口 80→8080 | | API + OpenAPI | | | | Prometheus | | 通过 `RESTRICT_INTERNAL_ENDPOINTS=true` 进行限制 | | 健康检查（深度） | | 在生产环境中通过环境变量进行限制 | ### 选项 B — 本地开发 ``` # Backend python -m venv .venv && .venv/Scripts/Activate.ps1 # Windows pip install -r requirements.txt # 可选：通过 DATABASE_URL + Alembic migrations 配置 PostgreSQL export DATABASE_URL=postgresql+psycopg2://user:pass@host:5432/cybertwin alembic upgrade head uvicorn backend.api.main:app --reload --port 8000 # Frontend cd frontend && npm ci && npm run dev # http://localhost:5173 ``` ### 选项 C — 通过 Helm 部署 Kubernetes ``` helm install cybertwin deploy/helm/cybertwin-soc \ --set ingress.host=soc.example.com \ --set serviceMonitor.enabled=true \ --create-namespace -n cybertwin ``` `runAsNonRoot`、`drop:[ALL]`、liveness/readiness/startup 探针以及用于 `kube-prometheus-stack` 的 `ServiceMonitor` 均已预配置。 ## 📥 实时遥测接入 (OCSF) ### 单个 Windows 登录事件 ``` curl -X POST http://localhost:8000/api/ingest/event \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "source": "windows_security", "event_id": 4625, "host": "WIN-DC-01", "user": "alice", "src_ip": "203.0.113.45", "raw": "..." }' ``` ### NDJSON 批量上传（≤ 25 MB） ``` curl -X POST http://localhost:8000/api/ingest/upload \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/x-ndjson" \ --data-binary @sample.ndjson ``` ### 在事件缓冲区上运行检测 ``` curl -X POST http://localhost:8000/api/ingest/detect -H "Authorization: Bearer $TOKEN" ``` **已交付的强化功能（2026 年 4 月审计）**：`ingestion:write` 范围权限 · 每事件 64 KB 上限 · syslog 5 000 行 × 8 KB 上限 · `_approx_size()` 总量守卫 · 单次 600 请求/分钟，批量 60 请求/分钟。 ## 🎯 检测覆盖中心 ``` curl http://localhost:8000/api/coverage \ -H "Authorization: Bearer $TOKEN" | jq '.summary' ``` ``` { "catalog_total": 622, "validated": 0, "untested": 40, "rule_mapped": 40, "not_covered": 582, "high_risk_gaps": 293, "rule_mapped_pct": 6.43 } ``` 最新快照：[`docs/proof/mitre-coverage-snapshot.md`](docs/proof/mitre-coverage-snapshot.md) ## 🎫 SOC 工作流 | 方法 | 路径 | 权限 | 目的 | |--------:|---------------------------------------|--------------------|--------------------------------------------| | `POST` | `/api/cases` | `case:write` | 根据警报建立案例 | | `GET` | `/api/cases` | `case:read` | 使用过滤器和 SLA 状态列出 | | `GET` | `/api/cases/{id}` | `case:read` | 获取完整案例（评论 + 证据） | | `PATCH` | `/api/cases/{id}` | `case:write` | 更新状态/处理人（允许列表） | | `POST` | `/api/cases/{id}/comments` | `case:write` | 附加评论 | | `POST` | `/api/cases/{id}/evidence` | `case:write` | 附加证据工件 | | `POST` | `/api/cases/{id}/assign` | `case:assign` | 分配分析师 | | `POST` | `/api/cases/{id}/close` | `case:close` | 带有关闭原因地关闭 | | `POST` | `/api/alerts/{alert_id}/feedback` | `feedback:write` | 针对规则的 TP / FP 反馈 | | `POST` | `/api/suppressions` | `suppression:create` | 添加带 TTL 的范围化抑制 | ## ⚙️ 后台任务（Arq worker） 繁重的工作负载（长时间模拟、报告导出、数据保留）在一个由 Redis 支持的**独立 Arq worker 容器**中运行。API 通过 `arq.create_pool()` 将任务排入队列，如果 worker 不可用，则回退到进程内执行（对于没有 Redis 的测试和本地开发是无缝的）。 | 方法 | 路径 | 权限 | 目的 | |--------:|----------------------------|------------------|---------------------------------------------------------------| | `GET` | `/api/tasks` | `view_results` | 列出已注册的任务类型 | | `GET` | `/api/tasks/{task_id}` | `view_results` | 轮询状态（`queued` / `running` / `succeeded` / `failed`） | | `DELETE`| `/api/tasks/{task_id}` | `simulation:run` | 取消（对于今天的进程内执行器来说是协作式的） | ``` sequenceDiagram autonumber participant U as 🧑 Analyst participant API as ⚙️ FastAPI participant REG as 🗂 jobs/registry participant CACHE as 🔴 Redis participant TASK as 🛠 task fn U->>API: POST /api/coverage/recalculate API->>REG: enqueue("coverage_recalculate") REG->>CACHE: set cybertwin:task:{id} status=queued REG->>TASK: await fn(task_id, **kw) TASK->>CACHE: progress 30 → 100 TASK-->>REG: result REG->>CACHE: set status=succeeded · result API-->>U: 202 {task_id} Note over U,API: Client polls U->>API: GET /api/tasks/{id} API->>CACHE: read cybertwin:task:{id} CACHE-->>API: {status, progress, result} API-->>U: 200 {status: succeeded, progress: 100, result: ...} ``` 状态载荷： ``` { "task_id": "a1b2c3d4e5f6g7h8", "task": "coverage_recalculate", "status": "succeeded", "progress": 100, "result": { "summary": { "catalog_total": 622, "validated": 0 } }, "error": null, "enqueued_at": "2026-04-28T09:14:02+00:00", "started_at": "2026-04-28T09:14:02+00:00", "finished_at": "2026-04-28T09:14:03+00:00" } ``` ## 📊 可观测性与指标 ``` flowchart LR REQ["📥 Inbound request"] --> RID["RequestIDMiddleware
X-Request-ID"] RID --> TNT["TenantScopeMiddleware
JWT → tenant_id"] TNT --> AUTH["AuthMiddleware
JWT (jti check) + RBAC"] AUTH --> RL["RateLimit
tenant:user key"] RL --> AUD["AuditMiddleware
SHA-256 chained → audit_log"] AUD --> METR["MetricsMiddleware
Prometheus + OTel spans"] METR --> VER["APIVersionMiddleware
X-API-Version: v1"] VER --> SEC["SecurityHeadersMiddleware
CSP · HSTS · X-Frame · …"] SEC --> APP["⚙️ Application logic"] APP --> LOG["🪵 JSON log
W3C trace context"] APP --> RESP["📤 Response"] classDef mw fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a class RID,TNT,AUTH,RL,AUD,METR,VER,SEC mw ``` ``` # 每个端点的 p95 API 延迟 histogram_quantile(0.95, sum by (path,le)(rate(cybertwin_request_latency_seconds_bucket[5m]))) # 按来源的 ingestion EPS sum by (source)(rate(cybertwin_ingest_events_total[1m])) # 每个规则的滚动 FP 率 sum by (rule_id)(rate(cybertwin_feedback_total{verdict="false_positive"}[24h])) / sum by (rule_id)(rate(cybertwin_feedback_total[24h])) ``` ## 🔐 安全态势 ``` flowchart TB subgraph L1["🌐 Edge"] N["nginx-unprivileged
uid 101 · CSP · HSTS"] end subgraph L2["🔑 Auth & sessions"] A1["bcrypt 12 rounds"] A2["JWT HS256 · 64-char min"] A3["jti denylist (Redis)"] A4["Refresh rotation 1h/7d"] end subgraph L3["🛡️ Request"] R1["CORS strict"] R2["12-role scoped RBAC"] R3["slowapi rate-limit"] R4["Pydantic validation"] end subgraph L4["💉 Code-level"] C1["SQL allowlist + regex"] C2["YAML safe_load"] C3["ReDoS-proof regex"] C4["_safe_path() traversal guard"] end subgraph L5["🤖 AI"] I1["PII redaction"] I2["Prompt-injection sanitise"] I3["32 KB hard cap"] end subgraph L6["📋 Audit & supply chain"] S1["audit_log on every state-change"] S2["pip-audit · gitleaks · Checkov"] S3["CycloneDX SBOM"] end N --> A1 A4 --> R1 R4 --> C1 C4 --> I1 I3 --> S1 classDef layer fill:#1e293b,color:#fff,stroke:#0f172a classDef ctrl fill:#dbeafe,stroke:#3b82f6 class L1,L2,L3,L4,L5,L6 layer class N,A1,A2,A3,A4,R1,R2,R3,R4,C1,C2,C3,C4,I1,I2,I3,S1,S2,S3 ctrl ``` | 攻击面 | 控制措施 | |-----------------|------------------------------------------------------------------------------------------------------| | 认证 | bcrypt（12 轮） · JWT HS256（生产环境中为 64 字符密钥） · **jti 拒绝列表** · **刷新轮换** · **OIDC/SSO**（Entra ID、Okta、Keycloak） | | 会话 | **并发会话限制**（可配置） · `POST /api/auth/revoke-all` 强制登出 · Redis 支持的会话跟踪 | | 令牌 | 1 小时访问令牌 · 7 天刷新令牌 · `tenant_id` 声明 · `POST /api/auth/logout` 通过拒绝列表撤销 | | API | 基于 **tenant:user** 的速率限制 · 严格的 CORS · 12 角色范围的 RBAC + **数据库中按租户的动态角色** | | 加密 | **AES-256-GCM** 字段级加密 · 基于每个租户的 HKDF 密钥派生 · `EncryptedString` TypeDecorator | | HTTP 请求头 | `SecurityHeadersMiddleware`（后端） + `nginx.conf`（前端） — CSP · HSTS · X-Frame | | 文件上传 | `_safe_path()` 正则表达式 + 路径解析检查 — 杜绝遍历可能 | | Sigma 加载器 | YAML safe_load · 最大 256 KB · 防 ReDoS 的 glob 匹配 · `re.fullmatch` | | SQL | 参数化查询 · 用于动态 `UPDATE` 的列允许列表 + 正则表达式 · SQLAlchemy 2.0 ORM | | LLM | `_sanitise()` 编辑 PII/密钥 · 中和提示注入标记 · 32 KB 硬性上限 | | 数据接入 | `ingestion:write` 范围权限 · 每事件 64 KB · syslog 5 000 × 8 KB · `_approx_size()` 守卫 | | 机密 | 环境变量驱动 · 生产环境门控在机密过于弱时拒绝启动 · `.gitleaks.toml` 允许列表 | | 容器 | `nginx-unprivileged`（uid 101） · `runAsNonRoot` · `drop:[ALL]` · 多阶段构建 | | 审计 | 带有 **SHA-256 链式哈希**的 **防篡改** 审计追踪 · PostgreSQL 仅追加 · `verify_audit_chain()` | | DB | SQLAlchemy 2.0 + Alembic · 11+ ORM 表 · 带有 CASCADE 的 **FK 约束** · 每个模型上的 `tenant_id` | | 连接器 | **熔断器**（CLOSED→OPEN→HALF_OPEN） + 对所有外部调用的指数重试 | | 合规性 | **SOC 2 Type II** 就绪映射 · **ISO 27001:2022** 附录 A 映射 · **GDPR** 数据处理文档 | ### 持续安全检查 | 工具 | 范围 | 状态 | |---------------|------------------------------------------------|:------:| | **pip-audit** | Python 依赖项 CVE | ✅ **阻塞式** · 0 个已知 CVE | | **npm audit** | 前端依赖项 CVE（高及以上） | ✅ **阻塞式** · 0 个高危 | | **Gitleaks** | 跨整个 git 历史记录的机密扫描 | ✅ **阻塞式** · 0 处泄漏 | | **Bandit** | Python 静态安全分析 | ⚠ 非阻塞式 · 0 个高危 | | **Semgrep** | 多语言 SAST | ⚠ 非阻塞式 | | **Trivy** | 文件系统 + 容器漏洞扫描 | ⚠ 非阻塞式 | | **Checkov** | IaC 扫描（Dockerfile + Helm） | ⚠ 非阻塞式 | | **CycloneDX** | SBOM（Python + npm） | 📦 制品上传 | 完整审计报告（7 个领域评分，修复了 4 个关键问题）：[`docs/proof/audit-report.md`](docs/proof/audit-report.md)。 ## 🔄 CI/CD 流水线 ``` flowchart LR PUSH["📥 git push / PR"] --> JOBS{9 parallel jobs} JOBS --> J1["🧪 Backend Tests
pytest · ~30 s · cov ≥ 71 %"] JOBS --> J2["🐘 PostgreSQL Migration
upgrade · downgrade · idempotency"] JOBS --> J3["⚛️ Frontend Build
vite + Lighthouse CI"] JOBS --> J4["✨ Code Quality
flake8 · 0 errors"] JOBS --> J5["🔐 Security Scans
pip-audit · npm audit · gitleaks"] JOBS --> J6["🐳 Docker Build
compose smoke + healthcheck"] JOBS --> J7["⎈ Helm Lint
lint + render artefact"] JOBS --> J8["🏗️ Checkov
Dockerfile · Helm IaC
soft-fail"] J1 & J2 & J3 & J4 & J5 & J6 & J7 --> QG["🎯 quality-gate
(7 blocking jobs
for branch protection)"] J8 -.->|non-blocking| QG QG -->|✅| MERGE["🟢 Merge allowed"] QG -->|❌| BLOCK["🔴 Blocked"] classDef job fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a classDef soft fill:#fef3c7,stroke:#f59e0b,color:#78350f classDef pass fill:#dcfce7,stroke:#22c55e,color:#14532d classDef fail fill:#fee2e2,stroke:#ef4444,color:#7f1d1d class J1,J2,J3,J4,J5,J6,J7 job class J8 soft class QG,MERGE pass class BLOCK fail ``` ## 🚢 生产部署 ### Docker Compose ``` # 完整 SOC 栈 (包含 SOAR) docker compose --profile soar up -d # 仅 SOC 核心 docker compose up -d ``` | 服务 | 端口 (主机→容器) | 目的 | |-------------|----------------------:|--------------------------------------------------| | `frontend` | 80 → 8080 | nginx-unprivileged（uid 101）React SPA | | `backend` | 8000 | FastAPI uvicorn（uid 1000 非 root） | | `worker` | — | **Arq 后台 worker**（Redis broker） | | `redis` | 6379 | 缓存 · Streams · 会话 · 任务 · jti 拒绝列表 | | `thehive` | 9000 | （仅限 `soar` 配置文件 — 演示，无认证） | | `cortex` | 9001 | （仅限 `soar` 配置文件 — 演示，无认证） | ### Helm ``` helm upgrade --install cybertwin deploy/helm/cybertwin-soc \ --set image.backend.tag=v3.2.0 \ --set image.frontend.tag=v3.2.0 \ --set ingress.host=soc.example.com \ --set ingress.tls.enabled=true \ --set serviceMonitor.enabled=true ``` ### 数据库迁移 (PostgreSQL) ``` # 设置一次 DATABASE_URL export DATABASE_URL=postgresql+psycopg2://user:pass@host:5432/cybertwin # 应用 Alembic migrations (11+ 表，FK 约束，审计哈希，租户角色) alembic upgrade head # 回滚上次的 migration alembic downgrade -1 ``` ### 负载基准测试 ``` # k6 — API 负载测试 (p95 < 500 ms 门槛) k6 run benchmarks/k6_api_test.js -e BASE=http://localhost:8000 -e TOKEN=$JWT # Locust — ingestion 吞吐量 locust -f benchmarks/locust_ingestion.py --host http://localhost:8000 # Pipeline — 端到端耗时 python -m benchmarks.bench_pipeline ``` ## 📂 项目结构 ``` flowchart TB ROOT["📁 CyberTwin-SOC"] ROOT --> BE["🐍 backend/
16 357 LoC · Python 3.12"] ROOT --> FE["⚛️ frontend/
12 396 LoC · React 18 + Vite"] ROOT --> TS["🧪 tests/
867 automated (855 py +10 RTL +2 E2E)
100 % passing"] ROOT --> AL["🗄️ alembic/
migration infra"] ROOT --> BM["📊 benchmarks/
k6 · locust · pipeline · MITRE snapshot"] ROOT --> DEP["⎈ deploy/helm/
chart + ServiceMonitor"] ROOT --> SC["📜 scenarios/
11 attack JSON"] ROOT --> SCR["🔧 scripts/"] ROOT --> DOC["📖 docs/
proof/ · compliance/ · operations/"] ROOT --> CI["🔄 .github/workflows/
ci.yml — 9 jobs + gate"] ROOT --> JB["⚙️ backend/jobs/
Arq-shaped task registry"] BE --> BE1["api/ — 14 routers + main.py + deps.py + errors.py"] BE --> BE2["detection/ — 46 rules + Sigma + correlation"] BE --> BE3["coverage/ — 8-state machine + gap analyzer"] BE --> BE4["soc/ — cases · feedback · suppressions"] BE --> BE5["ingestion/ — Redis Streams + pipeline"] BE --> BE6["mitre/ — 622 techniques · TAXII sync"] BE --> BE7["auth/ — JWT · OIDC · RBAC store · sessions"] BE --> BE8["observability/ — Prometheus · OpenTelemetry · JSON logs"] BE --> BE9["db/ — SQLAlchemy ORM (11+ models · TenantRepository)"] BE --> BE10["crypto/ — AES-256-GCM field encryption · HKDF"] BE --> BE11["middleware/ — TenantScope · RequestID · APIVersion"] BE --> BE12["connectors/ — circuit breaker · retry · 15 integrations"] BE --> BE13["jobs/ — Arq worker + task registry + data retention"] FE --> FE1["src/pages/ — 26 pages"] FE --> FE2["src/components/ — 10 reusable"] FE --> FE3["nginx.conf — CSP · HSTS · X-Frame · port 8080"] classDef root fill:#fef3c7,stroke:#f59e0b classDef be fill:#dbeafe,stroke:#3b82f6 classDef fe fill:#fee2e2,stroke:#ef4444 classDef ops fill:#dcfce7,stroke:#22c55e class ROOT root class BE,BE1,BE2,BE3,BE4,BE5,BE6,BE7,BE8,BE9,BE10,BE11,BE12,BE13 be class FE,FE1,FE2,FE3 fe class TS,AL,BM,DEP,SC,SCR,DOC,CI,JB ops ``` ## 🧪 质量与测试 ### 测试金字塔 ``` flowchart TB E2E["🌐 End-to-end
compose smoke · CI Postgres job
breadth-first scenarios"] API["🔌 API · integration routers
test_api · test_soc · test_ingestion · test_jobs
router + workflow coverage"] UNIT["⚙️ Domain-heavy pytest (~bulk of 855)
auth · tenancy · detection · rules · SOC · crypto · orch…"] UNIT --> API --> E2E classDef u fill:#dcfce7,stroke:#22c55e,stroke-width:2px classDef a fill:#dbeafe,stroke:#3b82f6,stroke-width:2px classDef e fill:#fef3c7,stroke:#f59e0b,stroke-width:2px class UNIT u class API a class E2E e ``` ### 本地运行 ``` # 完整套件 python -m pytest tests/ -v # 带覆盖率 (门槛：≥ 71 %，目标 80 %+) python -m pytest tests/ --cov=backend --cov-report=term-missing # 等效 CI lint flake8 backend/ --max-line-length=120 --ignore=E501,W503,E402,E241,E231,E704 # Frontend E2E (Chromium 冒烟测试；CI job playwright-e2e) cd frontend && npm ci && npm run test:e2e # 本地安全扫描 bandit -r backend/ -ll --skip B101,B104 pip-audit -r requirements.txt --strict ``` 当前 `master` 分支： ``` ============================ 855 passed in … s ============================= flake8: 0 errors · pip-audit: 0 CVE · npm audit: 0 high · gitleaks: 0 leaks coverage: ~72 % (gate ≥ 71 % · target 80 %+) ``` ## 📚 文档 | 文档 | 目的 | |----------|---------| | [`docs/proof/audit-report.md`](docs/proof/audit-report.md) | 高级架构师审计 · 7 个领域评分 · 4 项关键修复 | | [`docs/proof/coverage-report.md`](docs/proof/coverage-report.md) | Pytest 摘要 · 代码路径覆盖 | | [`docs/proof/database-indexing-report.md`](docs/proof/database-indexing-report.md) | 数据库索引审计 · 7 张表 · 0 处缺失 | | [`docs/proof/mitre-coverage-snapshot.md`](docs/proof/mitre-coverage-snapshot.md) | 真实的 6.43 % 规则映射快照 | | [`docs/proof/security-scan-summary.md`](docs/proof/security-scan-summary.md) | pip-audit / Bandit / Gitleaks / Trivy / npm audit | | [`docs/proof/benchmark-results.md`](docs/proof/benchmark-results.md) | 流水线 EPS · 延迟 | | [`docs/proof/docker-validation.md`](docs/proof/docker-validation.md) | Compose + Docker 构建证明 | | [`docs/operations/backup-recovery.md`](docs/operations/backup-recovery.md) | 备份/DR 运维手册（PostgreSQL、Redis、验证） | | [`docs/compliance/soc2-readiness.md`](docs/compliance/soc2-readiness.md) | SOC 2 Type II 就绪度 — CC1–CC9 映射 + 差距分析 | | [`docs/compliance/iso27001-readiness.md`](docs/compliance/iso27001-readiness.md) | ISO 27001:2022 附录 A 控制映射 + 补救措施 | | [`docs/compliance/gdpr-data-processing.md`](docs/compliance/gdpr-data-processing.md) | GDPR 数据类别、保留期限、数据主体权利 | | [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) | 分层待办列表（Playwright GIF、连接器、打磨） | | [`CHANGELOG.md`](CHANGELOG.md) | 版本化更新日志 | | [`SECURITY.md`](SECURITY.md) | 漏洞披露政策 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | 如何贡献 | | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | 社区标准 | ## 🗺 路线图 ``` gantt title CyberTwin SOC — delivery timeline dateFormat YYYY-MM-DD axisFormat %b section Foundation Sim engine + 11 scenarios :done, p1, 2025-09-01, 30d Telemetry + LogEvent :done, p2, after p1, 14d Detection 46 rules + Sigma :done, p3, after p2, 21d section Intelligence LLM AI Analyst :done, p4, after p3, 21d ML anomaly + UEBA :done, p5, after p4, 14d MITRE 622 + TAXII :done, p6, after p5, 14d section Platform Redis · WebSocket · async :done, p7, after p6, 14d NIST CSF + CIS :done, p8, after p7, 14d Frontend pages :done, p9, after p8, 21d Test suite :done, p10, after p9, 14d section Operations Docker Compose :done, p11, after p10, 7d SOAR (TheHive + Cortex) :done, p12, after p11, 14d Stabilisation + governance :done, p13, after p12, 14d Coverage Center 8-state :done, p14, after p13, 14d SOC Workflow :done, p15, after p14, 14d Live OCSF ingestion :done, p16, after p15, 14d Enterprise (Helm · RBAC ×12) :done, p17, after p16, 21d section Hardening Audit Apr 2026 :done, p18, 2026-04-20, 7d v3.1.0 hardening release :done, p19, 2026-04-27, 1d section Enterprise v3.2.0 enterprise readiness :done, p20, 2026-04-28, 1d ``` ### 下一步计划（尚未在 `master` 分支上） 参见 [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — **紫队工作流**、**STIX/TAXII源发布**、**eBPF 代理**、**检测即代码 GitOps**、**MFA** 等。在连接器方面，**Splunk · Sentinel · TheHive · Jira · MISP** 已通过测试连接（`docs/proof/connectors-validation.md`）；**Elastic、ServiceNow、OpenCTI、Defender** 等 … 仍是下一步计划。 ## 🤝 贡献与许可证 欢迎提交 PR。标准如下： 1. `pytest tests/` 为绿色（855+ 项），并且在涉及 UI 时本地的前端 `npm run test:e2e` 也能通过。 2. `flake8` 使用 CI 相同的标记后保持干净。 3. 新端点需配备一个单元测试**以及**一个范围权限（`resource:action`）。 4. 新的 ATT&CK 技术需添加到 `backend/mitre/attack_data.py`。 5. 不含机密，不含硬编码凭据，不含易受路径遍历攻击的字符串操作。 6. 安全扫描（`pip-audit`、`npm audit`、`gitleaks`）保持绿色 — 它们是阻塞式的。 在开启 PR 之前，请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。 **许可证**：MIT — 参见 [`LICENSE`](LICENSE)。

**用 ❤️ 为网络安全社区而建。** 如果这个项目为您的团队节省了一个冲刺周期，请 **[⭐ 给仓库加星](https://github.com/omarbabba779xx/CyberTwin-SOC)** — 这是我唯一关注的指标。

标签：AES-256-GCM, AI安全分析师, Alembic, AMSI绕过, API集成, Cloudflare, DevSecOps, Entra ID, GET参数, GPT, Helm, HTTP工具, IAM, IP 地址批量处理, ISO 27001, Keycloak, MITRE ATT&CK, NIDS, OCSF, OIDC, Okta, OpenTelemetry, PostgreSQL, Python, RBAC, React, Redis, Redis Streams, SaaS安全, Sigma规则, SOAR, SOC 2, SSO, Syscalls, 上游代理, 单点登录, 可观测性, 基于角色的访问控制, 威胁检测, 子域名突变, 安全合规, 安全响应, 安全测试, 安全运营中心, 安全遥测, 审计日志, 容器化, 开源框架, 持续集成, 搜索引擎查询, 攻击性安全, 攻击模拟, 数字孪生, 数据加密, 无后门, 机器学习异常检测, 测试用例, 漏洞管理, 用户代理, 目标导入, 网络代理, 网络安全, 网络安全审计, 网络安全开源项目, 网络映射, 网络靶场, 自定义请求头, 请求拦截, 身份与访问管理, 防篡改审计, 隐私保护, 驱动签名利用