Rootless-Ghost/ClusterIQ

# ClusterIQ — 上下文感知告警聚类引擎 属于 **Nebula Forge** 安全工具套件。 ClusterIQ 根据信号指纹对 ECS-lite 告警进行分组，然后对每个聚类进行上下文评分，以确定是否应将其 **升级**、**审查** 或 **抑制** 为噪声。与简单的去重不同，ClusterIQ 绝不会仅因信号匹配就抑制一个聚类——上下文始终优先。 ## 核心差异化 两条具有 **相同信号**（相同进程名称、相同目标 IP、相同事件操作）的告警，如果其中一条携带 TI 标签或涉及非常规用户，则会收到 **不同的判决**： ``` Cluster A — powershell.exe / C2_IP → ESCALATE (TI indicator present) Cluster B — powershell.exe / C2_IP → REVIEW (off-hours, rare user) Cluster C — powershell.exe / C2_IP → SUPPRESSED (known user, business hours, no TI) ``` ## 功能特性 - **信号指纹** — 可配置的聚类字段（process.name、event.action、目的 IP 等） - **模糊聚类合并** — 基于令牌级的 Jaccard 相似度，超过可配置阈值 - **五个上下文维度** — TI 指示器、关键资产启发式、用户异常、时段、命中率 - **上下文优先判决引擎** — TI 标签始终优先升级，无论相似度得分 - **精确去重** — 提供 `/api/deduplicate` 接口，使用滑动时间窗口 - **会话库** — 持久化 SQLite 存储，支持搜索、分页与导出 - **导出** — 每个会话支持 JSON 与 Markdown 格式导出 - **CLI** — 可在无 Web 界面情况下进行离线分析 - **集成** — 可直接从 LogNorm（端口 5006）接收 ECS-lite 数据 ## 快速开始 ``` cd ClusterIQ pip install -r requirements.txt cp config.example.yaml config.yaml # optional python app.py ``` 打开 [http://127.0.0.1:5009](http://127.0.0.1:5009)。 ## 使用方式 ### Web 界面 1. 粘贴或上传 ECS-lite 告警（JSON 数组或 NDJSON）。 2. 选择用于聚类的字段并设置相似度阈值。 3. 点击 **Cluster Alerts**。 4. 结果以颜色编码的聚类卡片展示： - **红色** — 升级 - **黄色** — 审查 - **灰色** — 抑制 5. 点击任意卡片可打开详情模态框（Overview、Context Scores、Members）。 ### CLI ``` # 集群警报，打印摘要 python cli.py --alerts alerts.json # 自定义字段和阈值 python cli.py --alerts alerts.json --fields process.name,event.action --threshold 0.8 # 另存输出为 Markdown python cli.py --alerts alerts.json --output session.md # 去重，5 分钟窗口 python cli.py --dedup --alerts alerts.json --window 300 # 打印为 JSON python cli.py --alerts alerts.json --format json ``` ## API 参考 | 方法 | 端点 | 描述 | |------|------|------| | GET | `/api/health` | 健康检查 | | POST | `/api/cluster` | 聚类告警 | | POST | `/api/deduplicate` | 移除精确重复项 | | GET | `/api/sessions` | 列出会话（分页） | | GET | `/api/session/` | 获取单个会话 | | DELETE | `/api/session/` | 删除会话 | | GET | `/api/session//export` | 导出（JSON 或 Markdown） | ### POST /api/cluster ``` { "alerts": [{...ECS-lite...}], "similarity_threshold": 0.75, "cluster_by": ["process.name", "event.action", "network.destination.ip"], "label": "Monday SOC triage", "save": true } ``` 同时接受 `alerts_json`（原始 JSON 字符串）和 `multipart/form-data`。 **响应：** ``` { "success": true, "session_id": "uuid", "clusters": [...], "original_count": 847, "cluster_count": 12, "suppressed_count": 821, "review_count": 18, "escalate_count": 8, "noise_reduction_pct": 96.8 } ``` ### POST /api/deduplicate ``` {"alerts": [...], "window_seconds": 300} ``` **响应：** `{"success": true, "unique": [...], "removed": 103, "original": 206}` ## 判决逻辑 | 条件 | 判决 | |------|------| | 任意成员包含 TI 指示器 | **升级**（始终优先，覆盖相似度得分） | | 关键资产 + 风险 ≥ 65% | **升级** | | 非常规/未知用户 ≥ 65% | **升级** | | 离时段 ≥ 30% 的成员 | **审查** | | 非常规用户 20–65% | **审查** | | 资产风险偏高 30–65% | **审查** | | 无异常上下文 | **抑制** | 上下文在每个层级均优先于信号相似度。 ## 上下文评分维度 | 维度 | 描述 | |------|------| | `ti_tags` | 标签中的威胁情报指示模式（rule.tags、threat.indicator.*） | | `has_critical_asset` | 主机名启发式：dc-、exchange、sql、prod-、srv-、backup 等 | | `user_anomaly` | 在会话告警中出现频率 ≤ 1% 的用户 | | `asset_risk` | 聚类成员中位于关键资产的比例 | | `time_anomaly` | 聚类成员中位于周一至周五 09:00–17:00 之外的比例 | | `hit_rate_anomaly` | 聚类大小相对于会话平均值的比率 | ## 聚类算法 1. **指纹化** 每个告警，提取 `cluster_by` 字段。 2. **精确分组** 按指纹的 SHA-256 哈希值分组。 3. **合并近似组**，其中令牌级 Jaccard 相似度 ≥ 阈值。 4. **评分上下文**，针对每个聚类计算五个维度的分数。 5. **分配判决** — 按优先级顺序：升级 → 审查 → 抑制。 ## 配置 | 配置键 | 默认值 | 描述 | |--------|--------|------| | `port` | `5009` | HTTP 端口 | | `db_path` | `./clusteriq.db` | SQLite 数据库路径 | | `clustering.default_threshold` | `0.75` | 相似度阈值 | | `clustering.default_fields` | `[process.name, event.action, network.destination.ip]` | 默认聚类字段 | | `clustering.max_alerts` | `50000` | 输入上限 | | `clustering.auto_save` | `true` | 自动持久化会话 | | `integrations.lognorm_url` | `http://127.0.0.1:5006` | LogNorm 端点 | ## Nebula Forge 集成 在 `nebula-dashboard/config.yaml` 中添加： ``` tools: clusteriq: label: "ClusterIQ" url: "http://127.0.0.1:5009" health_path: "/api/health" description: "Contextual alert clustering engine" category: "Detection" ``` ## 许可证 本项目采用 MIT License 授权——详情参见 [LICENSE](LICENSE) 文件。

由 [Rootless-Ghost](https://github.com/Rootless-Ghost) 构建 属于 **Nebula Forge** 安全工具套件。

标签：ClusterIQ, ECS-lite, Jaccard相似度, Nebula Forge, SQLite存储, Web界面, 上下文告警聚类, 上下文评分, 云计算, 会话管理, 信号指纹, 关键词：上下文, 关键词：告警管理, 关键词：噪声, 关键词：威胁情报标签, 关键词：安全工具, 关键词：相似度, 关键词：离岗告警, 关键词：聚类, 关键词：进程指纹, 去重, 可疑用户检测, 告警升级, 告警审查, 告警抑制, 告警聚类引擎, 命中频率, 噪声抑制, 威胁情报, 导出JSON, 导出Markdown, 开发者工具, 模糊聚类, 滑动时间窗口, 相似度分组, 离时段检测, 端口5006, 规则引擎, 资产关键性, 逆向工具, 集成LogNorm