Examples
IDAPython examples
This collection of examples organizes all IDAPython sample code into categories for easy reference. Each example demonstrates practical implementation for the IDAPython API, complementing the reference documentation with a real-world usage scenario.
How to run the examples?
Load the script via File Loader
Navigate to File -> Script file....
In the new dialog, select the
.pyscript you want to run and click Open.
Load the script via Script command
Navigate to File -> Script command....
Paste the code into Please enter script body field and click Run.
Load the script via output window/console
In the output window/IDAPython console, type the following command:
exec(open("path/to/your_script.py").read())to execute the script.
Example Categories: Overview
Creating & manipulating user-interface widgets, prompting the user with forms, enriching existing widgets, or creating your own UI through Python Qt bindings.
Various ways to query, or modify the disassembly listing, alter the way analysis is performed, or be notified of changes made to the IDB.
Querying the decompiler, manipulating the decompilation trees (either at the microcode level, or the C-tree), and examples showing how to intervene in the decompilation output.
Driving debugging sessions, be notified of debugging events.
These samples utilize our Type APIs, which allow you to manage the types and perform various operations on them, like creating the structures or enums and adding their members programmatically.
Miscellaneous examples that don't quite fall into another category, but don't really justify one of their own.
User interface
Beginner
Intermediate
Advanced
Disassembly
Beginner
Intermediate
Decompilation
Beginner
Intermediate
Advanced
Debuggers
Beginner
Working with types
Beginner
Intermediate
Miscellaneous
Examples list
Assign a shortcut to a custom function
ida_kernwin.add_hotkey is a simpler, but much less flexible alternative to ida_kernwin.register_action (though it does use the same mechanism under the hood.)
It's particularly useful during prototyping, but note that the actions that are created cannot be inserted in menus, toolbars or cannot provide a custom ida_kernwin.action_handler_t.update callback.
APIs Used:
ida_kernwin.add_hotkeyida_kernwin.del_hotkey
Add custom menus to IDA
It is possible to add custom menus to IDA, either at the toplevel (i.e., into the menubar), or as submenus of existing menus.
Notes:
the same action can be present in more than 1 menu
this example does not deal with context menus
APIs Used:
ida_kernwin.AST_ENABLE_ALWAYSida_kernwin.SETMENU_INSida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_menuida_kernwin.create_menuida_kernwin.register_action
Assign a background color to an address, function & segment
This illustrates the setting/retrieval of background colours using the IDC wrappers
In order to do so, we'll be assigning colors to specific ranges (item, function, or segment). Those will be persisted in the database.
APIs Used:
idc.CIC_FUNCidc.CIC_ITEMidc.CIC_SEGMidc.get_coloridc.hereidc.set_color
Override the default "Functions" chooser colors
Color the function in the Function window according to its size. The larger the function, the darker the color.
The key, is overriding ida_kernwin.UI_Hooks.get_chooser_item_attrs
APIs Used:
ida_funcs.get_funcida_kernwin.UI_Hooksida_kernwin.enable_chooser_item_attrs
Create a dockable container, and populate it with Qt widgets
Using ida_kernwin.PluginForm.FormToPyQtWidget, this script converts IDA's own dockable widget into a type that is recognized by PyQt5, which then enables populating it with regular Qt widgets.
APIs Used:
ida_kernwin.PluginForm
Prevent an action from being triggered
Using ida_kernwin.UI_Hooks.preprocess_action, it is possible to respond to a command instead of the action that would otherwise do it.
APIs Used:
ida_kernwin.UI_Hooks
Use timers for delayed execution
Register (possibly repeating) timers.
APIs Used:
ida_kernwin.register_timer
Show, update & hide the progress dialog
Using the progress dialog (aka 'wait box') primitives.
APIs Used:
ida_hexrays.decompileida_kernwin.hide_wait_boxida_kernwin.replace_wait_boxida_kernwin.show_wait_boxida_kernwin.user_cancelledidautils.Functions
Custom actions, with icons & tooltips
How to create user actions, that once created can be inserted in menus, toolbars, context menus, ...
Those actions, when triggered, will be passed a 'context' that contains some of the most frequently needed bits of information.
In addition, custom actions can determine when they want to be available (through their ida_kernwin.action_handler_t.update callback)
APIs Used:
ida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.SETMENU_APPida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_menuida_kernwin.attach_action_to_popupida_kernwin.attach_action_to_toolbarida_kernwin.get_widget_typeida_kernwin.load_custom_iconida_kernwin.register_actionida_kernwin.unregister_action
Show tabular data
Shows how to subclass the ida_kernwin.Choose class to show data organized in a simple table. In addition, registers a couple actions that can be applied to it.
APIs Used:
ChooseChoose.ALL_CHANGEDChoose.CH_CAN_DELChoose.CH_CAN_EDITChoose.CH_CAN_INSChoose.CH_CAN_REFRESHChoose.CH_RESTOREChoose.NOTHING_CHANGEDida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.is_chooser_widgetida_kernwin.register_actionida_kernwin.unregister_action
Show tabular data, with multiple selection
Similar to choose, but with multiple selection
APIs Used:
ChooseChoose.ALL_CHANGEDChoose.CHCOL_HEXChoose.CH_MULTIChoose.NOTHING_CHANGED
Create custom listings in IDA
How to create simple listings, that will share many of the features as the built-in IDA widgets (highlighting, copy & paste, notifications, ...)
In addition, creates actions that will be bound to the freshly-created widget (using ida_kernwin.attach_action_to_popup.)
APIs Used:
ida_kernwin.AST_ENABLE_ALWAYSida_kernwin.IK_DELETEida_kernwin.IK_ESCAPEida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.ask_longida_kernwin.ask_strida_kernwin.attach_action_to_popupida_kernwin.register_actionida_kernwin.simplecustviewer_tida_kernwin.simplecustviewer_t.Createida_kernwin.simplecustviewer_t.Showida_kernwin.unregister_actionida_lines.COLOR_DEFAULTida_lines.COLOR_DNAMEida_lines.COLSTRida_lines.SCOLOR_PREFIXida_lines.SCOLOR_VOIDOP
Implement an alternative "Functions" window
Partially re-implements the "Functions" widget present in IDA, with a custom widget.
APIs Used:
ida_funcs.get_func_nameida_kernwin.Chooseida_kernwin.Choose.ALL_CHANGEDida_kernwin.Choose.CHCOL_FNAMEida_kernwin.Choose.CHCOL_HEXida_kernwin.Choose.CHCOL_PLAINida_kernwin.get_icon_id_by_nameidautils.Functionsidc.del_func
Implement a "jump to next comment" action within IDA's listing
We want our action not only to find the next line containing a comment, but to also place the cursor at the right horizontal position.
To find that position, we will have to inspect the text that IDA generates, looking for the start of a comment. However, we won't be looking for a comment "prefix" (e.g., "; "), as that would be too fragile.
Instead, we will look for special "tags" that IDA injects into textual lines, and that bear semantic information.
Those tags are primarily used for rendering (i.e., switching colors), but can also be very handy for spotting tokens of interest (registers, addresses, comments, prefixes, instruction mnemonics, ...)
APIs Used:
ida_bytes.next_headida_idaapi.BADADDRida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.CVNF_LAZYida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.custom_viewer_jumpida_kernwin.get_custom_viewer_locationida_kernwin.place_t_as_idaplace_tida_kernwin.register_actionida_kernwin.unregister_actionida_lines.SCOLOR_AUTOCMTida_lines.SCOLOR_ONida_lines.SCOLOR_REGCMTida_lines.SCOLOR_RPTCMTida_lines.generate_disassemblyida_lines.tag_strlenida_moves.lochist_entry_t
Dynamically colorize [parts of] lines
Shows how one can dynamically alter the lines background rendering (as opposed to, say, using ida_nalt.set_item_color()), and also shows how that rendering can be limited to just a few glyphs, not the whole line.
APIs Used:
ida_bytes.next_headida_idaapi.BADADDRida_kernwin.CK_EXTRA1ida_kernwin.CK_EXTRA10ida_kernwin.CK_EXTRA11ida_kernwin.CK_EXTRA12ida_kernwin.CK_EXTRA13ida_kernwin.CK_EXTRA14ida_kernwin.CK_EXTRA15ida_kernwin.CK_EXTRA16ida_kernwin.CK_EXTRA2ida_kernwin.CK_EXTRA3ida_kernwin.CK_EXTRA4ida_kernwin.CK_EXTRA5ida_kernwin.CK_EXTRA6ida_kernwin.CK_EXTRA7ida_kernwin.CK_EXTRA8ida_kernwin.CK_EXTRA9ida_kernwin.CK_TRACEida_kernwin.CK_TRACE_OVLida_kernwin.LROEF_CPS_RANGEida_kernwin.UI_Hooksida_kernwin.get_screen_eaida_kernwin.line_rendering_output_entry_tida_kernwin.refresh_idaview_anyway
React to UI events/notifications
Hooks to be notified about certain UI events, and dump their information to the "Output" window
APIs Used:
ida_kernwin.UI_Hooks
Paint on top of the navigation band
Using an "event filter", we will intercept paint events targeted at the navigation band widget, let it paint itself, and then add our own markers on top.
APIs Used:
ida_kernwin.PluginForm.FormToPyQtWidgetida_kernwin.get_navband_pixelida_kernwin.open_navband_windowida_segment.get_segm_qtyida_segment.getnsegidc.here
Save, and then restore, positions in a listing
Shows how it is possible re-implement IDA's bookmark capability, using 2 custom actions: one action saves the current location, and the other restores it.
Note that, contrary to actual bookmarks, this example:
remembers only 1 saved position
doesn't save that position in the IDB (and therefore cannot be restored if IDA is closed & reopened.)
APIs Used:
ida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_CUSTVIEWida_kernwin.BWN_DISASMida_kernwin.BWN_PSEUDOCODEida_kernwin.BWN_TILVIEWida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.custom_viewer_jumpida_kernwin.find_widgetida_kernwin.get_custom_viewer_locationida_kernwin.register_actionida_kernwin.unregister_actionida_moves.lochist_entry_t
Retrieve the selection from the "Strings" window
In IDA it's possible to write actions that can be applied even to core (i.e., "standard") widgets. The actions in this example use the action "context" to know what the current selection is.
This example shows how you can either retrieve string literals data directly from the chooser (ida_kernwin.get_chooser_data), or by querying the IDB (ida_bytes.get_strlit_contents)
APIs Used:
ida_bytes.get_strlit_contentsida_idaapi.BADADDRida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_STRINGSida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.find_widgetida_kernwin.get_chooser_dataida_kernwin.open_strings_windowida_kernwin.register_actionida_kernwin.unregister_actionida_strlist.get_strlist_itemida_strlist.string_info_t
Follow the movements of one graph, in another
Since it is possible to be notified of movements that happen take place in a widget, it's possible to "replay" those movements in another.
In this case, "IDA View-B" (will be opened if necessary) will show the same contents as "IDA View-A", slightly zoomed out.
APIs Used:
ida_graph.GLICTL_CENTERida_graph.viewer_fit_windowida_graph.viewer_get_gliida_graph.viewer_set_gliida_kernwin.DP_RIGHTida_kernwin.IDAViewWrapperida_kernwin.MFF_FASTida_kernwin.TCCRT_GRAPHida_kernwin.execute_syncida_kernwin.find_widgetida_kernwin.get_custom_viewer_placeida_kernwin.jumptoida_kernwin.open_disasm_windowida_kernwin.set_dock_posida_kernwin.set_view_renderer_typeida_moves.graph_location_info_t
Trigger actions programmatically
It's possible to invoke any action programmatically, by using either of those two:
ida_kernwin.execute_ui_requests()
ida_kernwin.process_ui_action()
Ideally, this script should be run through the "File > Script file..." menu, so as to keep focus on "IDA View-A" and have the 'ProcessUiActions' part work as intended.
APIs Used:
ida_kernwin.ask_ynida_kernwin.execute_ui_requestsida_kernwin.msgida_kernwin.process_ui_action
Advanced usage of the form API
How to query for complex user input, using IDA's built-in forms.
Note: while this example produces full-fledged forms for complex input, simpler types of inputs might can be retrieved by using ida_kernwin.ask_str and similar functions.
APIs Used:
ida_kernwin.Chooseida_kernwin.Choose.CH_MULTIida_kernwin.Formida_kernwin.PluginForm.FORM_TABida_kernwin.ask_str
Restore custom widgets across sessions
This is an example demonstrating how one can create widgets from a plugin, and have them re-created automatically at IDA startup-time or at desktop load-time.
This example should be placed in the 'plugins' directory of the IDA installation, for it to work.
There are 2 ways to use this example:
reloading an IDB, where the widget was opened
open the widget ('View > Open subview > ...')
save this IDB, and close IDA
restart IDA with this IDB => the widget will be visible
reloading a desktop, where the widget was opened
open the widget ('View > Open subview > ...')
save the desktop ('Windows > Save desktop...') under, say, the name 'with_auto'
start another IDA instance with some IDB, and load that desktop => the widget will be visible
APIs Used:
ida_idaapi.plugin_tida_kernwin.AST_ENABLE_ALWAYSida_kernwin.SETMENU_APPida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_menuida_kernwin.find_widgetida_kernwin.register_actionida_kernwin.simplecustviewer_tida_kernwin.simplecustviewer_t.Create
Showing tabular data in a flat, or tree-like fashion
By adding the necessary bits to a ida_kernwin.Choose subclass, IDA can show the otherwise tabular data, in a tree-like fashion.
The important bits to enable this are:
ida_dirtree.dirspec_t (and my_dirspec_t)
ida_kernwin.CH_HAS_DIRTREE
ida_kernwin.Choose.OnGetDirTree
ida_kernwin.Choose.OnIndexToInode
APIs Used:
ida_dirtree.DTE_OKida_dirtree.direntry_tida_dirtree.direntry_t.BADIDXida_dirtree.dirspec_tida_dirtree.dirtree_tida_dirtree.dirtree_t.isdirida_kernwin.CH_CAN_DELida_kernwin.CH_CAN_EDITida_kernwin.CH_CAN_INSida_kernwin.CH_HAS_DIRTREEida_kernwin.CH_MULTIida_kernwin.Chooseida_kernwin.Choose.ALL_CHANGEDida_kernwin.Choose.CHCOL_DRAGHINTida_kernwin.Choose.CHCOL_INODENAMEida_kernwin.Choose.CHCOL_PLAINida_kernwin.ask_strida_netnode.BADNODEida_netnode.netnode
Colorize lines interactively
This builds upon the ida_kernwin.UI_Hooks.get_lines_rendering_info feature, to provide a quick & easy way to colorize disassembly lines.
Contrary to @colorize_disassembly, the coloring is not persisted in the database, and will therefore be lost after the session.
By triggering the action multiple times, the user can "carousel" across 4 predefined colors (and return to the "no color" state.)
APIs Used:
ida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.CK_EXTRA5ida_kernwin.CK_EXTRA6ida_kernwin.CK_EXTRA7ida_kernwin.CK_EXTRA8ida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_current_viewerida_kernwin.get_custom_viewer_locationida_kernwin.get_custom_viewer_place_xcoordida_kernwin.get_widget_titleida_kernwin.line_rendering_output_entry_tida_kernwin.register_actionida_moves.lochist_entry_t
Add a custom command-line interpreter
Illustrates how one can add command-line interpreters to IDA
This custom interpreter doesn't actually run any code; it's there as a 'getting started'. It provides an example tab completion support.
APIs Used:
ida_idaapi.NW_CLOSEIDBida_idaapi.NW_OPENIDBida_idaapi.NW_REMOVEida_idaapi.NW_TERMIDAida_idaapi.notify_whenida_kernwin.cli_t
Draw custom graphs
Showing custom graphs, using ida_graph.GraphViewer. In addition, show how to write actions that can be performed on those.
APIs Used:
ida_funcs.get_funcida_funcs.get_func_nameida_graph.GraphViewerida_graph.get_graph_viewerida_graph.screen_graph_selection_tida_graph.viewer_get_selectionida_idp.is_call_insnida_kernwin.AST_ENABLE_ALWAYSida_kernwin.View_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_dynamic_action_to_popupida_kernwin.get_screen_eaida_ua.decode_insnida_ua.insn_tida_xref.XREF_FARida_xref.xrefblk_t
Retrieve & dump current selection
Shows how to retrieve the selection from a listing widget ("IDA View-A", "Hex View-1", "Pseudocode-A", ...) as two "cursors", and from there retrieve (in fact, generate) the corresponding text.
After running this script:
select some text in one of the listing widgets (i.e., "IDA View-...", "Local Types", "Pseudocode-...")
press Ctrl+Shift+S to dump the selection
APIs Used:
ida_kernwin.ACF_HAS_SELECTIONida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.BWN_PSEUDOCODEida_kernwin.BWN_TILVIEWida_kernwin.IWID_ANY_LISTINGida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_last_widgetida_kernwin.get_viewer_user_dataida_kernwin.l_compare2ida_kernwin.linearray_tida_kernwin.read_selectionida_kernwin.register_actionida_kernwin.twinpos_tida_kernwin.unregister_actionida_lines.tag_remove
Inject commands in the "Output" window
This example illustrates how one can execute commands in the "Output" window, from their own widgets.
A few notes:
the original, underlying
cli:Executeaction, that has to be triggered for the code present in the input field to execute and be placed in the history, requires that the input field has focus (otherwise it simply won't do anything.)this, in turn, forces us to do "delayed" execution of that action, hence the need for a
QTimerthe IDA/SWiG 'TWidget' type that we retrieve through
ida_kernwin.find_widget, is not the same type as aQtWidgets.QWidget. We therefore need to convert it usingida_kernwin.PluginForm.TWidgetToPyQtWidget
APIs Used:
ida_kernwin.PluginForm.TWidgetToPyQtWidgetida_kernwin.disabled_script_timeout_tida_kernwin.find_widgetida_kernwin.process_ui_action
A lazy-loaded, tree-like data view
Brings lazy-loading of folders to the tree-like tabular views.
The important bit to enable this are:
ida_kernwin.Choose.OnLazyLoadDir
Paint text on graph view edges
This sample registers an action enabling painting of a recognizable string of text over horizontal nodes edge sections beyond a satisfying size threshold.
In a disassembly view, open the context menu and select "Paint on edges". This should work for both graph disassembly, and proximity browser.
Using an "event filter", we will intercept paint events targeted at the disassembly view, let it paint itself, and then add our own markers along.
APIs Used:
ida_gdl.edge_tida_graph.get_graph_viewerida_graph.get_viewer_graphida_graph.point_tida_graph.viewer_get_gliida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.PluginForm.FormToPyQtWidgetida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.get_widget_typeida_kernwin.register_actionida_moves.graph_location_info_t
Programmatically manipulate disassembly and graph widgets
This is an example illustrating how to manipulate an existing IDA-provided view (and thus possibly its graph), in Python.
APIs Used:
ida_graph.NIF_BG_COLORida_graph.NIF_FRAME_COLORida_graph.node_info_tida_kernwin.IDAViewWrapperida_kernwin.MFF_FASTida_kernwin.TCCRT_FLATida_kernwin.TCCRT_GRAPHida_kernwin.execute_sync
Dump function flowchart
Dumps the current function's flowchart, using 2 methods:
the low-level
ida_gdl.qflow_chart_ttypethe somewhat higher-level, and slightly more pythonic
ida_gdl.FlowCharttype.
APIs Used:
ida_funcs.get_funcida_gdl.FlowChartida_gdl.qflow_chart_tida_kernwin.get_screen_ea
Insert information into listing prefixes
By default, disassembly line prefixes contain segment + address information (e.g., '.text:08047718'), but it is possible to "inject" other bits of information in there, thanks to the ida_lines.user_defined_prefix_t helper type.
APIs Used:
ida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_lines.SCOLOR_INVida_lines.user_defined_prefix_t
Enumerate file imports
Using the API to enumerate file imports.
APIs Used:
ida_nalt.enum_import_namesida_nalt.get_import_module_nameida_nalt.get_import_module_qty
Enumerate patched bytes
Using the API to iterate over all the places in the file, that were patched using IDA.
APIs Used:
ida_bytes.visit_patched_bytesida_idaapi.BADADDR
Enumerate known problems
Using the API to list all problems that IDA encountered during analysis.
APIs Used:
ida_ida.inf_get_min_eaida_idaapi.BADADDRida_problems.PR_ATTNida_problems.PR_BADSTACKida_problems.PR_COLLISIONida_problems.PR_DECIMPida_problems.PR_DISASMida_problems.PR_FINALida_problems.PR_HEADida_problems.PR_ILLADDRida_problems.PR_JUMPida_problems.PR_MANYLINESida_problems.PR_NOBASEida_problems.PR_NOCMTida_problems.PR_NOFOPida_problems.PR_NONAMEida_problems.PR_NOXREFSida_problems.PR_ROLLEDida_problems.get_problemida_problems.get_problem_name
List segment functions (and cross-references to them)
List all the functions in the current segment, as well as all the cross-references to them.
APIs Used:
ida_funcs.get_funcida_funcs.get_func_nameida_funcs.get_next_funcida_kernwin.get_screen_eaida_segment.getsegida_xref.xrefblk_t
List all functions (and cross-references) in segment
List all the functions in the current segment, as well as all the cross-references to them.
Contrary to @list_segment_functions, this uses the somewhat higher-level idautils module.
APIs Used:
ida_funcs.get_func_nameida_idaapi.BADADDRida_kernwin.get_screen_eaida_segment.getsegidautils.CodeRefsToidautils.Functions
Dump the strings that are present in the file
This uses idautils.Strings to iterate over the string literals that are present in the IDB. Contrary to @show_selected_strings, this will not require that the "Strings" window is opened & available.
APIs Used:
ida_nalt.STRTYPE_Cida_nalt.STRTYPE_C_16idautils.Strings
Produce disassembly listing for the entire file
Automate IDA to perform auto-analysis on a file and, once that is done, produce a .lst file with the disassembly.
Run like so:
where:
-A instructs IDA to run in non-interactive mode
-S holds a path to the script to run (note this is a single token; there is no space between '-S' and its path.)
APIs Used:
ida_auto.auto_waitida_fpro.qfile_tida_ida.inf_get_max_eaida_ida.inf_get_min_eaida_loader.OFILE_LSTida_loader.PATH_TYPE_IDBida_loader.gen_fileida_loader.get_pathida_pro.qexit
Rewrite the representation of some instructions
Implements disassembly of BUG_INSTR used in Linux kernel BUG() macro, which is architecturally undefined and is not disassembled by IDA's ARM module
See Linux/arch/arm/include/asm/bug.h for more info
APIs Used:
ida_bytes.get_wide_dwordida_bytes.get_wide_wordida_idp.CUSTOM_INSN_ITYPEida_idp.IDP_Hooksida_idp.PLFM_ARMida_idp.ph.idida_idp.str2regida_segregs.get_sreg
Implement assembly of instructions
We add support for assembling the following pseudo instructions:
"zero eax" -> xor eax, eax
"nothing" -> nop
APIs Used:
ida_idp.IDP_Hooksidautils.DecodeInstruction
Retrieve comments surrounding instructions
Use the ida_lines.get_extra_cmt API to retrieve anterior and posterior extra comments.
This script registers two actions, that can be used to dump the previous and next extra comments.
APIs Used:
ida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.find_widgetida_kernwin.get_screen_eaida_kernwin.register_actionida_kernwin.unregister_actionida_lines.E_NEXTida_lines.E_PREVida_lines.get_extra_cmtida_view
Dump function information
Dump some of the most interesting bits of information about the function we are currently looking at.
APIs Used:
ida_funcs.FUNC_FRAMEida_funcs.FUNC_LUMINAida_funcs.FUNC_OUTLINEida_funcs.FUNC_THUNKida_funcs.get_fchunkida_funcs.is_func_entryida_funcs.is_func_tailida_kernwin.get_screen_ea
Using "ida_bytes.find_string"
IDAPython's ida_bytes.find_string can be used to implement a simple replacement for the 'Search > Sequence of bytes...' dialog, that lets users search for sequences of bytes that compose string literals in the binary file (either in the default 1-byte-per-char encoding, or as UTF-16.)
APIs Used:
ida_bytes.BIN_SEARCH_FORWARDida_bytes.BIN_SEARCH_NOBREAKida_bytes.BIN_SEARCH_NOSHOWida_bytes.find_stringida_ida.inf_get_max_eaida_idaapi.BADADDRida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.Formida_kernwin.Form.ChkGroupControlida_kernwin.Form.StringInputida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_screen_eaida_kernwin.jumptoida_kernwin.register_actionida_nalt.BPU_1Bida_nalt.BPU_2Bida_nalt.get_default_encoding_idx
Print notifications about function prototype changes
The goal of this script is to demonstrate some usage of the type API. In this script, we will create an IDB hook that intercepts ti_changed IDB events, and if it is a function prototype that changed, print it.
APIs Used:
ida_funcs.get_func_nameida_idp.IDB_Hooksida_typeinf.tinfo_t
List listing bookmarks
This sample shows how to programmatically access the list of bookmarks placed in a listing widget (e.g., "IDA View-A", "Pseudocode-", …) using the low-level ida_moves.bookmarks_t type.
APIs Used:
ida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_current_viewerida_kernwin.get_viewer_user_dataida_kernwin.get_widget_titleida_kernwin.register_actionida_moves.bookmarks_t
Showcase (some of) the iterators available on a function
This demonstrates how to use some of the iterators available on the func_t type.
This example will focus on:
func_t[.__iter__]: the default iterator; iterates on instructionsfunc_t.data_items: iterate on data items contained within a functionfunc_t.head_items: iterate on 'heads' (i.e., addresses containing the start of an instruction, or a data item.func_t.addresses: iterate on all addresses within function (code and data, beginning of an item or not)
Type help(ida_funcs.func_t) for a full list of iterators.
In addition, one can use:
func_tail_iterator_t: iterate on all the chunks (including the main one) of the functionfunc_parent_iterator_t: iterate on all the parent functions, that include this chunk
APIs Used:
ida_bytes.get_flagsida_bytes.is_codeida_bytes.is_dataida_bytes.is_tailida_bytes.is_unknownida_funcs.func_tail_iterator_tida_funcs.get_fchunkida_funcs.get_funcida_funcs.get_func_nameida_kernwin.get_screen_eaida_ua.print_insn_mnem
React to database events/notifications
These hooks will be notified about IDB events, and dump their information to the "Output" window
APIs Used:
ida_idp.IDB_Hooks
React to processor events/notifications
These hooks will be notified about IDP events, and dump their information to the "Output" window
APIs Used:
ida_idp.IDP_Hooks
Record and replay changes in function prototypes
This is a sample script, that will record (in memory) all changes in functions prototypes, in order to re-apply them later.
To use this script:
open an IDB (say, "test.idb")
modify some functions prototypes (e.g., by triggering the 'Y' shortcut when the cursor is placed on the first address of a function)
reload that IDB, without saving it first
call rpc.replay(), to re-apply the modifications.
Note: 'ti_changed' is also called for changes to the function frames, but we'll only record function prototypes changes.
APIs Used:
ida_funcs.get_funcida_idp.IDB_Hooksida_typeinf.PRTYPE_1LINEida_typeinf.TINFO_DEFINITEida_typeinf.apply_tinfoida_typeinf.get_idatiida_typeinf.tinfo_t
Add a new member to an existing function frame
The goal of this script is to demonstrate some usage of the type API. In this script, we show a way to add a new frame member (a pointer to an uint64) inside a wide enough gap in the frame:
Get the function object surrounding cursor location.
Use this function to retrieve the corresponding frame object.
Find a wide enough gap to create our new member.
If found, we use cal_frame_offset() to get the actual offset in the frame structure.
Use the previous result to add the new member.
APIs Used:
ida_frame.add_frame_memberida_frame.calc_frame_offsetida_frame.get_func_frameida_funcs.get_funcida_range.rangeset_tida_typeinf.BTF_UINT64ida_typeinf.tinfo_tidc.here
Custom data types & printers
IDA can be extended to support certain data types that it does not know about out-of-the-box.
A 'custom data type' provide information about the type & size of a piece of data, while a 'custom data format' is in charge of formatting that data (there can be more than one format for a specific 'custom data type'.)
APIs Used:
ida_bytes.data_format_tida_bytes.data_type_tida_bytes.find_custom_data_typeida_bytes.get_byteida_bytes.register_data_types_and_formatsida_bytes.unregister_data_types_and_formatsida_idaapi.NW_CLOSEIDBida_idaapi.NW_OPENIDBida_idaapi.NW_REMOVEida_idaapi.NW_TERMIDAida_idaapi.notify_whenida_idaapi.struct_unpackida_lines.COLSTRida_lines.SCOLOR_IMPNAMEida_lines.SCOLOR_INSNida_lines.SCOLOR_NUMBERida_lines.SCOLOR_REGida_nalt.get_input_file_pathida_netnode.netnodeida_typeinf.tinfo_t
List operands representing a "path" to a (possibly nested) structure member
It is possible to assign, to instruction operands, the notion of "structure offset", which really is a pointer to a specific offset in a type, leading to a possible N-deep path within types.
E.g., assuming the following types
and assuming an instruction that initially looks like this:
by pressing t, the user will be able set the "structure offset" to either:
c.trailb.c_instance.quuxa.b_inscance.c_instance.baz
Here's why IDA offers a.b_inscance.c_instance.baz:
This sample shows how to programmatically retrieve information about that "structure member path" that an operand was made pointing to.
APIs Used:
ida_bytes.get_full_flagsida_bytes.get_stroff_pathida_bytes.is_stroffida_typeinf.get_tid_nameida_typeinf.tinfo_tida_ua.decode_insnida_ua.insn_tida_ua.o_immida_ua.o_void
Notify the user when an instruction operand changes
Show notifications whenever the user changes an instruction's operand, or a data item.
APIs Used:
ida_bytes.ALOPT_IGNCLTida_bytes.ALOPT_IGNHEADSida_bytes.get_flagsida_bytes.get_max_strlit_lengthida_bytes.get_opinfoida_bytes.get_strlit_contentsida_bytes.is_custfmtida_bytes.is_customida_bytes.is_enumida_bytes.is_offida_bytes.is_strlitida_bytes.is_stroffida_bytes.is_structida_idp.IDB_Hooksida_nalt.STRENC_DEFAULTida_nalt.get_default_encoding_idxida_nalt.get_encoding_nameida_nalt.get_str_encoding_idxida_nalt.get_strtype_bpuida_nalt.opinfo_tida_typeinf.get_tid_nameida_typeinf.tinfo_t
Produce C listing for the entire file
Automate IDA to perform auto-analysis on a file and, once that is done, produce a .c file containing the decompilation of all the functions in that file.
Run like so:
where:
-A instructs IDA to run in non-interactive mode
-S holds a path to the script to run (note this is a single token; there is no space between '-S' and its path.)
APIs Used:
ida_auto.auto_waitida_hexrays.VDRUN_MAYSTOPida_hexrays.VDRUN_NEWFILEida_hexrays.VDRUN_SILENTida_hexrays.decompile_manyida_loader.PATH_TYPE_IDBida_loader.get_pathida_pro.qexit
Decompile & print current function
Decompile the function under the cursor
APIs Used:
ida_funcs.get_funcida_hexrays.decompileida_hexrays.get_hexrays_versionida_hexrays.init_hexrays_pluginida_kernwin.get_screen_eaida_lines.tag_remove
Generate microcode for the selected range of instructions
Generates microcode for selection and dumps it to the output window.
APIs Used:
ida_bytes.get_flagsida_bytes.is_codeida_hexrays.DECOMP_WARNINGSida_hexrays.gen_microcodeida_hexrays.hexrays_failure_tida_hexrays.init_hexrays_pluginida_hexrays.mba_ranges_tida_hexrays.vd_printer_tida_kernwin.read_range_selectionida_kernwin.warningida_range.range_t
Dump statement blocks
Using a ida_hexrays.ctree_visitor_t, search for ida_hexrays.cit_block instances and dump them.
APIs Used:
ida_hexrays.CMAT_BUILTida_hexrays.CV_FASTida_hexrays.Hexrays_Hooksida_hexrays.cit_blockida_hexrays.ctree_visitor_tida_hexrays.init_hexrays_plugin
Provide custom decompiler hints
Handle ida_hexrays.hxe_create_hint notification using hooks, to return our own.
If the object under the cursor is:
a function call, prefix the original decompiler hint with
==>a local variable declaration, replace the hint with our own in the form of
!{varname}(where{varname}is replaced with the variable name)an
ifstatement, replace the hint with our own, saying "condition"
APIs Used:
ida_hexrays.Hexrays_Hooksida_hexrays.USE_MOUSEida_hexrays.VDI_EXPRida_hexrays.VDI_LVARida_hexrays.cit_ifida_hexrays.cot_call
Interactively color decompilation lines
Provides an action that can be used to dynamically alter the lines background rendering for pseudocode listings (as opposed to using ida_hexrays.cfunc_t.pseudocode[N].bgcolor)
After running this script, pressing 'M' on a line in a "Pseudocode-?" widget, will cause that line to be rendered with a special background color.
APIs Used:
ida_hexrays.get_widget_vduiida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_PSEUDOCODEida_kernwin.CK_EXTRA11ida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_custom_viewer_locationida_kernwin.line_rendering_output_entry_tida_kernwin.refresh_custom_viewerida_kernwin.register_actionida_moves.lochist_entry_t
Decompile entrypoint automatically
Attempts to load a decompiler plugin corresponding to the current architecture right after auto-analysis is performed, and then tries to decompile the function at the first entrypoint.
It is particularly suited for use with the '-S' flag, for example: idat -Ldecompile.log -Sdecompile_entry_points.py -c file
APIs Used:
ida_auto.auto_waitida_entry.get_entryida_entry.get_entry_ordinalida_entry.get_entry_qtyida_hexrays.decompileida_hexrays.init_hexrays_pluginida_idp.PLFM_386ida_idp.PLFM_ARMida_idp.PLFM_MIPSida_idp.PLFM_PPCida_idp.PLFM_RISCVida_idp.ph.idida_kernwin.cvar.batchida_kernwin.msgida_loader.load_pluginida_pro.qexitidc.get_idb_path
Add custom microcode instruction optimization rule
Installs a custom microcode instruction optimization rule, to transform:
into
To see this plugin in action please use arm64_brk.i64
APIs Used:
ida_bytes.get_cmtida_hexrays.init_hexrays_pluginida_hexrays.mop_strida_hexrays.optinsn_tida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_typeinf.STI_PCCHARida_typeinf.tinfo_t.get_stock
Dynamically provide a custom call type
This plugin can greatly improve decompilation of indirect calls:
For them, the decompiler has to guess the prototype of the called function. This has to be done at a very early phase of decompilation because the function prototype influences the data flow analysis. On the other hand, we do not have global data flow analysis results yet because we haven't analyzed all calls in the function. It is a chicked-and-egg problem.
The decompiler uses various techniques to guess the called function prototype. While it works very well, it may fail in some cases.
To fix, the user can specify the call prototype manually, using "Edit, Operand types, Set operand type" at the call instruction.
This plugin illustrates another approach to the problem: if you happen to be able to calculate the call prototypes dynamically, this is how to inform the decompiler about them.
APIs Used:
ida_hexrays.Hexrays_Hooksida_hexrays.init_hexrays_pluginida_hexrays.m_callida_hexrays.mcallinfo_tida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_kernwin.msgida_kernwin.warningida_nalt.get_op_tinfoida_typeinf.BT_INTida_typeinf.CM_CC_STDCALLida_typeinf.CM_N32_F48ida_typeinf.parse_declida_typeinf.tinfo_t
Dump user-defined information for a function
Prints user-defined information to the "Output" window. Namely:
user defined label names
user defined indented comments
user defined number formats
user defined local variable names, types, comments
This script loads information from the database without decompiling anything.
APIs Used:
ida_bytes.get_radixida_funcs.get_funcida_hexrays.CIT_COLLAPSEDida_hexrays.NF_NEGATEida_hexrays.init_hexrays_pluginida_hexrays.lvar_uservec_tida_hexrays.restore_user_cmtsida_hexrays.restore_user_iflagsida_hexrays.restore_user_labelsida_hexrays.restore_user_lvar_settingsida_hexrays.restore_user_numformsida_hexrays.user_cmts_freeida_hexrays.user_iflags_freeida_hexrays.user_labels_freeida_hexrays.user_numforms_freeida_kernwin.get_screen_ea
Superficially modify the decompilation output
Modifies the decompilation output in a superficial manner, by removing some white spaces
Note: this is rather crude, not quite "pythonic" code.
APIs Used:
ida_hexrays.Hexrays_Hooksida_hexrays.init_hexrays_pluginida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_lines.tag_advanceida_lines.tag_skipcodes
Improve decompilation by turning specific patterns into custom function calls
Registers an action that uses a ida_hexrays.udc_filter_t to decompile svc 0x900001 and svc 0x9000F8 as function calls to svc_exit() and svc_exit_group() respectively.
You will need to have an ARM + Linux IDB for this script to be usable
In addition to having a shortcut, the action will be present in the context menu.
APIs Used:
ida_allins.ARM_svcida_hexrays.get_widget_vduiida_hexrays.init_hexrays_pluginida_hexrays.install_microcode_filterida_hexrays.udc_filter_tida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_PSEUDOCODEida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.get_widget_typeida_kernwin.register_action
React to decompiler events/notifications
Shows how to hook to many notifications sent by the decompiler.
This plugin doesn't really accomplish anything: it just prints the parameters.
The list of notifications handled below should be exhaustive, and is there to hint at what is possible to accomplish by subclassing ida_hexrays.Hexrays_Hooks
APIs Used:
ida_hexrays.Hexrays_Hooksida_hexrays.cfunc_tida_hexrays.lvar_tida_hexrays.vdui_t
Modifying function local variables
Use a ida_hexrays.user_lvar_modifier_t to modify names, comments and/or types of local variables.
APIs Used:
ida_hexrays.modify_user_lvarsida_hexrays.user_lvar_modifier_tida_typeinf.parse_declidc.here
Print information about the current position in decompilation
Shows how user input information can be retrieved during processing of a notification triggered by that input
APIs Used:
ida_hexrays.Hexrays_Hooksida_kernwin.get_user_input_eventida_kernwin.iek_key_pressida_kernwin.iek_key_releaseida_kernwin.iek_mouse_button_pressida_kernwin.iek_mouse_button_releaseida_kernwin.iek_mouse_wheelida_kernwin.iek_shortcutida_kernwin.input_event_t
Add a custom microcode block optimization rule
Installs a custom microcode block optimization rule, to transform:
into
In other words we fix a goto target if it points to a chain of gotos. This improves the decompiler output in some cases.
APIs Used:
ida_hexrays.getf_reginsnida_hexrays.init_hexrays_pluginida_hexrays.m_gotoida_hexrays.optblock_tida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_t
List instruction registers
Shows a list of direct references to a register from the current instruction.
APIs Used:
ida_bytes.get_flagsida_bytes.is_codeida_funcs.get_funcida_hexrays.ACFL_GUESSida_hexrays.DECOMP_NO_CACHEida_hexrays.DECOMP_WARNINGSida_hexrays.GCO_DEFida_hexrays.GCO_USEida_hexrays.GC_REGS_AND_STKVARSida_hexrays.MERR_OKida_hexrays.MMAT_PREOPTIMIZEDida_hexrays.MUST_ACCESSida_hexrays.gco_info_tida_hexrays.gen_microcodeida_hexrays.get_current_operandida_hexrays.get_merror_descida_hexrays.hexrays_failure_tida_hexrays.init_hexrays_pluginida_hexrays.mba_ranges_tida_hexrays.mlist_tida_hexrays.op_parent_info_tida_hexrays.voff_tida_kernwin.Chooseida_kernwin.get_screen_eaida_kernwin.jumptoida_kernwin.warningida_lines.GENDSM_REMOVE_TAGSida_lines.generate_disasm_lineida_pro.eavec_t
Invoke the structure offset-choosing dialog from decompilation
Registers an action opens the "Select offsets" widget (select_udt_by_offset() call).
This effectively repeats the functionality already available through Alt+Y.
Place cursor on the union field and press Shift+T
APIs Used:
ida_hexrays.USE_KEYBOARDida_hexrays.cot_addida_hexrays.cot_castida_hexrays.cot_memptrida_hexrays.cot_memrefida_hexrays.cot_numida_hexrays.cot_refida_hexrays.get_hexrays_versionida_hexrays.get_widget_vduiida_hexrays.init_hexrays_pluginida_hexrays.select_udt_by_offsetida_hexrays.ui_stroff_applicator_tida_hexrays.ui_stroff_ops_tida_idaapi.BADADDRida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_PSEUDOCODEida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_custom_viewer_curlineida_kernwin.msgida_kernwin.register_actionida_kernwin.warningida_lines.tag_removeida_typeinf.PRTYPE_1LINEida_typeinf.print_tinfoida_typeinf.remove_pointer
Add a custom microcode instruction optimization rule
Installs a custom microcode instruction optimization rule, to transform:
into
To see this plugin in action please use be_ornot_be.idb
APIs Used:
ida_hexrays.init_hexrays_pluginida_hexrays.m_bnotida_hexrays.m_movida_hexrays.m_orida_hexrays.minsn_visitor_tida_hexrays.mop_tida_hexrays.optinsn_tida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_t
Invert if/else blocks in decompilation
Registers an action that can be used to invert the if and else blocks of a ida_hexrays.cif_t.
For example, a statement like
will be displayed as
The modifications are persistent: the user can quit & restart IDA, and the changes will be present.
APIs Used:
ida_hexrays.CMAT_FINALida_hexrays.CV_FASTida_hexrays.CV_INSNSida_hexrays.Hexrays_Hooksida_hexrays.ITP_ELSEida_hexrays.USE_KEYBOARDida_hexrays.VDI_TAILida_hexrays.cexpr_tida_hexrays.cit_ifida_hexrays.ctree_visitor_tida_hexrays.get_widget_vduiida_hexrays.init_hexrays_pluginida_hexrays.lnotida_hexrays.qswapida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_idp.IDP_Hooksida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_PSEUDOCODEida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.register_actionida_netnode.netnode
Dump C-tree graph
Registers an action that can be used to show the graph of the ctree. The current item will be highlighted in the graph.
The command shortcut is Ctrl+Shift+G, and is also added to the context menu.
To display the graph, we produce a .gdl file, and request that ida displays that using ida_gdl.display_gdl.
APIs Used:
ida_gdl.display_gdlida_hexrays.Hexrays_Hooksida_hexrays.USE_KEYBOARDida_hexrays.cit_asmida_hexrays.cit_gotoida_hexrays.cot_helperida_hexrays.cot_memptrida_hexrays.cot_memrefida_hexrays.cot_numida_hexrays.cot_objida_hexrays.cot_ptrida_hexrays.cot_strida_hexrays.cot_varida_hexrays.ctree_parentee_tida_hexrays.get_ctype_nameida_hexrays.get_widget_vduiida_hexrays.init_hexrays_pluginida_idaapi.PLUGIN_HIDEida_idaapi.PLUGIN_KEEPida_idaapi.plugin_tida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_PSEUDOCODEida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.register_actionida_kernwin.warningida_lines.tag_removeida_pro.str2user
Show decompiler cross-references
Show decompiler-style Xref when the Ctrl+X key is pressed in the Decompiler window.
supports any global name: functions, strings, integers, ...
supports structure member.
APIs Used:
ida_funcs.get_func_nameida_hexrays.DECOMP_GXREFS_FORCEida_hexrays.Hexrays_Hooksida_hexrays.USE_KEYBOARDida_hexrays.VDI_EXPRida_hexrays.VDI_FUNCida_hexrays.cexpr_tida_hexrays.cfunc_tida_hexrays.cinsn_tida_hexrays.decompileida_hexrays.get_widget_vduiida_hexrays.init_hexrays_pluginida_hexrays.open_pseudocodeida_hexrays.qstring_printer_tida_idaapi.BADADDRida_kernwin.AST_DISABLEida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLEida_kernwin.BWN_PSEUDOCODEida_kernwin.PluginFormida_kernwin.PluginForm.Showida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.register_actionida_typeinf.PRTYPE_1LINEida_typeinf.STRMEM_OFFSETida_typeinf.print_tinfoida_typeinf.tinfo_tida_typeinf.udm_tidautils.Functionsidautils.XrefsTo
Print all registers, for all threads in the debugged process
Iterate over the list of threads in the program being debugged, and dump all registers contents
To use this example:
run
ida64on test programsimple_appcall_linux64, oridaon test programsimple_appcall_linux32, and wait for auto-analysis to finishput a breakpoint somewhere in the code
select the 'linux debugger' (either local, or remote)
start debugging
Press Alt+Shift+C at the breakpoint
APIs Used:
ida_dbg.get_reg_valsida_dbg.get_thread_qtyida_dbg.getn_threadida_idd.get_dbgida_kernwin.AST_ENABLE_ALWAYSida_kernwin.action_desc_tida_kernwin.register_action
Dump symbols from a process being debugged
Queries the debugger (possibly remotely) for the list of symbols that the process being debugged, provides.
APIs Used:
ida_dbg.DSTATE_SUSPida_dbg.get_process_stateida_dbg.is_debugger_onida_ida.inf_get_max_eaida_ida.inf_get_min_eaida_name.get_debug_names
Print call stack
Print the return addresses from the call stack at a breakpoint, when debugging a Linux binary. (and also print the module and the debug name from debugger)
To use this example:
run
idaon test programsimple_appcall_linux64, oridaon test programsimple_appcall_linux32, and wait for auto-analysis to finishput a breakpoint where you want to see the call stack
select the 'linux debugger' (either local, or remote)
start debugging
Press Shift+C at the breakpoint
APIs Used:
ida_dbg.collect_stack_traceida_dbg.get_current_threadida_dbg.get_module_infoida_idd.call_stack_tida_idd.modinfo_tida_kernwin.AST_ENABLE_ALWAYSida_kernwin.action_desc_tida_kernwin.register_actionida_name.GNCN_NOCOLORida_name.GNCN_NOLABELida_name.GNCN_NOSEGida_name.GNCN_PREFDBGida_name.get_nice_colored_name
Add a custom action to the "registers" widget
It's possible to add actions to the context menu of pretty much all widgets in IDA.
This example shows how to do just that for registers-displaying widgets (e.g., "General registers")
APIs Used:
ida_dbg.get_dbg_reg_infoida_dbg.get_reg_valida_idd.register_info_tida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_CPUREGSida_kernwin.UI_Hooksida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.attach_action_to_popupida_kernwin.get_widget_typeida_kernwin.register_actionida_ua.dt_byteida_ua.dt_dwordida_ua.dt_qwordida_ua.dt_word
Programmatically drive a debugging session
Start a debugging session, step through the first five instructions. Each instruction is disassembled after execution.
APIs Used:
ida_dbg.DBG_Hooksida_dbg.get_reg_valida_dbg.request_exit_processida_dbg.request_run_toida_dbg.request_step_overida_dbg.run_requestsida_ida.inf_get_start_ipida_idaapi.BADADDRida_lines.generate_disasm_lineida_lines.tag_remove
React to trace notifications
This script demonstrates using the low-level tracing hook (ida_dbg.DBG_Hooks.dbg_trace). It can be run like so:
APIs Used:
GENDSM_FORCE_CODEGENDSM_REMOVE_TAGSNN_callNN_callfiNN_callnigenerate_disasm_lineida_dbg.DBG_Hooksida_dbg.ST_OVER_DEBUG_SEGida_dbg.ST_OVER_LIB_FUNCida_dbg.enable_step_traceida_dbg.get_process_stateida_dbg.get_reg_valida_dbg.get_step_trace_optionsida_dbg.load_debuggerida_dbg.refresh_debugger_memoryida_dbg.request_continue_processida_dbg.request_enable_step_traceida_dbg.request_set_step_trace_optionsida_dbg.run_requestsida_dbg.run_toida_dbg.set_step_trace_optionsida_dbg.wait_for_next_eventida_ida.f_ELFida_ida.f_MACHOida_ida.f_PEida_ida.inf_get_filetypeida_ida.inf_get_max_eaida_ida.inf_get_min_eaida_ida.inf_get_start_ipida_pro.qexitida_ua.decode_insnida_ua.insn_tidc.ARGV
Execute code into the application being debugged (on Linux)
Using the ida_idd.Appcall utility to execute code in the process being debugged.
This example will run the test program and stop wherever the cursor currently is, and then perform an appcall to execute the ref4 and ref8 functions.
To use this example:
run
ida64on test programsimple_appcall_linux64, oridaon test programsimple_appcall_linux32, and wait for auto-analysis to finishselect the 'linux debugger' (either local, or remote)
run this script
Note: the real body of code is in simple_appcall_common.py.
APIs Used:
ida_dbg.DBG_Hooksida_dbg.run_toida_idaapi.BADADDRida_idd.Appcallida_idd.Appcall.byrefida_idd.Appcall.int64ida_kernwin.get_screen_eaida_name.get_name_eaida_name.set_nameida_typeinf.apply_cdecl
Execute code into the application being debugged (on Windows)
Using the ida_idd.Appcall utility to execute code in the process being debugged.
This example will run the test program and stop wherever the cursor currently is, and then perform an appcall to execute the ref4 and ref8 functions.
To use this example:
run
idaon test programsimple_appcall_win64.exe, oridaon test programsimple_appcall_win32.exe, and wait for auto-analysis to finishselect the 'windows debugger' (either local, or remote)
run this script
Note: the real body of code is in simple_appcall_common.py.
APIs Used:
ida_dbg.DBG_Hooksida_dbg.run_toida_ida.inf_is_64bitida_idaapi.BADADDRida_idd.Appcallida_idd.Appcall.byrefida_idd.Appcall.int64ida_kernwin.get_screen_eaida_name.get_name_eaida_name.set_nameida_typeinf.apply_cdecl
Create a structure by parsing its definition
The goal of this script is to demonstrate some usage of the type API. In this script, we create a structure using the "parsing" method.
APIs Used:
ida_typeinf.tinfo_t
Delete structure members that fall within an offset range
The goal of this script is to demonstrate some usage of the type API. In this script, we first create a structure with many members, and then remove all those that fall within a range.
APIs Used:
ida_typeinf.STRMEM_OFFSETida_typeinf.TERR_OKida_typeinf.tinfo_tida_typeinf.udm_t
Print enumeration members
In this example, we will first ask the user to provide the name of an enumeration, and then iterate on it
APIs Used:
ida_kernwin.ask_str
Print function stack frame information
The goal of this script is to demonstrate some usage of the type API. In this script, we retrieve the function frame structure, and iterate on the frame members.
APIs Used:
ida_funcs.get_funcida_kernwin.get_screen_ea
List database functions prototypes
This script demonstrates how to list a function return type along with its parameters types and name if any. We do this for all the functions found in the database.
APIs Used:
ida_funcs.get_funcidautils.Functions
List structure members
The goal of this script is to demonstrate some usage of the type API. In this script, we:
Ask the user for a structure name. It must already be present in the local types.
Retrieve the structure type info from the local type
Extract its type details (udt)
Iterates it members and prints their names.
APIs Used:
ida_kernwin.ask_strida_typeinf.BTF_STRUCTida_typeinf.get_idatiida_typeinf.tinfo_tida_typeinf.udt_type_data_t
List cross-references to a structure
The goal of this script is to demonstrate some usage of the type API. In this script, we:
Ask the user for a structure name. It must already be present in the local types.
Get its tid
Create the list of all the reference.
Print it
APIs Used:
ida_kernwin.choose_structida_typeinf.tinfo_tida_xref.xrefblk_t
List union members
The goal of this script is to demonstrate some usage of the type API. In this script, we:
Ask the user for a union name. It must already be present in the local types.
Retrieve the union type info from the local type
Extract its type details (udt)
Iterates it members and prints their names.
APIs Used:
ida_kernwin.ask_strida_typeinf.BTF_UNIONida_typeinf.get_idatiida_typeinf.tinfo_tida_typeinf.udt_type_data_t
Mark a register "spoiled" by a function
At least two possibilies are offered in order to indicate that a function spoils registers (excluding the "normal" ones):
You can either parse & apply a declaration:
or retrieve & modify the tinfo_t object directly.
This script showcases the latter.
APIs Used:
ida_funcs.get_funcida_idp.parse_reg_nameida_idp.reg_info_tida_kernwin.get_screen_eaida_nalt.get_tinfoida_typeinf.FTI_SPOILEDida_typeinf.TINFO_DEFINITEida_typeinf.apply_tinfoida_typeinf.func_type_data_tida_typeinf.tinfo_t
Apply function prototype to call sites
The goal of this script is to demonstrate some usage of the type API. In this script, we:
Open the private type libary.
Load its declaration in the type library by parsing its declaration and keep the return tuple for future use.
Deserialize the type info stored in the returned tuple.
Get the address of the function.
Get the address of the code reference to the function and apply the type info there.
APIs Used:
ida_idaapi.BADADDRida_name.get_name_eaida_typeinf.PT_REPLACEida_typeinf.apply_callee_tinfoida_typeinf.get_idatiida_typeinf.idc_parse_declida_typeinf.tinfo_tidautils.CodeRefsTo
Create an array type
The goal of this script is to demonstrate some usage of the type API. In this script, we create an array using both versions of create_array tinfo_t method.
APIs Used:
ida_typeinf.BTF_INTida_typeinf.array_type_data_tida_typeinf.tinfo_t
Create a structure with bitfield members
The goal of this script is to demonstrate some usage of the type API. In this script, we:
Create a bitfield structure. In the present case the bitfield is an int32 made of three 'members' spanning it entirely: bit0->bit19: bf1 bit20->bit25: bf2 bit26->bit31: bf3
For each member create a repeatable comment.
APIs Used:
ida_typeinf.tinfo_tida_typeinf.udm_tida_typeinf.udt_type_data_t
Create a bitmask enumeration
The goal of this script is to demonstrate some usage of the type API. In this script, we create a bitmask enumeration member by member.
APIs Used:
ida_typeinf.BTE_BITMASKida_typeinf.BTE_HEXida_typeinf.tinfo_t
Create a type library file
The goal of this script is to demonstrate some usage of the type API. In this script:
We create a new libssh2-64.til file holding some libssh2 64-bit structures.
Once the file has been created, it can copied in the IDA install til directory or in the user IDA til directory.
APIs Used:
ida_typeinf.HTI_DCLida_typeinf.HTI_PAKDEFida_typeinf.compact_tilida_typeinf.free_tilida_typeinf.new_tilida_typeinf.parse_declsida_typeinf.store_til
Create a structure programmatically
The goal of this script is to demonstrate some usage of the type API. In this script, we create a structure by building it member by member.
APIs Used:
ida_typeinf.BTF_UINT32ida_typeinf.NTF_TYPEida_typeinf.del_named_typeida_typeinf.tinfo_errstrida_typeinf.tinfo_tida_typeinf.udt_type_data_t
Create & populate a structure
Usage of the API to create & populate a structure with members of different types.
APIs Used:
ida_typeinf.BTF_BYTEida_typeinf.BTF_DOUBLEida_typeinf.BTF_FLOATida_typeinf.BTF_INTida_typeinf.BTF_INT128ida_typeinf.BTF_INT16ida_typeinf.BTF_INT64ida_typeinf.BTF_TBYTEida_typeinf.BTF_UINT32ida_typeinf.FRB_NUMOida_typeinf.NTF_TYPEida_typeinf.PRTYPE_DEFida_typeinf.PRTYPE_MULTIida_typeinf.PRTYPE_TYPEida_typeinf.del_named_typeida_typeinf.idc_parse_typesida_typeinf.tinfo_errstrida_typeinf.tinfo_tida_typeinf.udm_tida_typeinf.udt_type_data_tida_typeinf.value_repr_t
Create a union
The goal of this script is to demonstrate some usage of the type API. In this script, we create a union by building it member after member.
APIs Used:
ida_typeinf.BTF_CHARida_typeinf.BTF_FLOATida_typeinf.BTF_INT32ida_typeinf.BTF_UNIONida_typeinf.NTF_TYPEida_typeinf.PRTYPE_DEFida_typeinf.PRTYPE_MULTIida_typeinf.PRTYPE_TYPEida_typeinf.del_named_typeida_typeinf.tinfo_tida_typeinf.udm_tida_typeinf.udt_type_data_t
Create a segment, and define (complex) data in it
The goal of this script is to demonstrate some usage of the type API. In this script, we show how to create, set type and name of a user shared data region in an ntdll IDB:
Load the
_KUSER_SHARED_DATAdata type from a type info library shipped with IDA, and import it into the IDB's "local types"Create a data segment with UserSharedData as its name.
Apply the type to the start of the newly created segment base address.
Set the address name.
APIs Used:
ida_name.set_nameida_segment.add_segm_exida_segment.saRelParaida_segment.scPubida_segment.segment_tida_segment.setup_selectorida_typeinf.TINFO_DEFINITEida_typeinf.apply_tinfoida_typeinf.free_tilida_typeinf.load_til
Utilities to detect structure gaps & alignment
The goal of this script is to illustrate ways to detect gaps & alignments in structures, from a structure name & (byte) offset.
APIs Used:
ida_range.rangeset_t
Get member by offset, taking into account variable sized structures
The goal of this script is to provide a way to figure out what structure member, is most likely referenced by an offset.
This also works for variable sized types.
APIs Used:
ida_typeinf.tinfo_tida_typeinf.udt_type_data_t
Get information about the "innermost" member of a structure
Assuming the 2 following types:
looking at an offset of 5 bytes inside an a instance, might be interpreted as pointing somewhere inside member b_instance, of type b. Alternatively, that same offset might be intprereted as pointing somewhere inside low, of type int.
We refer to that latter interpretation as "innermost", and this sample shows how the API lets us "drill down" to retrieve that innermost member.
APIs Used:
ida_typeinf.get_idatiida_typeinf.parse_decls
Load a type library from a file, and then a type from it
The goal of this script is to demonstrate some usage of the type API. In this script, we:
ask the user for a specific til to be lodaed
if successfully loaded ask the user for a type name to be imported.
append the type to the local types.
APIs Used:
ida_kernwin.ask_strida_typeinf.load_til
Inject a member in the middle of a structure
This sample will retrieve the type info object by its name, find the member at the specified offset, and insert a new member right before it
APIs Used:
ida_typeinf.TERR_OKida_typeinf.tinfo_t
List all xrefs to a function stack variable
Contrary to (in-memory) data & code xrefs, retrieving stack variables xrefs requires a bit more work than just using ida_xref's first_to(), next_to() (or higher level utilities such as idautils.XrefsTo)
APIs Used:
ida_bytes.get_flagsida_bytes.is_stkvarida_frame.calc_stkvar_struc_offsetida_funcs.get_funcida_ida.UA_MAXOPida_kernwin.AST_DISABLE_FOR_WIDGETida_kernwin.AST_ENABLE_FOR_WIDGETida_kernwin.BWN_DISASMida_kernwin.action_desc_tida_kernwin.action_handler_tida_kernwin.get_current_viewerida_kernwin.get_highlightida_kernwin.get_screen_eaida_kernwin.register_actionida_typeinf.tinfo_tida_ua.decode_insnida_ua.insn_t
List cross-references to function stack frame variables
The goal of this script is to demonstrate some usage of the type API. In this script, we demonstrate how to list each stack variables xref:
Get the function object surrounding cursor location.
Use this function to retrieve the corresponding frame object.
For each frame element:
Build the stack variable xref list
Print it.
APIs Used:
ida_frame.build_stkvar_xrefsida_frame.get_func_frameida_frame.xreflist_tida_funcs.get_funcida_kernwin.get_screen_eaida_typeinf.tinfo_tida_typeinf.udt_type_data_tida_xref.dr_Rida_xref.dr_W
Assign DOS/PE headers structures to a PE binary
The goal of this script is to demonstrate some usage of the type API.
In this script, we:
load a PE64 file in binary mode
import some types from the mssdk64 til
apply these types at the correct ofsset in the DB
finally, rebase the program based on the information stored in the ImageBase field of the IMAGE_OPTIONAL_HEADER64.
APIs Used:
ida_bytes.create_structida_bytes.get_dwordida_bytes.get_qwordida_bytes.get_wordida_hexrays.get_typeida_name.set_nameida_netnode.BADNODEida_segment.MSF_FIXONCEida_segment.rebase_programida_typeinf.ADDTIL_DEFAULTida_typeinf.BTF_STRUCTida_typeinf.add_tilida_typeinf.tinfo_tida_typeinf.udt_type_data_tidc.import_type
Recursively visit a type and its members
In this script, we show an example of tinfo_visitor_t to list a user define type members, recursively.
This scripts skips array & pointer members (by calling tinfo_visitor_t.prune_now())
APIs Used:
ida_netnode.BADNODEida_typeinf.ADDTIL_DEFAULTida_typeinf.TVST_DEFida_typeinf.add_tilida_typeinf.array_type_data_tida_typeinf.get_idatiida_typeinf.tinfo_tida_typeinf.tinfo_visitor_tidc.import_type
Change the name of an existing stack variable
The goal of this script is to demonstrate some usage of the type API. In this script, we demonstrate a way to change the name of a stack variable:
Get the function object surrounding cursor location.
Use this function to retrieve the corresponding frame object.
Find the frame member matching the given name.
Using its offset in the frame structure object, calculate the actual stack delta.
Use the previous result to redefine the stack variable name if it is not a special or argument member.
APIs Used:
ida_frame.define_stkvarida_frame.get_func_frameida_frame.is_funcarg_offida_frame.is_special_frame_memberida_frame.soff_to_fpoffida_funcs.get_funcida_typeinf.tinfo_tida_typeinf.udm_tidc.here
Change the type & name of a function stack frame variable
The goal of this script is to demonstrate some usage of the type API.
In this script, we show a way to change the type and the name of a stack variable. In this case we will take advantage of the fact that RtlImageNtHeader calls RtlImageNtHeaderEx which takes a pointer to PIMAGE_NT_HEADERS as its fourth parameter and, for this, uses a stack variable of its caller.
Get the function object for RtlImageNtHeader.
Iterate through the function item to localize the load of the stack variable address before the call to RtlImageNtHeaderEx. We keep this information.
Localize the call and take advantage of the previoulsy stored instruction to get the stack variable index in the frame.
Set the type and rename the stack variable.
APIs Used:
ida_allins.NN_callida_allins.NN_leaida_frame.get_func_frameida_funcs.func_item_iterator_tida_funcs.get_funcida_funcs.get_func_nameida_ida.inf_get_procnameida_ida.inf_is_64bitida_idaapi.BADADDRida_name.get_name_eaida_typeinf.BTF_STRUCTida_typeinf.TERR_OKida_typeinf.tinfo_tida_ua.decode_insnida_ua.insn_tida_ua.o_regidautils.procregs.r9.reg
Turn instruction operand into a structure offset
The goal of this script is to demonstrate some usage of the type API. In this script, we:
ask the user to choose the structure that will be used for the conversion.
build the structure path and call ida_bytes.op_stroff. In case an enum is found a modal chooser is displayed in order to select a member.
APIs Used:
ida_bytes.op_stroffida_kernwin.Chooseida_kernwin.Choose.CHCOL_HEXida_kernwin.Choose.CHCOL_PLAINida_kernwin.choose_structida_kernwin.get_opnumida_kernwin.get_screen_eaida_pro.tid_arrayida_typeinf.STRMEM_OFFSETida_typeinf.tinfo_tida_typeinf.udm_tida_typeinf.udt_type_data_tida_ua.decode_insnida_ua.insn_t
Code to be run right after IDAPython initialization
The idapythonrc.py file:
%APPDATA%\Hex-Rays\IDA Pro\idapythonrc.py (on Windows)
~/.idapro/idapythonrc.py (on Linux & Mac)
can contain any IDAPython code that will be run as soon as IDAPython is done successfully initializing.
Add functions to the IDC runtime, from IDAPython
You can add IDC functions to IDA, whose "body" consists of IDAPython statements!
We'll register a 'pow' function, available to all IDC code, that when invoked will call back into IDAPython, and execute the provided function body.
After running this script, try switching to the IDC interpreter (using the button on the lower-left corner of IDA) and executing pow(3, 7)
APIs Used:
ida_expr.VT_LONGida_expr.add_idc_func
Add 64-bit (.idb->.i64) conversion capabilities to custom plugins
For more infortmation see SDK/plugins/cvt64_sample example
APIs Used:
ida_idaapi.BADADDRida_idaapi.BADADDR32ida_netnode.atagida_netnode.htagida_netnode.stag
Add merge functionality to a simple plugin
This is a primitive plugin which asks user for some info and saves it for some addresses.
We will add a merge functionality to plugin.
An IDA plugin may have two kinds of data with permanent storage:
Data common for entire database (e.g. the options). To describe them we will use the idbattr_info_t type.
Data specific to a particular address. To describe them we will use the merge_node_info_t type.
Also, see SDK/plugins/mex1 example
APIs Used:
ida_funcs.get_funcida_ida.IDI_ALTVALida_ida.IDI_CSTRida_ida.IDI_SCALARida_ida.IDI_SUPVALida_ida.idbattr_info_tida_idaapi.BADADDRida_idaapi.PLUGIN_MODida_idaapi.PLUGIN_MULTIida_idaapi.plugin_tida_idaapi.plugmod_tida_idp.IDP_Hooksida_kernwin.Formida_kernwin.Form.ChkGroupControlida_kernwin.Form.StringInputida_kernwin.get_screen_eaida_merge.MERGE_KIND_ENDida_merge.MERGE_KIND_NONEida_merge.NDS_IS_STRida_merge.NDS_MAP_IDXida_merge.merge_handler_params_tida_merge.merge_node_info_tida_merge.moddata_diff_helper_tida_mergemod.create_std_modmerge_handlersida_netnode.BADNODEida_netnode.SIZEOF_nodeidx_tida_netnode.atagida_netnode.netnodeida_netnode.stag
Implement merging functionality for custom plugins
IDA Teams uses a chooser to display the merge conflicts. To fill the chooser columns IDA Teams uses the following methods from diff_source_t type:
print_diffpos_name()
print_diffpos_details()
and UI hints from merge_handler_params_t type:
ui_has_details()
ui_complex_details()
ui_complex_name()
In general, chooser columns are filled as following:
Also, see SDK/plugins/mex3 example
APIs Used:
ida_funcs.get_funcida_ida.IDI_ALTVALida_ida.IDI_CSTRida_ida.IDI_SCALARida_ida.IDI_SUPVALida_ida.idbattr_info_tida_idaapi.BADADDRida_idaapi.PLUGIN_MODida_idaapi.PLUGIN_MULTIida_idaapi.plugin_tida_idaapi.plugmod_tida_idp.IDP_Hooksida_kernwin.Formida_kernwin.Form.ChkGroupControlida_kernwin.Form.StringInputida_kernwin.get_screen_eaida_merge.MERGE_KIND_ENDida_merge.MERGE_KIND_NONEida_merge.MH_UI_COLONNAMEida_merge.MH_UI_COMMANAMEida_merge.MH_UI_NODETAILSida_merge.NDS_IS_STRida_merge.NDS_MAP_IDXida_merge.create_nodeval_merge_handlersida_merge.get_ea_diffpos_nameida_merge.merge_handler_params_tida_merge.merge_node_helper_tida_merge.merge_node_info_tida_merge.moddata_diff_helper_tida_mergemod.create_std_modmerge_handlersida_nalt.node2eaida_netnode.BADNODEida_netnode.SIZEOF_nodeidx_tida_netnode.atagida_netnode.netnodeida_netnode.stag
Last updated
