User Guide
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 14
| Download | |
| Open PDF In Browser | View PDF |
Retargetable Decompiler’s IDA Plugin User Guide Version 0.4 https://github.com/avast-tl/retdec-idaplugin https://retdec.com support@retdec.com January 16, 2018 Contents 1 Introduction 2 2 Installation 2.1 IDA . . . . . . . . . . . . 2.2 Linux . . . . . . . . . . . 2.3 Windows . . . . . . . . . 2.4 Windows Plugin on Linux . . . . 3 3 3 4 4 3 Configuration 3.1 IDA’s plugin.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Decompilation Configuration . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Configuration from IDA . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5 5 6 4 Plugin Information 4.1 About Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 GUI Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7 7 9 5 Decompilation 5.1 Selective Decompilation . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Full Decompilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 9 9 6 User Interactions 6.1 Basic Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Code Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10 10 11 7 List 7.1 7.2 7.3 7.4 11 11 12 12 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of All User Actions Function-Declaration/Definition Context Function-Call Context . . . . . . . . . . Global-Variable Context . . . . . . . . . Global Context . . . . . . . . . . . . . . 8 Support and Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1 1 Introduction This document describes the Retargetable Decompiler’s plugin for IDA (RetDec plugin). Its goal is to integrate with IDA, give transparent access to the Retargetable Decompiler and provide user-interaction capabilities like navigation or code refactoring. An example of code decompiled by Retdec plugin is shown in Figure 1. Retargetable Decompiler (RetDec) is a reverse-engineering tool independent of any particular target architecture, file format, operating system, or compiler. It was developed in cooperation of Faculty of Information Technology, Brno University of Technology and AVG Technologies. Since the acquisition of AVG Technologies by Avast in 2016, Avast has continued to develop the decompiler. It is using Capstone disassembler engine and a Capstone2LlvmIR library to translate machine code into a high-level-language representation. Currently, the decompiler supports the MIPS, ARM (including Thumb extension), x86, and PowerPC architectures using the Windows PE, COFF, Unix ELF, Intel HEX, and RAW binary file formats. RetDec can be used in the following ways: 1. Online decompilation using web interface. 2. Remote decompilation using Application programming interface (API). 3. Local build: (a) Compiling RetDec repository on your own. (b) Downloading and installing RetDec binary release. 4. RetDec IDA plugin (this quide’s topic): (a) Remote decompilation using API. (b) Local decompilation using local build. 2 Figure 1: Example of code decompiled by RetDec plugin. 2 Installation This section describes prerequisites and the installation process of RetDec IDA plugin binary release. It is also possible to build and install the plugin directly from sources. To do so, follow the Build and Installation instructions instead of this section. 2.1 IDA The plugin is created using IDA SDK version 6.6. The plugin is compatible with the following IDA versions: 6.6, 6.7, 6.8, 6.9, 6.95. The plugin does NOT work with IDA 7.x. 2.2 Linux Follow the next steps to install RetDec plugin in a Linux environment: 1. Install 32-bit versions of the following shared-object dependencies: libc.so.6 libgcc_s.so.1 libm.so.6 libpthread.so.0 libstdc++.so.6 2. If you plan to use local RetDec build, install Python 3 and Pygments. 3. Download the Linux installation package (Table 1) from the project’s release page. 4. Copy retdec.plx to the IDA’s plugin directory (/plugins). 3 Table 1: Linux installation package contents. File license license/LICENSE license/LICENSE-THIRD-PARTY retdec.plx user_guide.pdf 2.3 Description Directory with licenses. RetDec IDA plugin’s license. Licenses of libraries used by RetDec plugin. 32-bit Linux RetDec plugin. RetDec plugin’s user guide (this document). Windows The Windows version of the plugin requires Windows 7 or later, with the MSVC 2015 runtime1 installed. Follow the next steps to install RetDec plugin in a Windows environment: 1. If you plan to use local RetDec build, install Python 3 and Pygments. 2. Download the Windows installation package (Table 2) from the project’s release page. 3. Copy retdec.plw to the IDA’s plugin directory ( /plugins). Table 2: Windows installation package contents. File license license/LICENSE license/LICENSE-THIRD-PARTY retdec.plw user_guide.pdf 2.4 Description Directory with licenses. RetDec IDA plugin’s license. Licenses of libraries used by RetDec plugin. 32-bit Windows RetDec plugin. RetDec plugin’s user guide (this document). Windows Plugin on Linux It is also possible to run the Windows version of IDA with the Windows version of RetDec plugin on Linux using Wine2 . Install RetDec plugin as described in Section 2.3 and if it does not run out of the box, try a workaround3 . 3 Configuration This section describes how to configure RetDec plugin. After you follow these steps, you should have your plugin ready for work. 1 Visual C++ Redistributable for Visual Studio 2015: https://www.microsoft.com/en-us/ download/details.aspx?id=48145 2 https://www.winehq.org/ 3 https://bugs.winehq.org/show_bug.cgi?id=39437#c6 4 3.1 IDA’s plugin.cfg The plugin’s default mode is set to selective decompilation (see Section 5). It tries to register hotkey CTRL+D for its invocation. If you already use this hotkey for another action or you just want to use a different hotkey, you need to modify IDA’s plugin configuration file. Moreover, the plugin supports one more decompilation mode and a hotkey invocation for the plugin’s configuration. If you want to use any of them, you also have to modify the config file. The IDA’s plugin configuration file is in /plugins/plugins.cfg. Its format is documented inside the file itself. To configure RetDec plugin, add the following lines at the beginning4 of the file: ; Plugin_name File_name Hotkey Arg ; ------------------------------------------------Retargetable_Decompiler retdec Ctrl-d 0 Retargetable_Decompiler retdec Ctrl-Shift-d 1 Retargetable_Decompiler retdec Ctrl-Shift-c 2 These lines tell IDA which hotkeys invoke the plugin and what argument is passed to it. The plugin’s behavior after invocation is determined by the passed argument. Possible argument values are summarized in Table 3. In the provided example, we mapped selective decompilation to hotkey CTRL+D (plugin’s default), full decompilation to CTRL+SHIFT+D, and plugin configuration to CTRL+SHIFT+C. However, you may choose whichever hotkeys you like, provided they do not clash with other plugins or IDA. Table 3: Description of RetDec plugin’s invocation arguments. Argument value Description 0 Invokes selective decompilation. See Section 5. 1 Invokes full decompilation. See Section 5. 2 Invokes plugin configuration inside IDA. See Section 3.3. 3.2 Decompilation Configuration Each time a decompilation is triggered, plugin checks that it is properly configured. If it is not, warning shown in Figure 2 is displayed. After you hit OK, the configuration dialog (Figure 3) appears. Here, you can choose the decompilation mode to use: 1. Remote API decompilation (plugin’s default) – you have to provide your API key. To access it, register to https://retdec.com, login, and click on Account. 2. Local decompilation – you have to install RetDec local build and make sure plugin finds the retdec-decompiler.sh script. Either add the decompiler’s bin directory to the system PATH, or set path to retdec-decompiler.sh in the form as shown in Figure 4. 4 Newer versions of IDA behave strangely when the lines are appended at the end, so just put them at the start. 5 The settings will be saved and if you want to change them later, you need to manually invoke the plugin’s configuration from IDA (see Section 3.3). Figure 2: RetDec plugin’s configuration warning. Figure 3: RetDec plugin’s configuration dialog. Figure 4: RetDec plugin’s configuration dialog – path to retdec-decompiler.sh set. 3.3 Configuration from IDA The same dialog (Figure 3) that is displayed if the plugin is misconfigured can be opened from IDA anytime later. There are the following two ways to do it: 6 • If you configured a hotkey for the plugin’s configuration argument value according to Section 3.1, you can use it to invoke the configuration dialog. • You can also open the configuration dialog from the Options/RetDec plugin options menu (Figure 5). Figure 5: Opening the plugin’s configuration dialog from the menu. 4 Plugin Information This section describes how to find information about RetDec plugin you are currently using and how the plugin communicates information to you. 4.1 About Plugin Information about RetDec plugin can be found among IDA’s information on the registered plugins at Help/About program (Figure 6), where you need to click on the Addons button (Figure 7). Then, find the Retargetable Decompiler entry in the presented list (Figure 8). 4.2 Output Window Right after the start, as well as during the work with RetDec plugin, it communicates with you mainly through the IDA’s output window (Figure 9). Here, you are shown several kinds of important messages: [RetDec info] : [RetDec warning]: [RetDec error] : some important piece of information something went a little bit wrong something went very wrong 7 Figure 6: Opening the About IDA dialog from the menu. Figure 7: Information window about IDA. Figure 8: Information window about RetDec plugin. 8 Figure 9: IDA’s output window. 4.3 GUI Windows Sometimes, RetDec plugin wants to be sure you noticed an important message or event. In such a case, it shows you a pop-up window, which forces you to acknowledge it by pressing OK or a similar button. 5 Decompilation This section describes how to invoke a decompilation. After reading it, you should be able to decompile a selected function, as well as an entire binary that is being analyzed. 5.1 Selective Decompilation RetDec plugin’s primary decompilation mode is selective decompilation. It decompiles the function that is currently under the cursor. It is invoked from the IDA’s disassembly window, where you need to bring focus to the desired function and use either the default hotkey CTRL+D, or a hotkey you configured according to Section 3.1. Once the decompilation is finished, the decompiled source code is displayed in a new IDA viewer window. Here, you can invoke new decompilations by double-clicking on function calls. 5.2 Full Decompilation If you configured a hotkey for full decompilation in Section 3.1, you can use it to decompile an entire binary that is being analyzed. The result of this decompilation is stored into an output file, whose location is communicated to you through IDA’s output window. The result cannot be displayed in the IDA’s viewer window. 6 User Interactions This section describes various kinds of user interactions that are currently supported by RetDec plugin. As was stated in Section 5, these interactions are applicable only on results from selective decompilations because full decompilations cannot be displayed in IDA’s viewer window. 9 6.1 Basic Interactions We use the IDA’s native custom viewer window to display the decompiled source codes. Therefore, the plugin feels like part of IDA and we get a word occurrences highlighting (Figure 10) out of the box. Figure 10: Native word occurrence highlighting. 6.2 Navigation RetDec plugin supports function navigation—jumping forward and backward between already decompiled functions, or invoke an entirely new decompilation. When you doubleclick on a function call, the plugin presents the requested function. If it was already decompiled in the past, the cached result is shown to perform the action faster. You have to either explicitly request a re-decompilation of the previously processed functions, or perform an action that triggers the re-decompilation automatically (see Section 6.3). Re-decompilation can be forced by using the selective decompilation hotkey in IDA’s disassembly (re-decompilation of any function), or in the RetDec plugin’s viewer window (re-decompilation of currently shown function). If the double-clicked function was not decompiled yet, it is selectively reversed and displayed. In either case, only one function is shown at a time. A navigation entry for the newly presented function is added into a doubly linked navigation list, right after the entry for function from which the invocation was made. The list is then used for forward and backward navigation between the stored functions. An example of such navigation is depicted in Figure 11. Unfortunately, we were not able to integrate navigation with IDA’s graphical control elements, so it can be done only through keyboard hotkeys: • ESC to move back. • CTRL+F to move forward. 10 Figure 11: Decompiled function navigation example. 6.3 Code Refactoring The RetDec plugin’s viewer windows also allows you to refactor displayed source code. We can divide the source-code modifications into two basic categories: • Those which do not require immediate re-decompilation, like object-identifier renaming or function-comment insertion. • Those which automatically trigger re-decompilation of the modified function. These are typically changes that can be used or propagated by reversing analyses. For example, a user-specified object data type can by spread by the data-flow type recovery analysis among other objects. Refactoring actions are triggered either by hotkeys associated with them, or by popup menus shown on right-click. Actions are sensitive to the current context (current word under the cursor). As is shown in Figure 12 and Figure 13, actions available for functions differ from actions for global variables. Available actions at any given position are composed of two sets of actions: • Actions available for the current context, i.e. for functions, global variables, function calls, etc. This set may be empty. • Global actions available at all posistions, i.e. navigation, current function comment modification, etc. The complete catalog of available user actions is listed in Section 7. 7 List of All User Actions This section provides a complete catalog of available user actions for all possible contexts. 7.1 Function-Declaration/Definition Context Function actions are available on function declarations or definitions. They are listed in Table 4. 11 Figure 13: Context actions available for global variables. Figure 12: Context actions available for functions. Table 4: Function context user actions. 7.2 Action description Hotkey Jump to IDA’s ASM Rename function Change type declaration Open xrefs window Open calls window A N Y X C Triggers re-decompilation 7 7 3 7 7 Function-Call Context Function-call actions are available on function calls. We can divide them into two categories: • Calls of user defined functions—actions are the same as in function-declaration/definition context (Section 7.1), except the “Change type declaration” action. Also, you can double-click on a call to decompile/display the called function. • Calls of dynamically linked functions—the only available action is double-click, which takes you on the import stub in the IDA’s disassembly view. 7.3 Global-Variable Context Global-variable actions are available on global-variable definitions and uses. They are listed in Table 5. 7.4 Global Context Global context actions are available everywhere. They are listed in Table 6. 12 Table 5: Global-variable context user actions. Action description Hotkey Jump to IDA’s ASM Rename global variable A N Triggers re-decompilation 7 7 Table 6: Global context user actions. Action description Hotkey Edit current function’s comment ; Move backward (navigation) ESC Move forward (navigation) CTRL+F 8 Triggers re-decompilation 7 7 7 Support and Feedback RetDec plugin is still in an experimental beta version. If you have any feedback, suggestions, or bug reports, please open an issue in the GitHub project (preferred), or send them to us either through our website, or through email. https://github.com/avast-tl/retdec-idaplugin https://retdec.com support@retdec.com 13
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 14 Page Mode : UseOutlines Author : Title : Subject : Creator : LaTeX with hyperref package Producer : pdfTeX-1.40.18 Create Date : 2018:01:16 18:00:44+01:00 Modify Date : 2018:01:16 18:00:44+01:00 Trapped : False PTEX Fullbanner : This is pdfTeX, Version 3.14159265-2.6-1.40.18 (TeX Live 2017/Arch Linux) kpathsea version 6.2.3EXIF Metadata provided by EXIF.tools