IDAPython examples

IDAPython scripts examples

The following examples demonstrate the usage of the IDAPython API in more complex scripts.

Where can I find all the examples?

IDA is shipped with examples of IDAPython scripts that perform specific tasks, useful for common situations.

The full library of our examples is shipped with your IDA instance in the python/examples folder. You can find them also in the GitHub repository.

How to run the examples?

Load the script via File Loader

  1. Navigate to File -> Script file....

  2. In the new dialog, select the .py script you want to run and click Open.

Load the script via Script command

  1. Navigate to File -> Script command....

  2. Paste the code into Please enter script body field and click Run.

Load the script via output window/console

  1. In the output window/IDAPython console, type the following command: exec(open("path/to/your_script.py").read()) to execute the script.

IDAPython examples

Category: analysis

dump_func_info

Dump (some) information about the current function.

Source code

analysis/dump_func_info.py

Category

analysis

Description

Dump some of the most interesting bits of information about the function we are currently looking at.

Uses

  • ida_funcs.FUNC_FRAME

  • ida_funcs.FUNC_LUMINA

  • ida_funcs.FUNC_OUTLINE

  • ida_funcs.FUNC_THUNK

  • ida_funcs.get_fchunk

  • ida_funcs.is_func_entry

  • ida_funcs.is_func_tail

  • ida_kernwin.get_screen_ea

Category: core

actions

Custom actions, with icons & tooltips

Source code

core/actions.py

Category

core

Description

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)

Shortcut

Ctrl+F12

Keywords

actions ctxmenu UI_Hooks

Uses

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.BWN_DISASM

  • ida_kernwin.SETMENU_APP

  • ida_kernwin.UI_Hooks

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.attach_action_to_menu

  • ida_kernwin.attach_action_to_popup

  • ida_kernwin.attach_action_to_toolbar

  • ida_kernwin.get_widget_type

  • ida_kernwin.load_custom_icon

  • ida_kernwin.register_action

  • ida_kernwin.unregister_action

See also

add_hotkey

Triggering bits of code by pressing a shortcut

Source code

core/add_hotkey.py

Category

core

Description

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.

Keywords

actions

Uses

  • ida_kernwin.add_hotkey

  • ida_kernwin.del_hotkey

See also

add_idc_hotkey

Triggering bits of code by pressing a shortcut (older version)

Source code

core/add_idc_hotkey.py

Category

core

Description

This is a somewhat ancient way of registering actions & binding shortcuts. It's still here for reference, but "fresher" alternatives should be preferred.

Keywords

actions

Uses

  • ida_expr.compile_idc_text

  • ida_kernwin.add_idc_hotkey

See also

auto_instantiate_widget_plugin

Better integrating custom widgets in the desktop layout

Source code

core/auto_instantiate_widget_plugin.py

Category

core

Description

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:

  1. 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

  2. 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

Keywords

desktop plugin UI_Hooks

Uses

  • ida_idaapi.plugin_t

  • ida_kernwin.AST_ENABLE_ALWAYS

  • ida_kernwin.SETMENU_APP

  • ida_kernwin.UI_Hooks

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.attach_action_to_menu

  • ida_kernwin.find_widget

  • ida_kernwin.register_action

  • ida_kernwin.simplecustviewer_t

  • ida_kernwin.simplecustviewer_t.Create

colorize_disassembly_on_the_fly

An easy-to-use way to colorize lines

Source code

core/colorize_disassembly_on_the_fly.py

Category

core

Description

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.)

Shortcut

!

Keywords

coloring UI_Hooks

Uses

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.CK_EXTRA5

  • ida_kernwin.CK_EXTRA6

  • ida_kernwin.CK_EXTRA7

  • ida_kernwin.CK_EXTRA8

  • ida_kernwin.UI_Hooks

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.get_current_viewer

  • ida_kernwin.get_custom_viewer_location

  • ida_kernwin.get_custom_viewer_place_xcoord

  • ida_kernwin.get_widget_title

  • ida_kernwin.line_rendering_output_entry_t

  • ida_kernwin.register_action

  • ida_moves.lochist_entry_t

See also

create_structure_programmatically

Programmatically create & populate a structure

Source code

core/create_structure_programmatically.py

Category

core

Description

Usage of the API to create & populate a structure with members of different types.

Uses

  • ida_typeinf.BTF_BYTE

  • ida_typeinf.BTF_DOUBLE

  • ida_typeinf.BTF_FLOAT

  • ida_typeinf.BTF_INT

  • ida_typeinf.BTF_INT128

  • ida_typeinf.BTF_INT16

  • ida_typeinf.BTF_INT64

  • ida_typeinf.BTF_TBYTE

  • ida_typeinf.BTF_UINT32

  • ida_typeinf.FRB_NUMO

  • ida_typeinf.NTF_TYPE

  • ida_typeinf.PRTYPE_DEF

  • ida_typeinf.PRTYPE_MULTI

  • ida_typeinf.PRTYPE_TYPE

  • ida_typeinf.del_named_type

  • ida_typeinf.idc_parse_types

  • ida_typeinf.tinfo_errstr

  • ida_typeinf.tinfo_t

  • ida_typeinf.udm_t

  • ida_typeinf.udt_type_data_t

  • ida_typeinf.value_repr_t

Author

Gergely Erdelyi (gergely.erdelyi@d-dome.net)

custom_cli

A custom command-line interpreter

Source code

core/custom_cli.py

Category

core

Description

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.

Uses

  • ida_idaapi.NW_CLOSEIDB

  • ida_idaapi.NW_OPENIDB

  • ida_idaapi.NW_REMOVE

  • ida_idaapi.NW_TERMIDA

  • ida_idaapi.notify_when

  • ida_kernwin.cli_t

custom_data_types_and_formats

Using custom data types & printers

Source code

core/custom_data_types_and_formats.py

Category

core

Description

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'.)

Uses

  • ida_bytes.data_format_t

  • ida_bytes.data_type_t

  • ida_bytes.find_custom_data_type

  • ida_bytes.get_byte

  • ida_bytes.register_data_types_and_formats

  • ida_bytes.unregister_data_types_and_formats

  • ida_idaapi.NW_CLOSEIDB

  • ida_idaapi.NW_OPENIDB

  • ida_idaapi.NW_REMOVE

  • ida_idaapi.NW_TERMIDA

  • ida_idaapi.notify_when

  • ida_idaapi.struct_unpack

  • ida_lines.COLSTR

  • ida_lines.SCOLOR_IMPNAME

  • ida_lines.SCOLOR_INSN

  • ida_lines.SCOLOR_NUMBER

  • ida_lines.SCOLOR_REG

  • ida_nalt.get_input_file_path

  • ida_netnode.netnode

  • ida_typeinf.tinfo_t

dump_extra_comments

Retrieve extra comments

Source code

core/dump_extra_comments.py

Category

core

Description

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.

Shortcuts

Ctrl+Shift+Y Ctrl+Shift+Z

Keywords

ctxmenu

Uses

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.BWN_DISASM

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.attach_action_to_popup

  • ida_kernwin.find_widget

  • ida_kernwin.get_screen_ea

  • ida_kernwin.register_action

  • ida_kernwin.unregister_action

  • ida_lines.E_NEXT

  • ida_lines.E_PREV

  • ida_lines.get_extra_cmt

  • ida_view

dump_flowchart

Dump function flowchart

Source code

core/dump_flowchart.py

Category

core

Description

Dumps the current function's flowchart, using 2 methods:

  • the low-level ida_gdl.qflow_chart_t type

  • the somewhat higher-level, and slightly more pythonic ida_gdl.FlowChart type.

Uses

  • ida_funcs.get_func

  • ida_gdl.FlowChart

  • ida_gdl.qflow_chart_t

  • ida_kernwin.get_screen_ea

dump_selection

Retrieve & dump current selection

Source code

core/dump_selection.py

Category

core

Description

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

Shortcut

Ctrl+Shift+S

Uses

  • ida_kernwin.ACF_HAS_SELECTION

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.BWN_DISASM

  • ida_kernwin.BWN_PSEUDOCODE

  • ida_kernwin.BWN_TILVIEW

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.get_current_viewer

  • ida_kernwin.get_viewer_user_data

  • ida_kernwin.l_compare2

  • ida_kernwin.linearray_t

  • ida_kernwin.read_selection

  • ida_kernwin.register_action

  • ida_kernwin.twinpos_t

  • ida_kernwin.unregister_action

  • ida_lines.tag_remove

extend_idc

Add functions to the IDC runtime from IDAPython

Source code

core/extend_idc.py

Category

core

Description

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)

Uses

  • ida_expr.VT_LONG

  • ida_expr.add_idc_func

find_string

Showcasing `ida_bytes.find_string`

Source code

core/find_string.py

Category

core

Description

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.)

Shortcut

Ctrl+Shift+S

Uses

  • ida_bytes.BIN_SEARCH_FORWARD

  • ida_bytes.BIN_SEARCH_NOBREAK

  • ida_bytes.BIN_SEARCH_NOSHOW

  • ida_bytes.find_string

  • ida_ida.inf_get_max_ea

  • ida_idaapi.BADADDR

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.BWN_DISASM

  • ida_kernwin.Form

  • ida_kernwin.Form.ChkGroupControl

  • ida_kernwin.Form.StringInput

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.get_screen_ea

  • ida_kernwin.jumpto

  • ida_kernwin.register_action

  • ida_nalt.BPU_1B

  • ida_nalt.BPU_2B

  • ida_nalt.get_default_encoding_idx

idapythonrc

Code to be run right after IDAPython initialization

Source code

core/idapythonrc.py

Category

core

Description

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.

install_user_defined_prefix

Inserting information into disassembly prefixes

Source code

core/install_user_defined_prefix.py

Category

core

Description

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.

Keywords

plugin

Uses

  • ida_idaapi.PLUGIN_KEEP

  • ida_idaapi.plugin_t

  • ida_lines.SCOLOR_INV

  • ida_lines.user_defined_prefix_t

list_bookmarks

List bookmarks associated to a listing

Source code

core/list_bookmarks.py

Category

core

Description

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.

Shortcut

Ctrl+!

Keywords

bookmarks

Uses

  • ida_kernwin.AST_DISABLE_FOR_WIDGET

  • ida_kernwin.AST_ENABLE_FOR_WIDGET

  • ida_kernwin.action_desc_t

  • ida_kernwin.action_handler_t

  • ida_kernwin.get_current_viewer

  • ida_kernwin.get_viewer_user_data

  • ida_kernwin.get_widget_title

  • ida_kernwin.register_action

  • ida_moves.bookmarks_t

list_function_items

Showcases (a few of) the iterators available on a function

Source code

core/list_function_items.py

Category

core

Description

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 instructions

  • func_t.data_items: iterate on data items contained within a function

  • func_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 function

  • func_parent_iterator_t: iterate on all the parent functions, that include this chunk

Keywords

funcs iterator

Uses

  • ida_bytes.get_flags

  • ida_bytes.is_code

  • ida_bytes.is_data

  • ida_bytes.is_tail

  • ida_bytes.is_unknown

  • ida_funcs.func_tail_iterator_t

  • ida_funcs.get_fchunk

  • ida_funcs.get_func

  • ida_funcs.get_func_name

  • ida_kernwin.get_screen_ea

  • ida_ua.print_insn_mnem

list_imports

Enumerate file imports

Source code

core/list_imports.py

Category

core

Description

Using the API to enumerate file imports.

Uses

  • ida_nalt.enum_import_names

  • ida_nalt.get_import_module_name

  • ida_nalt.get_import_module_qty

list_patched_bytes

Enumerate patched bytes