adiallo10/security-alert-triage-cli

# 安全告警分诊 CLI 一款零依赖的命令行工具，能够对安全告警进行评分，标记可能的误报，并生成一个**已排序、可解释的分诊队列** —— 让分析师能够优先处理最高风险的告警，而不是阅读一大堆毫无头绪的噪音。 旨在模拟真实的 SOC 初筛分诊：每个告警都会获得一个 0–100 的优先级评分、一个建议的操作（**升级 / 调查 / 监控 / 可能是误报**），以及一份驱动该评分确切因素的透明列表。 ``` # SCORE RECOMMENDATION SEV ALERT ------------------------------------------------------------------------------ 1 99 Escalate critical Data exfiltration: large upload ... └─ Microsoft Sentinel · a.smith@corp.local · Base severity: critical 2 78 Escalate critical Malware detected and quarantined └─ CrowdStrike Falcon · WKS-4521 · Base severity: critical ... 9 4 Likely False Positive medium Vulnerability scan detected open port └─ qualys · 10.20.4.11 · Source 'qualys' is typically benign Triaged 12 alerts | 2 Escalate 3 Investigate 5 Likely False Positive 2 Monitor ``` ## 为什么开发它 在 SOC 工作期间，很大一部分初筛分诊工作是机械化的：阅读告警、权衡严重性和上下文、猜测是否为误报，并决定将哪些内容升级。该工具自动化了这一机械层，同时保留了人工介入环节 —— 并且重要的是，它会**展示其推理过程**，以便分析师能够信任或质疑每一个决定。 ## 功能特性 - **可解释的评分** —— 每个增加或扣除的分数都会附上通俗的原因记录。没有黑盒。 - **误报检测** —— 会降低已知的良性扫描器、测试/实验室活动以及低严重性的单一事件的排名。确认的威胁情报命中始终会覆盖误报判定。 - **上下文感知** —— 综合考虑特权账户、外部来源、非工作时间活动、事件量和 IOC 匹配等因素。 - **灵活的输入** —— 读取 JSON 或 CSV，并规范化来自不同 SIEM/EDR 导出的混乱字段名（`alert_id`/`uuid`、`priority`/`level`、`sev2` 等）。 - **机器可读输出** —— 支持 `--json` 以通过管道传递给其他工具。 - **可选的 AI 摘要** —— `--explain` 标志可生成纯英文描述。默认引擎**完全离线且免费**；可选的 Anthropic/Claude 提供程序可以启用，但绝非必须。 - **零必要依赖** —— 在 Python 3.9+ 标准库上运行。 ## 安装 无需安装即可运行 —— 只需克隆并执行： ``` git clone https://github.com/adiallo10/security-alert-triage-cli.git cd security-alert-triage-cli python3 -m alert_triage --input sample_data/alerts.json ``` 或者将其安装为正式的命令： ``` pip install -e . alert-triage --input sample_data/alerts.json ``` ## 用法 ``` # 基本分诊 python3 -m alert_triage -i sample_data/alerts.json # 仅显示前 5 个，附带通俗易懂的解释 python3 -m alert_triage -i sample_data/alerts.json --top 5 --explain # 隐藏低优先级 noise python3 -m alert_triage -i sample_data/alerts.json --min-score 45 # CSV 输入，JSON 输出（用于 pipelines） python3 -m alert_triage -i sample_data/alerts.csv --json ``` ### 选项 | 标志 | 描述 | |------|-------------| | `-i, --input` | 告警文件的路径（`.json` 或 `.csv`）。**必填。** | | `-f, --format` | `auto`（默认）、`json` 或 `csv`。 | | `-t, --top N` | 仅显示优先级最高的前 N 个告警。 | | `--min-score` | 隐藏得分低于此值 (0–100) 的告警。 | | `--explain` | 为每个告警打印通俗易懂的解释。 | | `--ai-provider` | `local`（离线，默认）或 `anthropic`（使用 Claude API）。 | | `--json` | 输出机器可读的 JSON，而不是表格。 | | `--no-color` | 禁用 ANSI 颜色。 | ## 评分原理 分数从告警的严重性开始计算，并通过透明的规则进行调整： | 因素 | 影响 | |--------|--------| | 基础严重性（critical → info） | +50 … +3 | | 匹配已知威胁情报 / IOC | +20 | | 涉及特权账户/资产 | +12 | | 高事件量 (≥10) | +10 | | 发生在工作时间之外 | +8 | | 外部 / 公共来源 | +6 | | 良性来源（扫描器、健康检查） | −22 | | 文本中的测试/实验室指标 | −12 | | 低严重性 + 单次发生 | −6 | 分数被限制在 0–100 之间。建议阈值：**≥70 升级**，**≥45 调查**，**≥20 监控**，否则为**可能是误报**。 有关完整逻辑，请参见 [alert_triage/scoring.py](alert_triage/scoring.py)。 ## 可选：AI 驱动的解释 `--explain` 功能在开箱即用时使用确定性的离线引擎运行。要使用 Claude 生成更丰富的摘要，请执行： ``` pip install anthropic export ANTHROPIC_API_KEY="sk-ant-..." # never commit this python3 -m alert_triage -i sample_data/alerts.json --explain --ai-provider anthropic ``` 如果密钥或 SDK 缺失，该工具将静默回退到离线解释器 —— AI 层是一项增强功能，而不是硬性依赖。 ## 运行测试 ``` python3 -m unittest discover -s tests -v ``` 18 个测试涵盖了评分行为、误报逻辑、字段规范化和输入加载。 ## 项目布局 ``` alert_triage/ ├── models.py # Alert dataclass + field normalization ├── loader.py # JSON/CSV loading ├── scoring.py # explainable scoring + false-positive rules ├── report.py # table and JSON rendering ├── explain.py # optional (offline or Claude) explanations └── cli.py # argparse entry point sample_data/ # example alerts (JSON + CSV) tests/ # unit tests ``` ## 安全与数据说明 - 所有样本数据均为**合成数据**。不包含任何真实的告警数据。 - Anthropic API 密钥仅从环境变量中读取 —— 绝不硬编码或提交到代码库。 ## 许可证 MIT © Alhousseiny Diallo —— 详见 [LICENSE](LICENSE)。

标签：Python, SOC运营, 安全告警分诊, 安全运营, 扫描框架, 文档结构分析, 无后门, 误报过滤, 逆向工具