IDAPython Documentation

IDAPython examples are organized into several functional domains to help you find specific implementation patterns:

• User interface: Creating and manipulating UI widgets, using Python Qt bindings, prompting users with forms, and enriching existing IDA widgets.
• Disassembly: Querying or modifying the disassembly listing, altering analysis, and reacting to IDB changes.
• Decompilation: Querying the decompiler, manipulating microcode or C-trees, and intervening in decompilation output.
• Debuggers: Driving debugging sessions and reacting to debugging events.
• Working with types: Using Type APIs to manage types, such as programmatically creating structures or enums and adding members.
• Miscellaneous: General purpose examples that do not fit into the specific categories above.

IDA can be extended to support unknown data types through 'custom data types' (defining size/type) and 'custom data formats' (defining how the data is displayed).

Use ida_bytes.register_data_types_and_formats to register your custom logic. This allows you to control how specific bytes are interpreted and formatted in the UI, leveraging ida_bytes.data_type_t and ida_bytes.data_format_t.

On Apple Silicon Macs, strict codesigning rules prevent traditional methods of patching libpython load commands in IDAPython modules, as modifying binaries invalidates their signature and causes macOS to kill the process.

To solve this, IDAPython uses .tbd (text-based stub) files. Instead of linking directly to a specific libpython binary, IDAPython modules link to a .tbd file that defines an install-name pointing to a symlink (e.g., @executable_path/libpython3.link.dylib). This allows users to switch between different Python versions simply by updating the symlink target, without ever modifying the signed IDAPython binaries.

The ida_funcs.func_t type provides several iterators to traverse the contents of a function.

Key Iterators:

• __iter__: The default iterator, iterates over instructions.
• .data_items: Iterates over data items contained within the function.
• .head_items: Iterates over 'heads' (addresses containing the start of an instruction or data item).
• .addresses: Iterates over all addresses within the function (including those in the middle of items).

Advanced Iterators:

• func_tail_iterator_t: Iterates over all chunks of the function (including the main chunk).
• func_parent_iterator_t: Iterates over all parent functions that include the current chunk.

There are two ways to indicate that a function modifies (spoils) specific registers:

1. Parsing a declaration: Use a string like int _spoils<rsi> main(); with ida_typeinf.tinfo_t and apply it using ida_typeinf.apply_tinfo with the ida_typeinf.TINFO_DEFINITE flag.
2. Directly modifying the tinfo_t object: Retrieve the function's type info and modify the func_type_data_t directly to include the ida_typeinf.FTI_SPOILED flag for the target register.

When building a plugin that requires permanent data storage, you can use two types of data:

1. Database-wide data: Use idbattr_info_t for options or settings common to the entire database.
2. Address-specific data: Use merge_node_info_t for data tied to specific addresses.

To implement merging (similar to IDA Teams), you must handle merge conflicts. When filling chooser columns for conflicts, use the following pattern:

columns.clear()
NAME = print_diffpos_name()
if ui_complex_name():
    columns.add(split NAME by ui_split_char())
else:
    columns[0] = NAME

if not ui_complex_details():
    columns.add(print_diffpos_details())

Key methods for diff_source_t to populate UI details:

• print_diffpos_name()
• print_diffpos_details()

Key UI hints from merge_handler_params_t:

• ui_has_details()
• ui_complex_details()
• ui_complex_name()

For professional UI integration, create custom actions using ida_kernwin.register_action.

Capabilities:

• Contextual Availability: Use the ida_kernwin.action_handler_t.update callback to enable/disable the action based on the current context (e.g., which widget is focused).
• Visuals: Load custom icons with ida_kernwin.load_custom_icon and provide tooltips.
• Placement: Actions can be attached to menus (attach_action_to_menu), toolbars (attach_action_to_toolbar), or popups (attach_action_to_popup).
• Context: When triggered, actions receive a 'context' containing relevant information about the current state.

When C++ functions are wrapped for Python, some parameters change behavior (e.g., an out pointer in C++ becomes a return value in Python). To ensure the IDAPython documentation is accurate, inject_pydoc.py uses SWIG-generated prototypes to identify which parameters are actually present in the Python version. It then strips the corresponding documentation for the non-relevant C++ parameters from the Doxygen-extracted XML before injection.

Example of parameter transformation:

C++ Header:

inline void get_registered_actions(qstrvec_t *out)

Python API: ida_kernwin.get_registered_actions() (returns list(str))

In this case, the documentation for the out parameter is removed so users don't see instructions for a parameter that no longer exists in the Python signature.

To display data in a table format, subclass ida_kernwin.Choose.

Key Features:

• Selection Modes: Supports single selection or multiple selection (using Choose.CH_MULTI).
• Callbacks: Handle events like Choose.ALL_CHANGED or Choose.NOTHING_CHANGED.
• Column Configuration: Define columns using constants like Choose.CHCOL_HEX or Choose.CHCOL_FNAME.
• Actions: You can register actions that can be applied specifically to the chooser widget.

By subclassing ida_hexrays.Hexrays_Hooks, you can listen to various notifications sent by the decompiler. This allows your plugin to react to changes in the decompiler state, such as function changes, variable changes, or UI interactions.

Key APIs:

• ida_hexrays.Hexrays_Hooks
• ida_hexrays.cfunc_t
• ida_hexrays.lvar_t
• ida_hexrays.vdui_t

To customize how items appear in the Function window (e.g., coloring functions based on size), override ida_kernwin.UI_Hooks.get_chooser_item_attrs.

Workflow:

1. Subclass ida_kernwin.UI_Hooks.
2. Implement get_chooser_item_attrs to return custom attributes.
3. Enable the hooks using ida_kernwin.enable_chooser_item_attrs.