これは **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プラグインのトラブルシューティング

To troubleshoot issues with the IDA extension two options are available in the
file `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 のプラグインフォルダにコピーしてください。例:

`%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`）。

| デバッガーコマンド           | 説明                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
| `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 <モジュール名>`  |  指定されたモジュールをアクティブな IDB に設定します (`modlist` の強化版 `lm` を参照) |
| `modmap <base> <size> <name>` |  合成（「偽の」）モジュール（ベースアドレスとサイズで定義）をデバッガーの内部リストに追加します  |
| `modunmap <base>` |  指定したベースアドレスの合成モジュールマッピングを削除します  |
| `modcheck <\|\|md5>`  |  現在のモジュールが本当に IDB のファイルと一致しているか確認するために使用します（例：モジュールが更新された場合）  |
| `bpcmds <\|\|save\|load\|>` | **bpcmds** ラッパー。**.bpcmds**（ブレークポイントコマンドリスト）出力を現在の IDB に保存/再読み込みします  |
| `ks` | デバッガーマークアップ言語 (DML) 強化版 **kv** コマンドの出力   |


GDB 固有のコマンド:

| デバッガーコマンド           | 説明                                                                               |
|----------------------------|-------------------------------------------------------------------------------------------|
|`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 同期を切り替えるための 2 つのボタンがあります。

### IDA のデバッガーコマンドへのバインド

``Syncplugin.py`` は、デバッガーコマンドラッパーのホットキーも登録します。

* ``F2`` - カーソルアドレスにブレークポイントを設定
* ``F3`` - カーソルアドレスにワンショットブレークポイントを設定
* ``Ctrl-F2`` - カーソルアドレスにハードウェアブレークポイントを設定
* ``Ctrl-F3`` - カーソルアドレスにワンショットハードウェアブレークポイントを設定
* ``Alt-F2`` - 現在のカーソルアドレスを変換（デバッガーで再ベース）
* ``Alt-F5`` - Go
* ``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 拡張のものと似ています（"Go" コマンドを除く）。

* ``F2``  - カーソルアドレスにブレークポイントを設定
* ``Ctrl-F2`` - カーソルアドレスにハードウェアブレークポイントを設定
* ``Alt-F3`` - カーソルアドレスにワンショットブレークポイントを設定
* ``Ctrl-F3`` - カーソルアドレスにワンショットハードウェアブレークポイントを設定
* ``Alt-F2`` - 現在のカーソルアドレスを変換（デバッガーで再ベース）
* ``F5`` - Go
* ``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`` - Go
* ``F10`` - シングルステップ
* ``F11`` - シングルトレース


## WinDbg の使用法

### WinDbg プラグインコマンド

* **!sync**: 同期を開始
* **!syncoff**: 同期を停止
* **!synchelp**: 利用可能なコマンドのリストを簡単な説明付きで表示
* **!cmt [-a address] <string>**: IDA 内の現在の 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

    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.

# 拡張

当初は動的解析（デバッガ）に焦点を当てていましたが、もちろんプラグインセットを拡張して他のツールと統合することも可能です。

- [Tetrane](https://www.tetrane.com/) による **REVEN** Timeless Analysis and Debugging Platform との統合:
  - http://blog.tetrane.com/2015/02/reven-in-your-toolkit.html
  - https://twitter.com/tetrane/status/1374768014193799175
- Assaf Carlsbad（[@assaf_carlsbad](https://twitter.com/assaf_carlsbad)）による **EFI DXE Emulator** との統合:
  - https://twitter.com/assaf_carlsbad/status/1242114356881641474
  - https://github.com/assafcarlsbad/efi_dxe_emulator

その他のリソース:

- Jean-Christophe Delaunay による「*Combining static and dynamic binary analysis - ret-sync*」
  - 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' コマンドを使用した場合、stop イベントが呼び出されないようです。
- マルチスレッドデバッグではシグナルに問題があります。

WinDbg の場合:

- IDA のクライアントプラグインは、遭遇したブレークポイントが継続させるコマンド文字列（`g`）を使用している場合でも通知を受け取ります。これらのイベントが多すぎると、大幅な速度低下を引き起こす可能性があります。限定的な修正が実装されていますが、最善の解決策は一時的に同期をオフにすることです。
- レースコンディションの可能性

Ghidra の場合:

- 逆コンパイラウィジェットでショートカットが期待通りに動作しません。

IDA の場合:

- 大きなグラフの場合、グラフウィンドウの再描画が非常に遅いです。
- **ret-sync** のショートカットが Linux 環境で競合します。

競合:

- Logitech Updater ソフトウェアが同じデフォルトポート (9100) を使用することが知られています。解決策は、グローバルな `.sync` 設定ファイルを使用して別のポートを定義することです。```
[INTERFACE]
host=127.0.0.1
port=9234