jadzoghaib/aegis-soc-triage

# Aegis — SOC 警报分诊 Copilot **这是一个安全运营分诊系统，其整个流水线都是一个可检查的 n8n 工作流层 —— 而且产品本身深谙此道。** 来自四个异构源的警报会依次流经数据摄取、威胁情报富化、事件关联、双分类器严重性分诊、队列路由以及人工干预的遏制措施。UI 中的每一个派生事实 —— 无论是判定结果、严重程度、摘要还是被封禁的 IP —— 都链接到生成该事实的确切 n8n 执行记录。 ``` IDS ─┐ Cloud ─┤ n8n: ingest ──► enrich ──► correlate ──► triage ──► route ─► ticket Phish ─┤ (webhook, (VT/Abuse (attach/ (rules + (queue │ EDR ─┘ normalize, IPDB/OTX + create/ LLM, dis- policy) ▼ validate, offline noise) agreement containment dedupe) fallback) flag) (Wait node — analyst must Aegis app (FastAPI + SQLite) ◄──────────────────────── approve in UI) ontology · audit log · lineage panel · control surface ``` ## 为什么这不是“一个使用 n8n 的应用” 分工即是设计本身： | 层级 | 职责 | 所在位置 | |---|---|---| | **n8n** | 每一个流水线决策：验证、富化扇出、关联策略、严重性评分、路由规则、遏制提案 | 6 个可组合的工作流，在画布上可见 | | **Aegis 应用** | 本体结构（警报 → 指标 → 事件 → 资产 → 剧本）、审计日志，以及分析师可执行的*受控操作* | 基于 FastAPI + SQLite 的记录系统 | | **结合部** | 双向的、一等公民的产品特性 | 见下文 | 大多数作品集项目从未展示过的三种集成模式： 1. **人在回路的恢复。** 遏制剧本会在 n8n 的 `Wait` 节点上暂停。Aegis UI 中的 *Approve* (批准) 按钮会将分析师的决定通过 POST 请求发送到执行记录的恢复 URL —— 暂停的工作流将被唤醒并执行（或跳过）该操作。n8n 的执行状态机即是审批机制。 2. **执行血缘作为 UI。** 来自 n8n 的每个回调都带有 `workflow` + `$execution.id`。事件页面会渲染一个血缘面板 —— 摄取、富化、关联、分诊、遏制 —— 每一行都深度链接到 n8n 的执行视图，并通过 n8n 公共 API 获取实时状态。 3. **带有溯源信息的诚实降级。** 威胁情报富化在密钥存在时会尝试 VirusTotal / AbuseIPDB / OTX，并*始终*查询内置的离线情报包；每个判定结果都会与其来源一起存储，因此 UI 会准确显示哪方面的情报说了什么 —— `virustotal ⚠` 和 `offline-pack ⚠` 代表不同的声明。 ## 流水线，逐个工作流解析 | 工作流 | 触发器 | 展示内容 | |---|---|---| | `aegis/ingest-alert` | Webhook `aegis-ingest?source=…` | 分源标准化（4 种 payload 结构），带有 **死信路由** 的边界验证，重传时的 **幂等去重**，子工作流组合 | | `aegis/enrich-indicator` | 由父工作流调用 | **24h 缓存短路**，动态多提供商扇出（仅针对有密钥的提供商），每个提供商的重试 + 发生故障时继续，带有诚实溯源的离线回退 | | `aegis/correlate` | 由父工作流调用 | 画布上的关联策略：按共享指标附加 → 按共享资产附加 → 创建 —— 或者 **保持为独立警报**（并非所有情况都会构成事件） | | `aegis/triage-incident` | 由父工作流调用 | **两个独立的分类器**（确定性规则 + Groq LLM）；分歧 ≥2 个级别会标记为 *严重性争议* 并路由至高级分析师审查；最终严重性会取更安全（更高）的级别 | | `aegis/containment` | 由分诊调用（即发即弃） | 剧本提案（封禁 IP / 隔离主机 / 禁用账户 / 清除邮箱），**`Wait` 节点审批门控（12 小时超时 → 过期）**，针对每个操作的执行/失败/拒绝报告 | | `aegis/daily-digest` | 定时调度 07:00 **+ 按需 Webhook** | 多触发器模式；定时聚合任务将 Markdown 摘要写回产品中 | 包含失败分支和测试用例的完整规格说明：[docs/workflows.md](docs/workflows.md) · 本体结构：[docs/ontology.md](docs/ontology.md) · 生命周期：[docs/process-map.md](docs/process-map.md) ## 快速开始 前置条件：Python 3.11+ 并安装 [uv](https://docs.astral.sh/uv/)，Docker。 ``` # n8n (本地 Docker) — 参见 .env.example 了解其所需变量 docker compose up -d # 配置 cp .env.example .env # then: open n8n at http://localhost:5678, finish owner # setup, create an API key (Settings -> n8n API), paste # it into .env as N8N_API_KEY # 导入 + 激活六个工作流（幂等 — 可安全重新运行） uv sync uv run python scripts/bootstrap_n8n.py # 运行应用 uv run aegis # http://localhost:8100 ``` ### 90 秒演示 1. 打开 **http://localhost:8100**，选择 `ransomware_precursor`，点击 **Inject scenario**。 2. 六个原始警报（Suricata + EDR 格式）在约 10 秒内命中 n8n 的 Webhook。观察事件在队列中是如何组装的 —— 富化判定、ATT&CK 杀伤链、严重性、队列路由、分析师摘要。 3. 事件状态变为 `awaiting_containment` —— 打开它，审查提议的剧本（`block_ip 203.0.113.66`，`isolate_host ws-emea-207`…），点击其中一个旁边的 **Approve**。Toast 消息会确认 *n8n workflow resumed* —— 暂停的执行继续，针对模拟的执行层面“执行”该操作，指标随之翻转为 `blocked` 状态。 4. 检查 **Pipeline lineage** 部分：每一个阶段都链接到了 n8n 编辑器的执行视图。 5. 触发 `noise_and_edges` 以查看边界处理逻辑：格式不正确的 payload 会进入 **Rejects**（死信队列），重新传递的警报会被去重（审计日志中的 `alert.duplicate_delivery`），而良性的扫描会保持为独立警报，而不是升级为事件。 ## 威胁情报密钥（可选，免费） 如果没有密钥，富化将在离线情报包上运行。如果有密钥，实时的判定结果会显示在它旁边： | 提供商 | 免费层级 | 获取密钥 | `.env` 变量 | |---|---|---|---| | VirusTotal | 4 次请求/分钟 | virustotal.com → profile → API key | `VIRUSTOTAL_API_KEY` | | AbuseIPDB | 1000 次请求/天 | abuseipdb.com/account/api | `ABUSEIPDB_API_KEY` | | AlienVault OTX | 免费 | otx.alienvault.com → settings | `OTX_API_KEY` | 密钥仅存在于 `.env` / 容器环境变量中 —— 绝不出现在工作流 JSON 中。LLM 步骤（严重性二次评估、分析师摘要）会使用 `GROQ_API_KEY`，若未配置则会降级为确定性模板。 ## 技术栈 FastAPI · SQLite (WAL) · 原生 JS 任务控制 UI · n8n（自托管，Docker）· Groq Llama-3.3-70b · VirusTotal / AbuseIPDB / OTX API

标签：AV绕过, FastAPI, n8n, 告警分诊, 威胁情报, 安全运营, 开发者工具, 扫描框架, 数据可视化, 自动化响应, 自动化编排, 请求拦截, 逆向工具