{"id":13746378,"url":"https://github.com/bootleg/ret-sync","last_synced_at":"2025-05-15T08:07:34.440Z","repository":{"id":37431104,"uuid":"49377590","full_name":"bootleg/ret-sync","owner":"bootleg","description":"ret-sync is a set of plugins that helps to synchronize a debugging session (WinDbg/GDB/LLDB/OllyDbg2/x64dbg) with IDA/Ghidra/Binary Ninja disassemblers.","archived":false,"fork":false,"pushed_at":"2024-02-29T07:08:34.000Z","size":2792,"stargazers_count":2125,"open_issues_count":35,"forks_count":272,"subscribers_count":54,"default_branch":"master","last_synced_at":"2025-04-07T03:11:58.622Z","etag":null,"topics":["binaryninja","debugger","disassembler","ghidra","ida-plugin","ida-pro","reverse-engineering","software-analysis"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bootleg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-10T17:36:12.000Z","updated_at":"2025-04-07T00:43:49.000Z","dependencies_parsed_at":"2024-09-25T00:28:06.084Z","dependency_job_id":"a6791c8d-f826-4e3b-ad53-f20918bf2a4c","html_url":"https://github.com/bootleg/ret-sync","commit_stats":{"total_commits":151,"total_committers":15,"mean_commits":"10.066666666666666","dds":"0.26490066225165565","last_synced_commit":"a6d0b53826d0dc5a075229ce5efe9004f834339e"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootleg%2Fret-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootleg%2Fret-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootleg%2Fret-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bootleg%2Fret-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bootleg","download_url":"https://codeload.github.com/bootleg/ret-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248871071,"owners_count":21175147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binaryninja","debugger","disassembler","ghidra","ida-plugin","ida-pro","reverse-engineering","software-analysis"],"created_at":"2024-08-03T06:00:52.698Z","updated_at":"2025-04-14T11:28:00.946Z","avatar_url":"https://github.com/bootleg.png","language":"C","readme":"# ret-sync\n\n**ret-sync** stands for Reverse-Engineering Tools SYNChronization. It is a set\nof plugins that help to synchronize a debugging session\n(WinDbg/GDB/LLDB/OllyDbg/OllyDbg2/x64dbg) with a disassembler (IDA/Ghidra/Binary Ninja).\nThe underlying idea is simple: take the best from both worlds (static and\ndynamic analysis).\n\nDebuggers and dynamic analysis provide us with:\n\n* local view, with live dynamic context (registers, memory, *etc.*)\n* built-in specialized features/API (ex: WinDbg's ``!peb``, ``!drvobj``,\n``!address``, *etc.*)\n\nDisassemblers and static analysis provide us with:\n\n* macro view over modules\n* code analysis, signatures, types, *etc.*\n* fancy graph view\n* decompilation\n* persistent storage of knowledge within IDBs/GPRs\n\nKey features:\n\n* synchronize graph and decompilation views with debugger's state\n* no need to deal with ASLR, addresses are rebased on-the-fly\n* pass data (comment, command output) from debugger to disassembler\n* multiple IDBs/GPRs can be synced at the same time allowing to easily trace\n  through multiple modules\n* disassembler and debugger can be on different hosts / VMs\n\n**ret-sync** is a fork of [qb-sync](https://github.com/quarkslab/qb-sync)\nthat I developed and maintained during my stay at\n[Quarkslab](http://www.quarkslab.com).\n\n\n-------------------------------------------------------------------------------\n# Table of contents\n\n- [Repository content](#repository-content)\n- [General prerequisites](#general-prerequisites)\n- [Binary release](#binary-release)\n- [**ret-sync** configuration](#ret-sync-configuration)\n- [Installation](#installation)\n  - [IDA extension](#ida-extension)\n  - [Ghidra extension](#ghidra-extension)\n  - [Binary Ninja extension](#binary-ninja-extension)\n  - [WinDbg extension](#windbg-extension)\n  - [GNU gdb (GDB) installation](#gnu-gdb-gdb-installation)\n  - [LLDB installation](#lldb-installation)\n  - [OllyDbg 1.10 installation](#ollydbg-110-installation)\n  - [OllyDbg2 installation](#ollydbg2-installation)\n  - [x64dbg installation](#x64dbg-installation)\n- [Usage](#usage)\n  - [**ret-sync** debugger commands](#ret-sync-debugger-commands)\n  - [IDA usage](#ida-usage)\n  - [Ghidra usage](#ghidra-usage)\n  - [Binary Ninja usage](#binary-ninja-usage)\n  - [WinDbg usage](#windbg-usage)\n  - [GNU gdb (GDB) usage](#gnu-gdb-gdb-usage)\n  - [LLDB usage](#lldb-usage)\n  - [OllyDbg 1.10 usage](#ollydbg-110-usage)\n  - [OllyDbg2 usage](#ollydbg2-usage)\n  - [x64dbg usage](#x64dbg-usage)\n  - [Python library usage](#python-library-usage)\n- [Extend](#extend)\n- [TODO](#todo)\n- [Known Bugs/Limitations](#known-bugslimitations)\n- [License](#license)\n- [Greetz](#greetz)\n-------------------------------------------------------------------------------\n\n# Repository content\n\nThe debugger plugins:\n\n* `ext_windbg/sync`: WinDbg extension source files, once built: `sync.dll`\n* `ext_gdb/sync.py`: GDB plugin\n* `ext_lldb/sync.py`: LLDB plugin\n* `ext_olly1`: OllyDbg 1.10 plugin\n* `ext_olly2`: OllyDbg v2 plugin\n* `ext_x64dbg`: x64dbg plugin\n\nThe disassembler plugins:\n\n* `ext_ida/SyncPlugin.py`\n* `ext_ghidra/dist/ghidra_*_retsync.zip`: Ghidra plugin\n* `ext_bn/retsync`: Binary Ninja plugin\n\n\nAnd the library plugin:\n\n* `ext_lib/sync.py`: standalone Python library\n\n\n# General prerequisites\n\nIDA and GDB plugins require a valid Python setup. Python 2 (\u003e=2.7) and Python\n3 are supported.\n\n\n# Binary release\n\nPre-built binaries for WinDbg/OllyDbg/OllyDbg2/x64dbg debuggers are proposed\nthrough an ``Azure DevOps`` pipeline: [![Build Status](https://dev.azure.com/bootlegdev/ret-sync-release/_apis/build/status/ret-sync-release-CI?branchName=master)](https://dev.azure.com/bootlegdev/ret-sync-release/_build/latest/ret-sync-release-CI?definitionId=8?branchName=master)\n\nSelect the last build and check the artifacts under the ``Related`` section: ``6 published``.\n\n![](img/pipeline.png)\n\n\nA pre-built plugin archive of the Ghidra plugin is provided in `ext_ghidra/dist`.\n\n\n# **ret-sync** configuration\n\n**ret-sync** should work out of the box for most users with a typical setup:\ndebugger and disassembler(s) on the same host, module names matching.\n\nStill, in some scenarios a specific configuration may be used. For that,\nextensions and plugins check for an optional global configuration file named\n`.sync` in the user's home directory. It must be a valid ``.INI`` file.\n\nAdditionally, the IDA and Ghidra plugins also look for the configuration file\nin the IDB or project directory (`\u003cproject\u003e.rep`) first to allow local,\nper-IDB/project, settings. If a local configuration file is present, the\nglobal configuration file is ignored.\n\nValues declared in these configuration files override default values. Please\nnote, that **no** `.sync` file is created by default.\n\nBelow we detail, three common scenarios where a configuration file is\nuseful/needed:\n\n* Remote debugging\n* Modules names mismatch\n* Missing PID\n\n\n## Remote debugging: debugger and disassembler are on different hosts\n\nThe ``[INTERFACE]`` section is used to customize network related settings.\nLet's suppose one wants to synchronize IDA with a debugger running inside a\nvirtual machine (or simply another host), common remote kernel debugging\nscenario.\n\nSimply create two ``.sync`` file:\n\n* one on the machine where IDA is installed, in the IDB directory:\n* For Ghidra, place at home directory, ex. \"/home/user\" or \"C:\\Users\\user\".\n```\n[INTERFACE]\nhost=192.168.128.1\nport=9234\n```\n\nIt tells **ret-sync** ``IDA`` plugin to listen on the interface\n``192.168.128.1`` with port ``9234``. It goes without saying that this\ninterface must be reachable from the remote host or virtual machine.\n\n* one on the machine where the debugger is executed, in the user's home directory:\n\n```\n[INTERFACE]\nhost=192.168.128.1\nport=9234\n```\n\nIt tells **ret-sync** debugger plugin to connect to the **ret-sync** ``IDA``\nplugin configured previously to listen in this interface.\n\n\n***NOTE:*** You must specify a real IP here, and not use `0.0.0.0`. This is\nbecause the variable is used by multiple sources both for binding and\nconnecting, so using `0.0.0.0` will result in weird errors.\n\n\n\n## IDB and debugger modules names are different\n\n```\n[ALIASES]\nntoskrnl_vuln.exe=ntkrnlmp.exe\n```\n\nThe ``[ALIASES]`` section is used to customize the name which is used by a\ndisassembler (IDA/Ghidra) to register a module to its dispatcher/program\nmanager.\n\nBy default, disassembler plugins use the name of the input file. However one\nmay have renamed the file beforehand and it doesn't match anymore the name of\nthe actual process or loaded module as seen by the debugger.\n\nHere we simply tell to the dispatcher to match the name `ntkrnlmp.exe` (real\nname) instead of `ntoskrnl_vuln.exe` (IDB name).\n\n\n## gdb with Qt Creator debugging frontend\n\nThe Qt Creator debugging frontend changes the way gdb command output is logged. Since\nthis would interfere with the synchronization an option exists to use the raw gdb output\nfor synchronization instead of a temporary file. In the .sync configuration file use\n\n```\n[GENERAL]\nuse_tmp_logging_file=false\n```\n\nif you wish to use the Qt debugging frontend for the target.\n\n## Embedded devices and missing ``/proc/\u003cpid\u003e/maps``\n\nIn some scenarios, such as debugging embedded devices over serial or raw\nfirmware in QEMU, gdb is not aware of the PID and cannot access\n``/proc/\u003cpid\u003e/maps``.\n\nIn these cases, The ``[INIT]`` section is used to pass a custom context to the\nplugin. It allows overriding some fields such as the PID and memory mappings.\n\n`.sync` content extract:\n\n```\n[INIT]\ncontext = {\n      \"pid\": 200,\n      \"mappings\": [ [0x400000, 0x7A81158, 0x7681158, \"asav941-200.qcow2|lina\"] ]\n  }\n```\n\nEach entry in the mappings is: ``mem_base``, ``mem_end``, ``mem_size``, ``mem_name``.\n\n\n## Bypassing automatic address rebasing\n\nIn some scenarios, such as debugging embedded devices or connecting to\nminimalist debug interfaces, it may be more convenient to bypass the\nautomatic address rebasing feature implemented in the disassembler plugins.\n\nThe `use_raw_addr` option is currently supported only for Ghidra. In\nthe .sync configuration file use:\n\n```\n[GENERAL]\nuse_raw_addr=true\n```\n\n\n# Installation\n\n## IDA extension\n\n### IDA prerequisites\n\nIDA 7.x branch is required. For older versions (6.9x) please see archived\nrelease ``ida6.9x``.\n\n### Install the IDA extension\n\nFor IDA installation, copy ``Syncplugin.py`` and ``retsync`` folder from\n``ext_ida`` to IDA plugins directory, for example:\n\n* ``C:\\Program Files\\IDA Pro 7.4\\plugins``\n* ``%APPDATA%\\Hex-Rays\\IDA Pro\\plugins``\n* ``~/.idapro/plugins``\n\n### Run the IDA extension\n\n1. Open IDB\n2. Run the plugin in IDA (``Alt-Shift-S``) or ``Edit`` -\u003e ``Plugins`` -\u003e ``ret-sync``\n\n```\n[sync] default idb name: ld.exe\n[sync] sync enabled\n[sync] cmdline: \"C:\\Program Files\\Python38\\python.exe\" -u \"C:\\Users\\user\\AppData\\Roaming\\Hex-Rays\\IDA Pro\\plugins\\retsync\\broker.py\" --idb \"target.exe\"\n[sync] module base 0x100400000\n[sync] hexrays #7.3.0.190614 found\n[sync] broker started\n[sync] plugin loaded\n[sync] \u003c\u003c broker \u003c\u003c dispatcher not found, trying to run it\n[sync] \u003c\u003c broker \u003c\u003c dispatcher now runs with pid: 6544\n[sync] \u003c\u003c broker \u003c\u003c connected to dispatcher\n[sync] \u003c\u003c broker \u003c\u003c listening on port 63107\n\n```\n\n### IDA plugin troubleshooting\n\nTo troubleshoot issues with the IDA extension two options are available in the\nfile `retsync/rsconfig.py`:\n\n```\nLOG_LEVEL = logging.INFO\nLOG_TO_FILE_ENABLE = False\n```\n\nSetting `LOG_LEVEL` value to ` logging.DEBUG` makes the plugin more verbose.\n\nSetting `LOG_TO_FILE_ENABLE` value to `True` triggers the logging of exception\ninformation from `broker.py` and `dispatcher.py` into dedicated files. Log file\nare generated in the `%TMP%` folder with a name pattern `retsync.%s.err` .\n\n\n## Ghidra extension\n\n### Build the Ghidra extension\n\nEither use the pre-built version from the `ext_ghidra/dist` folder or follow the instruction to build it.\nEach extension build only supports the version of Ghidra specified in the plugin's file name.\nE.g. `ghidra_9.1_PUBLIC_20191104_retsync.zip` is for Ghidra 9.1 Public.\n\n1. Install Ghidra\n2. Install gradle\n\n```bash\napt install gradle\n```\n\n3. Build extension for your Ghidra installation (replace `$GHIDRA_DIR` with your installation directory)\n\n```bash\ncd ext_ghidra\ngradle -PGHIDRA_INSTALL_DIR=$GHIDRA_DIR\n```\n\n### Install the Ghidra extension\n\n1. From Ghidra projects manager: ``File`` -\u003e ``Install Extensions...``, click on the\n   `+` sign and select the `ext_ghidra/dist/ghidra_*_retsync.zip` and click OK.\n   This will effectively extract the `retsync` folder from the zip into\n   `$GHIDRA_DIR/Extensions/Ghidra/`\n2. Restart Ghidra as requested\n3. After reloading Ghidra, open a module in CodeBrowser. It should tell you a\n   new extension plugin has been detected. Select \"yes\" to configure it. Then\n   tick \"RetSyncPlugin\" and click OK. The console should show something like:\n\n```\n[*] retsync init\n[\u003e] programOpened: tm.sys\n    imageBase: 0x1c0000000\n```\n\n4. From Ghidra CodeBrowser tool: use toolbar icons or shortcuts to enable (``Alt+s``)/disable (``Alt+Shift+s``)/restart (``Alt+r``)\n   synchronization.\n\nA status window is also available from ``Windows`` -\u003e ``RetSyncPlugin``. You\ngenerally want to drop it on the side to integrate it with the Ghidra\nenvironment windows.\n\n\n## Binary Ninja extension\n\nBinary Ninja support is experimental, make sure to backup your analysis\ndatabases.\n\n### Binary Ninja prerequisites\n\n**ret-sync** requires Binary Ninja version 2.2 at minimum as well as Python 3\n(Python 2 is not supported).\n\n\n### Install the Binary Ninja extension\n\n**ret-sync** is not yet distributed through the Binary Ninja's Plugin Manager;\na manual installation is required. Simply copy that content of the `ext_bn`\nfolder into Binary Ninja's plugins folder, for example:\n\n`%APPDATA%\\Binary Ninja\\plugins`\n\nAfter restarting Binary Ninja, the following output should be present in the\nconsole window:\n\n```\n[sync] commands added\nLoaded python3 plugin 'retsync'\n```\n\n\n## WinDbg extension\n\n### Build the WinDbg extension\n\nEither use pre-built binaries or use the Visual Studio 2017\nsolution provided in ``ext_windbg``, (see\nhttps://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-relnotes if\nneeded).\n\nThis will build the `x64\\release\\sync.dll` file.\n\n### Install the WinDbg extension\n\nYou will need to copy the resulting `sync.dll` file into the\nappropriate Windbg extension path.\n\n* WinDbg Classic:\n\nFor earlier versions of Windbg this is is something like this (be\ncareful of ``x86``/``x64`` flavours), for example\n\n`C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\winext\\sync.dll`\n\n* Windbg Preview\n\nThe folder for storing extension seems to be based on the PATH, so you need to\nput it one of the queried locations.\n\nOne example is to put it here:\n\n`C:\\Users\\user\\AppData\\Local\\Microsoft\\WindowsApps\\sync.dll`\n\n### Run the WinDbg extension\n\n1. Launch WinDbg on target\n2. Load extension (``.load`` command)\n\n```\n    0:000\u003e .load sync\n    [sync.dll] DebugExtensionInitialize, ExtensionApis loaded\n```\n\n3. Sync WinDbg\n\n```\n      0:000\u003e !sync\n      [sync] No argument found, using default host (127.0.0.1:9100)\n      [sync] sync success, sock 0x5a8\n      [sync] probing sync\n      [sync] sync is now enabled with host 127.0.0.1\n```\n\nE.g. in IDA's Output window\n\n```\n      [*] \u003c\u003c broker \u003c\u003c dispatcher msg: add new client (listening on port 63898), nb client(s): 1\n      [*] \u003c\u003c broker \u003c\u003c dispatcher msg: new debugger client: dbg connect - HostMachine\\HostUser\n      [sync] set debugger dialect to windbg, enabling hotkeys\n```\n\nIf Windbg's current module matches IDA file name\n\n```\n      [sync] idb is enabled with the idb client matching the module name.\n```\n\n### WinDbg installation troubleshooting\n\nNote: If you get the following error, it is because you haven't copied the file\nto the right folder in the above steps.\n\n```\n0: kd\u003e .load sync\nThe call to LoadLibrary(sync) failed, Win32 error 0n2\n    \"The system cannot find the file specified.\"\nPlease check your debugger configuration and/or network access.\n```\n\nThe error below usually means that Windbg tried to load the incorrect flavour\nof the extension, ex: ``x64`` in place of the ``x86`` `sync.dll`.\n\n```\n0:000\u003e .load sync\nThe call to LoadLibrary(sync) failed, Win32 error 0n193\n    \"%1 is not a valid Win32 application.\"\nPlease check your debugger configuration and/or network access.\n```\n\nAs WinDbg Preview loads both plugins (``x86`` and  ``x64``) from the same\ndirectory, one can rename the ``x86`` file `sync32.dll`.\n\n```\n0:000\u003e .load sync32\n```\n\n\n## GNU gdb (GDB) installation\n\n1. Copy the `ext_gdb/sync.py` to the directory of your choice\n2. Load the extension (see auto-load-scripts)\n\n```\n    gdb\u003e source sync.py\n    [sync] configuration file loaded 192.168.52.1:9100\n    [sync] commands added\n```\n\n## LLDB installation\n\nLLDB support is experimental, however:\n\n1. Load extension (can also be added in ``~/.lldbinit``)\n\n```\n    lldb\u003e command script import sync\n```\n\n## OllyDbg 1.10 installation\n\nOllyDbg 1.10 support is experimental, however:\n\n1. Build the plugin using the VS solution (optional, see pre-built binaries)\n2. Copy the dll within OllyDbg's plugin directory\n\n## OllyDbg2 installation\n\nOllyDbg2 support is experimental, however:\n\n1. Build the plugin using the VS solution (optional, see pre-built binaries)\n2. Copy the dll within OllyDbg2's plugin directory\n\n## x64dbg installation\n\nBased on testplugin,  https://github.com/x64dbg/testplugin. x64dbg support is experimental, however:\n\n1. Build the plugin using the VS solution (optional, see pre-built binaries).\n   May you need a different version of the plugin sdk,\n   a copy can be found in each release of x64dbg.\n   Paste the \"``pluginsdk``\" directory into \"``ext_x64dbg\\x64dbg_sync``\"\n2. Copy the dll (extension is ``.d32`` or ``.dp64``) within x64dbg's plugin directory.\n\n# Usage\n\n## **ret-sync** debugger commands\n\nFor command-line oriented debuggers (mainly Windbg and GDB) a set of commands\nis exposed by **ret-sync** to assist in the reverse-engineering task.\n\nThe commands below are generic (Windbg and GDB), please note that a `!`\nprefix is needed on WinDbg (e.g.: `sync`  in GDB, `!sync` in Windbg).\n\n| Debugger command           | Description                                                                               |\n|----------------------------|-------------------------------------------------------------------------------------------|\n| `synchelp`                   | Display the list of available commands with short explanation                             |\n| `sync`                       | Start synchronization                                                                     |\n| `syncoff`                    | Stop synchronization                                                                      |\n| `cmt [-a address] \u003cstring\u003e`  | Add a comment at current ip in disassembler                                               |\n| `rcmt [-a address]`          | Reset comment at current ip in disassembler                                               |\n| `fcmt [-a address] \u003cstring\u003e` | Add a function comment for function in which current ip is located                        |\n| `raddr \u003cexpression\u003e`         | Add a comment with rebased address evaluated from expression                              |\n| `rln \u003cexpression\u003e`           | Get symbol from the disassembler for the given address                                    |\n| `lbl [-a address] \u003cstring\u003e`  | Add a label name at current ip in disassembler                                            |\n| `cmd \u003cstring\u003e`               | Execute a command in debugger and add its output as comment at current ip in disassembler |\n| `bc \u003c\\|\\|on\\|off\\|set 0xBBGGRR\u003e` | Enable/disable path coloring in disassembler                                              |\n| `idblist`                    | Get list of all IDB clients connected to the dispatcher                                   |\n| `syncmodauto \u003con\\|off\u003e`       | Enable/disable disassembler auto switch based on module name                              |\n| `idbn \u003cn\u003e`                   | Set active IDB to the nth client                                                          |\n| `jmpto \u003cexpression\u003e`         |                                                                                           |\n| `jmpraw \u003cexpression\u003e` | If an IDB is enabled then disassembler's view is synced with the resulting address.    |\n| `translate \u003cbase\u003e \u003caddr\u003e \u003cmod\u003e` | rebase an address with respect to its module's name and offset   |\n\n\nWinDbg specific commands:\n\n| Debugger command           | Description                                                                               |\n|----------------------------|-------------------------------------------------------------------------------------------|\n| `curmod`  |  Display module infomation for current instruction offset (for troubleshooting) |\n| `modlist`  |  Debugger Markup Language (DML) enhanced module list meant for smoother active idb switching  |\n| `idb \u003cmodule name\u003e`  |  Set given module as the active idb (see `modlist` enhanced version of `lm`) |\n| `modmap \u003cbase\u003e \u003csize\u003e \u003cname\u003e` |  A synthetic (\"faked\") module (defined using its base address and size) is added to the debugger internal list  |\n| `modunmap \u003cbase\u003e` |  Remove a previously mapped synthetic module at base address  |\n| `modcheck \u003c\\|\\|md5\u003e`  |  Use to check if current module really matches IDB's file (ex: module has been updated)  |\n| `bpcmds \u003c\\|\\|save\\|load\\|\u003e` | **bpcmds** wrapper, save and reload **.bpcmds** (breakpoints commands list) output to current IDB  |\n| `ks` | Debugger Markup Language (DML) enhanced output of **kv** command   |\n\n\nGDB specific commands:\n\n| Debugger command           | Description                                                                               |\n|----------------------------|-------------------------------------------------------------------------------------------|\n|`bbt` |  Beautiful backtrace. Similar to **bt** in GDB but requests symbols from disassembler  |\n| `patch`  | Patch bytes in disassembler based on live context   |\n| `bx` | Similar to GDB **x** but using a symbol. The symbol will be resolved by disassembler   |\n| `cc` | Continue to cursor in disassembler  |\n\n\n## IDA usage\n\n### IDA plugin's GUI\n\nThe ``Overwrite idb name`` input field is meant to change the default IDB\nname. It is the name that is used by the plugin to register with the\ndispatcher. IDB automatic switch is based on module name matching. In case of\nconflicting names (like a ``foo.exe`` and ``foo.dll``), this can be used to\nease matching. Please note, if you modify the input field while the sync is\nactive, you have to re-register with the dispatcher; this can be done simply\nby using the \"``Restart``\" button.\n\nAs a reminder it is possible to alias by default using the ``.sync`` configuration file.\n\n\n\n### IDA global shortcuts\n\n**ret-sync** defines these global shortcuts in IDA:\n\n* ``Alt-Shift-S``  - Run **ret-sync** plugin\n* ``Ctrl-Shift-S``  - Toggle global syncing\n* ``Ctrl-H``  - Toggle Hex-Rays syncing\n\nTwo buttons are also available in the Debug toolbar to toggle global and\nHex-Rays syncing.\n\n### IDA bindings over debugger commands\n\n``Syncplugin.py`` also registers debugger command wrapper hotkeys.\n\n* ``F2`` - Set breakpoint at cursor address\n* ``F3`` - Set one-shot breakpoint at cursor address\n* ``Ctrl-F2`` - Set hardware breakpoint at cursor address\n* ``Ctrl-F3`` - Set one-shot hardware breakpoint at cursor address\n* ``Alt-F2`` - Translate (rebase in debugger) current cursor address\n* ``Alt-F5`` - Go\n* ``Ctrl-Alt-F5`` - Run (GDB only)\n* ``F10`` - Single step\n* ``F11`` - Single trace\n\nThese commands are only available when the current IDB is active. When\npossible they have also been implemented for others debuggers.\n\n## Ghidra usage\n\n### Ghidra plugin's GUI\n\nOnce the RetSyncPlugin opened, you can add it to the CodeBrowser window by simple\ndrag'n'drop:\n\n![](img/ghidra.png)\n\nIf you want to view several modules, files need to be open in the same CodeBrowser\nviewer, simply drag'n'drop the additional ones in the CodeBrowser window to obtain\nthe result as above.\n\n### Ghidra global shortcuts\n\n**ret-sync** defines these global shortcuts in Ghidra:\n\n* ``Alt-S``  - Enable syncing\n* ``Alt-Shift-S``  - Disable syncing\n* ``Alt-R``  - Restart syncing\n* ``Alt-Shift-R``  - Reload configuration\n\n### Ghidra bindings over debugger commands\n\nBindings over debugger commands are also implemented. They are similar to the\nones from IDA's extension (except the \"Go\" command).\n\n* ``F2``  - Set breakpoint at cursor address\n* ``Ctrl-F2`` - Set hardware breakpoint at cursor address\n* ``Alt-F3`` - Set one-shot breakpoint at cursor address\n* ``Ctrl-F3`` - Set one-shot hardware breakpoint at cursor address\n* ``Alt-F2`` - Translate (rebase in debugger) current cursor address\n* ``F5`` - Go\n* ``Alt-F5`` - Run (GDB only)\n* ``F10`` - Single step\n* ``F11`` - Single trace\n\n\n## Binary Ninja usage\n\n### Binary Ninja global shortcuts\n\n**ret-sync** defines these global shortcuts in Binary Ninja:\n\n* ``Alt-S``  - Enable syncing\n* ``Alt-Shift-S``  - Disable syncing\n\n\n### Binary Ninja shortcuts\n\nBindings over debugger commands are also implemented. They are similar to the\nones from IDA's extension.\n\n* ``F2``  - Set breakpoint at cursor address\n* ``Ctrl-F2`` - Set hardware breakpoint at cursor address\n* ``Alt-F3`` - Set one-shot breakpoint at cursor address\n* ``Ctrl-F3`` - Set one-shot hardware breakpoint at cursor address\n* ``Alt-F2`` - Translate (rebase in debugger) current cursor address\n* ``Alt-F5`` - Go\n* ``F10`` - Single step\n* ``F11`` - Single trace\n\n\n## WinDbg usage\n\n### WinDbg plugin commands\n\n* **!sync**: Start synchronization\n* **!syncoff**: Stop synchronization\n* **!synchelp**: Display the list of available commands with short explanation.\n* **!cmt [-a address] \u003cstring\u003e**: Add comment at current ip in IDA\n\n```\n    [WinDbg]\n    0:000:x86\u003e pr\n    eax=00000032 ebx=00000032 ecx=00000032 edx=0028eebc esi=00000032 edi=00000064\n    eip=00430db1 esp=0028ed94 ebp=00000000 iopl=0         nv up ei pl nz na po nc\n    cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202\n    image00000000_00400000+0x30db1:\n    00430db1 57    push    edi\n\n    0:000:x86\u003e dd esp 8\n    0028ed94  00000000 00433845 0028eebc 00000032\n    0028eda4  0028f88c 00000064 002b049e 00000110\n\n    0:000:x86\u003e !cmt 0028ed94  00000000 00433845 0028eebc 00000032\n    [sync.dll]  !cmt called\n\n    [IDA]\n    .text:00430DB1    push    edi             ; 0028ed94  00000000 00433845 0028eebc 00000032\n```\n\n* **!rcmt [-a address]**: Reset comment at current ip in IDA\n\n```\n    [WinDbg]\n    0:000:x86\u003e !rcmt\n    [sync] !rcmt called\n\n    [IDA]\n    .text:00430DB1    push    edi\n```\n\n* **!fcmt [-a address] \u003cstring\u003e**: Add a function comment for function in which current ip is located\n\n```\n    [WinDbg]\n    0:000:x86\u003e !fcmt decodes buffer with key\n    [sync] !fcmt called\n\n    [IDA]\n    .text:004012E0 ; decodes buffer with key\n    .text:004012E0                 public decrypt_func\n    .text:004012E0 decrypt_func    proc near\n    .text:004012E0                 push    ebp\n```\n\nNote: calling this command without argument reset the function's comment.\n\n* **!raddr \u003cexpression\u003e**: Add a comment with rebased address evaluated from expression\n* **!rln \u003cexpression\u003e**: Get symbol from the disassembler for the given address\n* **!lbl [-a address] \u003cstring\u003e**: Add a label name at current ip in disassembler\n\n```\n    [WinDbg]\n    0:000:x86\u003e !lbl meaningful_label\n    [sync] !lbl called\n\n    [IDA]\n    .text:000000000040271E meaningful_label:\n    .text:000000000040271E    mov     rdx, rsp\n```\n\n* **!cmd \u003cstring\u003e**: Execute a command in WinDbg and add its output as comment at current ip in disassembler\n\n```\n    [WinDbg]\n    0:000:x86\u003e pr\n    eax=00000032 ebx=00000032 ecx=00000032 edx=0028eebc esi=00000032 edi=00000064\n    eip=00430db1 esp=0028ed94 ebp=00000000 iopl=0         nv up ei pl nz na po nc\n    cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202\n    image00000000_00400000+0x30db1:\n    00430db1 57     push    edi\n    [sync.dll]  !cmd r edi\n\n    [IDA]\n    .text:00430DB1    push    edi             ; edi=00000064\n```\n\n* **!bc \u003c||on|off|set 0xBBGGRR\u003e** : Enable/disable path coloring in disassembler.\n  This is NOT a code tracing tool,\n  there are efficient tools for that. Each manually stepped instruction is\n  colored in the graph. Color a single instruction at current ip if called\n  without argument.\n  \"set\" argument is used to set path color with a new hex rgb code (reset color\n  if called with a value \u003e 0xFFFFFF).\n* **!idblist**: Get list of all IDB clients connected to the dispatcher:\n\n```\n    [WinDbg]\n    0:000\u003e !idblist\n    \u003e currently connected idb(s):\n        [0] target.exe\n```\n\n* **!syncmodauto \u003con|off\u003e**: Enable/disable disassembler auto switch based on module name:\n\n```\n    [WinDbg]\n    0:000\u003e !syncmodauto off\n\n    [IDA]\n    [*] \u003c\u003c broker \u003c\u003c dispatcher msg: sync mode auto set to off\n```\n\n* **!idbn \u003cn\u003e**: Set active IDB to the nth client. n should be a valid decimal value.\n  This is a semi-automatic mode (personal tribute to the tremendous jj)\n\n```\n    [WinDbg]\n    0:000:\u003e !idbn 0\n    \u003e current idb set to 0\n```\n\nIn this example, current active IDB client would have been set to:\n\n```\n\t[0] target.exe.\n```\n\n* **!jmpto \u003cexpression\u003e**: Expression given as argument is evaluated in the context of the current debugger's status.\n  disassembler's view is then synced with the resulting address if a matching module is registered.\n  Can be seen as a manual syncing, relocation is automatically performed, on the fly.\n  Especially useful for randomly relocated binary.\n* **!jmpraw \u003cexpression\u003e**: Expression given as argument is evaluated in the context of the current debugger's status.\n  If an IDB is enabled then disassembler's view is synced with the resulting address. Address is not rebased\n  and there is no IDB switching.\n  Especially useful for dynamically allocated/generated code.\n* **!modmap \u003cbase\u003e \u003csize\u003e \u003cname\u003e**: A synthetic (\"faked\") module (defined using its base address and size) is added to the debugger internal list.\n  From msdn: \"If all the modules are reloaded - for example, by calling Reload with the Module parameter set to an empty string - all synthetic modules will be discarded.\"\n  It can be used to more easily debug dynamically allocated/generated code.\n* **!modunmap \u003cbase\u003e**: Remove a previously mapped synthetic module at base address.\n* **!modcheck \u003c||md5\u003e**: Use to check if current module really matches IDB's file (ex: module has been updated)\n  When called without an argument, pdb's GUID from Debug Directory is used. It can alternatively use md5,\n  but only with a local debuggee (not in remote kernel debugging).\n* **!bpcmds \u003c||save|load|\u003e**: **bpcmds** wrapper, save and reload **.bpcmds** (breakpoints commands list) output to current IDB.\n  Display (but not execute) saved data if called with no argument.\n  Persistent storage is achieved using IDA's netnode feature.\n* **!ks**: Debugger Markup Language (DML) enhanced output of **kv** command. Code Addresses are clickable (**!jmpto**) as well as data addresses (**dc**).\n* **!translate \u003cbase\u003e \u003caddr\u003e \u003cmod\u003e**: Meant to be used from IDA (``Alt-F2`` shortcut), rebase an address with respect to its module's name and offset.\n\n#### Address optional argument\n\n**!cmt**, **!rcmt** and **!fcmt** commands support an optional address option: ``-a`` or ``--address``.\nAddress should be passed as an hexadecimal value. Command parsing is based on python's\n``argparse`` module. To stop line parsing use ``--``.\n\n```\n    [WinDbg]\n    0:000:x86\u003e !cmt -a 0x430DB2 comment\n```\n\nThe address has to be a valid instruction's address.\n\n## GNU gdb (GDB) usage\n\nSync with host:\n\n```\n    gdb\u003e sync\n    [sync] sync is now enabled with host 192.168.52.1\n    \u003cnot running\u003e\n\n    gdb\u003e r\n    Starting program: /bin/ls\n    [Thread debugging using libthread_db enabled]\n    Using host libthread_db library \"/lib/libthread_db.so.1\".\n```\n\n### GDB plugin commands\n\nUse commands, **without \"!\" prefix**\n\n```\n    (gdb) cmd x/i $pc\n    [sync] command output: =\u003e 0x8049ca3:    push   edi\n\n    (gdb) synchelp\n    [sync] extension commands help:\n     \u003e sync \u003chost\u003e\n     \u003e syncoff\n     \u003e cmt [-a address] \u003cstring\u003e\n     \u003e rcmt [-a address] \u003cstring\u003e\n     \u003e fcmt [-a address] \u003cstring\u003e\n     \u003e cmd \u003cstring\u003e\n     \u003e bc \u003con|off|\u003e\n     \u003e rln \u003caddress\u003e\n     \u003e bbt \u003csymbol\u003e\n     \u003e patch \u003caddr\u003e \u003ccount\u003e \u003csize\u003e\n     \u003e bx /i \u003csymbol\u003e\n     \u003e cc\n     \u003e translate \u003cbase\u003e \u003caddr\u003e \u003cmod\u003e\n```\n\n* **rln**: Get symbol from the IDB for the given address\n* **bbt**: Beautiful backtrace. Similar to **bt** but requests symbols from disassembler\n\n```\n    (gdb) bt\n    #0  0x0000000000a91a73 in ?? ()\n    #1  0x0000000000a6d994 in ?? ()\n    #2  0x0000000000a89125 in ?? ()\n    #3  0x0000000000a8a574 in ?? ()\n    #4  0x000000000044f83b in ?? ()\n    #5  0x0000000000000000 in ?? ()\n    (gdb) bbt\n    #0 0x0000000000a91a73 in IKE_GetAssembledPkt ()\n    #1 0x0000000000a6d994 in catcher ()\n    #2 0x0000000000a89125 in IKEProcessMsg ()\n    #3 0x0000000000a8a574 in IkeDaemon ()\n    #4 0x000000000044f83b in sub_44F7D0 ()\n    #5 0x0000000000000000 in  ()\n```\n\n\n* **patch**: Patch bytes in disassembler based on live context\n* **bx**: Beautiful display. Similar to **x** but using a symbol. The symbol\n  will be resolved by disassembler.\n* **cc**: Continue to cursor in disassembler. This is an alternative to using ``F3`` to\n  set a one-shot breakpoint and ``F5`` to continue. This is useful if you prefer\n  to do it from gdb.\n\n```\n    (gdb) b* 0xA91A73\n    Breakpoint 1 at 0xa91a73\n    (gdb) c\n    Continuing.\n\n    Breakpoint 1, 0x0000000000a91a73 in ?? ()\n    (gdb) cc\n    [sync] current cursor: 0xa91a7f\n    [sync] reached successfully\n    (gdb)\n```\n\n\n## LLDB usage\n\n1. Sync with host\n\n```\n    lldb\u003e process launch -s\n    lldb\u003e sync\n    [sync] connecting to localhost\n    [sync] sync is now enabled with host localhost\n    [sync] event handler started\n```\n\n2. Use commands\n\n```\n    lldb\u003e synchelp\n    [sync] extension commands help:\n     \u003e sync \u003chost\u003e                   = synchronize with \u003chost\u003e or the default value\n     \u003e syncoff                       = stop synchronization\n     \u003e cmt \u003cstring\u003e                  = add comment at current eip in IDA\n     \u003e rcmt \u003cstring\u003e                 = reset comments at current eip in IDA\n     \u003e fcmt \u003cstring\u003e                 = add a function comment for 'f = get_func(eip)' in IDA\n     \u003e cmd \u003cstring\u003e                  = execute command \u003cstring\u003e and add its output as comment at current eip in IDA\n     \u003e bc \u003con|off|\u003e                  = enable/disable path coloring in IDA\n                                       color a single instruction at current eip if called without argument\n    lldb\u003e cmt mooo\n```\n\n\n## OllyDbg 1.10 usage\n\n1. Use Plugins menu or shortcuts to enable (``Alt+s``)/disable (``Alt+u``)\n   synchronization.\n\n\n## OllyDbg2 usage\n\n1. Use Plugins menu or shortcuts to enable (``Ctrl+s``)/disable (``Ctrl+u``)\n   synchronization.\n\nDue to the beta status of OllyDbg2 API, only the following features have been implemented:\n\n- Graph sync [use ``F7``; ``F8`` for stepping]\n- Comment   [use ``CTRL+;``]\n- Label     [use ``CTRL+:``]\n\n\n## x64dbg usage\n\n1. Use Plugins menu or commands enable (\"``!sync\"``) or disable (\"``!syncoff``\") synchronization.\n\n2. Use commands\n\n```\n[sync] synchelp command!\n[sync] extension commands help:\n \u003e !sync                          = synchronize with \u003chost from conf\u003e or the default value\n \u003e !syncoff                       = stop synchronization\n \u003e !syncmodauto \u003con | off\u003e        = enable / disable idb auto switch based on module name\n \u003e !synchelp                      = display this help\n \u003e !cmt \u003cstring\u003e                  = add comment at current eip in IDA\n \u003e !rcmt \u003cstring\u003e                 = reset comments at current eip in IDA\n \u003e !idblist                       = display list of all IDB clients connected to the dispatcher\n \u003e !idb \u003cmodule name\u003e             = set given module as the active idb (see !idblist)\n \u003e !idbn \u003cn\u003e                      = set active idb to the n_th client. n should be a valid decimal value\n \u003e !translate \u003cbase\u003e \u003caddr\u003e \u003cmod\u003e = rebase an address with respect to local module's base\n```\n\nNote: using the **!translate** command from a disassembler (IDA/Ghidra,\n``Alt-F2`` shortcut), will make the disassembler window to \"jump\" to the\nspecific address (equivalent of running **disasm \u003crebased addr\u003e** in x64dbg\ncommand line).\n\n\n## Python library usage\n\nOne may want to use **ret-sync** core features (position syncing with a\ndisassembler, symbol resolution) even though a full debugging environment is\nnot available or with a custom tool. To that end, a minimalist Python library\nhas been extracted.\n\nThe example below illustrates the usage of the Python library with a script\nthat walks through the output of an event based logging/tracing tool.\n\n\n```python\nfrom sync import *\n\nHOST = '127.0.0.1'\n\nMAPPINGS = [\n    [0x555555400000, 0x555555402000,  0x2000, \" /bin/tempfile\"],\n    [0x7ffff7dd3000, 0x7ffff7dfc000, 0x29000, \" /lib/x86_64-linux-gnu/ld-2.27.so\"],\n    [0x7ffff7ff7000, 0x7ffff7ffb000,  0x4000, \" [vvar]\"],\n    [0x7ffff7ffb000, 0x7ffff7ffc000,  0x1000, \" [vdso]\"],\n    [0x7ffffffde000, 0x7ffffffff000, 0x21000, \" [stack]\"],\n]\n\nEVENTS = [\n    [0x0000555555400e74, \"malloc\"],\n    [0x0000555555400eb3, \"open\"],\n    [0x0000555555400ee8, \"exit\"]\n]\n\nsynctool = Sync(HOST, MAPPINGS)\n\nfor e in EVENTS:\n    offset, name = e\n    synctool.invoke(offset)\n    print(\"    0x%08x - %s\" % (offset, name))\n    print(\"[\u003e] press enter for next event\")\n    input()\n```\n\n\n# Extend\n\nWhile initially focused on dynamic analysis (debuggers), it is of-course\npossible to extend the plugins set and integrate with other tools.\n\n- Integration with **REVEN** Timeless Analysis and Debugging Platform by [Tetrane](https://www.tetrane.com/):\n  - http://blog.tetrane.com/2015/02/reven-in-your-toolkit.html\n  - https://twitter.com/tetrane/status/1374768014193799175\n- Integration with **EFI DXE Emulator** by Assaf Carlsbad ([@assaf_carlsbad](https://twitter.com/assaf_carlsbad)):\n  - https://twitter.com/assaf_carlsbad/status/1242114356881641474\n  - https://github.com/assafcarlsbad/efi_dxe_emulator\n\nOther resource(s):\n\n- \"*Combining static and dynamic binary analysis - ret-sync*\" by Jean-Christophe Delaunay\n  - https://www.synacktiv.com/ressources/bieresecu1_ret-sync_en.pdf\n\n\n# TODO\n\n- Sure.\n\n# Known Bugs/Limitations\n\n- Tested with Python 2.7/3.7, IDA 7.7 (Windows, Linux and Mac OS X), Ghidra 10.1.1, Binary Ninja 3.0.3225-dev, GNU gdb (GDB) 8.1.0 (Debian), lldb 310.2.37.\n- **THERE IS NO AUTHENTICATION/ENCRYPTION** whatsoever between the parties; you're on your own.\n- Self modifying code is out of scope.\n\nWith GDB:\n\n- it seems that stop event is not called when using 'return' command.\n- multi-threading debugging have issues with signals.\n\nWith WinDbg:\n\n- IDA's client plugin gets notified even though encountered breakpoint\n  uses a command string that makes it continue ('``g``'). This can cause major slow-down\n  if there are too much of these events. A limited fix has been implemented, the\n  best solution is still to sync off temporarily.\n- Possible race condition\n\nWith Ghidra:\n\n- Shortcuts are not working as expected in decompiler widget.\n\nWith IDA:\n\n- Graph window redrawing is quite slow for big graphs.\n- **ret-sync** shortcuts conflicts in Linux environments.\n\nConflict(s):\n\n- Logitech Updater software is known to use the same default port (9100). A solution\n  is to use a global `.sync` configuration file to define a different port.\n\n```\n[INTERFACE]\nhost=127.0.0.1\nport=9234\n```\n\n# License\n\n**ret-sync** is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see http://www.gnu.org/licenses/.\n\nThe Binary Ninja plugin is released under the MIT licence.\n\n\n# Greetz\n\nHail to Bruce Dang, StalkR, @Ivanlef0u, Damien Aumaître, Sébastien Renaud and\nKévin Szkudlapski, @_m00dy_, @saidelike, Xavier Mehrenberger, ben64, Raphaël\nRigo, Jiss for their kindness, help, feedbacks and thoughts. Ilfak Guilfanov,\nIgor Skochinsky and Arnaud Diederen for their help with IDA's internals and\noutstanding support. Thank you to Jordan Wiens and Vector 35. Finally, thank\nyou also to all the contributors and everyone who reported issues/bugs.\n","funding_links":[],"categories":["\u003ca id=\"f7d311685152ac005cfce5753c006e4b\"\u003e\u003c/a\u003e与调试器同步\u0026\u0026通信\u0026\u0026交互","C","C (286)","Firmware Security","Reverse Engine","使用","Ghidra Scripts/Plugins/Extension"],"sub_categories":["\u003ca id=\"46c9dfc585ae59fe5e6f7ddf542fb31a\"\u003e\u003c/a\u003eYara","Reverse Engineering Tools","\u003ca id=\"f7d311685152ac005cfce5753c006e4b\"\u003e\u003c/a\u003e与调试器同步\u0026\u0026通信\u0026\u0026交互"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbootleg%2Fret-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbootleg%2Fret-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbootleg%2Fret-sync/lists"}