Это указывает плагину **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).

## gdb с интерфейсом отладки Qt Creator

Интерфейс отладки 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. В инструменте CodeBrowser Ghidra: используйте значки панели инструментов или сочетания клавиш для включения (``Alt+s``)/отключения (``Alt+Shift+s``)/перезапуска (``Alt+r``) синхронизации.

Окно состояния также доступно через ``Windows`` -> ``RetSyncPlugin``. Обычно его стоит разместить сбоку, чтобы интегрировать с окнами среды Ghidra.


## Binary Ninja extension

Поддержка Binary Ninja является экспериментальной, обязательно создавайте резервные копии ваших баз данных анализа.

### Binary Ninja prerequisites

**ret-sync** требует Binary Ninja версии не ниже 2.2, а также Python 3 (Python 2 не поддерживается).


### Install the Binary Ninja extension

**ret-sync** пока не распространяется через менеджер плагинов Binary Ninja; требуется ручная установка. Просто скопируйте содержимое папки `ext_bn` в папку плагинов Binary Ninja, например:

`%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 требуется префикс `!` (например: `sync` в GDB, `!sync` в WinDbg).

| Команда отладчика           | Описание                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
| `synchelp`                   | Отобразить список доступных команд с кратким пояснением                             |
| `sync`                       | Запустить синхронизацию                                                                     |
| `syncoff`                    | Остановить синхронизацию                                                                      |
| `cmt [-a address] <string>`  | Добавить комментарий по текущему ip в дизассемблере                                               |
| `rcmt [-a address]`          | Сбросить комментарий по текущему ip в дизассемблере                                               |
| `fcmt [-a address] <string>` | Добавить комментарий к функции, в которой находится текущий ip                        |
| `raddr <expression>`         | Добавить комментарий с пересчитанным адресом, вычисленным из выражения                              |
| `rln <expression>`           | Получить символ из дизассемблера для заданного адреса                                    |
| `lbl [-a address] <string>`  | Добавить имя метки по текущему ip в дизассемблере                                            |
| `cmd <string>`               | Выполнить команду в отладчике и добавить её вывод в качестве комментария по текущему ip в дизассемблере |
| `bc <\|\|on\|off\|set 0xBBGGRR>` | Включить/выключить цветовую маршрутизацию в дизассемблере                                              |
| `idblist`                    | Получить список всех клиентов IDB, подключенных к диспетчеру                                   |
| `syncmodauto <on\|off>`       | Включить/выключить автоматическое переключение дизассемблера на основе имени модуля                              |
| `idbn <n>`                   | Установить активный IDB как n-й клиент                                                          |
| `jmpto <expression>`         |                                                                                           |
| `jmpraw <expression>` | Если IDB включен, представление дизассемблера синхронизируется с результирующим адресом.    |
| `translate <base> <addr> <mod>` | пересчитать адрес относительно имени его модуля и смещения   |


Специфичные команды WinDbg:

| Команда отладчика           | Описание                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
| `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` | Расширенный вывод команды **kv** на языке разметки отладчика (DML)   |


Специфичные команды GDB:

| Команда отладчика           | Описание                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
|`bbt` |  Красивый обратный трейс. Аналогичен **bt** в GDB, но запрашивает символы у дизассемблера  |
| `patch`  | Пропатчить байты в дизассемблере на основе живого контекста   |
| `bx` | Аналогично GDB **x**, но с использованием символа. Символ будет разрешен дизассемблером   |
| `cc` | Продолжить до курсора в дизассемблере  |


## Использование в IDA

### Графический интерфейс плагина IDA

Поле ввода ``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

После открытия 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 (за исключением команды "Go").

* ``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>**: Добавить комментарий по текущему ip в 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) usage

Синхронизация с хостом:```
    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 usage

1. Используйте меню плагинов или сочетания клавиш для включения (``Alt+s``)/отключения (``Alt+u``) синхронизации.

## OllyDbg2 usage

1. Используйте меню плагинов или сочетания клавиш для включения (``Ctrl+s``)/отключения (``Ctrl+u``) синхронизации.

Из-за бета-статуса API OllyDbg2 реализованы только следующие функции:

- Синхронизация графа [используйте ``F7``; ``F8`` для пошагового выполнения]
- Комментарий [используйте ``CTRL+;``]
- Метка [используйте ``CTRL+:``]

## x64dbg usage

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.

# Extend

Хотя изначально проект был сосредоточен на динамическом анализе (отладчиках), конечно же, можно расширить набор плагинов и интегрироваться с другими инструментами.

- Интеграция с платформой **REVEN** Timeless Analysis and Debugging от компании [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

Другие ресурсы:

- "*Combining static and dynamic binary analysis - ret-sync*" от Jean-Christophe Delaunay
  - https://www.synacktiv.com/ressources/bieresecu1_ret-sync_en.pdf


# TODO

- Конечно.

# Известные ошибки/ограничения

- Протестировано с 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.

Конфликты:

- Известно, что программное обеспечение Logitech Updater использует тот же порт по умолчанию (9100). Решение — использовать глобальный конфигурационный файл `.sync` для указания другого порта.```
[INTERFACE]
host=127.0.0.1
port=9234