blueteam-log-analyzer 1.5.0

BlueTeam Log Analyzer - 蓝队应急响应日志分析工具

BlueTeam Log Analyzer

离线蓝队日志分析器：把混杂日志变成告警、Incident、攻击链、IOC 和 SARIF
面向应急响应、HVV/重保、值守复盘、样本验证和 CI 安全门禁

BLA 是一个离线优先的蓝队日志分析工具。它把 Windows、Linux、Web、HVV/重保 P0 结构化安全日志统一解析成事件，再做富化、检测、关联和报告输出，帮助安全团队快速回答几个应急现场最常见的问题：

• 谁在攻击，命中了哪些入口？
• 哪台资产、哪个账号、哪个会话可能已经失陷？
• 事件能不能串成一条可信攻击链？
• 哪些 IOC、命令、进程、URL、账号需要进入封禁、排查或工单？
• 结果能不能同时给人看，也能交给 SIEM、CI 或 Code Scanning 继续处理？

所有分析默认在本机完成，不上传日志，不依赖在线服务；HTML 报告也是离线单文件。

快速开启

先确认安装成功：

pip install -U blueteam-log-analyzer
bla --version

分析一个日志目录：

bla logs/

需要生成完整报告时再加输出目录：

bla logs/ --out report/

如果你已经有本地 GeoIP JSON 缓存，可以让 HTML 报告展示攻击源地理分布；BLA 不会联网查询 IP，缓存不可读或无法定位时会退回日志内地理字段，仍无结果则自动隐藏地图：

bla logs/ --out report/ --geoip-cache geo-cache.json

分析完成后打开 report/index.html。报告目录会同时生成：

文件	用途
index.html	离线 HTML 报告，适合值守、复盘和汇报
report.json	完整结构化结果，适合二次分析和自动化
incident_brief.md	应急研判摘要，区分确认事实、研判假设、不能确认项和补证建议
incident_evidence.csv	研判证据包，只包含摘要中被引用的原始证据，避免重新翻完整事件表
events.csv	事件明细，适合 Excel 排查
iocs.txt	IOC 清单，适合封禁、狩猎和工单流转
report.sarif	SARIF 2.1.0，适合 GitHub Code Scanning 等平台
manifest.json	交付清单和文件哈希

大日志场景可以限制 JSON 事件明细体积：

bla logs/ --out report/ --json-events-limit 50000 --raw-line-limit 500
bla logs/ --out report/ --no-json-events

需要解释某个案件或告警时：

bla explain inc-001 --report report/report.json

需要从结构化报告直接导出可粘贴的研判摘要时：

bla explain brief --report report/report.json --format markdown

只需要导出应急研判摘要时：

bla logs/ --brief incident_brief.md --evidence-csv incident_evidence.csv --exit-on none

v1.5.0

v1.5.0 以检测可信度为核心：

• 检测规则化：把散落在解析器里的硬编码 Web 攻击签名收敛进可扩展的 YAML 规则引擎，web_access 与 p0_security 统一消费同一规则集，签名只维护一处，研究员可直接编辑 rules/*.yaml 扩展检测。
• HVV 规则库 3 → 27 条：覆盖 Shiro/Fastjson/Struts2/ThinkPHP/Weblogic/Spring/Java 反序列化/XXE/SSRF/未授权/国产 OA 等护网高频漏洞。
• 可度量的检测质量：新增带对抗性良性样本的评测语料与 scripts/eval_detection.py，输出 precision/recall/误报率并设为回归门禁；内置 77 样本 precision=1.00 / recall=1.00 / 误报率=0.00，并支持用你自己的真实日志验证。详见 检测质量评测。
• 统一多源 JSONL 解析器：自动识别并按 source 分流 SIEM/应急平台的统一事件 JSONL，避免被单一解析器认领、其余来源静默丢弃。
• 真实数据修复：修正带头部/.log 命名的 shell history 被误判为 0 事件、目录遍历误把 README 等文档当日志产生高危误报；在一份带 ground truth 的真实 10 阶段 APT 链上攻击链覆盖 10/10。

更多变更见 v1.5.0 发布说明，历史版本见 docs/releases。

多源攻击链示例

下面是一组 HVV/重保 P0 样本的终端和报告截图。6 条关键事件来自 WAF、应用、EDR、DNS、代理和防火墙，BLA 会把它们关联成同一个 Incident，并保持 ATT&CK 拓扑、案件拓扑和告警阶段一致。

终端视图适合一线值守先判断“是否成链”，HTML 报告适合复盘时回答“入口是什么、主机是否失陷、是否有外联和外传”。

核心能力

能力	说明
多源解析	Windows XML/EVTX/JSON、EDR Excel、Linux auth.log/secure、Apache/Nginx access log、Bash/Zsh shell history、HVV/重保 P0 CSV/JSONL/JSON/key=value、统一多源 JSONL、通用文本日志
数据驱动检测	Web/HVV 命名攻击集中在可扩展 YAML 规则（27 条内置，可编辑 rules/*.yaml 扩展），解析器只产事实；validate-rules 校验 MITRE/正则/ReDoS/元数据
可度量质量	带对抗性良性样本的评测语料 + eval_detection.py 输出 precision/recall/误报率，设回归门禁；支持用你自己的真实日志度量
检测规则	覆盖暴力破解、密码喷洒、Web 攻击、横向移动、权限提升、持久化、防御规避、凭据访问、可疑执行、C2 外联、数据外传等场景
国内画像	--profile cn-hvv 增强 Shiro、Fastjson、Struts2、ThinkPHP、WebLogic、Spring、Webshell、敏感路径探测等常见痕迹
Incident 关联	按 IP、账号、主机、资产、URL、session、trace 等线索聚合事件和告警，输出可处置案件视图
攻击链还原	按 ATT&CK / 应急 kill chain 顺序展示阶段、技术编号、日志源和关键事件
应急研判摘要	将事件和告警压缩为确认事实、主要发现、研判假设、案情演化、疑似落地文件、IP 行为画像、不能确认项和补证建议
IOC 提取	提取 IP、域名、URL、Hash、账号、路径、进程、命令，并过滤静态资源和低价值噪音
攻击源地理分布	可选加载本地 GeoIP 缓存或日志自带地理字段，在 HTML 报告中展示可定位公网源 IP 分布
报告交付	一次生成 HTML、JSON、研判 Markdown、CSV、IOC、SARIF、manifest，兼顾人工研判和系统集成
离线与自动化	本地离线运行，支持 --exit-on、benchmark、Remote Workspace、规则校验和 CI 流水线

支持的日志

日志类型	输入格式	典型用途
Windows 事件日志	.xml、.evtx	登录、RDP、账号变更、服务安装、计划任务、日志清除、Sysmon 进程与网络行为
EDR/XDR 导出日志	.xlsx	进程创建、进程加载、文件签名、进程 SHA1、命令行、用户目录无签名执行和投放链
Linux 认证日志	auth.log、secure	SSH 爆破、成功登录、sudo、root 登录、账号创建
Shell 历史	.bash_history、.zsh_history、*history	主机枚举、工具下载、TTY 升级、SUID/sudo 提权、凭据文件读取、清痕命令；目录扫描会保留 Bash/Zsh history 证据文件
Web 访问日志	Apache/Nginx Combined	SQLi、XSS、LFI/RFI、RCE、扫描器、敏感文件探测、异常流量
HVV/重保 P0 日志	CSV、JSONL、JSON object、JSON 数组、key=value	WAF、VPN、堡垒机、DNS、代理/NAT、防火墙、EDR、应用日志
统一多源事件	带 source 标签的统一 JSONL（SIEM/应急平台导出）	按来源自动分流到各解析器，一份文件完整还原多源攻击链
通用文本日志	任意文本	关键字提取、轻量告警和 IOC 辅助提取

EVTX 二进制解析是可选能力：

pip install -U "blueteam-log-analyzer[evtx]"

未安装 EVTX 依赖时，BLA 会明确提示转换方案，不会静默产出空报告。

常用工作流

分析本地日志目录

bla /var/log/ --out report/ --exit-on none

带本地 GeoIP 缓存生成攻击源地图：

bla /var/log/ --out report/ --geoip-cache geo-cache.json --exit-on none

缓存可以是按 IP 索引的 JSON 对象，例如：

{
  "8.8.8.8": {
    "country": "United States",
    "regionName": "California",
    "city": "Mountain View"
  }
}

自动识别不准时可以指定解析器：

bla access.log --type web-access --out report/
bla Security.xml --type windows-xml --out report/
bla .bash_history --type shell-history --out report/
bla hvv_chain.jsonl --type p0-security --profile cn-hvv --out report/
bla unified_events.jsonl --type unified-jsonl --out report/

SIEM/应急平台导出的统一多源 JSONL（每行带 source 标签 + raw 或结构化字段）通常无需指定类型，BLA 会自动按来源分流到各子解析器并合并成一条完整攻击链：

bla unified_events.jsonl --out report/ --exit-on none

HVV/重保多源研判

bla p0-logs/ --type p0-security --profile cn-hvv --out hvv-report/ --exit-on none

建议第一轮优先采集 WAF、CDN/SLB、Web access、应用日志、VPN/零信任、堡垒机、AD/域控、EDR/XDR、DNS、出口代理、防火墙/NAT、NDR/全流量、数据库审计和云审计。完整采集矩阵可由 CLI 输出：

bla --list-log-sources

Windows 日志分析

导出 EVTX：

wevtutil epl Security Security.evtx /ow:true
wevtutil epl System System.evtx /ow:true
wevtutil epl "Microsoft-Windows-Sysmon/Operational" Sysmon.evtx /ow:true

导出无额外依赖的 XML：

wevtutil qe Security /f:RenderedXml /e:Events > Security.xml
wevtutil qe System /f:RenderedXml /e:Events > System.xml
wevtutil qe "Microsoft-Windows-Sysmon/Operational" /f:RenderedXml /e:Events > Sysmon.xml

分析：

bla Security.evtx System.evtx Sysmon.evtx --out windows-report/
bla Security.xml System.xml Sysmon.xml --out windows-report/

只看 RDP 登录：

bla Security.xml --rdp --json rdp.json --exit-on none

远程只读采集

目标主机无法安装 Python、pip 或 BLA 时，可以用 Remote Workspace 在本机分析远程日志。远程侧只需要 SSH 和系统自带命令。

bla remote-log [e-mail] /var/log/auth.log \
  --tail 1000 \
  --grep "Failed password" \
  --out case-auth \
  --audit-json case-auth-audit.json \
  --exit-on none

也可以进入交互式工作台：

bla ssh [e-mail]

工作台内支持 ls、cd、find、tail、bla FILE、bla FILE --tail N --grep TEXT、bla journalctl:ssh 等命令。

CI 和流水线门禁

# 高危及以上告警时退出 1
bla logs/ --exit-on high --json result.json --sarif report.sarif

# GitHub Code Scanning
gh code-scanning upload-sarif --sarif report.sarif

--exit-on 可选 none、low、medium、high、critical，默认是 critical。

自定义规则和误报压制

加载自定义 YAML Web 检测规则：

bla access.log --rules ./rules --profile cn-hvv --out report/
bla validate-rules --strict-metadata

使用 allowlist 压制可信扫描器、维护窗口或已知噪音：

bla logs/ --allowlist docs/allowlist-example.json --out report/

检测覆盖

类别	示例	MITRE ATT&CK
侦察	扫描器、敏感文件探测、目录枚举	T1595, T1083
初始访问	Web 漏洞利用、Log4Shell/JNDI、国内常见 Web 漏洞痕迹	T1190
身份突破	SSH/RDP/Kerberos 暴力破解、密码喷洒、爆破后成功登录	T1110.001, T1110.003
执行	高危 PowerShell、命令注入、LOLBins、Shell TTY 升级、远程工具下载	T1059, T1218, T1105
持久化	服务安装、计划任务、账号创建	T1543.003, T1053.005, T1136
权限提升	sudo shell、特权组变更、root 直接登录	T1548.003, T1098.001
主机失陷	Webshell、EDR/XDR 高危终端告警、恶意进程痕迹	T1505.003
横向移动	RDP 跳转、显式凭据、Pass-the-Hash 指示器	T1021.001, T1550.002
命令控制	DNS 隧道、高风险代理访问、C2 外联	T1071, T1071.004, T1105
数据外传	大流量外联、敏感数据外传迹象	T1041
凭据访问	Mimikatz、LSASS 访问、凭据转储、Linux 敏感凭据文件读取	T1003.001, T1003.008
防御规避	日志清除、审计策略修改、安全能力关闭、Shell history 清除和痕迹删除	T1070.001, T1070.003, T1070.004, T1562.002

检测质量（可度量）

检测质量不是“靠挑几个能过的样例做断言”，而是测量出来的。BLA 用一份带标注的语料持续度量 precision / recall / 误报率，语料特意混入对抗性良性流量（看着像攻击、实为正常：?id=1、含 select/union/exec 的业务词、/wp-content 图片、合法 curl 健康检查、携带外部 https 链接的 OAuth 回调等），让误报率有意义。

• 内置 77 样本（38 真阳 + 39 对抗性良性）：precision = 1.00 / recall = 1.00 / 误报率 = 0.00。
• 这个过程真的会抓 bug：评测先后暴露并修复了 scanner 误判通用 curl/wget、\bexec\b 命中路径单词、SSRF 把任意外部 url= 当攻击等真实误报。
• 在一份带 ground truth 的真实多源事件包（10 阶段 APT 链）上，攻击链还原覆盖 10/10 个阶段。
• 质量下限由 tests/test_detection_quality.py 设为回归门禁，纳入 CI，防止质量悄悄退化。

# 跑内置语料，打印混淆矩阵与 precision/recall/误报率
python3 scripts/eval_detection.py

# 用你自己的真实日志度量（标注清单指向真实日志文件即可）
python3 scripts/eval_detection.py --manifest /path/to/your-manifest.jsonl

方法、清单格式和“用你自己的真实日志验证”工作流见 检测质量评测。

报告截图

文档

文档	内容
检测质量评测	评测方法、当前 precision/recall 结果、修复的真实误报，以及用你自己的真实日志验证的工作流
应急研判摘要	incident_brief.md、HTML 研判章节和 report.json["incident_brief"] 的结构、边界和使用方式
架构说明	解析、富化、检测、关联、输出的可扩展设计
演示案例库	样例、复现命令和功能覆盖矩阵
SecRepo 样本验证	公开 auth.log 和 Web access.log 实测记录
测试资源清单	可用于评估日志分析能力的公开资源
发布检查清单	GitHub Release 和 PyPI 发布前检查项
历史版本	每个版本的发布说明

开发与测试

git clone https://github.com/Hackerchen716/blueteam-log-analyzer.git
cd blueteam-log-analyzer

python3 bla_cli.py --help
python3 -m compileall -q bla bla_cli.py setup.py tests
python3 -m unittest discover -s tests -v
python3 scripts/release_check.py

当前回归测试覆盖解析、检测、Incident 关联、攻击链阶段、HTML/JSON/研判 Markdown/研判证据包/CSV/IOC/SARIF 输出、Remote Workspace、规则校验、报告安全转义、终端控制字符清理、P0 多源 golden incident、统一多源 JSONL 分流、端到端攻击链覆盖门禁、检测质量（precision/recall/误报率）门禁和发布质量检查。

度量当前检测质量：

python3 scripts/eval_detection.py

包版本由 bla/__version__.py 作为单一版本源，pyproject.toml 和 setup.py 都读取同一来源。发布前请按 release checklist 执行完整检查。

项目结构

bla/
  parsers/      日志解析器、统一多源分流和自动识别入口
  detection/    富化、检测器、规则注册和 Incident 关联
  output/       终端、HTML、JSON、CSV、IOC、SARIF、manifest、报告包
  remote/       SSH 远程日志工作台
  rules/        内置 YAML Web 检测规则（27 条，可扩展）
docs/           架构、检测质量、案例、发布说明、测试资源和截图
sample_logs/    本地 smoke 示例日志
tests/          回归测试、检测质量语料和 P0 / 攻击链 golden fixture
scripts/        发布检查与检测质量评测脚本

参与贡献

欢迎提交 Issue 或 Pull Request，尤其是这些方向：

• 补充真实环境中常见的安全设备、主机、Web 服务和业务日志格式。
• 扩展 Web 攻击、身份突破、横向移动、权限变更、可疑执行、日志清除、C2 外联和数据外传检测规则。
• 改进 allowlist、可信扫描器、维护窗口和基线压制能力。
• 优化 HTML / JSON / CSV / IOC / SARIF 报告，让结果更适合值守、复盘和工单流转。
• 补充脱敏样本、单元测试、回归测试和性能测试。

请不要提交真实客户日志、敏感 IP、账号、Cookie、Token、业务数据或未脱敏截图。

交流与合作：[e-mail]

许可证

MIT License © 2026 Hackerchen716