mohilamin/ai-soc-telemetry-triage-platform

# AI SOC 遥测分诊平台 ## 为什么构建这个项目 我构建这个项目是为了对 AI 辅助 SOC 分诊背后的数据工程层进行建模：检测规则、告警关联、MITRE 风格映射、分析师队列、时间线和计分卡。 我想捕捉的关键挑战是那些通常在简单演示中被隐藏的部分：数据、信号、决策、约束、证据和操作风险如何在一个其他人可以检查并在本地运行的系统中流转。 我刻意将这个版本保持在本地和合成数据层面，因为目标是使架构和权衡可被审查，而无需外部服务、私有数据、付费 API 或云设置。 ## 真实的业务问题 SOC 团队收到太多互不关联的告警；困难的部分在于将遥测数据与证据和响应动作关联为可解释的事件。 这很重要，因为生产团队不仅需要输出。他们需要证据、所有权、可重复的验证、故障模式和从本地原型到受控生产系统的路径。 ## 本项目证明了什么 - 安全遥测建模 - 检测即代码 - 事件关联 - 风险评分 - 分析师工作流设计 - 证据报告 - 生产级数据管道设计 - 合成但逼真的数据建模 - 计分卡生成 - API/仪表盘服务 - 可测试的架构 - 诚实的局限性说明 ## 通俗易懂的架构 合成遥测数据经过标准化，匹配检测规则，映射到攻击者行为，进行去重，关联成事件，排定优先级，最后导出为分析师可直接使用的输出。 重要的模式是，输入不仅仅是转换为输出。它们被转化为有评分、有文档记录的工件，可供运维人员、分析师、工程师和业务利益相关者审查。 ## 关键设计决策 - 合成数据确保代码库可以安全运行和公开分享。 - 确定性的本地逻辑使验证可重复，无需付费 API。 - DuckDB 或本地工件提供了仓库式的检查能力，无需云设置。 - FastAPI 展示了如何将系统作为服务层提供服务。 - Streamlit 为审查者提供了一种快速直观检查输出的方法。 - 计分卡使质量、风险、可靠性或就绪度变得可衡量。 - 测试和 Ruff 防止代码库仅仅只是文档。 - Docker/CI 文件展示了预期的部署形态，而并未声称已具备生产就绪性。 详细的权衡记录请参见 [docs/design-decisions.md](docs/design-decisions.md)。 ## 验证证据 最新验证运行：2026-06-02。 - Pipeline：通过 - Pytest：通过（86 个测试） - Ruff：通过 - 代码库质量文档检查：通过 - 详细的命令输出记录在 [docs/validation-log.md](docs/validation-log.md) 中。 ## 可供检查的生成工件 - 安全遥测 - 检测告警 - 事件记录 - 分析师队列 - MITRE 风格覆盖 - 应急手册 - SOC 计分卡 ## 如何审查此代码库 招聘人员 / 招聘经理： - 首先阅读此 README。 - 如果存在，请查阅 [docs/recruiter-summary.md](docs/recruiter-summary.md)。 - 检查 [docs/validation-log.md](docs/validation-log.md)。 - 使用 [docs/repo-review-guide.md](docs/repo-review-guide.md) 获取最快的审查路径。 高级工程师： - 审查架构文档。 - 检查 `src/` 模块。 - 检查测试和生成的计分卡。 - 阅读 [docs/design-decisions.md](docs/design-decisions.md) 和 [docs/tradeoffs-and-simplifications.md](docs/tradeoffs-and-simplifications.md)。 面试路径： - 从验证日志中运行 pipeline 命令。 - 如果此代码库包含它们，请启动仪表盘或 API。 - 诚实地解释一项设计决策和一项简化。 ## 已知局限性 - 仅限合成数据。 - 本地原型，而非已部署的生产系统。 - 使用确定性规则或模拟，而生产系统可能会使用实时模型、流数据或企业集成。 - 未使用任何真实的敏感数据。 - 除非在代码库的其他地方明确说明，否则没有身份验证、RBAC、密钥管理或生产级安全边界。 - 外部系统是被模拟的，而非实时连接。 ## 生产路线图 - 接入 SIEM/EDR/云日志 - 集成 SOAR/案件管理 - 添加威胁情报丰富 - 流式检测 - 添加身份验证和分析师工作流控制 分阶段的路线图请参见 [docs/production-roadmap.md](docs/production-roadmap.md)。 ## 执行摘要 本项目模拟一个现代安全运营中心数据平台。 一个基本的安全仪表盘会问：**“触发了哪些告警？”** 而本项目会问：**“哪些告警属于同一个事件，事件的严重程度如何，有什么证据支持，可能的攻击者行为是什么，哪些系统受到了影响，以及分析师接下来应该做什么？”** 安全团队接收来自身份系统、端点、云日志、SaaS 应用、电子邮件网关、DNS、防火墙和 AI 应用的遥测数据。挑战不仅在于收集告警。真正的挑战在于将它们关联成有意义的事件、降低噪音、确定风险优先级，并为分析师提供可解释的证据。 该平台生成合成 SOC 遥测数据，注入攻击场景，应用 Sigma 风格的检测规则，将检测映射到 MITRE 风格的战术，将告警关联成事件，生成分析师队列，评估爆炸半径，并生成 SOC 计分卡。 **定位：** 我构建 AI 辅助 SOC 数据平台，将碎片化的安全遥测数据转化为相互关联的事件、分析师可直接调查的线索以及可衡量的检测质量。 ## 业务问题 现代 SOC 团队面临告警过载： - 太多低质量告警 - 来自多个系统的重复告警 - 身份告警未与端点活动关联 - 云访问异常未与数据移动关联 - 可疑电子邮件活动未与身份验证事件关联 - AI 提示注入攻击未与数据访问关联 - 分析师将时间浪费在误报上 - 缺乏爆炸半径上下文 - 事件时间线薄弱 - 应急手册不一致 业务风险在于漏报攻击、响应延迟、分析师疲劳以及对 SOC 有效性缺乏可见性。 ## 为什么这不是一个基础的安全仪表盘 本代码库不仅展示告警数量。它构建了一个确定性的 SOC 分诊 pipeline：合成遥测生成、攻击注入、检测即代码、MITRE 风格映射、去重、事件关联、严重性/置信度评分、爆炸半径分析、分析师队列、时间线、应急手册、计分卡、API、仪表盘、Docker 和 CI。 ## 架构 ``` flowchart LR A["Synthetic Assets"] --> B["Synthetic Telemetry"] C["Injected Attack Scenarios"] --> B B --> D["Normalization"] D --> E["Sigma-Style Detection Engine"] E --> F["Security Alerts"] F --> G["Deduplication"] G --> H["Incident Correlation"] H --> I["Severity + Confidence Scoring"] I --> J["Blast Radius"] I --> K["Analyst Queue"] H --> L["Timelines + Evidence"] K --> M["Runbook Recommendations"] M --> N["SOC Scorecards"] N --> O["DuckDB"] O --> P["FastAPI"] O --> Q["Streamlit"] ``` ## 遥测流 ``` flowchart TD A["Identity Logs"] --> J["Unified Telemetry"] B["Endpoint Events"] --> J C["Cloud Access"] --> J D["Network Flow"] --> J E["DNS Logs"] --> J F["Email Security"] --> J G["SaaS Audit"] --> J H["Firewall Logs"] --> J I["AI App Security"] --> J ``` ## 检测流 ``` flowchart LR A["Rules YAML"] --> B["Rule Loader"] B --> C["Sigma-Style Engine"] C --> D["Detection Results"] D --> E["Alerts with Evidence"] E --> F["MITRE-Style Mapping"] ``` ## 关联流 ``` flowchart LR A["Alerts"] --> B["Deduplicate"] B --> C["Entity + Time Window Correlation"] C --> D["Incident Builder"] D --> E["Incident Alert Links"] ``` ## 分诊流 ``` flowchart TD A["Incident"] --> B["Severity Inputs"] B --> C["Confidence Score"] C --> D["False Positive Estimate"] D --> E["Analyst Queue"] E --> F["Next Best Action"] ``` ## 事件响应流 ``` flowchart LR A["Incident"] --> B["Timeline"] A --> C["Evidence"] A --> D["Blast Radius"] A --> E["Runbook"] E --> F["Response Recommendation"] ``` ## 攻击场景目录 该平台注入了 20 个受控场景：不可能的旅行、密码喷洒、针对特权用户的暴力破解、MFA 疲劳攻击、云权限提升、可疑服务账户访问、数据泄露、OAuth 授权滥用、钓鱼链接点击、端点恶意软件、勒索软件前兆、DNS 信标、AI 提示注入、AI 敏感数据请求、内部人员数据访问、云密钥暴露、横向移动、C2 模式、大规模公共文件共享以及休眠账户重新激活。 ## 检测规则示例 规则按来源域位于 `rules/` 目录下。每个规则包含规则 ID、标题、日志来源、检测逻辑、严重性、战术、技术、误报说明和建议的响应。本地规则引擎是 Sigma 风格的，并非官方 Sigma 集成。 ## MITRE 风格映射 检测映射到 MITRE 风格的战术和技术，例如初始访问、凭证访问、权限提升、防御规避、发现、横向移动、命令与控制、数据泄露和影响。这些映射是合成的，并且在本地进行，仅用于作品集演示。 ## 分析师工作流 1. 审查 `/soc-summary` 或仪表盘的“执行概述”。 2. 打开分析师队列。 3. 检查相关联的事件证据和时间线。 4. 审查爆炸半径报告。 5. 使用推荐的应急手册。 6. 标记已知的误报或升级高严重性事件。 ## 计分卡 - `detection_quality_report.json/csv` - `incident_triage_report.json/csv` - `mitre_coverage_report.json/csv` - `soc_performance_report.json/csv` - `false_positive_report.json/csv` - `response_readiness_report.json/csv` - `attack_scenario_detection_report.json/csv` ## 快速开始 ``` python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m src.data_generation.generate_assets python -m src.data_generation.generate_telemetry python -m src.data_generation.inject_attack_scenarios python -m src.data_generation.generate_ground_truth python -m src.pipeline.run_all python -m pytest python -m ruff check . ``` ## API ``` uvicorn src.api.main:app --reload ``` 端点包括 `/health`、`/soc-summary`、`/telemetry-sources`、`/alerts`、`/alerts/{alert_id}`、`/incidents`、`/incidents/{incident_id}`、`/analyst-queue`、`/blast-radius/{incident_id}`、`/mitre-coverage`、`/scorecards`、`/runbooks`、`/evidence/{incident_id}`、`/simulate-attack-scenario`、`/triage-incident` 和 `/mark-false-positive`。 ## 仪表盘 ``` streamlit run src/dashboard/app.py ``` 仪表盘部分：执行概述、遥测来源、检测规则、告警、关联事件、分析师队列、MITRE 风格覆盖、事件时间线、爆炸半径、误报审查、AI 应用安全事件、应急手册建议和 SOC 计分卡。 ## 验证 V0.1 目标： - 资产生成通过 - 遥测生成通过 - 攻击场景注入通过 - 真值生成通过 - 完整 pipeline 通过 - 至少 70 个测试通过 - ruff 通过 - API 和仪表盘在本地启动 ## 已知局限性 - 仅限合成遥测 - 使用本地 DuckDB，而非 SIEM/数据湖 - Sigma 风格的本地规则，非官方 Sigma 规则库集成 - MITRE 风格映射，非官方覆盖范围验证 - 确定性规则，而非基于 ML 的检测 - 无真实威胁情报源 - 无云部署 - 无身份验证 - 无真实的 EDR/SIEM/SOAR 集成 ## 未来增强 - Sigma 规则导入/导出 - MITRE ATT&CK Navigator 层导出 - Splunk/Elastic/Sentinel 连接器模拟 - SOAR playbook 执行 - OpenTelemetry 日志接入 - Kafka 流式遥测 - 云日志适配器 - 身份提供商集成 - 威胁情报丰富 - ML 异常检测 - 案件管理工作流 - Slack/Jira/PagerDuty 升级 - 云部署 - 基于角色的访问控制 (RBAC) ## 项目状态 V0.1：可用的基线版本。 ## 未来增强就绪度 我添加了一个小型的就绪度计分卡，因此生产路线图不仅仅是文字描述。检查程序会读取 `config/future_enhancements.json`，验证代码库是否包含预期的路线图/审查工件，并写入： - `data/scorecards/future_enhancement_readiness.json` - `data/scorecards/future_enhancement_readiness.csv` 使用以下命令运行： ``` python scripts/generate_future_enhancement_scorecard.py ``` 这是一个本地规划信号，并非声称代码库已具备生产就绪状态。

标签：Kubernetes, 事件关联, 告警分诊, 安全运营, 扫描框架, 数据工程, 检测规则, 网络资产发现, 请求拦截, 逆向工具