SCRIBE

通过单一工作流，分析来自单台主机或整个机群的 Windows 取证分流收集数据。

快速开始 · 处理流水线 · 覆盖率 · 功能 · 配置 · 常见问题

## 概述 SCRIBE 用于分析由 KAPE、Velociraptor、CyLR、Aralez 生成的 Windows 取证分流收集数据，或直接取自挂载的镜像。给定一个收集数据（或包含多个收集数据的文件夹），它会： 1. 使用 Eric Zimmerman's tools **解析**标准的 Windows artifacts（MFT、UsnJrnl、Amcache、Prefetch、registry、event logs 等）。 2. 在每个已解析的 artifact 中**扫描** IOC 列表（hash、IP、domain、filename、path fragment）。 3. 通过 Hayabusa 使用 Sigma 规则**检测**活动。 4. 为每台主机**构建时间线**，或为整个批次构建全局时间线。 5. 以 HTML 格式**生成报告**，并根据风险评分对主机进行排名，报告附有具体的计算公式。 每个 artifact 在运行结束时都会处于明确的状态——已解析、收集数据中不存在、缺失工具、解析失败或通过配置跳过。没有任何情况会被静默丢弃。如果无法解析核心 artifact，结果将被报告为 `INCONCLUSIVE`（结论不明），而不是安全无虞。 SCRIBE 在原生的 Windows PowerShell 5.1 上运行。没有安装程序，没有 agent，在分析过程中也没有网络依赖。 ## 范围 **在范围内：**对 Windows 端点取证分流收集数据进行离线分析。 ## 处理流水线 ``` Triage collections (1 … N) IOC list .zip / .7z / .tar.gz / .rar hashes, IPs, domains, or extracted folders filenames, path fragments │ │ └───────────────┬──────────────┘ ▼ ┌───────────────────┐ │ Resolve layout │ KAPE / Velociraptor / CyLR / └─────────┬─────────┘ Aralez / Raw — auto-detected ▼ ┌───────────────────┐ │ Parse artifacts │ MFT · UsnJrnl · Amcache · Prefetch │ (EZ Tools) │ Registry · EventLogs · SRUM · LNK … └─────────┬─────────┘ ▼ ┌───────────────────┐ │ Sigma detection │ Hayabusa + DFIR event timeline └─────────┬─────────┘ ▼ ┌───────────────────┐ │ IOC sweep │ typed matching, confidence-labelled └─────────┬─────────┘ ▼ ┌───────────────────┐ │ Coverage verdict │ CLEAN · IOC MATCH · INCONCLUSIVE └─────────┬─────────┘ ▼ ┌───────────────────┐ │ Timelines │ per-host and global, Timesketch CSV └─────────┬─────────┘ ▼ ┌─────────────────────┴─────────────────────┐ ▼ ▼ ▼ HTML findings Global IOC Run manifest report timeline + (hashes, tool host × IOC matrix versions, params) ``` 单机处理流水线：解析布局 → 解析 artifact → Hayabusa → IOC 扫描 → 覆盖率判定 → 后续步骤（可见性窗口、清单、时间线、报告、过滤副本）。Batch 模式会针对每个收集数据封装该流水线，并增加跨主机的聚合分析。 ## 设计理念 本工具的开发主要为了解决两个问题。 **重复性劳动。** 将收集数据从打包状态处理为可分析的输出结果，需要经过解压、识别收集器布局、定位驱动器根目录，并对每台主机运行五到十个带有特定参数和输出路径的解析器。这些工作是机械性的，并且工作量随端点数量呈线性增长。 **静默失败。** 当解析器执行失败，或者收集数据包含的 artifact 少于预期时，其输出结果（未发现任何可疑项）与真正干净的主机毫无区别。这会导致系统在面对盲区时，依然可能报告“未发现入侵证据”。 SCRIBE 通过一条命令运行整个流水线来解决第一个问题；并通过记录和报告每个 artifact 的最终处理结果来解决第二个问题，从而确保在得出“未发现可疑项”结论的同时，附带一份关于实际已检查内容的说明。 ## 环境要求 - **Windows** 且具备 **PowerShell 5.1+**（预装于 Windows 10/11 和 Server 2016+）。SCRIBE 本身不需要其他 runtime。 - **Eric Zimmerman's tools** —— 即各类解析器。由 `Get-Tools.ps1` 获取。这些工具需要 [.NET Desktop Runtime](https://dotnet.microsoft.com/download)。 - **Hayabusa** —— 可选，用于 Sigma 检测。同样由 `Get-Tools.ps1` 获取。 - **7-Zip** —— 可选，仅在 batch 模式下处理非 `.zip` 格式的压缩包时需要。 本代码库不包含相关的可执行文件。解析器、EvtxECmd 映射和 Sigma 规则更新频繁，应从其官方来源获取。 ## 安装说明 1. 从 [Releases](../../releases) 下载最新版本的压缩包，并根据发布说明中的 SHA-256 值进行校验。 2. 在解压之前先解除锁定——Windows 会标记下载的文件，否则 PowerShell 将拒绝运行它们： Unblock-File -Path .\scribe-*.zip 然后进行解压，保持文件夹结构完整。 3. 允许在当前会话中执行脚本： Set-ExecutionPolicy -Scope Process Bypass 4. 获取外部解析器（只需执行一次；随时可重新运行以进行更新）： .\Get-Tools.ps1 此操作将通过官方更新程序获取 Eric Zimmerman's tools，并将包含 Sigma 规则的最新 Hayabusa 发行版下载到项目的 `tools\` 文件夹中，该文件夹会被自动检测。 无需安装其他任何内容。 对于物理隔离的环境，可以在能联网的机器上运行 `Get-Tools.ps1`，然后将 `tools\` 文件夹复制过去。分析过程不需要联网。 ## 快速开始 **图形化启动器。** 选择路径和选项；UI 会显示即将执行的确切命令，并且设置会在不同会话之间保留。 ``` .\Start-ScribeUI.ps1 ``` **单台主机：** ``` .\Invoke-Triage.ps1 -HostArtifacts D:\case\HOST01 -IocFile .\iocs.txt -Report ``` **Batch —— 包含多个收集数据的文件夹（压缩文件、文件夹或混合形式）：** ``` .\Invoke-Triage.ps1 -BatchFolder D:\evidence -IocFile .\iocs.txt ` -Hayabusa .\tools\hayabusa\hayabusa.exe -OutputPath D:\out -Report ``` `-Layout` 默认为 `Auto`。运行 `.\Invoke-Triage.ps1 -Help` 获取完整的参数列表，或查看 [HELP.md](HELP.md) 获取完整指南。 ## 覆盖率与结论 SCRIBE 已知的每个 artifact 在每次运行结束时都会确切处于以下五种状态之一，这些状态会被记录在 `Artifact_Coverage.csv` 中，显示在控制台中，并包含在 HTML 报告里： | 状态 | 含义 | 说明 | |---|---|---| | `Parsed` | 已分析；其内容已被扫描。 | 实际覆盖范围。 | | `NotInCollection` | 收集器未捕获该项。 | 盲区——需调整收集配置。 | | `ToolMissing` | 未在 `-ToolsPath` 下找到解析器。 | 盲区——请运行 `Get-Tools.ps1`。 | | `ParseFailed` | 解析器已运行但失败。命令行记录在 `_logs\` 中。 | 盲区——可手动复现。 | | `Skipped` | 被 tier 或 scope 配置排除。 | 已知的、计划内的遗漏。 | 运行结论基于上述状态及扫描结果得出： ``` core artifacts parsed? IOC hits? (MFT / Amcache / UsnJrnl / EventLogs) │ │ ┌──────┴──────┐ ┌───────┴───────┐ no yes yes no │ └───────┬──────┘ │ ▼ ▼ ▼ INCONCLUSIVE IOC MATCH(ES) NO HITS, reported (insufficient (review) alongside the coverage to coverage summary conclude) ``` 以下两个相关输出限制了根据单次运行能得出的结论： - **可见性窗口**（`-Visibility`）记录了每个 artifact 所能涵盖的时间范围。由于 USN 日志会发生回卷，且 event logs 会滚动覆盖，因此仅涵盖最近几天的 artifact 无法为早于该时期的事件提供证明。 - **未分析的卷和是否存在 VSS** 会被如实展示出来（而不是默认其不存在），以提示收集数据中包含了未被分析的取证数据。 ## 功能 **分析** - **单命令流水线** —— 一次调用即可完成对单台主机的 artifact 解析、IOC 扫描、Sigma 检测、构建时间线和生成 HTML 报告，并确保所有主机的解析器参数和输出路径保持一致。 - **通过 Eric Zimmerman's tools 解析 artifact** —— 对 MFT、UsnJrnl、Amcache、Prefetch、registry、event logs 等进行统一调用解析，且对每份收集数据处理方式一致。 - **通过 Hayabusa 进行 Sigma 检测** —— 无需手写规则，即可将社区检测规则应用于 event logs，同时附带 Hayabusa 的 DFIR 事件时间线。在案例初期缺乏明确线索时非常有用。 - **精确类型的 IOC 匹配** —— hash、IP 和 domain 会在词边界进行匹配，并标记为*高置信度* (high confidence)；其他字符串则作为子串进行匹配，并标记为*低置信度* (low confidence)。该标签会带入 `IOC_Hits.csv` 和报告中，因此子串的偶然匹配依然能与精确匹配区分开来。 **Batch 处理** - **Batch 模式** —— 可处理包含收集数据的文件夹：支持 `.zip`、`.7z`、`.tar.gz`、`.rar`、解压后的文件夹、受密码保护的压缩包或上述格式的混合。单台主机发生故障会被记录，batch 批处理将继续执行。 - **断点续传与并行处理** —— 中断的运行会从停止处继续。如果同名压缩包被重新收集，将会被重新分析而不是跳过。`-MaxParallelHosts` 支持在相互隔离的 worker 进程中并发处理收集数据。 - **预检容量评估** —— batch 模式会在启动前预估解压峰值和输出大小。 **跨主机关联分析** - **全局 IOC 时间线** —— 汇集所有主机上的每次命中记录，并按时间排序，用于梳理事件顺序和传播范围。 - **主机 × 指标矩阵** —— 展示每台主机/IOC 配对的最早发现时间、最晚发现时间及命中次数。 - **跨批次的主机覆盖率表格** —— 区分出哪些主机确实无发现，哪些主机是由于分析不充分导致无发现。 **可复现性与取证数据处理** - **风险排名** —— 采用机械的 0–100 分制，报告附带计算公式。不使用机器学习，也没有隐藏权重。 - **运行清单**（`-Manifest`）—— 记录输入文件的 hash、IOC 集合的 hash、工具版本及其 hash，以及所有参数，方便直接对比两次运行结果。 - **对证据进行只读处理** —— 输出结果会写入平级的 `_Analysis` 文件夹或指定的 `-OutputPath` 中，绝不会写入收集数据内部。Batch 模式仅会删除其自行解压出来的内容。 - **命令日志记录** —— 每次工具调用都会将其确切命令行记录到 `_logs\.log` 中。 - **全面采用 UTC 时间** —— 解析器以 UTC 模式运行，并且以不区分区域设置 (culture-invariant) 的方式解析时间戳，从而避免本地化设置打乱时间线。 **接口与扩展** - **兼容 Timesketch 的超级时间线** —— 支持单台主机或全局生成，可设定时间窗口边界，并生成按 artifact 过滤的副本。 - **基于同一引擎的 GUI 和 CLI** —— UI 会构建并显示其执行的命令行。 - **基于配置而非代码** —— artifact、解析器、收集数据布局、tier 和检测范围均在可编辑的 JSON 中定义。支持新的 artifact 或收集器只需修改配置文件即可。 ## 支持的 artifact | Tier | Artifact | 解析器 | |---|---|---| | `default` | $MFT, UsnJrnl ($J), Amcache, Prefetch, Registry (system hives, Kroll batch), Scheduled Tasks (raw copy), Event Logs | MFTECmd, AmcacheParser, PECmd, RECmd, EvtxECmd | | `extended` | + Shimcache, SRUM, Shellbags, Recycle Bin | AppCompatCacheParser, SrumECmd, SBECmd, RBCmd | | `full` | + LNK files, Jump Lists, NTUSER.DAT (per user) | LECmd, JLECmd, RECmd | | *可选* | $LogFile, $Secure, $Boot —— 通过 scope 配置显式添加 | MFTECmd / raw copy | 添加一个 artifact 只需在 `config/artifacts.json` 中添加一条 JSON 配置；完全不需要修改代码。 ## 支持的分流收集数据 | 布局 | 收集器 | |---|---| | `Auto` *(默认)* | 尝试所有已知的驱动器根目录模式，并报告其最终解析的路径 | | `KAPE` | Kroll Artifact Parser and Extractor (`--tdest` 输出，包含 `C%3A` 编码的驱动器) | | `Velociraptor` | Velociraptor 离线收集器 (`uploads/...` 结构) | | `CyLR` | CyLR 收集数据 | | `Aralez` | Kaspersky GERT Aralez | | `Raw` | 挂载的镜像、`Windows.old`，或任何自身即为驱动器根目录的文件夹 | 未在此列出的收集器通常只需在 `config/layouts.json` 中添加一段配置即可获得支持。欢迎提交添加新布局的 Pull request。 ## 示例 ``` # Sweep known IOCs across a set of collections and produce per-host and global # reports, bounded to an incident window .\Invoke-Triage.ps1 -BatchFolder D:\evidence -IocFile .\ransom-iocs.txt ` -Hayabusa .\tools\hayabusa\hayabusa.exe -Report -Timeline global ` -TimelineStart 2026-06-01T00:00:00 -TimelineEnd 2026-06-15T00:00:00 # No indicators available: parse everything and rely on Sigma detections .\Invoke-Triage.ps1 -HostArtifacts D:\case\HOST01 ` -Hayabusa .\tools\hayabusa\hayabusa.exe -Report # Mounted image or Windows.old .\Invoke-Triage.ps1 -HostArtifacts E:\mounted\C -Layout Raw -OutputPath D:\out -Report # Password-protected archives, four hosts in parallel, retaining extractions with hits .\Invoke-Triage.ps1 -BatchFolder D:\evidence -ArchivePassword infected ` -MaxParallelHosts 4 -KeepOnHit -IocFile .\iocs.txt -OutputPath D:\out # Reproducibility record and per-artifact time horizons .\Invoke-Triage.ps1 -HostArtifacts D:\case\HOST01 -IocFile .\iocs.txt -Manifest -Visibility ``` 示例 IOC 文件位于 [`examples/sample-iocs.txt`](examples/sample-iocs.txt)。 ## 输出结果 **单台主机：** _BLOCK_6/> **Batch 模式附加输出：** ``` _GLOBAL_IOC_Timeline.csv all hits, all hosts, time-sorted _GLOBAL_IOC_Matrix.csv host × IOC: first seen / last seen / count _GLOBAL_Coverage.csv per-host result and coverage (failed hosts listed here) _GLOBAL_Findings_Report.html risk-ranked batch report (-Report) _BATCH_Summary.txt batch summary ``` **`_Summary.txt` 示例：** ``` HOST : WKS-FINANCE-01 RESULT : 3 IOC MATCH(ES) - review Coverage : 7 parsed / 1 not-collected / 0 tool-missing / 0 parse-failed / 0 skipped (of 8) IOC hits : 3 Note : anything not 'Parsed' is a BLIND SPOT, not a clean result. ``` ## 代码库布局 ``` Invoke-Triage.ps1 entry point (CLI) — dispatch, config, preflight Start-ScribeUI.ps1 graphical launcher — builds and runs the same command Get-Tools.ps1 fetches external parsers from their official sources modules/ Resolve-Layout.ps1 find and validate the drive root for a collection layout Expand-Collection.ps1 archive extraction (native zip / 7-Zip), wrapper unwrapping Invoke-Parsing.ps1 run the configured parsers per artifact; build coverage Invoke-Hayabusa.ps1 Sigma detections and DFIR event timeline Invoke-Detections.ps1 IOC load, typing, and sweep across parsed output Get-Coverage.ps1 coverage report and verdict Get-Visibility.ps1 per-artifact visibility windows Build-Timeline.ps1 Timesketch super-timeline and windowed artifact copies Invoke-Batch.ps1 batch orchestration, parallel workers, resume, aggregation New-Report.ps1 per-host and global HTML findings reports, risk score Write-Manifest.ps1 run-manifest.json (reproducibility record) Test-Capacity.ps1 pre-flight disk-capacity check for batch mode Accelerator.ps1 optional compiled (C#) fast path for the sweep and timeline; falls back to pure PowerShell automatically Common.ps1 shared helpers: logging, timestamps, tool table, telemetry config/ artifacts.json artifact catalog: paths, parser, tier, purpose parsers.json parser command templates (tool flags are changed here) layouts.json collection-format layouts (add your collector here) config.json defaults: tool paths, tier, Sigma settings config-schema.json allowed keys for -ScopeConfig files ``` ## 配置 所有引擎行为均通过 `config/` 目录下的可编辑 JSON 文件定义： | 文件 | 控制内容 | 常见修改场景 | |---|---|---| | `config.json` | 工具路径、默认 tier、Sigma 设置 | 设置 `tools.toolsPath` 以便省略 `-ToolsPath` | | `artifacts.json` | 存在哪些 artifact、其路径、解析器以及所属 tier | 添加新 artifact (复制配置块) | | `parsers.json` | 每个解析器所使用的命令行 | 修改工具的 flag | | `layouts.json` | 收集数据的文件夹结构 | 添加新的收集器布局 | | `config-schema.json` | `-ScopeConfig` 文件允许的键 | 仅供参考 | 单次运行的 scope——如 tier、添加或跳过的 artifact、IOC 文件、聚焦时间等——可捕获在 JSON scope 配置文件中，并通过 `-ScopeConfig` 传入，从而确保相同的排查任务能被一模一样地重复执行。配置优先级为 **CLI 参数 > scope 配置文件 > `config.json`**。 ## 故障排除 | 症状 | 原因与修复 | |---|---| | *"running scripts is disabled on this system"* | 执行策略限制。运行 `Set-ExecutionPolicy -Scope Process Bypass`，并使用 `Unblock-File` 解除对下载文件的锁定 —— 参见 [安装说明](#installation)。 | | *Layout … anchor was not found* | 布局选择错误或结构非常规。错误信息会列出尝试过的所有路径。使用 `-Layout Raw` 并将 `-HostArtifacts` 指向确切的驱动器根目录文件夹，或者扩展 `config/layouts.json`。 | | 某个 artifact 旁显示 `TOOL MISSING` | 未在 `-ToolsPath` 下找到解析器。运行 `.\Get-Tools.ps1`，或在 `config.json` 中设置 `tools.toolsPath`。该 artifact 会被报告为盲区，而不会被静默跳过。 | | 解析器无法启动 | Eric Zimmerman's tools 需要 .NET Desktop Runtime —— https://dotnet.microsoft.com/download。 | | Batch 模式下提示 *7-Zip not found* | 仅在处理非 `.zip` 格式压缩包时需要。从 https://www.7-zip.org/ 安装，或设置 `tools.sevenZipPath`。 | | 结果显示为 `INCONCLUSIVE` | 没有核心 artifact (MFT / Amcache / UsnJrnl / EventLogs) 被成功解析。请检查 `Artifact_Coverage.csv` 和 `_logs\`；可能是收集数据内容太少或工具缺失。这是预期行为——没有有效覆盖率的主机不会被报告为安全状态。 | | Batch 批处理因容量报错停止 | 输出驱动器没有足够空间容纳解压峰值数据和输出结果。请清理可用空间，通过 `-OutputPath` 使用更大的驱动器，或使用 `-Force` 强行覆盖。 | | 时间线文件异常庞大 | 使用 `-TimelineStart` / `-TimelineEnd` 进行限制。包含完整 MFT 的时间线可能会长达数百万行。 | | 某主机因被标记为*"complete from a prior run"*而被跳过 | 断点续传行为所致。使用 `-Rerun` 强制重新分析；如果原地替换了解压文件夹的内容，请务必执行此操作。 | 每次工具调用都会将其确切命令行记录到 `_logs\.log` 中，因此任何故障均可通过手动执行来复现。 ## 常见问题 **SCRIBE 会收集证据吗？** 不会。它只分析由 KAPE、Velociraptor、CyLR、Aralez 生成的收集数据，或取自已挂载的镜像。它需要与现有的收集器配合使用。 **它是 Eric Zimmerman's tools 或 Hayabusa 的替代品吗？** 不是。它是构建在这些工具之上的编排、关联分析、覆盖率追踪和报告生成层。解析与检测的核心引擎依然来自原始工具，且从其官方渠道获取。 **`INCONCLUSIVE` 是什么意思？** 如果没有核心 artifact 被成功解析，那么“未发现可疑项”的结果将被报告为 INCONCLUSIVE（结论不明），因为该次运行尚未检查足够的证据来支撑结论。 **风险评分是如何计算的？** 采用纯机械方式计算，计算公式会直接打印在报告中以供核查。不涉及机器学习，也没有隐藏的权重。 **需要联网吗？** 分析过程完全在离线环境中运行。网络仅被 `Get-Tools.ps1` 用于获取工具。 **它会修改证据吗？** 不会。输出内容会写入同级的 `_Analysis` 文件夹或指定的 `-OutputPath`，绝不会写入收集数据内部。Batch 模式仅会删除其自行解压产生的文件。 **支持 macOS/Linux 端点，或是云端与身份认证相关的入侵分析吗？** 不在范围内。SCRIBE 专门用于分析 Windows 端点 artifact，其输出报告也会明确说明这一点，不会暗示具有更广泛的覆盖能力。 **时间戳使用的是什么时区？** 全面采用 UTC 时间。解析器以 UTC 模式运行，并且时间戳以不区分区域设置 (culture-invariant) 的方式解析。 **为什么限定使用 PowerShell 5.1？** 因为所有受支持的 Windows 系统都默认包含它，包括那些禁止安装软件的受限主机。 **运行一次需要多长时间？** 运行时间主要取决于收集数据的大小以及底层解析器。`-MaxParallelHosts` 和可选的编译加速器会影响大规模批处理的吞吐量。 ## 致谢 SCRIBE 依赖于以下项目： - **[Eric Zimmerman](https://ericzimmerman.github.io/)** —— 各类解析器 (MFTECmd、AmcacheParser、PECmd、EvtxECmd、RECmd 等)。 - **[Yamato Security — Hayabusa](https://github.com/Yamato-Security/hayabusa)** —— Sigma 检测引擎及 DFIR 事件时间线。 - **[SigmaHQ](https://github.com/SigmaHQ/sigma)** —— 提供检测规则。 - **KAPE, Velociraptor, CyLR, 和 Aralez** 的作者们 —— 提供 SCRIBE 所使用的收集工具。 以上项目均未为 SCRIBE 背书。 ## 开源协议 [MIT](LICENSE)。不提供任何担保。详情请参阅协议文件正文。 这是一个利用业余时间维护的社区项目。我们将优先处理带有详细复现步骤和日志的问题反馈。

标签：AI合规, IPv6, Libemu, PowerShell, 库, 应急响应, 网络调试, 自动化