Amtonsi/nodetrace-ir

# NodeTrace IR [](LICENSE)   **作者及版权所有者：** Абдрахманов Амаль Даулетович

_{Цепочка расследования: источник попадания → подозрительный файл → затронутые процессы, файлы, реестр и сеть.}

NodeTrace IR 0.3.0 是一款用于在 Windows 节点上进行初步事件调查的本地防御性工具。其主要分发形式是**真正可启动的 x86 WinPE ISO，并附带 AVZ**。启动 WinPE 后，它会自动找到已脱机的 Windows 安装和用于存放证据的独立可写介质，创建案例并启动调查。无需手动点击“启动”、“收集”或“分析”按钮。 不会执行可疑文件，也不会将其作为库加载。NodeTrace IR 和 AVZ 仅在分析配置文件中读取可用的痕迹；针对受调查系统的修复、删除、隔离和纠正功能均被禁用。 **英文摘要。** NodeTrace IR 0.3.0 是一款本地优先的 Windows 事件响应工具。其主要分发形式是一个可启动的 x86 WinPE 镜像，它会自动调查已挂载的脱机 Windows 安装，将证据存储在单独的可写卷上，使用 AVZ 作为分析检测器，并导出详细的 HTML 报告以及可缩放的 SVG 图表。调查结果保持在证据边界内：缺失的遥测数据会被报告为空白，而不是用猜测代替。 ## 调查界面

_{Связи снабжаются уровнем уверенности; отсутствие прямого артефакта не подменяется догадкой.}

内部管道按 **DETECT → PRESERVE → INVESTIGATE → IMPACT** 顺序执行，结果显示为因果链： ``` источник попадания → файл → воздействие URL / USB / другое хэши процессы, файлы, реестр, закрепление, сеть ``` 1. **DETECT（检测）。** 在 x86 WinPE 中，AVZ 首先扫描已挂载的脱机 Windows 目录树。WinPE 的进程、内核和网络实时检查已被禁用：因为它们反映的是启动环境，而不是受调查的操作系统。 2. **PRESERVE（保留）。** 可用的原始材料、AVZ 报告和哈希值被固定存放在单独介质上的案例目录中。 3. **INVESTIGATE（调查）。** 脱机收集器读取可用的 EVTX、Prefetch、文件元数据、浏览器永久记录以及 USB 设备安装历史。 4. **IMPACT（影响）。** 关联被分为观察结果、相关性和假设。未经证实的联系不会被提升为事实。 AVZ 是第三方检测器，而不是最终结论的来源。没有触发告警、AVZ 成功返回退出代码或 `CheckFile=0` 并不能证明没有遭到入侵。 ## 自动启动模式

_{Реальный smoke-тест VirtualBox: WinPE загрузился, нашёл offline Windows и создал SQLite-кейс на отдельном evidence-томе.}

ISO 启动后，会执行 `wpeinit` 和 `winpe\launch_nodetrace.cmd`。启动器会执行以下操作： - 根据 `Windows\System32\Config\SYSTEM` 和 `SOFTWARE` 定位首个 Windows 安装； - 不使用 `X:` 盘和受调查的卷来存储结果； - 优先选择根目录下带有 `NODETRACE_EVIDENCE_VOLUME` 标记的外部卷； - 否则，选择第一个不含其他 Windows 安装的独立可写卷； - 创建 `NodeTraceIR-Evidence\session-*` 目录并启动： ``` NodeTraceIR.exe --winpe --offline-root --data-dir ``` 如果 BitLocker 卷已锁定，请先使用 WinPE 的标准工具将其解锁，然后重新运行 `launch_nodetrace.cmd`。如果不存在独立的可写卷，调查将不会开始：这是为了防止将结果故意写入受调查的磁盘，或仅仅写入临时的 `X:` 盘中。 完成后，WinPE 模式会自动创建一个可验证的 ZIP 文件，并在旁边放置方便查阅的 `report.html`、`graph.svg`、`impact.json` 和 `SHA256SUMS.txt` 副本。HTML 中嵌入了相同的图表；独立的 `graph.svg` 带有 `viewBox`，并且在不损失质量的情况下进行缩放。 ## 精确的 URL 和 USB 标识符 NodeTrace IR 仅在保存的痕迹中存在精确值时才将其显示出来： - 来自 `Zone.Identifier` 的 `HostUrl` 和 `ReferrerUrl`； - 来自 Chromium 浏览器（Edge/Chrome）脱机 `History` 数据库的下载 URL 链； - 来自脱机日志 `Windows\INF\setupapi.dev.log` 的 USB instance ID、VID/PID、型号以及可提取的序列号； - 当确实正在调查该可移动卷上的文件时，显示当前可移动卷的标识符。 名称或时间的匹配并不能证明特定的字节来自找到的 URL。关于 USB 设备的历史记录本身也不能证明从该设备复制了文件。如果没有直接联系，报告会将来源显示为未知，并列出覆盖盲区，而不是选择最相似的 URL 或 USB。 ## 离线状态下的可用与不可用功能 启动模式能更好地与潜在受感染的操作系统隔离，但无法恢复磁盘上不存在的数据。 如果痕迹被保留，则可以使用： - 通过原生只读解析器获取的 EVTX，在出错时有明确的 fallback/gap 机制； - Windows Prefetch 和文件时间上下文； - Edge/Chrome 下载历史记录，包括保存的 URL； - SetupAPI USB 设备安装历史； - 可用文件的哈希值和元数据； - AVZ 针对已挂载 Windows 目录树的报告。 不可用或受到根本性限制： - 受感染 Windows 的当前活动进程、内存、TCP 连接和 DNS 缓存； - 已删除或覆盖的日志； - 对 MFT/USN 的全面调查以及 memory forensics； - 在没有直接遥测数据的情况下的确切因果关系； - 在解锁前加密卷的内容。 因此，NodeTrace IR 不能替代 forensic imaging、EDR/SIEM、网络传感器、沙箱以及分析师的劳动。 ## 构建 bootable ISO 的要求 AVZ 作为 x86 PE 提供。amd64 WinPE 中没有 WOW64，因此 AVZ 无法在其中运行。主要的 AVZ 镜像基于 **Windows 10 ADK/WinPE add-on 2004 中的 x86 WinPE** 以及 32 位 CPython/PyInstaller 构建。较新的 Windows 11 ADK 不包含 x86 WinPE；请与 [Microsoft ADK 官方表格](https://learn.microsoft.com/windows-hardware/get-started/adk-install) 核对。 需要： - Windows 和 PowerShell；仅在可选的 DISM/ADK 路径下需要管理员权限； - 接受 Microsoft 许可协议后获取的官方 x86 Windows 10 ADK/WinPE add-on 2004 payload； - 用于在不挂载和不提权的情况下进行便携式 WIM 维护的 `wimlib-imagex`； - CPython 3.11+ x86、PyInstaller 和 pytest； - 已根据固定的 `tools/avz-manifest.json` 验证过的官方 AVZ 存档； - AVZ 版权所有者对预期使用场景的许可。 首先安装构建依赖项，并务必使用 32 位 Python 构建 x86 EXE。标准脚本会自动运行测试，检查解释器的位数，并将结果放入 `dist\winpe-x86\NodeTraceIR.exe`： ``` & C:\Python311-x86\python.exe -m pip install pytest pyinstaller powershell -NoProfile -ExecutionPolicy Bypass ` -File .\scripts\build_release.ps1 ` -Python C:\Python311-x86\python.exe ` -Architecture x86 ``` 在阅读[第三方软件条款](iso/THIRD_PARTY_AVZ_NOTICE.txt)后，仅获取固定的 AVZ 输入文件： ``` powershell -NoProfile -File .\tools\fetch_avz.ps1 ` -AcceptNonCommercialLicense ` -Destination .\tools\cache ` -ManifestPath .\tools\avz-manifest.json ``` 从 Windows 10 ADK/WinPE add-on 2004 准备官方 WinPE 输入的缓存。 `prepare_winpe_2004_x86_portable.ps1` **不执行网络下载**：它采用 fail-closed 机制，在 `CacheDir` 下查找已获取的官方 bootstrap/MSI/CAB 文件，验证它们固定的大小、SHA-256/SHA-1 和 Microsoft 签名，仅提取所需的成员，并创建来源 manifest。 预期的文件名和哈希值完整列表直接写在脚本中。 请使用官方的 Microsoft layout-installer 或您所在组织批准的 下载器获取这些文件；不要随意重命名文件以匹配预期的 名称。 在 `CacheDir`、`CacheDir\Installers` 或 `CacheDir\winpe-layout\Installers` 中必须包含： - `adksetup.exe` 和 `adkwinpesetup.exe`； - `Windows PE x86 x64-x86_en-us.msi`； - `Windows PE x86 x64 wims-x86_en-us.msi`； - `Windows Deployment Tools-x86_en-us.msi`； - `690b8ac88bc08254d351654d56805aea.cab`； - `aa25d18a5fcce134b0b89fb003ec99ff.cab`； - `5d984200acbde182fd99cbfbe9bad133.cab`。 ``` powershell -NoProfile -ExecutionPolicy Bypass ` -File .\scripts\prepare_winpe_2004_x86_portable.ps1 ` -CacheDir ..\downloads\adk2004 ` -OutputDir .\build\winpe-input ` -AcceptMicrosoftLicense ``` `OutputDir` 必须是新的或为空的。主要的发布路径是 无需安装 ADK 且无需提权的便携构建： ``` powershell -NoProfile -ExecutionPolicy Bypass ` -File .\scripts\build_winpe_iso_portable.ps1 ` -WinPEMediaRoot .\build\winpe-input\Media ` -WinPEExtractionManifest .\build\winpe-input\extraction-manifest.json ` -EfiBootImage .\build\winpe-input\Media\fwfiles\efisys.bin ` -WimlibImagex ..\tools\wimlib-1.14.5\wimlib-imagex.exe ` -NodeTraceExecutable .\dist\winpe-x86\NodeTraceIR.exe ` -AvzDirectory .\tools\cache ` -OutputPath .\dist\NodeTraceIR-AVZ-0.3.0-Bootable-x86.iso ` -AcceptNonCommercialLicense ``` 该脚本检查 NodeTrace IR 和 AVZ 的 PE 架构、官方 WinPE manifest、存档哈希值以及每个提取的元素，将 payload 和自动启动功能嵌入到 `boot.wim` 中，创建 BIOS/IA32-UEFI El Torito ISO，并写入 `.iso.sha256`、`.verification.json` 和 `.build.json`。 ## 发布前验证 ISO 静态检查启动目录和强制性的 WIM： ``` python .\scripts\verify_bootable_iso.py ` .\dist\NodeTraceIR-AVZ-0.3.0-Bootable-x86.iso ` --expect-path SOURCES/BOOT.WIM Get-FileHash ` .\dist\NodeTraceIR-AVZ-0.3.0-Bootable-x86.iso ` -Algorithm SHA256 ``` 成功的静态检查可证明 El Torito 结构的完整性，但不能保证与每种固件都兼容。在发布之前，请在独立的 BIOS/IA32-UEFI 虚拟机中执行冒烟测试启动，并配备测试用的脱机 Windows 卷和单独的 evidence 磁盘；确保应用程序自动启动并生成 HTML/ZIP，且不写入受调查的卷。 要在 VirtualBox 中进行隔离的 BIOS 冒烟测试（网络、USB、剪贴板和拖放功能会被脚本禁用）： ``` .\scripts\smoke_test_winpe_vm.ps1 ` -IsoPath .\dist\NodeTraceIR-AVZ-0.3.0-Bootable-x86.iso ` -BuildRoot .\build\vm-smoke ` -BootTimeoutSeconds 90 ``` 默认情况下，这不仅仅是启动检查。脚本会在本地 创建两个一次性 MBR/FAT16 镜像：一个是包含 `Windows/System32/Config/SYSTEM` 和 `SOFTWARE` 路径的合成目标卷，另一个是带有 `NODETRACE_EVIDENCE_VOLUME` 标记的独立可写卷。镜像在 严格限制的会话目录内被转换为两个 VDI，并 连接到不同的 SATA 端口；网络、 USB、剪贴板和共享文件夹保持禁用。截图后，evidence-VDI 被导出回 RAW，并且 `build_fat16_disk.py` 确认生成了 `NodeTraceIR-Evidence/session-*/nodetrace_ir.sqlite3`。因此，成功的结果 证明了应用程序自动启动，而不仅仅是 WinPE 的启动。宿主机上 没有格式化任何物理磁盘，并且 WinPE 内部没有执行 `diskpart`/`format`。如果仅为了进行纯粹的启动检查，请指定 `-DisableFunctionalProbe`。 便携式脚本使用 `build_iso.py` 和 `build_fat12_efi.py` 进行确定性的底层构建，并验证混合目录。保留 `build_winpe_iso.ps1` 作为安装了 ADK 并具有管理员权限的 PowerShell 的机器的可选路径，但它不是默认的发布方式。 底层脚本 `fetch_winpe_2004_x86.ps1`、 `fetch_winpe_2004_x86_selective.ps1`、`resume_http_ranges.py`、 `resume_range_parts.ps1`、`extract_mszip_ranges.py` 和 `inspect_cab.py` 旨在用于在网络不稳定的情况下进行可验证的获取或恢复单个 官方 payload。它们不能取代由 `prepare_winpe_2004_x86_portable.ps1` 验证的完整缓存。 ## 更新 AVZ 数据库 详细的逐步操作规程，包括检查 candidate、回滚和重建 ISO：[docs/AVZ_DATABASE_UPDATES_RU.md](docs/AVZ_DATABASE_UPDATES_RU.md)。 **可启动 ISO 绝不会在调查期间通过网络更新 AVZ。** 这将破坏介质的可重现性，增加网络活动，并将固定输入替换为可变文件。 更新仅在受信任的构建机器上执行。`update_avz_base.py` 更新完整的 `avzbase.zip` 数据库；运行时存档 `avz4.zip` 仍然是独立的固定输入，并通过 `fetch_avz.ps1` 进行检查。官方页面：[AVZ 下载](https://z-oleg.com/secur/avz/download.php) 和 [数据库更新说明](https://z-oleg.com/secur/avz_doc/avz_avupdate.htm)。 ``` # 下载并验证 candidate；当前的 pin 保持不变。 python .\tools\update_avz_base.py ` --accept-noncommercial-license # 在验证 candidate ZIP 和 diff manifest 之后，记录已查看的 hash。 $baseSha = (Get-FileHash .\tools\cache\avzbase.candidate.zip -Algorithm SHA256).Hash $manifestSha = (Get-FileHash .\tools\avz-manifest.candidate.json -Algorithm SHA256).Hash # 接受确切已查看的 pair。不执行重新下载。 python .\tools\update_avz_base.py ` --accept-noncommercial-license ` --approve-repin ` --expected-base-sha256 $baseSha ` --expected-manifest-sha256 $manifestSha ``` 如果企业 trust store 阻止了 Python 的 HTTPS 请求，请使用允许的下载器手动下载 `https://z-oleg.com/secur/avz_up/avzbase.zip`，并将其作为 未受信任的本地 candidate 传入：`--source-archive .\avzbase.zip`。 结构限制和所有哈希检查同样适用；在执行 `--approve-repin` 之前，操作员必须单独验证本地文件的来源。 Updater 仅允许官方的 HTTPS 主机，限制下载和解压的大小，禁止目录遍历、加密和意外的 ZIP 条目，计算存档的 SHA-256/MD5 以及每个 `.avz` 的 SHA-256/CRC-32。完整数据库通过可变 URL 发布没有强有力的 publisher 签名，因此新的 SHA-256 是本地的 provenance pin，并不能证明内容的作者身份。 执行 repin 后，务必： 1. 审查 `tools/avz-manifest.json` 的 diff 以及存档的元数据； 2. 重新执行 `fetch_avz.ps1 -VerifyOnly`； 3. 重建 ISO； 4. 重复进行静态检查、虚拟机冒烟测试并发布新的 SHA-256。 旧数据库仍保留在已发布的只读 ISO 内；它不会被追溯更改。 ## 源码和发布打包 适配 GitHub 的 0.3.0 版本源码 ZIP 包： ``` .\scripts\package_release.ps1 -Version 0.3.0 -SourceOnly ``` 构建 x86 EXE 和 ISO 后，可以生成完整的套件： ``` .\scripts\package_release.ps1 ` -Version 0.3.0 ` -NodeTraceExecutable .\dist\winpe-x86\NodeTraceIR.exe ` -BootableIso .\dist\NodeTraceIR-AVZ-0.3.0-Bootable-x86.iso ``` 源码 ZIP 根据精确的名称允许列表构建。包含源代码、 合成测试 fixtures、WinPE 启动器、构建器、验证器和 AVZ 更新程序；不包含桌面截图、案例、SQLite、日志、缓存、 AVZ 数据库/二进制文件、WIM、ISO 以及构建目录。打包程序还会额外 拒绝 credential 文件以及几种极有可能包含敏感信息的格式。 在公开上传之前，仍请检查 ZIP 的内容列表，并排除真实的 证据、恶意样本和敏感信息。 ## 从源码运行 用于开发和独立的实时响应模式： ``` python .\run_nodetrace_ir.py python .\run_nodetrace_ir.py --data-dir E:\NodeTraceIR-Cases ``` 手动脱机运行需要明确指定目标根目录和独立的可写目录： ``` python .\run_nodetrace_ir.py ` --winpe ` --offline-root D:\ ` --data-dir E:\NodeTraceIR-Evidence ``` 程序拒绝将 `--data-dir` 设置在 `--offline-root` 内部。在 live 模式下，进程在受调查的操作系统中运行，因此不具备脱机启动的可信属性。 ## 报告与证据验证 案例导出包含： - `report.html` — 独立的详细报告； - `graph.svg` 和 `graph.json` — 可缩放且机器可读的关系图； - `impact.json` — source → file → impact 评估； - `evidence.csv` 和 `timeline.csv`； - 原始保存的 AVZ 报告； - `manifest.json` 和 `SHA256SUMS.txt`。 Manifest 证明了文件在导出后的不变性，但不能证明受调查系统输出内容的真实性。案例的 ZIP 文件不是磁盘或内存的完整镜像。 ## 安全与许可 - NodeTrace IR 不会修复受调查的系统，也不会执行可疑文件。 - AVZ、其可执行文件和数据库不包含在 MIT 源码分发中，并受版权所有者的单独条款约束。 - `-AcceptNonCommercialLicense` 仅记录操作员的确认，并不授予额外的权利。如需商业/企业分发，请获得必要的许可。 - ISO 和报告可能包含敏感路径、用户名、URL、设备标识符和事件日志；请像保护调查材料一样保护它们。 - 漏洞报告政策：[SECURITY.md](SECURITY.md)。

标签：AI合规, Python, WinPE, 库, 应急响应, 数字取证, 无后门, 漏洞挖掘, 离线取证, 自动化脚本, 逆向工具