LevaAverGit/log-incident-analyzer-v2

# 日志事件分析器 [](https://github.com/LevaAverGit/log-incident-analyzer-v2/actions/workflows/ci.yml)    Python CLI 工具，用于对 Linux auth 日志、Nginx access 日志和 syslog 进行基于规则的分析。它能解析原始日志、检测可疑模式、按源 IP 将发现结果分组为事件、分配严重性评分、构建时间线，并生成 Markdown 和 JSON 报告。 ## 工程亮点 - **分阶段流水线** — 解析 → 检测 → 分组 → 时间线 → 报告；每个阶段 都可以独立测试，并生成带有类型的输出（`List[ParsedEvent]`， `List[Finding]`, `List[Incident]`） - **配置驱动的阈值** — 检测阈值存在于 `config/default_rules.yml` 中 并通过流水线传递；检测器函数中没有硬编码的值 - **统一的检测器接口** — 所有检测器都接收 `(events, cfg) → List[Finding]`； 添加新规则无需更改流水线或报告代码 - **多指标加成** — 触发不止一种规则类型的 IP 在事件分组时将 获得 +20 的评分加成，从而展示出相关的攻击模式 - **双重输出格式** — 相同的数据模型可序列化为 Markdown （结构化事件报告）和 JSON（可 diff、机器可读格式） - **58 个测试，测试中 0 外部依赖** — 所有检测器均使用内联 合成的 `ParsedEvent` 对象进行测试；运行测试套件不需要日志文件 ## 检测流水线 ``` auth.log + nginx_access.log + syslog ↓ [1] Parser → List[ParsedEvent] ↓ [2] Detectors → List[Finding] (5 rules, configurable thresholds) ↓ [3] Incident → List[Incident] (group by IP, apply multi-indicator bonus) Grouping ↓ [4] Timeline → List[TimelineEvent] ↓ [5] Report → Markdown / JSON Generator ``` 有关详细的逐阶段分解，请参阅 `docs/DETECTION_PIPELINE.md`。 ## 如何添加新的检测规则 1. 将 `detect_*(events, cfg)` 添加到 `analyzer/detectors.py` 2. 在 `run_all_detectors()` 中注册 3. 在 `config/default_rules.yml` 中添加阈值 4. 在 `tests/test_detectors.py` 中编写测试 完整的操作指南请参阅 `docs/RULE_DEVELOPMENT_GUIDE.md`。 ## 问题背景 原始服务器日志包含大量噪音。在初步分类阶段，快速识别以下情况非常有用： - 来自单一 IP 的重复身份验证失败 - Web 目录扫描模式 - 访问敏感路径（`.env`, `/admin`, `/wp-login.php` 等） - 来自已知扫描器 user-agent（Nikto、sqlmap、gobuster）的请求 - 暗示撞库或强制浏览的重复 401/403 响应 跨多个日志文件手动执行此操作非常耗时。该工具可自动执行检测，并生成结构化、人类可读的事件报告。 ## 解决方案 ``` raw logs → parsed events → findings → incident grouping → severity scoring → timeline → Markdown/JSON report ``` ## 功能特性 - `auth.log` 解析：登录失败、登录成功、无效用户、sudo 事件 - Nginx `access.log` 解析：方法、URL、状态码、user-agent - `syslog` 解析：服务错误和警告 - **SSH 暴力破解**模式检测（基于阈值） - **Web 目录扫描**检测（每个 IP 的 404 数量） - **敏感路径访问**检测 - **可疑 user-agent**检测（sqlmap、nikto、gobuster、masscan 等） - **重复 401/403**检测 - 按源 IP 进行事件分组，并带有综合严重性评分 - 多指标加成：当一个 IP 触发不止一种发现类型时，评分 +20 - 按时间戳排序的可疑事件时间线 - 包含摘要、事件、时间线、建议和局限性的 Markdown 报告 - 用于下游处理的 JSON 报告 - `pytest` 测试套件 — 58 个测试 ## 项目结构 ``` log-incident-analyzer/ ├── analyzer/ │ ├── models.py # ParsedEvent, Finding, Incident, TimelineEvent │ ├── parser.py # Log parsers │ ├── detectors.py # Detection rules │ ├── scoring.py # Severity scoring │ ├── incident_grouping.py # Group findings into incidents by IP │ ├── timeline.py # Timeline builder │ └── reporter.py # Markdown and JSON report generation ├── sample_logs/ │ ├── auth.log │ ├── nginx_access.log │ └── syslog ├── reports/ # Example generated reports ├── tests/ ├── main.py ├── requirements.txt └── LICENSE ``` ## 安装 ``` git clone https://github.com/LevaAverGit/Log-incident-analyzer.git cd log-incident-analyzer python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ## 用法 分析所有示例日志，输出 Markdown 报告： ``` python3 main.py --all-samples --output reports/incident_report.md ``` JSON 报告： ``` python3 main.py --all-samples --format json --output reports/incident_report.json ``` 分析单个 auth 日志： ``` python3 main.py --auth sample_logs/auth.log --output reports/auth_report.md ``` 分析单个 Nginx 日志： ``` python3 main.py --nginx sample_logs/nginx_access.log --output reports/nginx_report.md ``` 所有选项： ``` --auth FILE path to auth.log --nginx FILE path to nginx access log --syslog FILE path to syslog --all-samples use all files in sample_logs/ --format md|json output format (default: md) --output PATH output file or directory (default: reports/incident_report.md) --config FILE path to YAML rules config (default: config/default_rules.yml) ``` 使用自定义配置： ``` python3 main.py --all-samples --config config/default_rules.yml --output reports/incident_report.md ``` ## 示例输出 在包含的示例日志上运行 `--all-samples`： ``` $ python3 main.py --all-samples --output reports/incident_report.md [*] auth: 100 events, 0 errors — sample_logs/auth.log [*] nginx: 100 events, 0 errors — sample_logs/nginx_access.log [*] syslog: 29 events, 0 errors — sample_logs/syslog [+] findings: 9, incidents: 5 [+] Report saved: reports/incident_report.md ``` ``` $ python3 main.py --all-samples --format json --output reports/incident_report.json [*] auth: 100 events, 0 errors — sample_logs/auth.log [*] nginx: 100 events, 0 errors — sample_logs/nginx_access.log [*] syslog: 29 events, 0 errors — sample_logs/syslog [+] findings: 9, incidents: 5 [+] Report saved: reports/incident_report.json ``` ``` $ python3 -m pytest tests/ -v ... 58 passed ``` 生成报告的摘要： | 字段 | 值 | |---|---| | 总解析事件数 | 229 | | 总发现数 | 9 | | 总事件数 | 5 | | 严重事件 | 2 | | 高危事件 | 1 | | 中危事件 | 1 | | 低危事件 | 1 | ## 报告 示例报告位于 `reports/` 中： - `reports/incident_report.md` — 完整的 Markdown 报告 - `reports/incident_report.json` — 机器可读的 JSON Markdown 报告包含：摘要、Top 源 IP、检测到的事件（包含证据和建议）、时间线、一般性建议和局限性。 ## 文档 | 文档 | 描述 | |---|---| | [`docs/DETECTION_RULES.md`](docs/DETECTION_RULES.md) | 完整的检测规则规范：触发器、阈值、证据、建议 | | [`docs/TRIAGE_PLAYBOOK.md`](docs/TRIAGE_PLAYBOOK.md) | 针对每种发现类型的分步分类程序 | | [`docs/INCIDENT_RESPONSE_MAPPING.md`](docs/INCIDENT_RESPONSE_MAPPING.md) | 发现结果如何映射到 IR 阶段（NIST SP 800-61）和 SOC L1 工作流 | | [`docs/SIEM_MAPPING.md`](docs/SIEM_MAPPING.md) | 映射到 SIEM 用例、JSON 集成、与生产环境 SIEM 的对比 | | [`docs/DETECTION_PIPELINE.md`](docs/DETECTION_PIPELINE.md) | 带有输入/输出类型的逐阶段流水线分解 | | [`docs/RULE_DEVELOPMENT_GUIDE.md`](docs/RULE_DEVELOPMENT_GUIDE.md) | 如何实现和测试新的检测规则 | | [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) | 配置文件 schema、阈值调整、误报指南 | | [`docs/ARCHITECTURE_DECISIONS.md`](docs/ARCHITECTURE_DECISIONS.md) | 为什么这样设计架构 | | [`docs/QUALITY_ASSURANCE.md`](docs/QUALITY_ASSURANCE.md) | 测试策略、模式以及手动验证检查清单 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | 本地设置、运行测试、添加规则和解析器 | ## 测试策略 ``` python3 -m pytest tests/ -v # 或 make test ``` **58 个测试全部通过。** 所有测试均可在没有日志文件或外部服务的情况下运行 — 检测器使用内联构建的合成 `ParsedEvent` 对象进行测试。 覆盖范围：`test_parser`、`test_detectors`、`test_scoring`、`test_incident_grouping`、 `test_timeline`、`test_reporter`、`test_config`。 有关测试策略和模式，请参阅 `docs/QUALITY_ASSURANCE.md`。 ## 检测逻辑 每个检测器都会生成一个包含以下内容的 **Finding**（发现）： - `finding_type` — 可疑活动的类别 - `source_ip` — 源 IP - `severity` — Low / Medium / High / Critical - `score` — 数字评分 (0–100) - `evidence` — 观察到的数据点 - `recommendation` — 建议的后续行动 发现结果按源 IP 分组为 **Incident**（事件）。如果一个 IP 触发不止一种发现类型，会在综合评分中加入 +20 的多指标加成。 **严重性等级表：** | 分数 | 严重性 | |---|---| | 0–20 | Low | | 21–50 | Medium | | 51–80 | High | | 81–100 | Critical | **SSH 暴力破解阈值：** | 失败尝试次数 | 分数 | 严重性 | |---|---|---| | > 10 | 30 | Medium | | > 30 | 55 | High | | > 100 | 90 | Critical | ## 局限性 - 仅基于规则的检测 — 阈值是固定的，并针对示例数据进行了调整 - 不能替代 SIEM 或 EDR - 不会自动确认系统是否被攻破 - 没有归属分析 — 源 IP 可能是伪造的，或者属于出口节点 - 示例日志是合成的，仅用于演示目的 - 在采取任何行动之前，所有发现结果都需要进行手动分类 - 不支持每种日志类型的日志轮转、压缩文件或多文件合并 - 时间戳以原始字符串存储；没有跨日志的时间关联 ## 数据和规模限制 包含的 `sample_logs/` 文件是 **合成的演示规模数据**（每个文件约 100 个事件，总共约 300 个事件）。它们的存在是为了演示该工具的流水线并生成具有代表性的报告。 该工具**未在生产规模的日志文件上进行过测试**。真实的服务器日志每天可能包含数十万到数百万行。当前的实现会将文件完全读入内存，这对于小文件来说足够了，但如果不加修改，可能不适合处理大量数据。 检测阈值（例如，暴力破解在失败尝试次数 >10 时触发）在代码中是固定的，并针对示例数据进行了校准。在真实环境中，适当的阈值取决于服务器的流量画像，并且应该是可配置的。 需要注意的主要限制： - 未在超过几 MB 的日志上进行过测试 - 仅基于规则 — 没有基于统计或 ML 的异常检测 - 不更改代码，阈值无法配置（计划在未来版本中实现） - 来自不同日志源的时间戳不按时间窗口关联 - 该工具是一个学习和演示项目 — 在根据任何输出采取行动之前，需要手动验证 ## 这如何映射到真实的 SOC 工作 日志分析是 SOC L1 分析师在初步分类期间的核心任务。 该工具针对静态日志文件自动化了该工作流的检测阶段。 | 本工具 | 真实的 SOC / SIEM 对应项 | |---|---| | 日志解析器 (`parser.py`) | 日志源连接器和规范化层 | | 检测规则 (`detectors.py`) | SIEM 关联规则（用例） | | 带有严重性和分数的发现 | 带有优先级的 SIEM 警报 | | 按源 IP 进行事件分组 | 基于实体的关联 | | 多指标加成 | 关联规则中的多事件 AND 条件 | | JSON 报告 | 用于 SOAR / 工单系统集成的警报 payload | | YAML 阈值 (`config/`) | SIEM 管理控制台中的规则调整参数 | 在真实的 SOC 中： - 日志源实时输入到 SIEM（MaxPatrol SIEM、KUMA、Splunk、ELK）中 - 关联规则自动触发，并在事件管理系统中创建工单 - L1 分析师使用 playbook 对警报进行分类，然后升级或关闭 - 跟踪诸如 MTTD（平均检测时间）和 MTTR（平均响应时间）等指标 该工具针对一批静态日志演示了该过程的检测规则逻辑和分类工作流。 有关详细比较，请参阅 [`docs/SIEM_MAPPING.md`](docs/SIEM_MAPPING.md)， 有关分步分类程序，请参阅 [`docs/TRIAGE_PLAYBOOK.md`](docs/TRIAGE_PLAYBOOK.md)。 ## MITRE ATT&CK 对齐 该工具中的检测规则映射到以下 MITRE ATT&CK 技术： | 检测 | MITRE 技术 | 战术 | |---|---|---| | SSH 暴力破解 | T1110.001 暴力破解：密码猜测 | 凭证访问 (TA0006) | | 失败后的成功登录 | T1078 有效账户 | 初始访问 (TA0001) | | Web 目录扫描 / 404 泛洪 | T1595.002 主动扫描：漏洞扫描 | 侦察 (TA0043) | | 敏感路径访问 (/.env, /.git) | T1083 文件和目录发现 | 发现 (TA0007) | | 扫描器 user-agent 字符串 | T1595 主动扫描 | 侦察 (TA0043) | | 重复的 401/403 响应 | T1110 暴力破解 | 凭证访问 (TA0006) | ## 本项目在安全岗位上展示的技能 - Linux 日志格式知识：`auth.log`、Nginx access 日志、syslog - SOC L1 分类逻辑：严重性优先级排序、升级标准、遏制步骤 - 基于规则的检测：阈值调整、误报推理、多信号聚合 - 将发现结果映射到 IR 阶段（NIST SP 800-61 检测和分析） - 结构化事件报告：收集、时间线重建 - SIEM 概念理解：用例、关联规则、警报 payload 格式 - MITRE ATT&CK 技术意识：将检测标记到战术/技术 ID - 使用受控的输入 fixture 对检测模块进行 pytest 设计 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：IP 地址批量处理, Python, 安全运营, 异常检测, 扫描框架, 文档结构分析, 无后门, 逆向工具