kiwids0220/TTDObjectsPy

# TTDObjectsPy MCP Server 用于 **Microsoft Time Travel Debugging (TTD)** 的 Model Context Protocol (MCP) 服务器。赋予 Codex 直接访问 TTD trace 记录的权限，以进行逆向工程、恶意软件分析、漏洞研究和调试。 TTDObjectsPy 通过 ctypes 直接与 `TTDReplay.dll` 通信 — 无需 WinDbg 或调试器引擎。 ## 功能 - **完整的 trace 导航** — 向前/向后单步执行，设置位置，重放至 watchpoint - **内存与寄存器检查** — 读取任意时间点的内存、寄存器和堆栈 - **函数调用追踪** — 查询针对某个函数地址的所有调用及其参数和返回值 - **数据流/污点分析** — 向后追踪值至其源头，提供完整的污点传播 - **内存 watchpoint** — 监视地址范围上的读取、写入或执行操作 - **事件查询** — 异常、线程事件、模块加载/卸载 - **无需 WinDbg 依赖** — 通过 ctypes vtable 绑定直接使用 TTDReplay.dll 原生 API ## 环境要求 - **Windows 10/11** (x64) - **Codex** 具备本地插件支持 - 使用 WinDbg、TTD.exe 或 tttracer 录制的 TTD trace 文件（`.run` + `.out`） ## 安装 ### 全新 Windows 安装 从解压的发布版本或仓库检出中： ``` Set-ExecutionPolicy -Scope Process Bypass .\installer\installer.ps1 ``` 安装程序会下载 TTD 运行时，并在需要时通过 `winget` 安装 Python， 创建项目 venv，安装依赖项，注册 Codex marketplace 和 MCP 服务器，并导出内置的 skill。安装完成后重启 Codex，然后调用 `$ttd-analysis`。 内置的 `ttd-installer.exe` 意味着在常规安装路径下， 无需 Git、Visual Studio、CMake 或预安装的 Python。 旧版辅助工具仍然可用，并会委托给完整的安装程序执行： ``` .\scripts\install_codex_plugin.ps1 ``` ### Python 环境（可选） ``` pip install -e . # 用于 data-flow tracing 的 Capstone disassembler pip install -e ".[dataflow]" # 开发工具 (pytest, black, ruff, mypy) pip install -e ".[dev]" ``` 如果您计划重新构建内置安装程序，请安装 Visual Studio 2022 Build Tools（包含 MSVC 工具链）、CMake 支持以及最新版本的 Windows SDK。 ## 快速入门 在 Codex 中安装完成后，打开一个对话并开始处理 TTD trace： ``` Open the trace at C:\traces\malware.run and show me what happened ``` Codex 会自动调用 MCP 工具。以下是典型会话的示例： ### 1. 打开 trace ``` # Codex 调用: ttd_unified_open("C:/traces/malware.run") # 返回: first_position, last_position, thread count ``` ### 2. 探索事件 ``` # ttd_unified_get_event_summary() # 返回计数: 3 exceptions, 12 thread events, 45 module loads # ttd_unified_get_module_events() # 显示每个加载的 DLL 及其 base address 和大小 # ttd_unified_get_exception_events() # 显示 crash location, exception code, faulting address ``` ### 3. 导航与检查 ``` # ttd_unified_set_position("1a3:5f") # 跳转到 trace 中的特定点 # ttd_unified_get_registers() # 读取该位置处的所有 CPU registers # ttd_unified_read_memory("0x7ff612340000", 256) # 读取此时此刻的 256 bytes 内存 # ttd_unified_step_forward(10) # 向前步进 10 instructions ``` ### 4. 追踪函数调用 ``` # ttd_unified_query_calls_by_address( # entry_address="0x7ffa6e520010", # WS2_32!send # exits=[{"address": "0x7ffa6e520080", "type": "ret"}], # max_calls=50 # ) # 返回每次对 send() 的调用及其 RCX/RDX/R8/R9 参数和 RAX 返回值 ``` ### 5. 数据流分析 ``` # ttd_trace_register_origin("rcx") # 向后追踪以查找 RCX 在何处获取了其当前值 # ttd_trace_register_taint("rax") # 完整 taint analysis: 汇集到 RAX 的每一个数据源 # ttd_unified_find_memory_write("0x00007ff612345678", 8) # 查找最后一次写入该 address 的 instruction ``` ### 6. 基于 watchpoint 的分析 ``` # ttd_unified_add_memory_watchpoint("0x7ff612340000", 4096, "write") # 监视对此 memory page 的任何写入操作 # ttd_unified_replay_forward() # 重放直到 watchpoint 触发 # ttd_unified_clear_watchpoints() ``` ## 示例：崩溃根因分析 ``` User: "Open crash.run and find the root cause of the access violation" Codex will: 1. Open the trace and find exception events 2. Navigate to the crash position 3. Read registers to see the faulting instruction 4. Trace the bad pointer backward using ttd_trace_register_origin 5. Follow the data flow to identify where the corruption originated 6. Report the root cause with exact positions and instruction context ``` ## 示例：恶意软件 C2 协议分析 ``` User: "Analyze the network communication in malware.run" Codex will: 1. Find WS2_32.dll's base address from module events 2. Query all calls to connect(), send(), recv() by address 3. Read the buffer contents at each send/recv call 4. Reconstruct the network protocol from the captured data 5. Identify encryption keys, C2 commands, and exfiltrated data ``` ## 工具参考 | 类别 | 工具 | |----------|-------| | **Trace 管理** | `ttd_unified_open`, `ttd_unified_close`, `ttd_unified_status` | | **导航** | `ttd_unified_set_position`, `ttd_unified_step_forward/backward`, `ttd_unified_replay_forward/backward`, `ttd_unified_run_to_address`, `ttd_unified_goto_start/end` | | **检查** | `ttd_unified_get_registers`, `ttd_unified_get_register`, `ttd_unified_read_memory`, `ttd_unified_read_string`, `ttd_unified_get_stack`, `ttd_unified_get_position` | | **调用追踪** | `ttd_unified_query_calls_by_address` | | **数据流** | `ttd_trace_register_origin`, `ttd_trace_memory_origin`, `ttd_trace_register_taint`, `ttd_find_data_source`, `ttd_unified_find_memory_write` | | **内存分析** | `ttd_collect_memory_accesses_detailed`, `ttd_trace_value_changes_detailed`, `ttd_analyze_memory_access_pattern` | | **事件** | `ttd_unified_get_event_summary`, `ttd_unified_get_exception_events`, `ttd_unified_get_module_events`, `ttd_unified_get_thread_events` | | **Watchpoint** | `ttd_unified_add_memory_watchpoint`, `ttd_unified_remove_memory_watchpoint`, `ttd_unified_clear_watchpoints` | ## 录制 TTD trace 推荐使用本仓库内置的录制器： - **内置 TTD.exe** — `C:\Tools\TTDObjectsPy\asset\amd64\ttd\TTD.exe -out C:\traces -launch myapp.exe` - **WinDbg** — `File > Start debugging > Launch executable (advanced)` 并勾选“Record with Time Travel Debugging” - **其他安装的 TTD.exe** — `TTD.exe -out C:\traces -launch myapp.exe` 如果您需要确切的捕获语法，请在不带参数的情况下运行内置录制器以显示其帮助菜单： ``` C:\Tools\TTDObjectsPy\asset\amd64\ttd\TTD.exe ``` 每次录制都会生成一个 `.run` 文件（trace 数据）和 `.out` 文件（索引）。两者都是必需的。 ## 架构 ``` Codex | | MCP (stdio) v TTDObjectsPy MCP Server (src/ttdobjectspy/server.py) | | Python ctypes v TTDReplay.dll (asset/amd64/ttd/TTDReplay.dll) | | Native API v .run trace file ``` 内置的加载器会优先使用位于 `asset/amd64/ttd` 下由安装程序管理的目录结构，如果旧版的扁平化 `asset/` 目录结构仍然存在，则会回退到该结构。 ## 许可证 MIT

标签：AI合规, DAST, MCP, Windows, 云资产清单, 恶意软件分析, 情报收集, 漏洞研究, 逆向工具, 逆向工程