JaskRendix/odlparser
GitHub: JaskRendix/odlparser
odlparser 是一个模块化、完全类型化的 OneDrive ODL 同步引擎日志解析器，能自动解码混淆与 AES 加密的二进制日志并输出结构化数据。
Stars: 0 | Forks: 0
# **odlparser — 现代、模块化的 OneDrive ODL 日志解析器**
一个针对 **Microsoft OneDrive ODL 同步引擎日志** 的简洁、带类型且完全模块化的解析器。
本项目是对 **Yogesh Khatri (@swiftforensics)** 原始取证解析器的现代重构。
它保留了原有的解码逻辑（混淆映射、AES keystore、CDEF 解析），同时提供了一个易于维护、可测试且可用于生产环境的代码库。
## **功能特性**
- 解析 **ODL v2** 和 **ODL v3** 日志格式
- 支持所有 OneDrive 日志扩展名：
`.odl`, `.odlgz`, `.odlsent`, `.aodl`
- 自动检测：
- 传统 **ObfuscationStringMap.txt**
- 现代 **general.keystore** (AES‑CBC)
- Gzip 封装的日志
- 清晰的关注点分离：
- **reader** → 文件 I/O + 解压
- **parser** → CDEF block 解析
- **decoder** → 解除混淆 + AES 解密
- **models** → 带类型的不可变记录
- **cli** → 统筹协调 + CSV 和 SQLite 输出
- 完全类型化（兼容 `mypy`）
- 所有组件 100% 的 pytest 覆盖率
- 适用于 DFIR pipeline、自动化以及大规模日志摄取
## **安装**
```
pip install odlparser # not yet published to PyPI
```
或从源码安装：
```
git clone https://github.com//odlparser
cd odlparser
pip install -e .
```
## **命令行使用**
```
odlparse [-o OUTPUT] [-s MAP] [-k] [--sqlite DB]
```
### **参数**
| 选项 | 描述 |
|--------|-------------|
| `folder` | 包含 `.odl`, `.odlgz`, `.odlsent`, `.aodl` 文件的文件夹 |
| `-o, --output` | 输出 CSV 路径（默认：文件夹中的 `ODL_Report.csv`） |
| `-s, --map` | `ObfuscationStringMap.txt` 的路径 |
| `-k, --all-keys` | 包含所有重复的映射值 |
| `--sqlite DB` | 将结果写入 SQLite 数据库（除 CSV 外） |
### **示例**
仅输出 CSV：
```
odlparse ~/OneDriveLogs -o ~/Desktop/odl.csv
```
仅输出 SQLite（默认仍会生成 CSV）：
```
odlparse ~/OneDriveLogs --sqlite ~/Desktop/odl.db
```
CSV + SQLite：
```
odlparse ~/OneDriveLogs -o report.csv --sqlite report.db
```
## **以编程方式使用**
```
from pathlib import Path
from odlparser.reader import load_odl_file
from odlparser.parser import parse_odl
from odlparser.decoder.unobfuscate import OdlDecryptor
odl_file = load_odl_file(Path("SyncEngine-2024-01-01.1234.odlgz"))
decryptor = OdlDecryptor(keystore=None, mapping={})
records = parse_odl(odl_file.version, odl_file.data, filename="log.odl", decryptor=decryptor)
for r in records:
print(r.timestamp, r.code_file, r.function, r.params)
```
## **OneDrive ODL 日志的工作原理**
OneDrive 同步引擎日志以二进制文件形式存储，其扩展名包括：
它们包含一系列 **CDEF block**，每个代表 OneDrive 同步引擎内部的一次函数调用。
### **字符串解码**
存在两种机制：
#### **1. 传统方式（2022 年之前）**
字符串使用存储在以下位置的键/值映射进行混淆：
#### **2. 现代方式（2022 年之后）**
字符串使用存储在以下位置的密钥进行 AES‑CBC 加密：
解析器会自动检测并使用现有的任何机制。
## **项目结构**
```
src/odlparser/
cli.py # CLI entrypoint
reader.py # File I/O + decompression
parser.py # CDEF v2/v3 parsing
models.py # Typed immutable OdlRecord
structures.py # Construct definitions
decoder/
keystore.py
obfuscation_map.py
string_extract.py
unobfuscate.py
tests/
test_*.py # Full pytest suite
```
## **输出格式**
CLI 会生成：
### CSV
- `filename`
- `index`
- `timestamp`
- `code_file`
- `function`
- `params`
### SQLite
一个名为 `records` 的单表，包含以下列：
- `filename`
- `index_num`
- `timestamp`
- `code_file`
- `function`
- `params`
CSV 行示例：
```
SyncEngine-2024-01-01.1234.odlgz,42,2024-01-01T12:34:56,SyncEngine.cpp,UploadItem,"/Documents/report.docx"
```
## **归属说明**
本项目是一个模块化的重写版本，灵感来自以下作者的原始 OneDrive ODL 解析器：
**Yogesh Khatri (@swiftforensics)**
[https://github.com/ydkhatri/OneDrive](https://github.com/ydkhatri/OneDrive)
所有的解码逻辑（CDEF 结构、解除混淆、AES 处理）均基于对原始实现的分析。
标签：AES解密, HTTP工具, Python, SQLite, 子域名变形, 安全规则引擎, 数字取证, 数据分析工具, 无后门, 日志解析, 自动化脚本, 证书伪造, 逆向工具