kev365/ual-timeliner

# ual-timeliner **ual-timeliner** (User Access Logging Timeliner) 是一个用于解析 Windows User Access Logging (UAL) 数据库的取证工具。它从 Windows Server 2012+ 服务器中提取历史访问数据，以便从离线检查收集和取证镜像中重建用户和主机活动时间线。 最初衍生自 BriMor Labs 的 [KStrike](https://github.com/brimorlabs/KStrike)。 ## 功能 - **多表提取**: 从 UAL ESE 数据库中解析 `CLIENTS`、`DNS` 和 `ROLE_ACCESS` 表。 - **脏数据库恢复**: 自动修补处于 Dirty Shutdown 状态的 ESE 数据库以进行离线解析。 - **时间戳关联**: 将 `InsertDate`、`LastAccess`、`FirstSeen`、`LastSeen` 和历史 `Day###` 列合并为统一的按时间顺序排列的视图。 - **高性能**: 基于 [Polars](https://pola.rs/) 构建，用于快速处理大型 UAL 数据集。 - **标准化输出**: 导出到 CSV、Excel (XLSX)、SQLite、Parquet 或 K2T (Timesketch JSONL)。 - **去重**: 智能处理 `Current.mdb` 和历史 GUID 数据库之间的重叠数据。 - **角色 GUID 解析**: 将已知的 Windows Server 角色 GUID 映射为人类可读的名称。 ## 安装 需要 Python 3.9 或更高版本。 ``` # 克隆仓库并安装 pip install -e . # 'ual-timeliner' 命令现已可用 ual-timeliner --help ``` ### 依赖项 - `polars` — 高性能 DataFrame 库 - `libesedb-python` — 用于读取 ESE (.mdb) 数据库 - `openpyxl` — 用于 Excel 输出 ## 用法 ``` # 基本用法 — 将 CSV 输出到 stdout ual-timeliner path/to/UAL_data/ # 导出到 Excel ual-timeliner path/to/UAL_data/ -f xlsx -o timeline.xlsx # 递归搜索并输出完整取证数据（所有列 + Day### 条目） ual-timeliner path/to/UAL_data/ -r --full-output -f parquet -o timeline.parquet # 将大输出拆分为多个文件（仅限 CSV 和 K2T） ual-timeliner path/to/UAL_data/ -f csv -o timeline.csv --split-rows 100000 # 单文件输入 ual-timeliner path/to/Current.mdb -o timeline.csv ``` ### 示例输出 (默认) ``` timestamp (UTC) | timestamp_desc | source_table | authenticated_user | ip_address | host_name | user | total_accesses | role_name | source_file 2021-06-05T18:47:19.633980 | FirstSeen | ROLE_ACCESS | | | | | | Print and Document Services | Current.mdb 2021-06-12T23:47:14.167754 | FirstSeen | ROLE_ACCESS | | | | | | Active Directory Domain Services | Current.mdb 2021-06-12T23:47:21.232323 | InsertDate | CLIENTS | lab\dc-1$ | ::1 | dc-1 | | 310 | Active Directory Domain Services | Current.mdb 2021-06-12T23:48:45.468902 | InsertDate | CLIENTS | lab\dc-1$ | fe80::e15c:... | dc-1 | | 101 | Active Directory Domain Services | Current.mdb 2021-06-12T23:49:44.255548 | InsertDate | CLIENTS | lab\dc-1$ | 10.0.0.10 | dc-1 | | 1 | File Server | Current.mdb 2021-06-13T14:26:58.359685 | InsertDate | CLIENTS | lab\administrator | 10.0.0.10 | | administrator | 1 | File Server | Current.mdb 2021-06-23T11:47:37.042000 | LastSeen | DNS | | 10.0.0.123 | Laptop-Bob| | | | Current.mdb ``` ### 示例输出 (`--full-output`) 完整输出增加了 `access_count`、`role_guid`、`tenant_id` 和 `client_name` 列，并包含 Day### 历史访问事件： ``` timestamp (UTC) | timestamp_desc | source_table | authenticated_user | ip_address | host_name | user | access_count | role_name | role_guid | tenant_id 2021-06-12T00:00:00.000000 | Day163 | CLIENTS | lab\administrator | fe80::... | | administrator | 1 | File Server | {10A9226F-50EE-49D8-A393-9A501D47CE04} | {00000000-...} 2021-06-12T00:00:00.000000 | Day163 | CLIENTS | lab\dc-2$ | 10.0.0.20 | dc-2 | | 4 | File Server | {10A9226F-50EE-49D8-A393-9A501D47CE04} | {00000000-...} ``` ### 输出格式 | 格式 | 标志 | 描述 | | :--- | :--- | :--- | | CSV | `-f csv` | 逗号分隔值 (默认)。如果未指定 `-o`，则打印到 stdout。 | | Excel | `-f xlsx` | 带自动筛选和 900K 行工作表拆分的流式 XLSX。 | | SQLite | `-f sqlite` | 包含 `timeline` 表的 SQLite 数据库。 | | Parquet | `-f parquet` | 用于大规模分析的压缩列式存储。 | | K2T | `-f k2t` | 与 Timesketch 兼容的 JSONL，包含 `message`、`datetime` 和 `timestamp_desc` 字段。 | ### Timesketch 集成 当使用 `-f k2t` 时，提供专用的 OpenSearch 映射文件，位置为： `resources/ual-timeliner-opensearch-mapping.json` 这确保了像 `ip_address` (类型: `ip`) 和 `datetime` (类型: `date`) 这样的字段在 OpenSearch 中正确输入类型，以便 Timesketch 摄取。 ## UAL 背景 User Access Logging (UAL) 是 Windows Server 内置功能，用于记录客户端对服务器角色的访问。UAL 数据库作为 ESE (Extensible Storage Engine) 文件存储在 `%SystemRoot%\System32\LogFiles\SUM\`： | 文件 | 用途 | | :--- | :--- | | `Current.mdb` | 当前正在写入的活动数据库 | | `{GUID}.mdb` | 每日 (每 24 小时) 轮换的年度快照 | | `SystemIdentity.mdb` | 服务器身份信息 (本工具跳过) | 数据保留期最长可达 3 年，涵盖的角色包括文件服务器、AD DS、DHCP、DNS、IIS、RDS、WSUS 等。第三方软件也可以注册到 UAL。 欲了解更多信息： - [KStrike 关于 UAL 取证的文章](https://dfir-kev.medium.com/kstrike-2aff53eaecce) - [Microsoft: User Access Logging 入门](https://learn.microsoft.com/windows-server/administration/user-access-logging/get-started-with-user-access-logging) ### 示例数据 [原始 KStrike 示例 UAL 数据库](https://github.com/brimorlabs/KStrike/tree/master/Sample_UAL) ## 许可证 MIT 许可证。请参阅 [LICENSE](LICENSE)。 本项目衍生自 Brian Moran (BriMor Labs) 的 [KStrike](https://github.com/brimorlabs/KStrike)。原始 KStrike 许可证保留在 [LICENSE-KSTRIKE](LICENSE-KSTRIKE) 中。

标签：Dirty Shutdown, ESE数据库, HTTPS请求, LibESEDB, Polars, UAL, User Access Logging, Windows Server, Windows取证, 主机取证, 开源安全工具, 数字取证, 数据库解析, 数据恢复, 活动重构, 用户活动审计, 电子取证, 离线取证, 自动化脚本, 逆向工具, 逆向工程平台