roshini111/sysmon-security-parser-and-log-analysis
GitHub: roshini111/sysmon-security-parser-and-log-analysis
一款零依赖的 Python Sysmon 日志解析与安全分析工具链，能将原始 XML 日志转化为结构化数据，并提供基于规则的风险评分、行为关联及 MITRE ATT&CK 映射。
Stars: 0 | Forks: 0
# Sysmon 安全解析器与日志分析
本文档涵盖了**基础解析器**（`parser.py`）以及**高级流水线**（`advanced_parser.py` 和 `investigation_report.py`）的日常使用。有关高级流水线的完整架构、MITRE 映射、OSINT 扩展及企业部署指南，请参阅 **[ADVANCED_README.md](ADVANCED_README.md)**。
## 目录
1. [这是什么项目？](#1-what-is-this-project)
2. [它解决什么问题？](#2-what-problem-does-it-solve)
3. [它在哪里使用？](#3-where-is-it-used)
4. [它为什么有用？](#4-why-is-it-useful)
5. [基础解析器与高级流水线对比](#5-basic-parser-vs-advanced-pipeline)
6. [必需的 Sysmon XML 输入及重要字段](#6-required-sysmon-xml-input-and-important-fields)
7. [如何运行 parser.py](#7-how-to-run-parserpy)
8. [如何运行 advanced_parser.py](#8-how-to-run-advanced_parserpy)
9. [过滤示例](#9-filtering-examples)
10. [JSON、JSONL 和 CSV 导出示例](#10-json-jsonl-and-csv-export-examples)
11. [调查报告命令](#11-investigation-report-command)
12. [JSON 输出示例](#12-example-json-output)
13. [如何运行测试](#13-how-to-run-tests)
14. [当前局限性](#14-current-limitations)
## 1. 这是什么项目？
Sysmon 安全解析器与日志分析是一个零依赖的 Python 工具链（仅使用标准库 —— 无需 `pip install`），它能够读取 Sysmon XML 事件日志并将其转化为结构化、可过滤、具有证据评分的安全数据。它的范围涵盖了从最小化的单一用途解析器（`parser.py`）到完整的多阶段流水线，后者可以对风险进行评分、将事件关联为行为链、映射至 MITRE ATT&CK、提取失陷指标，并且 —— 仅在获得明确的人工批准时 —— 核对这些指标与 VirusTotal 的比对情况。
## 2. 它解决什么问题？
Sysmon 日志是完整却冗长的 XML：每个进程、网络连接、文件写入、注册表更改以及 DNS 查询都是其自身深层嵌套的 `` 元素，这让人工阅读变得十分困难，且输入到临时脚本或笔记本中也十分繁琐。本项目通过以下方式解决此问题：
- 将原始的 Sysmon XML 转换为干净、结构化的 JSON/JSONL/CSV。
- 应用确定性的、基于证据的检测规则，而不再要求分析师人工识别可疑的命令行。
- 将相关事件（例如，一个进程写入文件，然后修改注册表，再建立网络连接）关联为一个单一的经过评分且有序的时间线，而无需分析师从扁平化的日志中拼凑事件。
- 生成一份可读的调查报告，而不需要进行单独的手动编写。
## 3. 它在哪里使用？
- **SOC（安全运营中心）** —— 对导出的 Sysmon 批次进行分类处理，以快速将普通活动与需要升级处理的事件区分开来。
- **事件响应** —— 针对怀疑遭到入侵的主机，构建一个有序、已评分的事件发生时间线。
- **威胁狩猎** —— 按进程、用户、计算机或时间窗口过滤大型的 Sysmon 导出数据，以测试某项假设（例如，“上周是否有主机运行过编码过的 PowerShell 命令？”）。
- **数字取证** —— 针对特定主机或时间范围，生成一份具备审计性、附有证据引用的进程/文件/注册表/网络/DNS 活动记录。
- **恶意软件分析** —— 检查在实验室环境中执行的样本的进程创建、文件释放、持久化以及网络/DNS 行为。
- **SIEM 日志准备** —— 在原始 Sysmon XML 被摄取或转发到 SIEM 之前，将其规范化为扁平的 JSON/JSONL/CSV。
## 4. 它为什么有用？
- **无第三方依赖。** 可在任何运行 Python 3 的地方运行，无需安装任何内容，且除了标准库之外没有任何供应链风险面。
- **确定且基于证据。** 每一个风险点和每一个 MITRE 映射都可以追溯到特定的规则和特定的日志证据片段 —— 绝无任何猜测或由模型推断的内容。
- **从不夸大声明。** 没有固定 MITRE 映射的规则将被报告为 `"Unmapped"`，而不是被分配一个看似合理的猜测；干净的 OSINT 结果也绝不会被称为安全的证明。
- **设计上保持人在回路。** 没有明确且被记录的人工批准步骤，就不会进行任何外部查询（例如 VirusTotal）。
- **可审计的输出。** JSON 输出保留了完整的细节（评分、证据、关联推理）以供机器/审计使用，而 Markdown 报告则保持了对人类分析师的可读性。
## 5. 基础解析器与高级流水线
| | `parser.py` (基础) | `advanced_parser.py` + 流水线 (高级) |
|---|---|---|
| 支持的事件 ID | 仅限 1（进程创建） | 1, 3, 11, 13, 22 |
| 提取的字段 | `EventID`, `TimeCreated`, `Computer`, `Image`, `CommandLine`, `ParentImage`, `User`, `IntegrityLevel` | 特定于事件 ID 的字段集（见下文），外加 `ProcessGuid`/`ProcessId` |
| 过滤 | 无 | `--event-id`, `--user`, `--process`, `--computer`, `--start-time`, `--end-time` |
| 输出格式 | 仅 JSON | JSON, JSONL, CSV |
| 检测/评分 | 无 | 基于规则的检测、风险评分、时间线关联、MITRE 映射（`timeline_analyzer.py`） |
| 报告 | 无 | Mermaid 流程图、IOC 提取、经人工批准的 OSINT 扩展、置信度评分，以及综合调查报告（参见 [ADVANCED_README.md](ADVANCED_README.md)） |
当您只需要快速查看事件 ID 1 的数据时，请使用 `parser.py`。若需要进行过滤、多事件类型解析、检测和报告，请使用 `advanced_parser.py` 及其余的流水线组件。
## 6. 必需的 Sysmon XML 输入及重要字段
两个解析器都期望使用 Windows 事件日志 XML 命名空间（`http://schemas.microsoft.com/win/2004/08/events/event`）的标准 Sysmon XML，可以是以下格式之一：
- 单个 `` 文档，或
- 包含多个 `` 子节点的 `` 文档。
每个事件都必须包含一个 `` 块，其中至少包含 `EventID`、`TimeCreated`（时间戳从 `SystemTime` 属性读取，而不是元素文本）和 `Computer`。相关的 `` 字段取决于事件 ID：
| 事件 ID | 含义 | 从 `` 读取的字段 |
|---|---|---|
| 1 | 进程创建 | `Image`, `CommandLine`, `ParentImage`, `User`, `IntegrityLevel`, `ProcessGuid`, `ProcessId`, `ParentProcessGuid`, `ParentProcessId` |
| 3 | 网络连接 | `Image`, `User`, `Protocol`, `SourceIp`, `SourcePort`, `DestinationIp`, `DestinationPort`, `DestinationHostname`, `ProcessGuid`, `ProcessId` |
| 11 | 文件创建 | `Image`, `TargetFilename`, `CreationUtcTime`, `User`, `ProcessGuid`, `ProcessId` |
| 13 | 注册表值更改 | `Image`, `TargetObject`, `Details`, `User`, `ProcessGuid`, `ProcessId` |
| 22 | DNS 查询 | `Image`, `QueryName`, `QueryStatus`, `QueryResults`, `User`, `ProcessGuid`, `ProcessId` |
XML 中缺失的任何字段都将作为 `null` 返回，而不会引发错误。`ProcessGuid` 是用于将来自同一进程的相关事件进行分组的首选关联键；当它缺失时，流水线会回退到按 Computer + User + Image 进行匹配。只有事件 ID 1 包含 `ParentProcessGuid`/`ParentProcessId`，因为只有进程创建事件才具有父进程。
## 7. 如何运行 parser.py
```
py parser.py sample_event.xml
py parser.py multiple_events.xml
```
`parser.py` 会将格式化的 JSON 打印到终端。如果给定的文件不存在，它会打印 `Error: file not found: ` 并以非零状态退出；如果 XML 无效，它会打印 `Error: invalid XML in :
` 并以非零状态退出。
## 8. 如何运行 advanced_parser.py
```
py advanced_parser.py advanced_events.xml
```
在没有选项的情况下，这会解析文件中的每个事件，并将其作为 JSON 打印到终端，其中包括事件 ID 1 事件通过内置的基于规则的检查所获取的 `Suspicious` 标志和 `DetectionReasons` 列表。
## 9. 过滤示例
所有过滤器都可以组合使用；提供的每个过滤器都必须匹配（逻辑 AND）。`--user`、`--process` 和 `--computer` 不区分大小写，并接受完整值或简写形式（例如，`asmith` 匹配 `CORP\asmith`，`WORKSTATION02` 匹配 `WORKSTATION02.corp.local`）—— 绝不进行子字符串匹配。
```
py advanced_parser.py advanced_events.xml --event-id 1
py advanced_parser.py advanced_events.xml --user asmith
py advanced_parser.py advanced_events.xml --computer WORKSTATION02
py advanced_parser.py advanced_events.xml --process powershell.exe
py advanced_parser.py advanced_events.xml --start-time 2026-07-13T09:00:00 --end-time 2026-07-13T09:31:00
py advanced_parser.py advanced_events.xml --event-id 1 --process powershell.exe --user asmith
```
## 10. JSON、JSONL 和 CSV 导出示例
`--format` 默认为 `json`；`--output` 会在文件中写入，而不是终端。
```
py advanced_parser.py advanced_events.xml --format json --output events.json
py advanced_parser.py advanced_events.xml --format jsonl --output events.jsonl
py advanced_parser.py advanced_events.xml --format csv --output events.csv
```
## 11. 调查报告命令
`investigation_report.py` 运行完整的流水线（解析、评分、关联、MITRE 映射，以及 —— 如果存在的话 —— OSINT 结果），并同时写入 `investigation_report.json`（完整细节）和 `investigation_report.md`（可读摘要）：
```
py investigation_report.py demo_mixed_events.xml
```
它本身从不执行 OSINT 查找。如果 `approval_record.json` 以及 `enrichment_plan.json` 或 `live_enrichment_results.json` 中任意一个已存在于当前目录中，它会自动检测并包含它们；否则，您可以显式指定它们的路径：
```
py investigation_report.py demo_mixed_events.xml --approval-record approval_record.json --enrichment-results enrichment_plan.json
```
## 12. JSON 输出示例
`advanced_parser.py` 针对单条事件 ID 1 记录的输出：
```
{
"EventID": "1",
"TimeCreated": "2026-07-13T09:30:00.0000000Z",
"Computer": "WORKSTATION02.corp.local",
"Image": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
"CommandLine": "powershell.exe -ExecutionPolicy Bypass -WindowStyle Hidden -File C:\\Users\\asmith\\AppData\\Roaming\\update.ps1",
"ParentImage": null,
"User": "CORP\\asmith",
"IntegrityLevel": "Medium",
"ProcessGuid": "{c3333333-0000-0000-0000-000000000003}",
"ProcessId": "4400",
"ParentProcessGuid": null,
"ParentProcessId": null,
"Suspicious": true,
"DetectionReasons": ["Execution policy bypass"]
}
```
针对相同样本文件（`demo_mixed_events.xml`）的 `investigation_report.json` 中的 `ExecutiveSummary` 片段：
```
{
"ExecutiveSummary": {
"InputFilename": "demo_mixed_events.xml",
"TotalEvents": 7,
"OverallRiskScore": 85,
"OverallSeverity": "Critical",
"EvidenceConfidenceScore": 75,
"SuspiciousEventCount": 4,
"RuleBasedDetectionCount": 4,
"BehavioralChainCount": 1
}
}
```
## 13. 如何运行测试
```
py -m unittest discover -s tests -p "test_*.py" -v
```
所有测试均仅针对本地固定的 XML 文件和临时文件运行。每个与 OSINT 相关的测试都会模拟网络调用 —— 测试套件绝不会向 VirusTotal 或任何其他外部服务发出真实请求，也绝不需要 API 密钥。
## 14. 当前局限性
- **当前项目分批分析 XML 日志文件。** 每次运行都会读取完整的 Sysmon XML 导出；不支持实时跟踪日志。
- **目前尚不支持连续的实时监控。** 检测和评分发生在您针对导出文件运行工具时，而不是在事件发生时。
- **Sysmon 事件 ID 3 不提供传输的字节量**，因此无法仅从网络事件评估数据泄露量。
- **横向移动检测需要身份验证、EDR、防火墙或 Windows 安全日志** —— 仅凭 Sysmon 数据不足以确认横向移动。
- **OSINT 结果是辅助证据，而非证明。** 恶意的 VirusTotal 结果会强化调查发现；干净或未找到的结果并不能为嫌疑洗脱嫌疑。
- **切勿将 API 密钥放在源代码中。** `VT_API_KEY` 必须在您自己的 shell 中设置为环境变量 —— 本仓库中的任何文件绝不会读取、写入或打印它。
标签：AMSI绕过, Cloudflare, MITRE ATT&CK, Python, Sysmon, 威胁检测, 无后门, 逆向工具