Gianjiji/scoobyLog
GitHub: Gianjiji/scoobyLog
一款 Python 编写的 Splunk CSV 日志分析工具，自动解析日志、检测异常、定位根因并生成完整的 Incident Response 报告。
Stars: 0 | Forks: 0
# scoobyLog
**Splunk 事件分析器** — 高级 Python 工具，用于处理从 Splunk 导出的 CSV 文件，并生成完整的 Markdown 或 HTML 格式的 Incident Response 报告。
```
scoobylog v4.3
```
## 功能简介
基于从 Splunk 导出的 CSV，scoobyLog 会自动执行：
- 解析任何格式的时间戳（ISO 8601、Apache/nginx、syslog、秒/毫秒级 epoch）
- 按时间顺序排序并标准化为 UTC
- 通过唯一键（会话、request ID、源 IP 等）隔离最异常的流程
- 通过 regex 进行异常检测：OOM、segfault、磁盘已满、timeout、身份验证失败、stack trace、slow query、连接池耗尽等
- 识别 **root cause**（根因）— 即错误链中的第一个错误 — 并测量级联深度
- 计算 **MTTR** (Mean Time To Recover) 并检测 **SLA 违规** (P1–P4)
- 生成完整的 **Incident Response 报告**，包含时间线、ASCII 事件链、网络证据、按主机划分的影响矩阵、RCA 分析、用于复现事件的 SPL 查询以及技术 playbook
## 系统要求
```
Python 3.8+
pandas >= 1.3.0
numpy >= 1.21.0
```
安装依赖项：
```
pip install -r requirements.txt
```
## 使用方法
```
# 位置参数 / drag & drop
python scoobylog.py logs.csv
# 带 flag 形式
python scoobylog.py --input logs.csv
# Report HTML，在浏览器中打开
python scoobylog.py --input logs.csv --format html --open
# 在 stdout 上快速输出 TLDR 摘要（不写入文件）
python scoobylog.py --input logs.csv --summary
# 从 stdin 读取（通过 pipe 从 Splunk CLI、curl 等传入）
cat export.csv | python scoobylog.py --input -
# 机器可读的 JSON + 增强的 CSV，不生成 Markdown report
python scoobylog.py --input logs.csv --no-report --json-summary --export-csv arricchito.csv
# 时间范围 + 最低级别过滤器
python scoobylog.py --input logs.csv --since 2024-03-15T08:00:00Z --until 2024-03-15T09:00:00Z --min-level ERROR
# 在共享前对 IP、会话 ID、UUID 和电子邮件进行匿名化处理
python scoobylog.py --input logs.csv --anonymize
# 将 JSON 摘要发送到 Slack/PagerDuty/Opsgenie webhook
python scoobylog.py --input logs.csv --alert-webhook https://hooks.example.com/incident
# 使用自定义 pattern 扩展检测
python scoobylog.py --input logs.csv --patterns-file pattern_custom.json
```
## CLI 选项参考
| Flag | 默认值 | 描述 |
|---|---|---|
| `CSV_FILE` | — | 位置输入文件（支持拖放） |
| `--input / -i` | — | Splunk CSV 的路径（`-` 表示 stdin） |
| `--output / -o` | `_incident_report.md` | 输出文件的路径 |
| `--output-dir` | — | 用于存放所有输出文件的文件夹 |
| `--timestamp-col` | 自动 | 时间戳列的名称 |
| `--level-col` | 自动 | log level 列的名称 |
| `--flow-key` | 自动 | 唯一流程键的列名 |
| `--flow-value` | 自动（最异常） | 要隔离的特定流程值 |
| `--no-flow` | 禁用 | 禁用流程隔离 |
| `--encoding` | utf-8 | CSV 文件的编码 |
| `--max-rows` | 30 | 时间线表格中的最大行数 |
| `--chain-depth` | 12 | ASCII 链中的最大事件数 |
| `--since` | — | 丢弃早于此 ISO 8601 时间戳的事件 |
| `--until` | — | 丢弃晚于此 ISO 8601 时间戳的事件 |
| `--min-level` | — | 时间线的最低 log level |
| `--max-events N` | — | 仅处理前 N 个事件（快速 triage） |
| `--json-summary` | 禁用 | 在生成报告的同时写入 `IR-.json` |
| `--export-csv PATH` | — | 将增强后的 DataFrame 导出为 CSV |
| `--patterns-file PATH` | — | 包含自定义检测 pattern 的 JSON 文件 |
| `--alert-webhook URL` | — | 将 JSON 摘要发送到 webhook |
| `--anonymize` | 禁用 | 对 IP、会话 ID、UUID 和 email 进行假名化处理 |
| `--format {md,html}` | md | 输出格式 |
| `--open` | 禁用 | 生成后在浏览器中打开报告 |
| `--no-report` | 禁用 | 跳过报告生成 |
| `--summary` | 禁用 | 将 TLDR 打印到 stdout 并退出 |
| `--quiet / -q` | 禁用 | 抑制进度输出 |
| `--version` | — | 打印版本并退出 |
## 报告结构
```
§0 Quick Reference — tabella pronta da incollare nel ticket
§1 Executive Summary + §1.1 Narrazione dell'Incidente
§2 Statistiche + §2.1 Impatto per Servizio (DOWN/DEGRADED/OK per sourcetype)
§3 Timeline eventi + §3.1 Catena ASCII + §3.2 Grafico densità errori + §3.3 Analisi Burst
§4 Analisi Precursori
§5 Analisi per Flusso + §5.1 Dettaglio flusso critico
§6 Matrice impatto per Host (Stato: DOWN/DEGRADED/OK)
§7 Recovery Timeline per Host (con durata downtime)
§8 Breakdown anomalie + §8.1 Co-occorrenze + §8.2 Sourcetype + §8.3 Errori ricorrenti
§9 Integrità Log — Gap Analysis
§10 Matrice Flussi di Rete (src → dst)
§11 Evidenze di Rete (IP, porte, URL, timeout, fallimenti auth, errori DNS)
§12 Estratti Log Raw (top 5 errori, ordinati per severità)
§13 RCA + §13.1 Evento root + §13.2 Cascata + §13.3 Cross-Host + §13.4 Lista cause
§14 Azioni Raccomandate + §14.1 Playbook Tecnico (rimedi per pattern)
§15 Appendice — §15.1 Colonne + §15.2 Parametri + §15.3 Query SPL (×3)
```
## 自定义 Pattern
无需修改脚本即可扩展内置检测功能：
```
{
"patterns": {
"mio_pattern": "stringa regex"
},
"labels": {
"mio_pattern": "**Etichetta** — descrizione per la lista cause"
},
"remediation": {
"mio_pattern": [
"Passo 1: ...",
"Passo 2: ..."
]
}
}
```
通过 `--patterns-file pattern_custom.json` 传入。
## 检测能力
**异常 Pattern**：OOM killer、segfault、磁盘已满、CPU 飙升、服务重启、TLS/SSL 证书错误、kernel panic、stack trace、slow query、连接池耗尽
**网络 Pattern**：IPv4/IPv6、端口、URL、MAC、timeout/ETIMEDOUT/ECONNRESET、身份验证失败 (401/403)、DNS 错误 (NXDOMAIN/SERVFAIL)、丢包/retransmit
**高级分析**：统计突发检测（均值+2σ）、自适应间隔检测（75 百分位数×5）、跨主机级联关联（2 秒窗口）、SLA 违规检测 (P1–P4)、事件趋势（ESCALATING/STABLE/RECOVERING）、RCA 置信度评分（ALTA/MEDIA/BASSA）
## JSON 摘要 schema
使用 `--json-summary` 时，scoobyLog 会写入包含以下内容的 `IR-.json`：
```
{
"version": "4.3",
"incident_id": "IR-XXXXXXXX",
"analyzed_at": "...",
"source_file": "...",
"total_events": 21,
"error_events": 11,
"warning_events": 5,
"anomaly_events": 14,
"host_count": 5,
"severity": { "score": 62, "grade": "P2 — ALTO", "components": {} },
"trend": "...",
"service_impact": "DEGRADED",
"mttr_seconds": 75.0,
"cascade_count": 10,
"root_cause_ts": "...",
"root_cause_level": "ERROR",
"root_cause_host": "lb-01",
"root_cause_tags": ["timeout"],
"playbook_patterns": ["timeout", "oom_killer"],
"network_evidence": {},
"burst_count": 1,
"log_gaps": [],
"duplicate_count": 0,
"recovery_timeline": []
}
```
## 快速测试
```
python scoobylog.py sample_splunk.csv
# → sample_splunk_incident_report.md (模拟 MySQL OOM → 级联 failure)
```
预期输出：
```
[✓] Root cause: ERROR @ 2024-03-15T08:01:45Z su lb-01 (timeout)
[✓] Cascata: 10 errori downstream | MTTR: 1m 15s
[✓] Severity: 62/100 — P2 ALTO
```
## 许可证
MIT — 见 [LICENSE](LICENSE)
标签：Python, 无后门, 自动化报告, 运维监控, 逆向工具