LWLawton/alertwise
GitHub: LWLawton/alertwise
一个用于 SIEM 告警分级与降噪的 Python 工具,帮助 SOC 团队降低告警噪音并提升响应效率。
Stars: 0 | Forks: 0
# AlertWise 🛡️
### SIEM 告警分级与降噪引擎
AlertWise 是一个命令行安全工具,用于摄取原始 SIEM 告警(JSON),通过四个威胁情报源进行增强,应用可配置的抑制规则,对每个告警的风险进行评分,并在几秒钟内输出清晰的分级建议。
专为 **SOC 分析员**、**虚拟 CISO**、**检测工程师** 和 **安全工程师** 而设计,帮助他们摆脱告警疲劳。
## 📸 演示输出
```
_ _ _ _ _ _ _
/_\ | |___ _ _ _| |_| | | (_)___ ___
/ _ \| / -_) '_| _\ __ / | (_- -_)
/_/ \_\_\___|_| \__|_||_|_|_/__/\___|
SIEM Alert Triage & Noise Reduction Engine v1.0.0
► Loading alerts from data/sample_alerts.json...
✓ Loaded 10 alert(s)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Triage Summary │
├────┬──────────────┬────────────────────────────────────┬──────────┬───────┬─────┤
│ # │ Alert ID │ Title │ Severity │ Score │ Dec │
├────┼──────────────┼────────────────────────────────────┼──────────┼───────┼─────┤
│ 1 │ AW-00001 │ Credential Dumping via LSASS... │ High │ 81 │ ESC │
│ 2 │ AW-00002 │ Suspicious Outbound Beacon — C2 │ High │ 74 │ INV │
│ 7 │ AW-00007 │ Ransomware-like File Extension... │ Critical │ 98 │ ESC │
│ 9 │ AW-00009 │ Scheduled Vulnerability Scan... │ Low │ 0 │ SUP │
└────┴──────────────┴────────────────────────────────────┴──────────┴───────┴─────┘
🔧 SIEM Tuning Recommendations
╭─────────────────────────────────────────────────────────────╮
│ Processed 10 alert(s): 2 ESCALATE, 4 INVESTIGATE, │
│ 3 SUPPRESS. Noise ratio: 30%. │
│ Noisiest rule: 'AUTH-FAIL-BURST' fired 3× (avg score 18) │
╰─────────────────────────────────────────────────────────────╯
✓ Done — AlertWise completed in 1.34s
Reports saved to reports/
```
### HTML 报告预览
HTML 报告包含以下特性:
- 深色主题的专业仪表盘
- 按严重性着色的每条告警卡片,支持展开查看 TI 结果
- 风险评分进度条(绿色 → 黄色 → 红色)
- 交互式分布图表
- 可折叠的 MITRE ATT&CK 详情
- SIEM 调优建议区域
- 适合打印的 CSS 样式
## 🏗️ 项目结构
```
alertwise/
├── main.py # CLI entry point
├── requirements.txt # Python dependencies
├── pyproject.toml # Build & tooling config
├── .env.example # API key template (copy to .env)
│
├── alertwise/ # Core package
│ ├── __init__.py
│ ├── pipeline.py # Orchestrator — ties all modules together
│ ├── normalizer.py # Alert schema normalisation & IOC extraction
│ ├── enricher.py # TI enrichment (VT, AbuseIPDB, Shodan, OTX)
│ ├── suppressor.py # Configurable suppression/whitelist engine
│ ├── scorer.py # Heuristic risk scoring & triage decisions
│ ├── tuner.py # SIEM tuning recommendations engine
│ ├── reporter.py # TXT + HTML report generation
│ └── utils.py # Logging setup, banner
│
├── data/
│ ├── sample_alerts.json # 10 realistic SIEM alert samples
│ ├── suppression_rules.json # Configurable suppression rules
│ └── decisions.json # Analyst override decisions
│
├── cache/ # TI API response cache (auto-created)
├── reports/ # Generated reports (auto-created)
│
└── tests/
├── __init__.py
└── test_normalizer.py # Unit tests (normalizer, suppressor, scorer)
```
## ⚙️ 安装
**要求:** Python 3.10+
```
# 1. 克隆仓库
git clone https://github.com/yourname/alertwise.git
cd alertwise
# 2. 创建虚拟环境(推荐)
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置 API 密钥(可选 — 离线演示跳过)
cp .env.example .env
# 编辑 .env 并添加您的 API 密钥
```
## 🔑 API 密钥(可选)
AlertWise 可以在 `--no-enrich` 模式下无需 API 密钥运行。如需完整增强功能,请将密钥添加到 `.env` 文件:
| 提供商 | 环境变量 | 免费额度 | 获取密钥 |
|---|---|---|---|
| VirusTotal | `VIRUSTOTAL_API_KEY` | 每日 500 次查询 | [virustotal.com](https://www.virustotal.com/gui/my-apikey) |
| AbuseIPDB | `ABUSEIPDB_API_KEY` | 每日 1,000 次检查 | [abuseipdb.com](https://www.abuseipdb.com/account/api) |
| Shodan | `SHODAN_API_KEY` | 有限免费 | [shodan.io](https://account.shodan.io/) |
| AlienVault OTX | `OTX_API_KEY` | 免费 | [otx.alienvault.com](https://otx.alienvault.com/api) |
TI 结果会**缓存**在 `cache/` 目录下的 JSON 文件中,以避免重复调用 API。
## 🚀 使用方法
### 基础用法
```
# 完整流水线(含 TI 丰富化)
python main.py --input data/sample_alerts.json
# 离线 / 演示模式(无 API 调用)
python main.py --input data/sample_alerts.json --no-enrich
# 自定义输出目录
python main.py --input data/sample_alerts.json --output-dir /tmp/triage/
# 跳过 HTML 报告生成
python main.py --input data/sample_alerts.json --no-html
# 详细调试日志
python main.py --input data/sample_alerts.json --log-level DEBUG
```
### 自定义规则与覆盖
```
# 使用自定义抑制规则
python main.py --input alerts.json --rules /path/to/my_rules.json
# 使用自定义分析师决策
python main.py --input alerts.json --decisions /path/to/my_decisions.json
```
### 输入格式
AlertWise 支持 **单个告警对象** 或 **告警列表**:
```
[
{
"event_type": "Alert",
"metadata": {
"alert_id": "CORP-12345",
"timestamp": "2024-06-15T14:32:11Z",
"source_product": "CrowdStrike Falcon",
"rule_id": "CRED-ACCESS-001",
"severity": "High"
},
"alert_summary": {
"title": "Credential Dumping via LSASS Memory Access",
"description": "mimikatz.exe accessed LSASS memory on WKSTN-042",
"severity": "High"
},
"entities": [
{ "type": "host", "hostname": "WKSTN-042", "ip": "192.168.10.42" },
{ "type": "user", "username": "jsmith" },
{ "type": "process", "name": "mimikatz.exe", "pid": 4821 },
{ "type": "ip", "value": "185.220.101.47", "direction": "dst" }
],
"mitre_attack": {
"tactic": "Credential Access",
"technique_id": "T1003.001",
"technique": "OS Credential Dumping: LSASS Memory"
}
}
]
```
**支持的实体类型:** `host`、`ip`、`user`、`process`、`file`、`hash`、`domain`、`url`
## 🧠 计分模型
AlertWise 使用一个透明、可解释的启发式计分模型(0–100):
| 组件 | 最高分 | 描述 |
|---|---|---|
| 基础严重性 | 35 | 危急=35,高=28,中=18,低=8,信息=3 |
| 威胁情报增强 | 40 | 基于所有提供者的最高指标得分进行缩放 |
| MITRE ATT&CK | 10 | 对高影响技术/战术提供加分 |
| 上下文因素 | 15 | 可疑进程、外部 IP、实体分布等 |
| 内网 IP 惩罚 | -10 | 全部为内网 RFC1918 流量会降低分数 |
### 分级决策
| 决策 | 分数范围 | 含义 |
|---|---|---|
| 🔴 **升级** | ≥ 55 | 需要分析员立即关注 |
| 🟠 **调查** | 40–54 | 在当前轮班安排调查 |
| 🔵 **监控** | 20–39 | 低优先级 — 加入观察列表 |
| ⚫ **抑制** | — | 匹配抑制规则或分析员覆盖 |
| 🟢 **良性** | < 20 | 无需操作 |
## 🔕 抑制规则
编辑 `data/suppression_rules.json` 以自定义抑制逻辑。支持以下规则类型:
```
[
{
"name": "internal-scanners",
"description": "Suppress known scanner IPs",
"type": "ip_whitelist",
"enabled": true,
"values": ["10.10.1.25", "10.10.1.26"]
},
{
"name": "internal-subnet",
"type": "ip_range",
"enabled": true,
"ranges": ["10.0.0.0/8"]
},
{
"name": "trusted-domains",
"type": "domain_whitelist",
"enabled": true,
"values": ["microsoft.com", "windows.com"]
},
{
"name": "info-level-noise",
"type": "severity_threshold",
"enabled": true,
"max_severity": "info"
},
{
"name": "noisy-rule-id",
"type": "rule_id",
"enabled": true,
"values": ["VULN-SCAN-COMPLETE"]
},
{
"name": "high-frequency-rule",
"type": "frequency_threshold",
"enabled": true,
"max_count": 5
},
{
"name": "scanner-accounts",
"type": "user_whitelist",
"enabled": true,
"values": ["svc_nessus", "svc_qualys"]
},
{
"name": "safe-processes",
"type": "process_whitelist",
"enabled": true,
"values": ["veeam_agent.exe", "backup_service.exe"]
},
{
"name": "patch-noise",
"type": "title_regex",
"enabled": true,
"patterns": ["(?i)WSUS.*update", "(?i)SCCM.*deploy"]
}
]
```
### 分析员覆盖
编辑 `data/decisions.json`,可按 `alert_id` 或 `rule_id` 覆盖分级决策:
```
{
"AW-00009": {
"action": "suppress",
"reason": "Confirmed scheduled scan — VM team notified",
"analyst": "alice@corp.com",
"reviewed_at": "2024-06-15T17:30:00Z"
}
}
```
操作:`escalate` | `investigate` | `suppress` | `benign`
## 🔧 SIEM 调优建议
AlertWise 会自动分析告警批次并输出:
- **嘈杂规则** — 触发次数 ≥3 次的规则,并附带建议(抑制、调低阈值、缩小范围)
- **抑制候选** — 抑制率 ≥70% 的规则 → 建议永久列入白名单
- **严重性偏差** — 高/危急规则持续低分 → 在 SIEM 中下调优先级
- **白名单建议** — 在 3 条以上告警中出现的 IP/域名 → 建议永久白名单
这些洞察可直接转化为 SIEM 调优工单,帮助减少分析员倦怠。
## 🧪 运行测试
```
pip install pytest
pytest tests/ -v
```
预期输出:
```
tests/test_normalizer.py::TestNormalizeSeverity::test_high PASSED
tests/test_normalizer.py::TestNormalizeSeverity::test_case_insensitive PASSED
...
tests/test_normalizer.py::TestAlertScorer::test_suppressed_alert_decision PASSED
======================== 22 passed in 0.31s ========================
```
## 🏢 实际应用场景
### 作为 SOC 分析员
- 在交接班前将 SIEM 导出 JSON 放入 AlertWise
- 在几秒钟内获得优先级排序的分级队列
- HTML 报告可直接与团队负责人分享
### 作为检测工程师
- 在一周告警数据上运行 AlertWise,识别最嘈杂的规则
- 使用调优建议减少误报
- 跟踪抑制比例以衡量改进情况
### 作为虚拟 CISO / 顾问
- 导入客户 SIEM 导出并生成专业的 HTML 分级报告
- 使用 SIEM 调优部分作为安全评审的讨论点
- 向客户展示可量化的噪声降低效果
### 在面试中
- 展示对 SOC 告警生命周期的端到端理解
- 体现构建生产级 Python 工具的能力
- 涵盖威胁情报集成、启发式计分和报告 — 均为关键 SOC 技能
- 可扩展的架构体现工程成熟度
## 🔌 扩展 AlertWise
### 添加新的威胁情报提供者
1. 在 `alertwise/enricher.py` 中添加查询函数:
```
def _my_provider_lookup(indicator: str) -> dict:
cached = _load_cache("myprovider", indicator)
if cached:
return cached
# ... call API ...
result = { "provider": "myprovider", "score": ..., "tags": [...], "raw": {} }
_save_cache("myprovider", indicator, result)
return result
```
2. 在 `ThreatEnricher.enrich()` 的相应指标区域中调用该函数。
### 添加新的抑制规则类型
1. 在 `alertwise/suppressor.py` 的 `SuppressionEngine.evaluate()` 中添加新的 `elif rtype == "my_type":` 块
2. 在 `data/suppression_rules.json` 中添加示例规则
### 添加新的计分因素
编辑 `alertwise/scorer.py` 中的 `AlertScorer.score()` — 分解字典和推理列表是透明且易于扩展的。
## 📄 输出文件
| 文件 | 描述 |
|---|---|
| `reports/alertwise_report_YYYYMMDD_HHMMSS.txt` | 完整纯文本分级报告 |
| `reports/alertwise_report_YYYYMMDD_HHMMSS.html` | 专业 HTML 仪表盘报告 |
| `cache/_.json` | 缓存的 TI API 响应 |
## 🔒 安全与隐私
- **除非配置了 API 密钥,否则数据不会离开你的机器**
- API 响应会本地缓存 — 指标仅发送一次到 TI 提供者
- 缓存文件包含原始 API 响应 — 如果指标敏感,请妥善处理
- `.env` 文件已加入 `.gitignore` — 切勿提交 API 密钥
## 📜 许可证
MIT 许可证 — 可自由使用、修改和分发。署名表示感谢。
## 🤝 贡献
欢迎提交 Pull Request。优先领域包括:
- 额外的威胁情报提供者集成(GreyNoise、IPInfo、Recorded Future)
- STIX/TAXII 告警摄取支持
- Sigma 规则映射
- Slack/Teams/PagerDuty 网页钩子通知
- Elasticsearch/OpenSearch 直接摄取
*用心为安全社区打造。AlertWise 是一个演示项目 — 在采取生产操作前,请务必手动验证结果。*
标签:JSON解析, Python CLI工具, SOC分析, vCISO, 告警 triage, 告警降噪, 命令行安全工具, 噪声抑制, 威胁情报, 安全工程师, 安全运营, 开发者工具, 扫描框架, 逆向工具, 配置化规则, 风险评分