Getting Started

Getting started with IDAPython

Intro

The IDAPython API provides you a range of functions to interact with the disassembler, navigate through the output, and manipulate various elements such as functions, instructions, data, and comments.

This guide is is designed to speed up the learning curve in IDAPython API and kickstart your journey with scripting in IDA, assuming that you are already found your way around IDA and got familiar with IDA basics.

How this guide is structured?

First, check basics for the core concepts like common variables, then dive into our simple, short and reusable code snippets showing basic examples of commonly used functions.

Where can I find the complete examples library?

When you feel comfortable with most popular IDAPython API usage, you can delve into our set of more complex examples. 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.

Basics

Common modules

IDAPython API is organized in modules, however their number may be a bit overwhelming for the first sigh. Here's the list of modules that should catch your attention first:

• idautils: This module extracts the most useful and handy functions allowing you to jump right away and interact with the disassembly without the need to scrutinize the whole IDAPython API from the start. You can find here functions to iterate through whole segments, functions (founded by IDA and also user-defined), named locations, etc.

• ida_idaapi: The ida_idaapi module comes handy when you want to create custom plugins or handle events, as it gives you access to more advanced functions and allows interaction with overall system

• idc: This module provides functions that were originally part of native IDA IDC scripting language, wrapped for use in IDAPython API. This is a great starting point if you're already familiar with IDC scripting.

• ida_funcs: This module gives you tools to create and manipulate functions within IDA.

• ida_kernwin: This module provides functionality to interact with IDA UI, so you can create custom dialogs and more.

Common variables and constants

When you start working with IDAPython, you'll realize that one of the most commonly passed variables is ea, which refers to the valid memory address (effective address). On the other hand, the BADADDR is a constant that indicates an invalid address. It is used to indicate that an operation (such as querying a function) has failed or returned an invalid result, or signify that a specific memory location is unusable. Whenever you're working with functions that return memory addresses, it's a best practice to check whether the result equals BADADDR to ensure the operation was successful.

Code snippets

Here you can check the most common functions grouped by topics and short code samples that can serve as building blocks for longer scripts. They are usually focused on performing one specific action and can be easily reusable in more complex scripts, which you can find later under examples.

Part 1: Navigating the disassembly—addresses and names

Get the current address:**

ea = idc.here()  # Get the current address
print(f"Current address: {hex(ea)}")

idc.get_screen_ea()

Set the current address

idc.jumpto(0x401000)  # Jump to address 0x401000

Get the minimum address in IDB

idc.get_inf_attr(INF_MIN_EA)

Get the maximum address in IDB

idc.get_inf_attr(INF_MAX_EA)

List all instruction addresses

for ea in idautils.Heads():
  print(hex(ea))

Get the name associated with a given address

ida_name.get_name(0x100000da0)

Get the address associated with a given name

ida_name.get_name_ea(0, "_main")

Part 2: Reading and Writing Data

Reading Bytes and Words

byte_value = idc.get_wide_byte(0x401000)  # Read a byte at address 0x401000
word_value = idc.get_wide_word(0x401002)  # Read a word (2 bytes) at address 0x401002
dword_value = idc.get_wide_dword(0x401004)  # Read a double word (4 bytes) at address 0x401004

print(f"Byte: {byte_value}, Word: {word_value}, Dword: {dword_value}")

Writing Bytes and Words

idc.patch_byte(0x401000, 0x90)  # Write a byte (0x90) at address 0x401000
idc.patch_word(0x401002, 0x9090)  # Write a word (0x9090) at address 0x401002
idc.patch_dword(0x401004, 0x90909090)  # Write a double word (0x90909090) at address 0x401004

Part 3: Comments

Add a regular (non-repetable) or repeatable comment

idc.set_cmt(0x401000, "This is a comment", 0)  # Add a regular comment at address 0x401000
idc.set_cmt(0x401000, "This is a repeatable comment", 1)  # Add a repeatable comment at address 0x401000

Get a regular comment

comment = idc.get_cmt(0x401000, 0)  # Get a regular comment at address 0x401000
print(f"Comment: {comment}")

Segments

Get a segment name

idc.get_segm_name(ea)

Get the first segment address:

get_first_seg()

Iterate through all segments and return segment names

for seg in idautils.Segments(): print (idc.get_segm_name(seg))

Add segment

Part X: Functions

Create and delete function

idc.add_func(0x401000, 0x401050)  # Create a function starting at 0x401000 and ending at 0x401050
idc.del_func(0x401000)  # Delete the function at 0x401000

Get the name of the function

get_func_name(ea)

Iterate through all functions and print their effective addresses and names

for func_ea in idautils.Functions(): func_name = idc.get_func_name(func_ea); print(hex(func_ea), func_name)

Part: Navigating cross-references (Xrefs)

List cross-references to an address

for xref in idautils.XrefsTo(0x401000):
    print(f"Xref to 0x401000 from {hex(xref.frm)}")

List cross-references from an address:**

for xref in idautils.XrefsFrom(0x401000):
    print(f"Xref from 0x401000 to {hex(xref.to)}")

Iterate through all cross-references to the specific address and print the address from where the reference originates.

for ref in idautils.XrefsTo(ea):
  print(hex(ref.frm))

Part X: UI

Set background color of a function

set_color(0x401000, idc.CIC_ITEM, 0x007fff)  # Set background color for the function starting at address 0x401000

Display a custom dialog

ida_kernwin.info("This is a custom message dialog. Good luck with learning IDAPython API!")

Complex script examples

If you feel more comfortable with IDAPython now, you can delve into more complex and advanced examples shipped with your IDA instance. You can find them in the python/examples folder where your IDA is installed or check them from our docs These collection gathered more advanced code samples, which usually make use of more modules and APIs.

What's next?

Delve into our tutorial on how to create your first custom plugin in IDAPython.