它告诉 **ret-sync** ``IDA`` 插件在接口 ``192.168.128.1`` 上监听，端口为 ``9234``。显而易见，此接口必须能够从远程主机或虚拟机访问。

* 在调试器执行所在的机器上，位于用户主目录中：```
[INTERFACE]
host=192.168.128.1
port=9234

``[ALIASES]`` 部分用于自定义反汇编器（IDA/Ghidra）用于向调度器/程序管理器注册模块的名称。

默认情况下，反汇编器插件使用输入文件的名称。但用户可能事先重命名了文件，导致其不再匹配调试器所见的实际进程或加载模块的名称。

这里我们简单地告诉调度器匹配名称 `ntkrnlmp.exe`（真实名称）而不是 `ntoskrnl_vuln.exe`（IDB 名称）。

## 使用 Qt Creator 调试前端的 gdb

Qt Creator 调试前端改变了 gdb 命令输出的记录方式。由于这会干扰同步，提供了一个选项，可以使用原始 gdb 输出进行同步，而不是临时文件。在 .sync 配置文件中使用```
[GENERAL]
use_tmp_logging_file=false

映射中的每个条目是：``mem_base``, ``mem_end``, ``mem_size``, ``mem_name``。


## 绕过自动地址重定位

在某些场景中，例如调试嵌入式设备或连接到极简调试接口时，绕过反汇编器插件中实现的自动地址重定位功能可能更为方便。

`use_raw_addr` 选项目前仅支持 Ghidra。在 .sync 配置文件中使用：```
[GENERAL]
use_raw_addr=true

### IDA 插件故障排除

要排查 IDA 扩展的问题，文件 `retsync/rsconfig.py` 中提供了两个选项：```
LOG_LEVEL = logging.INFO
LOG_TO_FILE_ENABLE = False

3. 为你的 Ghidra 安装构建扩展（将 `$GHIDRA_DIR` 替换为你的安装目录）```bash
cd ext_ghidra
gradle -PGHIDRA_INSTALL_DIR=$GHIDRA_DIR

4. 通过 Ghidra CodeBrowser 工具：使用工具栏图标或快捷键启用（``Alt+s``）/禁用（``Alt+Shift+s``）/重启（``Alt+r``）同步。

状态窗口也可从 ``Windows`` -> ``RetSyncPlugin`` 获取。通常建议将其拖放到侧边，以便与 Ghidra 环境窗口集成。


## Binary Ninja 扩展

Binary Ninja 支持为实验性功能，请确保备份您的分析数据库。

### Binary Ninja 前提条件

**ret-sync** 最低需要 Binary Ninja 2.2 版本以及 Python 3（不支持 Python 2）。


### 安装 Binary Ninja 扩展

**ret-sync** 尚未通过 Binary Ninja 的插件管理器分发；需要手动安装。只需将 `ext_bn` 文件夹的内容复制到 Binary Ninja 的 plugins 文件夹，例如：

`%APPDATA%\Binary Ninja\plugins`

重新启动 Binary Ninja 后，控制台窗口应显示以下输出：```
[sync] commands added
Loaded python3 plugin 'retsync'

3. 同步 WinDbg```
      0:000> !sync
      [sync] No argument found, using default host (127.0.0.1:9100)
      [sync] sync success, sock 0x5a8
      [sync] probing sync
      [sync] sync is now enabled with host 127.0.0.1

如果 Windbg 的当前模块匹配 IDA 文件名```
      [sync] idb is enabled with the idb client matching the module name.

下面的错误通常意味着 Windbg 尝试加载了不正确的扩展版本，例如：用 ``x64`` 代替了 ``x86`` 的 `sync.dll`。```
0:000> .load sync
The call to LoadLibrary(sync) failed, Win32 error 0n193
    "%1 is not a valid Win32 application."
Please check your debugger configuration and/or network access.

## GNU gdb (GDB) 安装

1. 将 `ext_gdb/sync.py` 复制到你选择的目录
2. 加载扩展（参见 auto-load-scripts）```
    gdb> source sync.py
    [sync] configuration file loaded 192.168.52.1:9100
    [sync] commands added

## OllyDbg 1.10 安装

OllyDbg 1.10 支持是实验性的，但：

1. 使用VS解决方案构建插件（可选，见预编译二进制文件）
2. 将dll复制到OllyDbg的插件目录中

## OllyDbg2 安装

OllyDbg2 支持是实验性的，但：

1. 使用VS解决方案构建插件（可选，见预编译二进制文件）
2. 将dll复制到OllyDbg2的插件目录中

## x64dbg 安装

基于 testplugin，https://github.com/x64dbg/testplugin。x64dbg 支持是实验性的，但：

1. 使用VS解决方案构建插件（可选，见预编译二进制文件）。
   可能需要不同版本的插件 sdk，
   可在 x64dbg 的每个发行版中找到。
   将 "``pluginsdk``" 目录粘贴到 "``ext_x64dbg\x64dbg_sync``" 中
2. 将 dll（扩展名为 ``.d32`` 或 ``.dp64``）复制到 x64dbg 的插件目录中。

# 用法

## **ret-sync** 调试器命令

对于面向命令行的调试器（主要是 Windbg 和 GDB），**ret-sync** 提供了一组命令
来辅助逆向工程任务。

以下命令是通用的（Windbg 和 GDB），请注意在 WinDbg 上需要加 `!` 前缀（例如：GDB 中为 `sync`，WinDbg 中为 `!sync`）。

| Debugger command           | Description                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
| `synchelp`                   | 显示可用命令列表及简短说明                                                             |
| `sync`                       | 开始同步                                                                                 |
| `syncoff`                    | 停止同步                                                                                 |
| `cmt [-a address] <string>`  | 在反汇编器中当前指令指针位置添加注释                                                     |
| `rcmt [-a address]`          | 重置反汇编器中当前指令指针位置的注释                                                     |
| `fcmt [-a address] <string>` | 在当前指令指针所在函数中添加函数注释                                                     |
| `raddr <expression>`         | 根据表达式计算重基地址并添加注释                                                         |
| `rln <expression>`           | 从反汇编器获取给定地址的符号                                                             |
| `lbl [-a address] <string>`  | 在反汇编器中当前指令指针位置添加标签名                                                   |
| `cmd <string>`               | 在调试器中执行命令，并将其输出作为注释添加到反汇编器中当前指令指针位置                   |
| `bc <\|\|on\|off\|set 0xBBGGRR>` | 启用/禁用反汇编器中的路径着色                                                           |
| `idblist`                    | 获取所有连接到调度器的 IDB 客户端列表                                                   |
| `syncmodauto <on\|off>`       | 启用/禁用基于模块名称的反汇编器自动切换                                                  |
| `idbn <n>`                   | 将第 n 个客户端设置为活动的 IDB                                                          |
| `jmpto <expression>`         |                                                                                           |
| `jmpraw <expression>` | 如果启用了某个 IDB，则将反汇编器的视图同步到结果地址。                                   |
| `translate <base> <addr> <mod>` | 根据模块名称和偏移量重新计算地址                                                   |

WinDbg 特定命令：

| Debugger command           | Description                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
| `curmod`  |  显示当前指令偏移的模块信息（用于故障排除）                                                 |
| `modlist`  |  调试器标记语言（DML）增强的模块列表，便于更流畅地切换活动 idb                              |
| `idb <module name>`  |  将给定模块设置为活动的 idb（参见 `modlist` 增强版 `lm`）                                    |
| `modmap <base> <size> <name>` |  将一个合成（“伪造”）模块（通过基址和大小定义）添加到调试器内部列表                        |
| `modunmap <base>` |  移除之前映射在基址处的合成模块                                                             |
| `modcheck <\|\|md5>`  |  用于检查当前模块是否与 IDB 的文件匹配（例如：模块已更新）                                 |
| `bpcmds <\|\|save\|load\|>` |  **bpcmds** 包装器，保存并重新加载 **.bpcmds**（断点命令列表）输出到当前 IDB             |
| `ks` | 调试器标记语言（DML）增强的 **kv** 命令输出                                                |

GDB 特定命令：

| Debugger command           | Description                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
|`bbt` |  美化回溯。类似于 GDB 中的 **bt**，但从反汇编器请求符号                                   |
| `patch`  |  基于实时上下文在反汇编器中打补丁字节                                                       |
| `bx` |  类似于 GDB 的 **x**，但使用符号。符号将由反汇编器解析                                      |
| `cc` |  在反汇编器中继续到光标处                                                                 |

## IDA 用法

### IDA 插件的 GUI

“``Overwrite idb name``”输入字段用于更改默认的 IDB 名称。
这是插件用于向调度器注册的名称。IDB 自动切换基于模块名称匹配。如果出现
名称冲突（如 ``foo.exe`` 和 ``foo.dll``），可用此字段简化匹配。请注意，如果在同步处于活动状态时修改输入字段，则必须重新向调度器注册；可以通过使用“``Restart``”按钮完成此操作。

提醒一下，可以使用 ``.sync`` 配置文件默认设置别名。

### IDA 全局快捷键

**ret-sync** 在 IDA 中定义了以下全局快捷键：

* ``Alt-Shift-S``  - 运行 **ret-sync** 插件
* ``Ctrl-Shift-S``  - 切换全局同步
* ``Ctrl-H``  - 切换 Hex-Rays 同步

在调试工具栏中还有两个按钮用于切换全局和 Hex-Rays 同步。

### IDA 调试器命令绑定

``Syncplugin.py`` 还注册了调试器命令包装器热键。

* ``F2`` - 在光标地址处设置断点
* ``F3`` - 在光标地址处设置一次性断点
* ``Ctrl-F2`` - 在光标地址处设置硬件断点
* ``Ctrl-F3`` - 在光标地址处设置一次性硬件断点
* ``Alt-F2`` - 转换（在调试器中重新基址）当前光标地址
* ``Alt-F5`` - 运行
* ``Ctrl-Alt-F5`` - 运行（仅 GDB）
* ``F10`` - 单步执行
* ``F11`` - 单步跟踪

这些命令仅在当前 IDB 处于活动状态时可用。在可能的情况下，它们也已在其他调试器中实现。

## Ghidra 用法

### Ghidra 插件的 GUI

打开 RetSyncPlugin 后，您可以通过简单的拖拽将其添加到 CodeBrowser 窗口中：

![](https://assets.kitploit.com/production/public/readmes/3693/c6d122e27a256e4f99d0f760d2d6febb89648881dbdee9d6ffd84092bb0d9931.png)

如果您想要查看多个模块，需要在同一个 CodeBrowser 查看器中打开文件，只需将其他模块拖拽到 CodeBrowser 窗口中即可得到上述结果。

### Ghidra 全局快捷键

**ret-sync** 在 Ghidra 中定义了以下全局快捷键：

* ``Alt-S``  - 启用同步
* ``Alt-Shift-S``  - 禁用同步
* ``Alt-R``  - 重新启动同步
* ``Alt-Shift-R``  - 重新加载配置

### Ghidra 调试器命令绑定

还实现了对调试器命令的绑定。它们与 IDA 扩展的绑定类似（除了“运行”命令）。

* ``F2``  - 在光标地址处设置断点
* ``Ctrl-F2`` - 在光标地址处设置硬件断点
* ``Alt-F3`` - 在光标地址处设置一次性断点
* ``Ctrl-F3`` - 在光标地址处设置一次性硬件断点
* ``Alt-F2`` - 转换（在调试器中重新基址）当前光标地址
* ``F5`` - 运行
* ``Alt-F5`` - 运行（仅 GDB）
* ``F10`` - 单步执行
* ``F11`` - 单步跟踪

## Binary Ninja 用法

### Binary Ninja 全局快捷键

**ret-sync** 在 Binary Ninja 中定义了以下全局快捷键：

* ``Alt-S``  - 启用同步
* ``Alt-Shift-S``  - 禁用同步

### Binary Ninja 快捷键

还实现了对调试器命令的绑定。它们与 IDA 扩展的绑定类似。

* ``F2``  - 在光标地址处设置断点
* ``Ctrl-F2`` - 在光标地址处设置硬件断点
* ``Alt-F3`` - 在光标地址处设置一次性断点
* ``Ctrl-F3`` - 在光标地址处设置一次性硬件断点
* ``Alt-F2`` - 转换（在调试器中重新基址）当前光标地址
* ``Alt-F5`` - 运行
* ``F10`` - 单步执行
* ``F11`` - 单步跟踪

## WinDbg 用法

### WinDbg 插件命令

* **!sync**: 开始同步
* **!syncoff**: 停止同步
* **!synchelp**: 显示可用命令列表及简短说明。
* **!cmt [-a address] <string>**: 在 IDA 中当前指令指针位置添加注释```
    [WinDbg]
    0:000:x86> pr
    eax=00000032 ebx=00000032 ecx=00000032 edx=0028eebc esi=00000032 edi=00000064
    eip=00430db1 esp=0028ed94 ebp=00000000 iopl=0         nv up ei pl nz na po nc
    cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202
    image00000000_00400000+0x30db1:
    00430db1 57    push    edi

    0:000:x86> dd esp 8
    0028ed94  00000000 00433845 0028eebc 00000032
    0028eda4  0028f88c 00000064 002b049e 00000110

    0:000:x86> !cmt 0028ed94  00000000 00433845 0028eebc 00000032
    [sync.dll]  !cmt called

    [IDA]
    .text:00430DB1    push    edi             ; 0028ed94  00000000 00433845 0028eebc 00000032

* **!fcmt [-a address] <string>**: 为当前IP所在的函数添加函数注释```
    [WinDbg]
    0:000:x86> !fcmt decodes buffer with key
    [sync] !fcmt called

    [IDA]
    .text:004012E0 ; decodes buffer with key
    .text:004012E0                 public decrypt_func
    .text:004012E0 decrypt_func    proc near
    .text:004012E0                 push    ebp

* **!cmd <string>**: 在 WinDbg 中执行一个命令，并将其输出作为注释添加到反汇编器中当前 ip 处```
    [WinDbg]
    0:000:x86> pr
    eax=00000032 ebx=00000032 ecx=00000032 edx=0028eebc esi=00000032 edi=00000064
    eip=00430db1 esp=0028ed94 ebp=00000000 iopl=0         nv up ei pl nz na po nc
    cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202
    image00000000_00400000+0x30db1:
    00430db1 57     push    edi
    [sync.dll]  !cmd r edi

    [IDA]
    .text:00430DB1    push    edi             ; edi=00000064

* **!syncmodauto <on|off>**：启用/禁用基于模块名称的反汇编器自动切换：```
    [WinDbg]
    0:000> !syncmodauto off

    [IDA]
    [*] << broker << dispatcher msg: sync mode auto set to off

在此示例中，当前活动的IDB客户端将被设置为：```
	[0] target.exe.

地址必须是有效的指令地址。

## GNU gdb (GDB) 用法

与主机同步：```
    gdb> sync
    [sync] sync is now enabled with host 192.168.52.1
    <not running>

    gdb> r
    Starting program: /bin/ls
    [Thread debugging using libthread_db enabled]
    Using host libthread_db library "/lib/libthread_db.so.1".

(gdb) synchelp
[sync] extension commands help:
 > sync <host>
 > syncoff
 > cmt [-a address] <string>
 > rcmt [-a address] <string>
 > fcmt [-a address] <string>
 > cmd <string>
 > bc <on|off|>
 > rln <address>
 > bbt <symbol>
 > patch <addr> <count> <size>
 > bx /i <symbol>
 > cc
 > translate <base> <addr> <mod>

* **rln**: 从IDB获取给定地址的符号
* **bbt**: 漂亮回溯。与**bt**类似，但从反汇编器请求符号```
    (gdb) bt
    #0  0x0000000000a91a73 in ?? ()
    #1  0x0000000000a6d994 in ?? ()
    #2  0x0000000000a89125 in ?? ()
    #3  0x0000000000a8a574 in ?? ()
    #4  0x000000000044f83b in ?? ()
    #5  0x0000000000000000 in ?? ()
    (gdb) bbt
    #0 0x0000000000a91a73 in IKE_GetAssembledPkt ()
    #1 0x0000000000a6d994 in catcher ()
    #2 0x0000000000a89125 in IKEProcessMsg ()
    #3 0x0000000000a8a574 in IkeDaemon ()
    #4 0x000000000044f83b in sub_44F7D0 ()
    #5 0x0000000000000000 in  ()

## LLDB 用法

1. 与宿主机同步```
    lldb> process launch -s
    lldb> sync
    [sync] connecting to localhost
    [sync] sync is now enabled with host localhost
    [sync] event handler started

## OllyDbg 1.10 使用

1. 使用插件菜单或快捷键启用（``Alt+s``）/禁用（``Alt+u``）同步。

## OllyDbg2 使用

1. 使用插件菜单或快捷键启用（``Ctrl+s``）/禁用（``Ctrl+u``）同步。

由于 OllyDbg2 API 仍处于测试阶段，仅实现了以下功能：

- 图形同步 [使用 ``F7``；``F8`` 进行单步调试]
- 注释   [使用 ``CTRL+;``]
- 标签   [使用 ``CTRL+:``]

## x64dbg 使用

1. 使用插件菜单或命令启用（"``!sync"``）或禁用（"``!syncoff``”）同步。

2. 使用命令```
[sync] synchelp command!
[sync] extension commands help:
 > !sync                          = synchronize with <host from conf> or the default value
 > !syncoff                       = stop synchronization
 > !syncmodauto <on | off>        = enable / disable idb auto switch based on module name
 > !synchelp                      = display this help
 > !cmt <string>                  = add comment at current eip in IDA
 > !rcmt <string>                 = reset comments at current eip in IDA
 > !idblist                       = display list of all IDB clients connected to the dispatcher
 > !idb <module name>             = set given module as the active idb (see !idblist)
 > !idbn <n>                      = set active idb to the n_th client. n should be a valid decimal value
 > !translate <base> <addr> <mod> = rebase an address with respect to local module's base
 > !insync                        = synchronize the selected instruction block in the disassembly window.

# 扩展

虽然最初专注于动态分析（调试器），但自然也可以扩展插件集并与其他工具集成。

- 与 **REVEN** 时间无关分析与调试平台（由 [Tetrane](https://www.tetrane.com/) 提供）集成：
  - http://blog.tetrane.com/2015/02/reven-in-your-toolkit.html
  - https://twitter.com/tetrane/status/1374768014193799175
- 与 **EFI DXE Emulator**（由 Assaf Carlsbad [@assaf_carlsbad](https://twitter.com/assaf_carlsbad) 开发）集成：
  - https://twitter.com/assaf_carlsbad/status/1242114356881641474
  - https://github.com/assafcarlsbad/efi_dxe_emulator

其他资源：

- "*结合静态与动态二进制分析 - ret-sync*"，作者 Jean-Christophe Delaunay
  - https://www.synacktiv.com/ressources/bieresecu1_ret-sync_en.pdf


# 待办事项

- 确实如此。

# 已知缺陷/限制

- 已在 Python 2.7/3.7、IDA 7.7（Windows、Linux 和 Mac OS X）、Ghidra 10.1.1、Binary Ninja 3.0.3225-dev、GNU gdb (GDB) 8.1.0 (Debian)、lldb 310.2.37 上测试。
- **双方之间没有任何身份验证/加密**；后果自负。
- 自修改代码不在支持范围内。

在 GDB 下：

- 使用 'return' 命令时似乎不会触发停止事件。
- 多线程调试存在信号相关的问题。

在 WinDbg 下：

- IDA 客户端插件即使遇到的断点使用了使其继续执行的命令字符串（``g``），仍然会收到通知。如果此类事件过多，可能会导致严重减速。已实现一个有限的修复，最佳方案仍然是临时关闭同步。
- 可能存在竞态条件。

在 Ghidra 下：

- 快捷键在反编译器窗口中无法正常工作。

在 IDA 下：

- 图形窗口对于大型图表的重绘速度相当慢。
- **ret-sync** 的快捷键在 Linux 环境中存在冲突。

冲突：

- 罗技更新软件已知使用相同的默认端口（9100）。一种解决方案是使用全局 `.sync` 配置文件来定义不同的端口。```
[INTERFACE]
host=127.0.0.1
port=9234