DOCSEARCHbyAlgolia
Submit Docs

IDA SDK Documentation

repository·main·Indexed 18 days ago

https://github.com/hexrayssa/ida-sdk

Development kit for extending IDA Pro, providing C++ and Python (IDAPython) interfaces to build custom plugins, loaders, processor modules, and debuggers. Includes instructions for building the SDK with CMake and Ninja, creating out-of-tree components, and a collection of IDAPython API examples ranging from beginner to advanced levels.

Tokens
37.3K
Snippets
125
Records
211
Agent score
64%

What's inside IDA SDK

  1. Overview of IDAPython example categories

    main

    The IDAPython examples are organized into several functional domains to help you implement specific automation tasks:

    • User interface: Creating and manipulating UI widgets, forms, and custom UI via Python Qt bindings.
    • 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: Managing types, including programmatically creating structures and enums.
    • Miscellaneous: General-purpose examples.

  2. Overview of the SAM8 Processor Module

    main

    The SAM8 processor module is designed for Samsung SAM8-based microcontrollers. It provides support for the SAMA assembler (available from http://www.cnatech.com/).

    Key features include:

    • Support for the SAMA assembler.
    • Automatic segment creation for cmem and emem.
    • Automatic remapping of external data accesses into the emem segment to handle address collisions with code memory.

  3. How IDAPython linking works on Apple Silicon Macs

    main

    On Apple Silicon Macs, strict codesigning rules prevent the traditional method of patching libpython load commands in IDAPython modules (which would invalidate the binary signature and cause macOS to kill the process).

    To allow switching between Python versions without modifying IDA's binaries, the SDK uses .tbd (text-based stub) files. Instead of linking directly to a specific Python dylib, IDAPython modules link to a .tbd file that points to a symlink (@executable_path/libpython3.link.dylib). Switching Python versions is then achieved simply by updating the symlink target, leaving the signed IDAPython binaries untouched.

  4. Add merge functionality to a simple plugin

    main

    When developing plugins that require permanent data storage, you must distinguish between two types of data:

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

    To implement merge functionality, you can leverage ida_merge and ida_mergemod modules to handle how data is reconciled between different database versions.

  5. Understanding Microcode (mba_t)

    main

    Microcode is represented by the mba_t class, which contains global information and a list of basic blocks.

    Structure

    • mba_t: The container for microcode. Access basic blocks via get_mblock() (index-based) or as a double-linked list using blk->nextb and blk->prevb.
    • mblock_t: Represents a basic block. Key attributes include block type (1way, 2way, nway), serial index, head/tail pointers to instructions, and predecessor/successor sets (predset/succset).
    • minsn_t: Represents an instruction. Each instruction contains an opcode, three operands (l, r, d), an address (ea), and various properties.

    Operations

    • Search: Use find_first_use() within a block or mbl_graph_t::is_accessed_globally() for global searches.
    • List Building: Before searching, you must build the necessary lists using build_use_list(), build_def_list(), append_use_list(), or append_def_list().
    • Modification: You can add or remove instructions using insert_into_block() and remove_from_block(), or modify fields directly.

  6. Iterate over function items using func_t iterators

    main

    The func_t type provides several iterators to traverse different aspects of a function. You can use these to inspect instructions, data, or specific addresses within a function's range.

    Available Iterators:

    • func_t[.__iter__] (Default): Iterates over instructions.
    • func_t.data_items: Iterates over data items contained within the function.
    • func_t.head_items: Iterates over 'heads' (addresses containing the start of an instruction or a data item).
    • func_t.addresses: Iterates over all addresses within the function (including code, data, and intermediate addresses).
    • 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.

    To see a full list of available iterators, use help(ida_funcs.func_t) in the IDAPython console.

    # Example of using func_t iterators (conceptual usage)
for insn in func:  # Uses default __iter__
    print(insn)

for addr in func.addresses:
    print(addr)

  7. Implement custom instruction disassembly and assembly using IDP_Hooks

    main

    By using ida_idp.IDP_Hooks, you can intercept and modify how instructions are disassembled or assembled. This is useful for supporting architecturally undefined instructions or pseudo-instructions.

    Use Cases:

    • Custom Disassembly: Use ida_idp.CUSTOM_INSN_ITYPE to define how a specific byte sequence should be represented in the listing (e.g., handling Linux kernel BUG() macros on ARM).
    • Custom Assembly: Use idautils.DecodeInstruction within a hook to support pseudo-instructions like zero eax $\rightarrow$ xor eax, eax or nothing $\rightarrow$ nop.
    # APIs Used:
# ida_idp.IDP_Hooks
# ida_idp.CUSTOM_INSN_ITYPE
# idautils.DecodeInstruction

  8. Understand SAM8 memory segments: cmem and emem

    main

    The SAM8 module manages two distinct memory segments:

    • cmem (code memory): Occupies addresses 0 through 0x10000.
    • emem (external data memory): Occupies addresses 0x800000 through 0x810000.

    Address Remapping: Since external data memory occupies the same address range as code memory, the module automatically remaps external data accesses into the emem segment. Use the samaout plugin to ensure these remapped names are correctly exported as EQU definitions in your assembly output.

  9. Naming conventions for Decompiler plugins

    main

    To ensure your plugin is loaded after the Hex-Rays decompiler plugin (preventing termination due to a missing decompiler), you should use a specific prefix in your plugin name:

    • Standard x86: Use the hexrays_ prefix (e.g., hexrays_myplugin.cpp).
    • Architecture-specific: If writing for non-x86 versions, use the corresponding prefix (e.g., hexx64 for x64, hexarm for ARM).

    Always check the IDA plugins directory to confirm the exact name used by the decompiler for your architecture.

  10. How merge functionality works in IDA Teams plugins

    main

    To support IDA Teams, a plugin must implement logic for merging databases. This process follows a specific lifecycle:

    1. Description: The plugin provides a description of the data that needs to be merged.
    2. Handler Creation: The plugin calls the kernel to create merge handlers based on those descriptions.
    3. Execution: The kernel uses these handlers to perform the actual merging and to display the merged data to users.
    4. Customization (Optional): The plugin can implement callback functions to modify specific aspects of the merging process if the default behavior is insufficient.

    Note: Before launching an IDA Teams session, you must prepare your databases by running the plugins first.

  11. Understand the IDA SDK documentation environment assumptions

    main

    The IDA SDK documentation is generated based on a specific compilation environment to ensure consistency with platform-dependent definitions. When interpreting the documentation, assume the code is being compiled on a 32-bit Windows system with Visual C++.

    Specifically, the following preprocessor macros are assumed to be defined:

    • __cplusplus
    • __X86__
    • __NT__
    • _MSC_VER
    • UNICODE
    • NO_OBSOLETE_FUNCS

    For more granular details regarding these definitions, refer to pro.h in the SDK.

  12. React to IDB and IDP events using Hooks

    main

    You can monitor changes within IDA by implementing hooks that react to database (IDB) or processor (IDP) events.

    • IDB Events: Use ida_idp.IDB_Hooks to be notified about changes to the IDA database (e.g., modifications to functions, types, or segments).
    • IDP Events: Use ida_idp.IDP_Hooks to be notified about processor-specific events (e.g., changes in how the processor interprets instructions).

    These hooks are useful for creating plugins that automatically update UI elements or perform analysis when the user modifies the database.