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
: Theida_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 systemidc
: 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.
Last updated
Was this helpful?