Mukesh-cpu-gif/ThreatSOC

# ThreatSOC ThreatSOC 是一个本地优先、证据优先的 SOC 调查平台，可将合成或导入的遥测数据转化为可解释的检测、关联事件、威胁狩猎、分析师决策以及事件报告。  ## 为什么开发它 ThreatSOC 展示了可信调查工作流背后的安全工程： ``` telemetry -> normalization -> detections -> alerts -> correlation -> incidents -> evidence -> decision -> report ``` 核心 pipeline 是确定性的并且可以离线工作。AI 是可选的，并且仅限于有证据依据的分析师辅助；它永远不会决定活动是否恶意，也永远不会更改事件状态或结论。 ## 核心功能 - 以 SQLite 为后端的 FastAPI 后端，带有确定性演示数据播种。 - 20 条 YAML 检测规则和 6 条 YAML 关联规则。 - 9 个可重放的场景：6 个恶意攻击故事和 3 个良性/噪声场景。 - 原始和标准化事件存储，并具有实体提取功能。 - 可解释的告警，包含证据、匹配字段、MITRE 映射和风险分解。 - 关联事件队列、时间线、证据图和不可变风格的决策账本。 - 受 KQL 启发的 ThreatSOC 查询语言，被编译为安全的 ORM 谓词。 - 保存的威胁狩猎和从事件到证据的事件附加。 - Detection Lab，用于规则检查、验证、克隆/自定义版本、规则测试和评估指标。 - 针对内置检测范围的 ATT&CK 覆盖视图。 - Markdown 和 HTML 事件报告生成。 - 离线证据助手以及可选的 OpenAI 兼容配置。 - Docker Compose、Windows/macOS/Linux 启动脚本、自动化测试和 CI。 ## 五分钟演示流程 1. 启动应用程序并打开 [http://localhost:5173](http://localhost:5173)。 2. 进入 Replay Lab。 3. 以 `Instant` 速度运行 `password-spray-to-execution`。 4. 打开生成的事件。 5. 检查概览、时间线、证据图、告警、证据和决策账本。 6. 添加带有告警/事件引用的账本注释或结论。 7. 运行威胁狩猎查询，例如 `process_name:powershell.exe AND command_line:*Encoded*`。 8. 生成 Markdown 或 HTML 事件报告。 9. 打开 Detection Lab 并测试 `suspicious-encoded-powershell`。 ## 截图 来自最终空间安全智能界面的最新视口捕获位于 `docs/screenshots/` 中，包括 Threat Core 概览、攻击故事重放、事件画布、证据图、检测工程、威胁狩猎、ATT&CK、数据、报告和设置路由。        ## 架构 ``` flowchart LR A["Demo generator / file import"] --> B["Raw events"] B --> C["Normalization"] C --> D["Normalized events"] D --> E["Detection engine"] D --> F["Threat hunting"] E --> G["Alerts"] G --> H["Correlation engine"] H --> I["Incidents"] I --> J["Timeline and evidence graph"] I --> K["Decision ledger"] I --> L["Reports"] I --> M["Offline / optional AI assistant"] ``` 前端：React、TypeScript、Vite、Tailwind CSS、TanStack Query、Recharts、Cytoscape.js。 后端：Python 3.12、FastAPI、Pydantic v2、SQLAlchemy 2.x、Alembic、SQLite。 ## 使用 Docker 快速开始 ``` docker compose up --build ``` 然后打开 [http://localhost:5173](http://localhost:5173)。后端暴露在 [http://localhost:8000](http://localhost:8000)，并且 `/health` 应该返回 `{"status":"ok"}`。 Windows 便捷脚本： ``` START_THREATSOC.bat ``` macOS/Linux 便捷脚本： ``` chmod +x start-threatsoc.sh ./start-threatsoc.sh ``` ## 本地开发 后端： ``` cd backend py -3.12 -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -r requirements.txt .\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` 前端： ``` cd frontend npm install $env:VITE_API_BASE_URL = "http://127.0.0.1:8000" npm run dev ``` 数据库在后端启动且内容为空时会自动初始化并播种数据。手动迁移命令： ``` cd backend .\.venv\Scripts\alembic.exe upgrade head ``` ## 检测即代码示例 ``` slug: suspicious-encoded-powershell title: Suspicious Encoded PowerShell severity: high base_score: 75 event_type: process.start match: all: - field: process_name op: equals_ci value: powershell.exe - field: command_line op: contains_ci value: "-encodedcommand" mitre: - tactic: Execution technique_id: T1059.001 technique_name: PowerShell ``` 内置规则位于 `detections/rules/*.yml`；内置关联故事位于 `detections/correlations/*.yml`。内置规则可以启用或禁用，而编辑则是通过克隆到自定义的、基于数据库的规则版本来进行的。 ## 威胁狩猎查询示例 ``` event_type:auth.failed AND user:m.rahman process_name:powershell.exe AND command_line:*encoded* source_ip:203.0.113.* AND NOT status:success host:WS-023 AND (event_type:process.start OR event_type:network.connect) ``` 解析器支持 `field:value`、带引号的字符串、`*` 通配符、`AND`、`OR`、`NOT` 和括号。查询被解析为 AST 并编译为 SQLAlchemy 谓词，而不是作为原始 SQL 执行。 ## 演示场景 恶意： - `password-spray-compromise` - `password-spray-to-execution` - `privileged-persistence` - `credential-access-indicators` - `lateral-movement` - `defense-evasion-network` 良性/噪声： - `benign-admin-maintenance` - `benign-password-mistakes` - `benign-network-volume` 所有遥测数据均为合成数据，并使用虚构的 Northstar Labs 身份以及 RFC 文档 IP 范围。 ## AI 设计 ThreatSOC 在禁用 AI 的情况下完全可以工作。离线模式提供确定性的证据摘要、技术清单和威胁狩猎建议。可选的提供程序设置仅位于服务器端： ``` THREATSOC_AI_PROVIDER=offline THREATSOC_AI_MODEL= OPENAI_API_KEY= ``` AI 响应会经过验证，因此证据引用必须属于活动的事件上下文。API 密钥永远不会返回给前端。 ## 测试 后端： ``` cd backend .\.venv\Scripts\python.exe -m pytest .\.venv\Scripts\python.exe -m ruff check . ``` 前端： ``` cd frontend npm run typecheck npm run lint npm test npm run build ``` E2E 冒烟测试： ``` cd frontend npm run test:e2e ``` 截图刷新，此时 E2E 后端/前端服务器分别在 `8011` 和 `5174` 端口运行： ``` cd frontend npm run screenshots ``` ## 数据管理 - `RESET_DEMO` 重新播种演示数据，同时保留导入的行。 - `CLEAR_IMPORTS` 删除导入的行并重建确定性的演示状态。 - `RESET_ALL_LOCAL_DATA` 删除导入的数据、自定义规则、自定义威胁狩猎和运行时证据，然后重新播种演示数据。 这些破坏性操作需要在 UI/API 中进行明确的确认值。 ## 安全说明 ThreatSOC 不会执行恶意软件、漏洞利用、凭证窃取、持久化或遏制操作。重放场景仅生成无害的合成遥测数据。 ## V1 的局限性 - 仅限本地单分析师工作流。 - SQLite 是默认数据库。 - 没有真实的 endpoint agent、SIEM 连接器、SOAR 操作、RBAC、SSO、Kafka、Elasticsearch 或 Kubernetes。 - 已实现 Markdown 和 HTML 报告；在 V1 版本中有意去除了 PDF 导出功能。 - ATT&CK 覆盖范围仅限于内置的检测范围，并不声称具有完整的 ATT&CK 覆盖。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：AV绕过, FastAPI, SIOC, 安全运营, 扫描框架, 版权保护