
ida-plugin-development
- GitHub stars
- 123
Install
/plugin install ida-plugin-development@HexRaysSARun it inside Claude Code after adding the marketplace with /plugin marketplace add HexRaysSA/ida-claude-plugins.
Contents
Discovered from sourceSkills 3
Domain API for IDA Pro
Use this skill to efficiently use the Domain API for IDA Pro, which is easier and more concise than the legacy IDA Python SDK.
Always prefer the IDA Domain API over the legacy low-level IDA Python SDK. The Domain API provides a clean, Pythonic interface that is easier to use and understand.
Documentation Resources
| Resource | URL |
|---|---|
| LLM-optimized overview | https://ida-domain.docs.hex-rays.com/llms.txt |
| Getting Started | https://ida-domain.docs.hex-rays.com/getting_started/index.md |
| Examples | https://ida-domain.docs.hex-rays.com/examples/index.md |
| API Reference | https://ida-domain.docs.hex-rays.com/ref/{module}/index.md |
Available API modules: bytes, comments, database, entries, flowchart, functions, heads, hooks, instructions, names, operands, segments, signature_files, strings, types, xrefs
To fetch specific API documentation, use URLs like:
https://ida-domain.docs.hex-rays.com/ref/functions/index.md- Function analysis APIhttps://ida-domain.docs.hex-rays.com/ref/xrefs/index.md- Cross-reference APIhttps://ida-domain.docs.hex-rays.com/ref/strings/index.md- String analysis API
Opening a Database
from ida_domain import Database
from ida_domain.database import IdaCommandOptions
# Open an existing .i64/.idb
ida_options = IdaCommandOptions(auto_analysis=False, new_database=False)
with Database.open("path/to/sample.i64", ida_options, save_on_close=False) as db:
pass
# Analyze a raw input file and create a new database
ida_options = IdaCommandOptions(
auto_analysis=True,
new_database=True,
output_database="path/to/cache/sample.i64",
load_resources=True,
)
with Database.open("path/to/input.exe", ida_options, save_on_close=True) as db:
pass
Commonly Used IdaCommandOptions
IdaCommandOptions maps directly to IDA command-line switches. Two options are especially common for headless analysis tools:
load_resources=True (maps to -R): loads MS Windows exe resources. Important for PE analysis that needs resource data.
plugin_options (maps to -O): pass options to IDA plugins. The most common use is disabling Lumina to prevent it from injecting bad or non-deterministic names:
ida_options = IdaCommandOptions(
auto_analysis=True,
new_database=True,
output_database=str(cache_path),
load_resources=True,
plugin_options="lumina:host=0.0.0.0 -Osecondary_lumina:host=0.0.0.0",
)
This sets both primary and secondary Lumina server addresses to 0.0.0.0, effectively disabling Lumina lookups. The plugin_options field is a raw string; build_args() emits -O{value} verbatim, so embedding -O inside the value for additional plugin options works correctly — the above produces -Olumina:host=0.0.0.0 -Osecondary_lumina:host=0.0.0.0.
Other useful fields: processor (-p), log_file (-L), script_file (-S), db_compression (-P). See the IdaCommandOptions docstring for the full list.
Transparent Database Cache for Headless Tools
For repeatable CLI tools, do not re-analyze raw binaries every run. Prefer this pattern:
- if the input is already an
.i64or.idb, use it directly - otherwise hash the raw input and use the SHA-256 as the cache key
- create
<cache>/<sha256>.i64on demand - serialize access with a lock file and an extra
.namcheck, because another IDA process may have the database unpacked - create the cached database with
save_on_close=True - reopen cached databases read-only with
save_on_close=False - after requesting auto-analysis, call
ida_auto.auto_wait()before querying
import contextlib
import fcntl
import hashlib
import os
import time
from pathlib import Path
import ida_auto
from ida_domain import Database
from ida_domain.database import IdaCommandOptions
DATABASE_POLL_INTERVAL = 0.25
DATABASE_ACCESS_TIMEOUT = 5.0
DATABASE_ANALYSIS_TIMEOUT = 120.0
def get_cache_dir() -> Path:
root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
return root / "your-tool"
def compute_sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as f:
for chunk in iter(lambda: f.read(65536), b""):
digest.update(chunk)
return digest.hexdigest()
def wait_for_repack(db_path: Path, timeout: float) -> None:
nam_path = db_path.with_suffix(".nam")
deadline = time.monotonic() + timeout
while nam_path.exists():
if time.monotonic() >= deadline:
raise RuntimeError(f"database appears busy: {db_path}")
time.sleep(DATABASE_POLL_INTERVAL)
@contextlib.contextmanager
def database_access_guard(db_path: Path, timeout: float):
wait_for_repack(db_path, timeout)
lock_path = Path(str(db_path) + ".lock")
lock_fd = lock_path.open("w")
deadline = time.monotonic() + timeout
try:
while True:
try:
fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
break
except OSError:
if time.monotonic() >= deadline:
raise RuntimeError(f"timed out waiting for lock: {db_path}")
time.sleep(DATABASE_POLL_INTERVAL)
wait_for_repack(db_path, max(0.0, deadline - time.monotonic()))
yield
finally:
fcntl.flock(lock_fd, fcntl.LOCK_UN)
lock_fd.close()
def resolve_database(file_path: Path) -> Path:
if file_path.suffix.lower() in {".i64", ".idb"}:
return file_path
cache_dir = get_cache_dir()
cache_dir.mkdir(parents=True, exist_ok=True)
cache_path = cache_dir / f"{compute_sha256(file_path)}.i64"
if cache_path.exists():
return cache_path
with database_access_guard(cache_path, DATABASE_ANALYSIS_TIMEOUT):
if cache_path.exists():
return cache_path
ida_options = IdaCommandOptions(
auto_analysis=True,
new_database=True,
output_database=str(cache_path),
load_resources=True,
)
with Database.open(str(file_path), ida_options, save_on_close=True):
ida_auto.auto_wait()
if not cache_path.exists():
raise RuntimeError(f"analysis did not create {cache_path}")
return cache_path
@contextlib.contextmanager
def open_database_session(db_path: Path, auto_analysis: bool = False):
with database_access_guard(db_path, DATABASE_ACCESS_TIMEOUT):
ida_options = IdaCommandOptions(auto_analysis=auto_analysis, new_database=False)
with Database.open(str(db_path), ida_options, save_on_close=False) as db:
if auto_analysis:
ida_auto.auto_wait()
yield db
Notes:
- keep cached database creation quiet in normal mode; only log cache paths in verbose/debug mode
- if you need a different cache policy, keep the same three-phase guard: wait for
.nam, acquireflock, re-check.nam - if you must fall back to
idapro.open_database(...)for options not exposed byida-domain, import your local project modules beforeimport idapro, becauseidaprocan mutatesys.path - disable Lumina via
plugin_options="lumina:host=0.0.0.0 -Osecondary_lumina:host=0.0.0.0"inIdaCommandOptions(see "Commonly Used IdaCommandOptions" above); no need to fall back toidapro.open_database()for this
Key Database Properties
with Database.open(path, ida_options) as db:
db.minimum_ea # Start address
db.maximum_ea # End address
db.metadata # Database metadata
db.architecture # Target architecture
db.functions # All functions (iterable)
db.strings # All strings (iterable)
db.segments # Memory segments
db.names # Symbols and labels
db.entries # Entry points
db.types # Type definitions
db.comments # All comments
db.xrefs # Cross-reference utilities
db.bytes # Byte manipulation
db.instructions # Instruction access
Functions
Iterating Functions
# Iterate all functions
for func in db.functions:
print(db.functions.get_name(func))
# Get function count
count = len(db.functions)
If your report needs thunk functions or library functions, iterate db.functions directly and classify them by flags. Do not assume a higher-level wrapper already included them.
Finding Functions
func = db.functions.get_at(0x401000) # By address
func = db.functions.get_function_by_name("main") # By name
func = db.functions.get_next(ea) # Next function after ea
# Functions in range
for func in db.functions.get_between(start_ea, end_ea):
print(func.start_ea)
Function Properties
name = db.functions.get_name(func)
signature = db.functions.get_signature(func)
flags = db.functions.get_flags(func) # Returns FunctionFlags
# Check function attributes
db.functions.is_far(func)
db.functions.does_return(func)
Function Code
# Get disassembly lines
lines = db.functions.get_disassembly(func, remove_tags=True)
# Get decompiled pseudocode
pseudocode = db.functions.get_pseudocode(func, remove_tags=True)
# Get microcode
microcode = db.functions.get_microcode(func, remove_tags=True)
Function Analysis
# Get instructions in function
for insn in db.functions.get_instructions(func):
print(insn.ea)
# Get flowchart for basic blocks
flowchart = db.functions.get_flowchart(func)
for block in flowchart:
print(f"Block: {block.start_ea:#x} - {block.end_ea:#x}")
# Get callers/callees
callers = db.functions.get_callers(func)
callees = db.functions.get_callees(func)
# Get function chunks
for chunk in db.functions.get_chunks(func):
print(f"Chunk: {chunk.start_ea:#x}, main={chunk.is_main}")
# Get data items within function
for data_ea in db.functions.get_data_items(func):
print(f"Data at {data_ea:#x}")
Thunk-Aware Analysis
If your tool renders callers/callees, API usage, or function summaries, resolve thunks once and reuse the result everywhere. A good default is:
- check
FunctionFlags.THUNK - follow only single-target thunk chains
- stop on cycles, zero-target chains, or multi-target chains
- cap the depth so malformed databases cannot loop forever
from ida_domain.functions import FunctionFlags
MAX_THUNK_DEPTH = 5
def resolve_thunk(db, func):
current = func
seen = set()
for _ in range(MAX_THUNK_DEPTH):
if not (db.functions.get_flags(current) & FunctionFlags.THUNK):
return current
if current.start_ea in seen:
return current
seen.add(current.start_ea)
callees = list(db.functions.get_callees(current))
if len(callees) != 1:
return current
current = callees[0]
return current
Use the resolved target consistently for:
- caller lists
- callee lists
- API/import classification
- attaching per-function metadata like matches or tags
Local Variables
# Get all local variables
lvars = db.functions.get_local_variables(func)
for lvar in lvars:
print(f"{lvar.name}: {lvar.type_str}, arg={lvar.is_argument}")
# Find variable by name
lvar = db.functions.get_local_variable_by_name(func, "result")
# Get variable references in pseudocode
refs = db.functions.get_local_variable_references(func, lvar)
for ref in refs:
print(f"Line {ref.line_number}: {ref.access_type} in {ref.context}")
Modifying Functions
db.functions.set_name(func, "new_name")
db.functions.set_comment(func, "This function does X", repeatable=False)
db.functions.create(ea) # Create function at address
db.functions.remove(ea) # Remove function at address
Instructions
Iterating Instructions
# All instructions in database
for insn in db.instructions:
print(db.instructions.get_disassembly(insn))
# Instructions in range
for insn in db.instructions.get_between(start_ea, end_ea):
print(insn.ea)
Getting Instructions
insn = db.instructions.get_at(ea) # Decode at address
insn = db.instructions.get_previous(ea) # Previous instruction
Instruction Properties
disasm = db.instructions.get_disassembly(insn)
mnemonic = db.instructions.get_mnemonic(insn) # "mov", "push", etc.
db.instructions.is_valid(insn)
Control Flow Analysis
db.instructions.is_call_instruction(insn) # Is this a call?
db.instructions.is_indirect_jump_or_call(insn) # Indirect jump/call?
db.instructions.breaks_sequential_flow(insn) # Stops flow (ret, jmp)?
Working with Operands
count = db.instructions.get_operands_count(insn)
operands = db.instructions.get_operands(insn) # List of Operand objects
for op in operands:
info = op.get_info()
print(f"Operand {op.number}: {op.type.name}")
if isinstance(op, RegisterOperand):
print(f" Register: {op.get_register_name()}")
elif isinstance(op, ImmediateOperand):
print(f" Value: 0x{op.get_value():x}")
elif isinstance(op, MemoryOperand):
if op.is_direct_memory():
print(f" Memory: 0x{op.get_address():x}")
Segments
Iterating Segments
for segment in db.segments:
name = db.segments.get_name(segment)
size = db.segments.get_size(segment)
print(f"{name}: {segment.start_ea:#x} - {segment.end_ea:#x}")
count = len(db.segments)
Finding Segments
seg = db.segments.get_at(0x401000) # Segment containing address
seg = db.segments.get_by_name(".text") # By name
Segment Properties
name = db.segments.get_name(segment)
size = db.segments.get_size(segment)
bitness = db.segments.get_bitness(segment) # 16, 32, or 64
seg_class = db.segments.get_class(segment) # "CODE", "DATA", etc.
Creating Segments
from ida_domain.segments import PredefinedClass, AddSegmentFlags
# Add segment with explicit range
seg = db.segments.add(
seg_para=0,
start_ea=0x1000,
end_ea=0x2000,
seg_name="MySegment",
seg_class=PredefinedClass.CODE
)
# Append segment after last one
seg = db.segments.append(seg_para=0, seg_size=0x1000, seg_name="NewSeg")
Modifying Segments
from ida_domain.segments import SegmentPermissions, AddressingMode
db.segments.set_name(segment, "new_name")
db.segments.set_permissions(segment, SegmentPermissions.READ | SegmentPermissions.EXEC)
db.segments.add_permissions(segment, SegmentPermissions.WRITE)
db.segments.remove_permissions(segment, SegmentPermissions.WRITE)
db.segments.set_addressing_mode(segment, AddressingMode.BIT64)
db.segments.set_comment(segment, "Code section", repeatable=False)
Strings
Iterating Strings
for string in db.strings:
print(f"{string.address:#x}: {string}")
# By index
first_string = db.strings[0]
count = len(db.strings)
Finding Strings
string = db.strings.get_at(0x402000) # String at address
# Strings in range
for s in db.strings.get_between(start_ea, end_ea):
print(s.contents)
String Properties
print(string.address) # Address
print(string.length) # Length in characters
print(string.type) # StringType enum
print(string.encoding) # Internal encoding
print(string.contents) # UTF-8 bytes
print(str(string)) # Decoded string
Rebuilding String List
from ida_domain.strings import StringListConfig, StringType
config = StringListConfig(
string_types=[StringType.C, StringType.C_16],
min_len=3,
only_ascii_7bit=False
)
db.strings.rebuild(config)
db.strings.clear() # Clear string list
Xrefs
Getting References TO an Address
# All xrefs to an address
for xref in db.xrefs.to_ea(target_ea):
print(f"{xref.from_ea:#x} -> {xref.to_ea:#x} ({xref.type.name})")
# Just code references
for ea in db.xrefs.code_refs_to_ea(target_ea, flow=False):
print(f"Code ref from {ea:#x}")
# Just data references
for ea in db.xrefs.data_refs_to_ea(target_ea):
print(f"Data ref from {ea:#x}")
# Call references only
for ea in db.xrefs.calls_to_ea(func_ea):
print(f"Called from {ea:#x}")
# Detailed caller information
for caller in db.xrefs.get_callers(func_ea):
print(f"Called from {caller.name} at {caller.ea:#x}")
Getting References FROM an Address
# All xrefs from an address
for xref in db.xrefs.from_ea(source_ea):
print(f"{xref.from_ea:#x} -> {xref.to_ea:#x}")
# Code/data refs from
for ea in db.xrefs.code_refs_from_ea(source_ea):
print(f"Code ref to {ea:#x}")
for ea in db.xrefs.calls_from_ea(source_ea):
print(f"Calls {ea:#x}")
Data Access Analysis
# Who reads this data?
for ea in db.xrefs.reads_of_ea(data_ea):
print(f"Read by {ea:#x}")
# Who writes to this data?
for ea in db.xrefs.writes_to_ea(data_ea):
print(f"Written by {ea:#x}")
XrefInfo Properties
xref.is_call # Is this a call reference?
xref.is_jump # Is this a jump reference?
xref.is_read # Is this a data read?
xref.is_write # Is this a data write?
xref.is_flow # Is this ordinary flow?
xref.user # Is this user-defined?
Names
Iterating Names
for ea, name in db.names:
print(f"{ea:#x}: {name}")
count = len(db.names)
Getting Names
name = db.names.get_at(0x401000)
ea, name = db.names[0] # By index
Setting Names
from ida_domain.names import SetNameFlags
db.names.set_name(ea, "my_function")
db.names.set_name(ea, "my_func", flags=SetNameFlags.CHECK) # Validate chars
db.names.force_name(ea, "func") # Creates func_2 if func exists
db.names.delete(ea) # Remove name
Name Properties
db.names.is_valid_name("my_name") # Check if valid
db.names.is_public_name(ea) # Is public?
db.names.is_weak_name(ea) # Is weak?
db.names.make_name_public(ea)
db.names.make_name_non_public(ea)
db.names.make_name_weak(ea)
db.names.make_name_non_weak(ea)
Demangling
from ida_domain.names import DemangleFlags
demangled = db.names.get_demangled_name(ea)
demangled = db.names.get_demangled_name(ea, DemangleFlags.NORETTYPE)
demangled = db.names.demangle_name("?main@@YAXXZ")
Types
Getting Types
# By name
tinfo = db.types.get_by_name("MyStruct")
# At address
tinfo = db.types.get_at(ea)
# Iterate all types
for tinfo in db.types:
print(tinfo)
Parsing Types
# Parse declarations from string
errors = db.types.parse_declarations(None, "struct Point { int x; int y; };")
# Parse single declaration
tinfo = db.types.parse_one_declaration(None, "int (*callback)(void*)", "callback_t")
# Parse header file
errors = db.types.parse_header_file(library, Path("header.h"))
Applying Types
from ida_domain.types import TypeApplyFlags
db.types.apply_at(tinfo, ea, flags=TypeApplyFlags.DEFINITE)
Type Details
details = db.types.get_details(tinfo)
print(details.name)
print(details.size)
print(details.attributes)
# For structs/unions
if details.udt:
print(details.udt.num_members)
print(details.udt.attributes)
# For functions
if details.func:
print(details.func.attributes)
Type Libraries
# Load/create libraries
lib = db.types.load_library(Path("types.til"))
lib = db.types.create_library(Path("new.til"), "My Types")
# Import/export types
db.types.import_type(source_lib, "MyStruct")
db.types.export_type(dest_lib, "MyStruct")
# Save library
db.types.save_library(lib, Path("output.til"))
db.types.unload_library(lib)
Bytes
Reading Values
byte = db.bytes.get_byte_at(ea)
word = db.bytes.get_word_at(ea)
dword = db.bytes.get_dword_at(ea)
qword = db.bytes.get_qword_at(ea)
float_val = db.bytes.get_float_at(ea)
double_val = db.bytes.get_double_at(ea)
# Read multiple bytes
data = db.bytes.get_bytes_at(ea, size=16)
original = db.bytes.get_original_bytes_at(ea, size=16)
# Read strings
string = db.bytes.get_string_at(ea)
cstring = db.bytes.get_cstring_at(ea, max_length=256)
Writing Values
db.bytes.set_byte_at(ea, 0x90)
db.bytes.set_word_at(ea, 0x1234)
db.bytes.set_dword_at(ea, 0x12345678)
db.bytes.set_qword_at(ea, 0x123456789ABCDEF0)
db.bytes.set_bytes_at(ea, b"\x90\x90\x90")
Patching (with History)
db.bytes.patch_byte_at(ea, 0x90) # Saves original
db.bytes.patch_bytes_at(ea, data)
db.bytes.revert_byte_at(ea) # Restore original
# Get original values
orig = db.bytes.get_original_byte_at(ea)
Searching
from ida_domain.bytes import SearchFlags
# Find bytes
ea = db.bytes.find_bytes_between(b"\x55\x89\xe5", start_ea, end_ea)
# Find all occurrences
addresses = db.bytes.find_binary_sequence(b"\x90\x90")
# Find text
ea = db.bytes.find_text_between("error", flags=SearchFlags.DOWN)
# Find immediate value
ea = db.bytes.find_immediate_between(0x1234)
Creating Data Items
from ida_domain.strings import StringType
db.bytes.create_byte_at(ea, count=4)
db.bytes.create_word_at(ea)
db.bytes.create_dword_at(ea, count=10) # Array of 10 dwords
db.bytes.create_qword_at(ea)
db.bytes.create_float_at(ea)
db.bytes.create_double_at(ea)
db.bytes.create_string_at(ea, string_type=StringType.C)
db.bytes.create_struct_at(ea, count=1, tid=struct_tid)
Querying Properties
size = db.bytes.get_data_size_at(ea)
db.bytes.is_value_initialized_at(ea)
db.bytes.is_code_at(ea)
db.bytes.is_data_at(ea)
db.bytes.is_head_at(ea)
db.bytes.is_tail_at(ea)
db.bytes.is_unknown_at(ea)
# Get disassembly at address
disasm = db.bytes.get_disassembly_at(ea)
Navigation
next_head = db.bytes.get_next_head(ea)
prev_head = db.bytes.get_previous_head(ea)
next_addr = db.bytes.get_next_address(ea)
prev_addr = db.bytes.get_previous_address(ea)
Comments
Regular Comments
from ida_domain.comments import CommentKind
# Get comment
info = db.comments.get_at(ea, CommentKind.REGULAR)
if info:
print(info.comment)
# Set comment
db.comments.set_at(ea, "This is important", CommentKind.REGULAR)
db.comments.set_at(ea, "Shows everywhere", CommentKind.REPEATABLE)
# Delete comment
db.comments.delete_at(ea, CommentKind.ALL)
Iterating Comments
for comment_info in db.comments:
print(f"{comment_info.ea:#x}: {comment_info.comment}")
# All comment types
for info in db.comments.get_all(CommentKind.ALL):
print(f"{info.ea:#x} (repeatable={info.repeatable}): {info.comment}")
Extra Comments (Anterior/Posterior)
from ida_domain.comments import ExtraCommentKind
# Set extra comment
db.comments.set_extra_at(ea, index=0, comment="Before line", kind=ExtraCommentKind.ANTERIOR)
db.comments.set_extra_at(ea, index=0, comment="After line", kind=ExtraCommentKind.POSTERIOR)
# Get extra comments
comment = db.comments.get_extra_at(ea, index=0, kind=ExtraCommentKind.ANTERIOR)
for comment in db.comments.get_all_extra_at(ea, ExtraCommentKind.ANTERIOR):
print(comment)
# Delete
db.comments.delete_extra_at(ea, index=0, kind=ExtraCommentKind.ANTERIOR)
Entries
Iterating Entry Points
for entry in db.entries:
print(f"{entry.ordinal}: {entry.name} at {entry.address:#x}")
count = len(db.entries)
first = db.entries[0]
Finding Entries
entry = db.entries.get_at(ea) # By address
entry = db.entries.get_by_ordinal(1) # By ordinal
entry = db.entries.get_by_name("main") # By name
entry = db.entries.get_at_index(0) # By index
Entry Properties
print(entry.ordinal)
print(entry.address)
print(entry.name)
print(entry.forwarder_name)
entry.has_forwarder()
Modifying Entries
db.entries.add(address=ea, name="new_entry", ordinal=10)
db.entries.rename(ordinal=10, new_name="renamed_entry")
db.entries.set_forwarder(ordinal=10, forwarder_name="other.dll!func")
db.entries.exists(ordinal=10)
Utility Iterators
for ordinal in db.entries.get_ordinals():
print(ordinal)
for addr in db.entries.get_addresses():
print(f"{addr:#x}")
for name in db.entries.get_names():
print(name)
for fwd in db.entries.get_forwarders():
print(f"{fwd.ordinal}: {fwd.name}")
Heads
Iterating Heads
for ea in db.heads:
print(f"Head at {ea:#x}")
# In range
for ea in db.heads.get_between(start_ea, end_ea):
print(ea)
Navigation
next_ea = db.heads.get_next(ea)
prev_ea = db.heads.get_previous(ea)
Head Properties
db.heads.is_head(ea) # Is start of item?
db.heads.is_tail(ea) # Is part of multi-byte item?
db.heads.is_code(ea) # Is instruction?
db.heads.is_data(ea) # Is data?
db.heads.is_unknown(ea) # Is unclassified?
size = db.heads.size(ea)
start, end = db.heads.bounds(ea)
Flowchart
Creating Flowcharts
from ida_domain.flowchart import FlowChart, FlowChartFlags
# From function
flowchart = FlowChart(db, func=my_func)
# From address range
flowchart = FlowChart(db, bounds=(start_ea, end_ea))
# With predecessor info
flowchart = FlowChart(db, func=my_func, flags=FlowChartFlags.PREDS)
Iterating Basic Blocks
for block in flowchart:
print(f"Block {block.id}: {block.start_ea:#x} - {block.end_ea:#x}")
# By index
block = flowchart[0]
count = len(flowchart)
Block Navigation
for succ in block.get_successors():
print(f"Successor: {succ.id}")
for pred in block.get_predecessors():
print(f"Predecessor: {pred.id}")
succ_count = block.count_successors()
pred_count = block.count_predecessors()
Block Instructions
for insn in block.get_instructions():
print(f"{insn.ea:#x}")
Enums Reference
XrefType
from ida_domain.xrefs import XrefType
XrefType.OFFSET # Offset reference
XrefType.WRITE # Write access
XrefType.READ # Read access
XrefType.CALL_FAR # Far call
XrefType.CALL_NEAR # Near call
XrefType.JUMP_FAR # Far jump
XrefType.JUMP_NEAR # Near jump
XrefType.ORDINARY_FLOW # Sequential flow
xref_type.is_code_ref() # Check if code ref
xref_type.is_data_ref() # Check if data ref
FunctionFlags
from ida_domain.functions import FunctionFlags
FunctionFlags.NORET # Doesn't return
FunctionFlags.LIB # Library function
FunctionFlags.THUNK # Thunk function
FunctionFlags.HIDDEN # Hidden chunk
FunctionFlags.LUMINA # From Lumina
FunctionFlags.FAR # Far function
FunctionFlags.FRAME # Uses frame pointer
LocalVariableAccessType
from ida_domain.functions import LocalVariableAccessType
LocalVariableAccessType.READ # Variable is read
LocalVariableAccessType.WRITE # Variable is written
LocalVariableAccessType.ADDRESS # Address taken (&var)
LocalVariableContext
from ida_domain.functions import LocalVariableContext
LocalVariableContext.ASSIGNMENT # var = expr
LocalVariableContext.CONDITION # if (var)
LocalVariableContext.CALL_ARG # func(var)
LocalVariableContext.RETURN # return var
LocalVariableContext.ARITHMETIC # var + 1
LocalVariableContext.COMPARISON # var == x
LocalVariableContext.ARRAY_INDEX # arr[var]
LocalVariableContext.POINTER_DEREF # *var
LocalVariableContext.CAST # (type)var
OperandType
from ida_domain.operands import OperandType
OperandType.REGISTER # Register
OperandType.MEMORY # Direct memory
OperandType.PHRASE # Register addressing
OperandType.DISPLACEMENT # Reg + displacement
OperandType.IMMEDIATE # Immediate value
OperandType.FAR_ADDRESS # Far address
OperandType.NEAR_ADDRESS # Near address
StringType
from ida_domain.strings import StringType
StringType.C # C-style null-terminated
StringType.C_16 # C-style 16-bit
StringType.C_32 # C-style 32-bit
StringType.PASCAL # Pascal-style
StringType.LEN2 # 2-byte length prefix
StringType.LEN4 # 4-byte length prefix
SegmentPermissions
from ida_domain.segments import SegmentPermissions
SegmentPermissions.READ
SegmentPermissions.WRITE
SegmentPermissions.EXEC
SegmentPermissions.ALL
AddressingMode
from ida_domain.segments import AddressingMode
AddressingMode.BIT16 # 16-bit segment
AddressingMode.BIT32 # 32-bit segment
AddressingMode.BIT64 # 64-bit segment
PredefinedClass
from ida_domain.segments import PredefinedClass
PredefinedClass.CODE
PredefinedClass.DATA
PredefinedClass.CONST
PredefinedClass.STACK
PredefinedClass.BSS
PredefinedClass.XTRN
CommentKind
from ida_domain.comments import CommentKind
CommentKind.REGULAR # Normal comment
CommentKind.REPEATABLE # Shows at all refs
CommentKind.ALL # Both types
ExtraCommentKind
from ida_domain.comments import ExtraCommentKind
ExtraCommentKind.ANTERIOR # Before the line
ExtraCommentKind.POSTERIOR # After the line
TypeAttr
from ida_domain.types import TypeAttr
TypeAttr.INT, TypeAttr.UINT
TypeAttr.FLOAT, TypeAttr.DOUBLE
TypeAttr.PTR, TypeAttr.ARRAY
TypeAttr.FUNC, TypeAttr.STRUCT
TypeAttr.UNION, TypeAttr.ENUM
TypeAttr.CONST, TypeAttr.VOLATILE
FlowChartFlags
from ida_domain.flowchart import FlowChartFlags
FlowChartFlags.NONE # Default
FlowChartFlags.NOEXT # Don't compute external blocks
FlowChartFlags.PREDS # Compute predecessors
Common Patterns
Find All Calls to a Function
func = db.functions.get_function_by_name("malloc")
if func:
for caller in db.xrefs.get_callers(func.start_ea):
print(f"Called from {caller.name} at {caller.ea:#x}")
Rename Functions Based on Strings
for func in db.functions:
for insn in db.functions.get_instructions(func):
for xref in db.xrefs.from_ea(insn.ea):
string = db.strings.get_at(xref.to_ea)
if string and "error" in str(string).lower():
db.functions.set_name(func, f"func_with_error_{func.start_ea:x}")
break
Analyze Function Complexity
func = db.functions.get_at(ea)
flowchart = db.functions.get_flowchart(func)
print(f"Basic blocks: {len(flowchart)}")
total_edges = sum(block.count_successors() for block in flowchart)
print(f"Cyclomatic complexity: {total_edges - len(flowchart) + 2}")
Export Function Pseudocode
for func in db.functions:
name = db.functions.get_name(func)
try:
pseudocode = db.functions.get_pseudocode(func)
print(f"// {name}")
for line in pseudocode:
print(line)
except RuntimeError:
print(f"// Could not decompile {name}")
Find Cross-References to Strings
for string in db.strings:
refs = list(db.xrefs.to_ea(string.address))
if refs:
print(f'"{string}" referenced from:')
for xref in refs:
print(f" {xref.from_ea:#x}")
Legacy API (Avoid)
The legacy idc, idautils, ida_funcs APIs still work but are harder to use. Prefer the Domain API for new analysis scripts. Only use legacy APIs when Domain API doesn't expose needed functionality.
Developing IDA Pro plugins
Use this skill when developing plugins for IDA Pro using Python.
IDA's UI and analysis passes can be almost completely replaced through plugins. There's a lot of power (and a lot of complexity), so its important to follow known patterns. This document lists tips and tricks for creating new plugins for modern versions of IDA.
Key concepts covered in this document:
- Use the IDA Domain API - prefer the high-level Pythonic interface
- Plugin Manager Integration - packaging and distribution
- Plugin Entry Point - version checking and conditional loading
- Hook Registration - pairwise register/unregister pattern
- Cross-Plugin Communication via IDC Functions - invoke plugin functionality from scripts/other plugins
- Save/Load state from netnodes - persist plugin data in IDB
- Respond to current address and selection change - UI location hooks
- Find widgets by prefix - managing multiple widget instances
- Context Menu Entries - "Send to Foo" patterns
- User Defined Prefix - add contextual markers in disassembly
- Viewer Hints - hover popups with context
- Overriding rendering - custom colors and mnemonics
- Custom Viewers - tagged lines with clickable addresses
Use the IDA Domain API
Always prefer the IDA Domain API over the legacy low-level IDA Python SDK. The Domain API provides a clean, Pythonic interface that is easier to use and understand. However, there will be some things that the Domain API doesn't cover, especially around plugin registration and GUI handling.
Right now: read this intro guide: https://ida-domain.docs.hex-rays.com/getting_started/index.md
Always refer to the documentation rather than doing introspection, because the documentation explains concepts, not just symbol names. To fetch specific API documentation, use URLs like:
https://ida-domain.docs.hex-rays.com/ref/functions/index.md- Function analysis APIhttps://ida-domain.docs.hex-rays.com/ref/xrefs/index.md- Cross-reference APIhttps://ida-domain.docs.hex-rays.com/ref/strings/index.md- String analysis API
Available API modules: bytes, comments, database, entries, flowchart, functions, heads, hooks, instructions, names, operands, segments, signature_files, strings, types, xrefs
URL pattern: https://ida-domain.docs.hex-rays.com/ref/{module}/index.md
You can always ask a subagent to answer a question by exploring the documentation and summarizing its findings.
Key Database Properties
with Database.open(path, ida_options) as db:
db.minimum_ea # Start address
db.maximum_ea # End address
db.metadata # Database metadata
db.architecture # Target architecture
db.functions # All functions (iterable)
db.strings # All strings (iterable)
db.segments # Memory segments
db.names # Symbols and labels
db.entries # Entry points
db.types # Type definitions
db.comments # All comments
db.xrefs # Cross-reference utilities
db.bytes # Byte manipulation
db.instructions # Instruction access
Common Analysis Tasks
List Functions
func: func_t
for func in db.functions:
name = db.functions.get_name(func)
print(f"{hex(func.start_ea)}: {name} ({func.size} bytes)")
Interesting func_t properties:
class func_t:
name: str
flags: int
start_ea: int
end_ea: int
size: int
does_return: bool
referers: list[int] # function start addresses
addresses: list[int]
frame_object: tinfo_t
prototype: tinfo_t
Cross-references
for xref in db.xrefs.to_ea(target_addr):
print(f"Referenced from {hex(xref.from_ea)} (type: {xref.type.name})")
for xref in db.xrefs.from_ea(source_addr):
print(f"References {hex(xref.to_ea)}")
for xref in db.xrefs.calls_to_ea(func_addr):
print(f"Called from {hex(xref.from_ea)}")
XrefInfo type:
XrefInfo(
from_ea: int,
to_ea: int,
is_code: bool,
type: XrefType,
user: bool,
)
Read data
db.bytes.get_byte_at(addr)
db.bytes.get_bytes_at(addr)
db.bytes.get_cstring_at(addr)
db.bytes.get_word_at(addr)
db.bytes.get_dword_at(addr)
db.bytes.get_qword_at(addr)
db.bytes.get_disassembly_at(addr)
db.bytes.get_flags_at(addr)
Plugin Manager Integration
Plugins must be compatible with the Hex-Rays Plugin Manager.
Making your plugin available via Plugin Manager offers several benefits:
- simplified plugin installation
- improved plugin discoverability through the central index
- easy Python dependency management
The key points to make your IDA plugin available via Plugin Manager are:
- Add
ida-plugin.json - Package your plugin into a ZIP archive (via source archives or GitHub Actions)
- Publish releases on GitHub
A complete ida-plugin.json example:
{
"IDAMetadataDescriptorVersion": 1,
"plugin": {
"name": "ida-terminal-plugin",
"entryPoint": "index.py",
"version": "1.0.0",
"idaVersions": ">=9.2",
"platforms": [
"windows-x86_64",
"linux-x86_64",
"macos-x86_64",
"macos-aarch64",
],
"description": "A lightweight terminal integration for IDA Pro that lets you open a fully functional terminal within the IDA GUI.\nQuickly access shell commands, scripts, or tooling without leaving your reversing environment.",
"license": "MIT",
"logoPath": "ida-plugin.png",
"categories": [
"ui-ux-and-visualization"
],
"keywords": [
"terminal",
"shell",
"cli",
],
"pythonDependencies": [
"pydantic>=2.12"
],
"urls": {
"repository": "https://github.com/williballenthin/idawilli"
},
"authors": [{
"name": "Willi Ballenthin",
"email": "wballenthin@hex-rays.com"
}],
"settings": [
{
"key": "theme",
"type": "string",
"required": true,
"default": "darcula",
"name": "color theme",
"documentation": "the color theme name, picked from https://windowsterminalthemes.dev/",
}
]
}
}
Before completing your work, review the following resources for packaging hints:
- https://hcli.docs.hex-rays.com/reference/plugin-repository-architecture/
- https://hcli.docs.hex-rays.com/reference/plugin-packaging-and-format/
- https://hcli.docs.hex-rays.com/reference/packaging-your-existing-plugin/
Use the script ./scripts/hcli-package.py to invoke HCLI in a consistent way and lint the current plugin.
Use ida-settings for configuration values
ida-settings is a Python library used by IDA Pro plugins to fetch configuration values from the shared settings infrastructure.
During plugin installation, the plugin manager prompts users for the configuration values and stores them in ida-config.json.
Subsequently, users can invoke HCLI (or later, the IDA Pro GUI) to update their configuration.
ida-settings is the library that plugins use to fetch the configuration values.
For example:
import ida_settings
api_key = ida_settings.get_current_plugin_setting("openai_key")
Note that this must be called from within the plugin (plugin_t or plugmod_t), not a callback or hook;
capture an instance of the plugin settings and pass it around as necessary:
class Hooks(idaapi.IDP_Hooks):
def __init__(self, settings):
super().__init__()
self.settings = settings
def ev_get_bg_color(self, color, ea):
mnem = ida_ua.print_insn_mnem(ea)
if mnem == "call" or mnem == "CALL":
bgcolor = ctypes.cast(int(color), ctypes.POINTER(ctypes.c_int))
bgcolor[0] = int(settings.get_setting("bg_color"))
return 1
else:
return 0
class FooPluginMod(ida_idaapi.plugmod_t):
def run(self, arg):
settings = ida_settings.get_current_plugin_settings()
self.hooks = Hooks(settings)
self.hooks.hook()
Available APIs are:
del(_current)_plugin_settingget(_current)_plugin_settinghas(_current)_plugin_settingset(_current)_plugin_settinglist(_current)_plugin_settings
Use standard logging module
Don't use print for status messages - use logging.* routines.
Do not configure logging from within a plugin - its up to the user to
configure which levels and sources they want to see in their output window.
Plugin Entry Point
The entrypoint of the plugin should be foo_entry.py
which imports from foo.py only if the environment is correct.
If the plugin runs in all IDA environments (assuming dependencies are present, which is reasonable), then you don't need a special wrapper like this.
For example, if the plugin requires Qt and/or IDA to be running graphically, you could do something like:
foo_entry.py:
import logging
import os
import ida_kernwin
logger = logging.getLogger(__name__)
def should_load():
"""Returns True if IDA 9.2+ is running interactively."""
if not ida_kernwin.is_idaq():
# https://community.hex-rays.com/t/how-to-check-if-idapythonrc-py-is-running-in-ida-pro-or-idalib/297/4
return False
if os.environ.get("IDA_IS_INTERACTIVE") != "1":
# https://community.hex-rays.com/t/how-to-check-if-idapythonrc-py-is-running-in-ida-pro-or-idalib/297/2
return False
kernel_version: tuple[int, ...] = tuple(
int(part) for part in ida_kernwin.get_kernel_version().split(".") if part.isdigit()
) or (0,)
if kernel_version < (9, 2): # type: ignore
logger.warning("IDA too old (must be 9.2+): %s", ida_kernwin.get_kernel_version())
return False
return True
if should_load():
# only attempt to import the plugin once we know the required dependencies are present.
# otherwise we'll hit ImportError and other problems
from foo import foo_plugin_t
def PLUGIN_ENTRY():
return foo_plugin_t()
else:
try:
import ida_idaapi
except ImportError:
import idaapi as ida_idaapi
class foo_nop_plugin_t(ida_idaapi.plugin_t):
flags = ida_idaapi.PLUGIN_HIDE | ida_idaapi.PLUGIN_UNL
wanted_name = "foo disabled"
comment = "foo is disabled for this IDA version"
help = ""
wanted_hotkey = ""
def init(self):
return ida_idaapi.PLUGIN_SKIP
# we have to define this symbol, or IDA logs a message
def PLUGIN_ENTRY():
# we have to return something here, or IDA logs a message
return foo_nop_plugin_t()
foo.py:
class foo_plugmod_t(ida_idaapi.plugmod_t):
def __init__(self):
# IDA doesn't invoke this for plugmod_t, only plugin_t
self.init()
def init(self):
# do things here that will always run,
# and don't require the menu entry (edit > plugins > ...) being selected.
#
# note: IDA doesn't call init, we do in __init__
if not ida_auto.auto_is_ok():
# don't capture events before auto-analysis is done, or we get all the system events.
#
# note:
# - when we first load a program, this plugin will be run before auto-analysis is complete
# (actually, before auto-analysis even starts).
# so auto_is_ok() returns False
# - when we load an existing IDB, auto_is_ok() return True.
# so we can safely use this to wait until auto-analysis is complete for the first time.
logger.debug("waiting for auto-analysis to complete before subscribing to events")
ida_auto.auto_wait()
logger.debug("auto-analysis complete, now subscribing to events")
...
def run(self, arg):
# do things here that users invoke via the menu entry (edit > plugins > ...)
...
def __del__(self):
# cleanup resources, unhook handlers, etc.
...
class foo_plugin_t(ida_idaapi.plugin_t):
flags = ida_idaapi.PLUGIN_MULTI
help = "Do some foo"
comment = ""
wanted_name = "Foo"
wanted_hotkey = ""
def init(self):
return foo_plugmod_t()
Hook Registration
Create pairwise helper functions for registering/unregistering hooks,
and call these from init/__del__
class oplog_plugmod_t(ida_idaapi.plugmod_t):
def __init__(self):
self.idb_hooks: IDBChangedHook | None = None
self.location_hooks: UILocationHook | None = None
...
def register_idb_hooks(self):
assert self.events is not None
self.idb_hooks = IDBChangedHook(self.events)
self.idb_hooks.hook()
def unregister_idb_hooks(self):
if self.idb_hooks:
self.idb_hooks.unhook()
def register_location_hooks(self):
assert self.events is not None
self.location_hooks = UILocationHook(self.events)
self.location_hooks.hook()
def unregister_location_hooks(self):
if self.location_hooks:
self.location_hooks.unhook()
def init(self):
...
self.register_idb_hooks()
self.register_location_hooks()
def run(self, arg):
...
def __del__(self):
# cleanup in reverse order
self.unregister_location_hooks()
self.unregister_idb_hooks()
...
Cross-Plugin Communication via IDC Functions
Python plugins can import shared libraries, and two plugins may even have the same dependencies. One plugin can import code from another plugin's module. However, to invoke functionality on a specific instance of a running plugin (accessing its state, calling methods that depend on instance data), you need a different mechanism.
Use ida_expr.add_idc_func to register a callable with a well-known name, and idc.eval_idc to invoke it from scripts or other plugins.
Key constraints:
- The function name must be globally unique - only one plugin should register a given name
- There's only a single provider for that name (no multiple instances registering the same name)
- The registering plugin must unregister the function during
__del__()
import ida_expr
class foo_plugmod_t(ida_idaapi.plugmod_t):
def __init__(self):
self.data: list[str] = []
self.init()
def register_idc_func(self):
data = self.data
def foo_get_data(index: int) -> str:
if 0 <= index < len(data):
return data[index]
return ""
def foo_add_data(value: str) -> int:
data.append(value)
return len(data)
if ida_expr.add_idc_func("foo_get_data", foo_get_data, (ida_expr.VT_LONG,)):
logger.debug("registered foo_get_data IDC function")
else:
logger.warning("failed to register foo_get_data IDC function")
if ida_expr.add_idc_func("foo_add_data", foo_add_data, (ida_expr.VT_STR,)):
logger.debug("registered foo_add_data IDC function")
else:
logger.warning("failed to register foo_add_data IDC function")
def unregister_idc_func(self):
ida_expr.del_idc_func("foo_get_data")
ida_expr.del_idc_func("foo_add_data")
def init(self):
self.register_idc_func()
def __del__(self):
self.unregister_idc_func()
Callers invoke the function via idc.eval_idc:
import idc
idc.eval_idc('foo_add_data("hello")')
result = idc.eval_idc('foo_get_data(0)')
Parameter types for add_idc_func:
ida_expr.VT_STR- string parameterida_expr.VT_LONG- integer parameterida_expr.VT_FLOAT- floating point parameter
This pattern is useful for:
- Exporting plugin data to external scripts (headless testing, automation)
- Allowing one plugin to trigger actions in another
- Providing a stable API for plugin functionality that doesn't depend on Python imports
Save/Load state from netnodes
Use netnodes to store data within the IDB. Serialize the current plugin state during shutdown, saving it to a netnode. Reload the state upon startup.
import pydantic
OUR_NETNODE = "$ com.williballenthin.idawilli.foo"
class State(pydantic.BaseModel):
...
def to_json(self):
return self.model_dump_json()
@classmethod
def from_json(cls, json_str: str):
return cls(State.model_validate_json(json_str))
def save_state(state: State):
buf = zlib.compress(state.to_json().encode("utf-8"))
node = ida_netnode.netnode(OUR_NETNODE)
node.setblob(buf, 0, "I")
logger.info("saved state")
def load_state() -> State:
node = ida_netnode.netnode(OUR_NETNODE)
if not node:
logger.info("no existing state")
return State()
buf = node.getblob(0, "I")
if not buf:
logger.info("no existing state (no data)")
return State()
state = State.from_json(zlib.decompress(buf).decode("utf-8"))
logger.info("loaded state")
return state
class UI_Closing_Hooks(ida_kernwin.UI_Hooks):
"""Respond to UI events and save the events into the database."""
# we could also use IDB_Hooks, but I found it less reliable:
# - closebase: "the database will be closed now", however, I couldn't figure out when its actually triggered.
# - savebase: notified during File -> Save, but not File -> Close.
# easier to keep all the hooks in one place.
def __init__(self, events: Events, *args, **kwargs):
super().__init__(*args, **kwargs)
self.events = events
def preprocess_action(self, action: str):
if action == "CloseBase":
# File -> Close
save_events(self.events)
return 0
elif action == "QuitIDA":
# File -> Quit
save_events(self.events)
return 0
elif action == "SaveBase":
# File -> Save
save_events(self.events)
return 0
else:
return 0
Respond to current address and selection change
class UILocationHook(ida_kernwin.UI_Hooks):
def handle_current_address_change(self, ea: int):
...
def handle_current_selection_change(self, start: int, end: int):
...
def screen_ea_changed(self, ea: ida_idaapi.ea_t, prev_ea: ida_idaapi.ea_t) -> None:
if ea == prev_ea:
return
v = ida_kernwin.get_current_viewer()
if ida_kernwin.get_widget_type(v) not in (
ida_kernwin.BWN_HEXVIEW,
ida_kernwin.BWN_DISASM,
# BWN_PSEUDOCODE
# BWN_CUSTVIEW
# BWN_OUTPUT the text area, in the output window
# BWN_CLI the command-line, in the output window
# BWN_STRINGS
# ...
):
return
if ida_kernwin.get_viewer_place_type(v) != ida_kernwin.TCCPT_IDAPLACE:
# other viewers might have other place types, when not address-oriented
return
has_range, start, end = ida_kernwin.read_range_selection(v)
if not has_range:
return self.handle_current_address_change(ea)
if ida_idaapi.BADADDR in (start, end):
return
return self.handle_current_selection_change(start, end)
Find widgets by prefix
def list_widgets(prefix: str) -> list[str]:
"""Probe A-Z for existing widgets, return found captions.
Args:
prefix: Caption prefix to search for
Returns: List of found widget captions (e.g., ["Foo-A", "Foo-C"])
"""
if not prefix.endswith("-"):
raise ValueError("prefix must end with dash")
found = []
for letter in "ABCDEFGHIJKLMNOPQRSTUVWXYZ":
caption = f"{prefix}{letter}"
if ida_kernwin.find_widget(caption) is not None:
found.append(caption)
return found
def find_next_available_caption(prefix: str) -> str:
"""Find first gap or next letter for widget caption.
Args:
prefix: Caption prefix to use
Returns: First available caption (e.g., "Foo-B")
Raises:
RuntimeError: If all 26 instances are in use
"""
if not prefix.endswith("-"):
raise ValueError("prefix must end with dash")
for letter in "ABCDEFGHIJKLMNOPQRSTUVWXYZ":
caption = f"{prefix}{letter}"
if ida_kernwin.find_widget(caption) is None:
return caption
raise RuntimeError("All 26 instances in use")
Context Menu Entries, "Send to Foo" and "Send to Foo-A"
When creating custom views, especially when there might be more than one, name them like "Foo-A", "Foo-B", etc. And, as appropriate, add context menu items for "sending" addresses/selections to the new views.
The new view is an instance of ida_kernwin.PluginForm and may have arbitrary Qt widgets.
The plugin instance maintains a registry of created views, and registers the action
handlers for opening new views, as well as notifying the views of events from a central place.
Action handlers encapsulate the code that's invoked during an event.
class FooForm(ida_kernwin.PluginForm):
def __init__(
self,
caption: str = "Foo-A",
form_registry: dict[str, "FooForm"] | None = None,
) -> None:
super().__init__()
self.TITLE = caption
self.form_registry = form_registry
def OnCreate(self, form):
self.parent = self.FormToPyQtWidget(form)
self.w = FooWidget(parent=self.parent, show_ida_buttons=True)
... # other Qt stuff here
if self.form_registry is not None:
self.form_registry[self.TITLE] = self
def OnClose(self, form):
if self.form_registry is not None:
self.form_registry.pop(self.TITLE, None)
class create_foo_widget_action_handler_t(ida_kernwin.action_handler_t):
def __init__(self, plugmod: "foo_plugmod_t", *args, **kwargs) -> None:
super().__init__(*args, **kwargs)
self.plugmod = plugmod
def activate(self, ctx):
self.plugmod.create_viewer()
def update(self, ctx):
return ida_kernwin.AST_ENABLE_ALWAYS
class send_to_foo_action_handler_t(ida_kernwin.action_handler_t):
"""Action handler for 'Send to Foo' context menu item."""
def __init__(self, plugmod: "foo_plugmod_t", *args, **kwargs) -> None:
super().__init__(*args, **kwargs)
self.plugmod = plugmod
def activate(self, ctx):
"""Handle 'Send to Foo' action - always creates new instance."""
v = ida_kernwin.get_current_viewer()
if ida_kernwin.get_widget_type(v) not in (
ida_kernwin.BWN_HEXVIEW,
ida_kernwin.BWN_DISASM,
):
# for example: only allow sending from hexview or disassembly view
return 0
form = self.plugmod.create_viewer()
if form and form.w:
... # do initialization
return 1
def update(self, ctx):
"""Enable action when there's a valid selection."""
v = ida_kernwin.get_current_viewer()
if ida_kernwin.get_widget_type(v) not in (
ida_kernwin.BWN_HEXVIEW,
ida_kernwin.BWN_DISASM,
):
# for example: only allow sending from hexview or disassembly view
return ida_kernwin.AST_DISABLE
return ida_kernwin.AST_ENABLE
class send_to_specific_widget_action_handler_t(ida_kernwin.action_handler_t):
"""Action handler for sending to a specific Foo instance."""
def __init__(
self,
form_registry: dict[str, FooForm],
caption: str,
*args,
**kwargs,
) -> None:
super().__init__(*args, **kwargs)
self.form_registry = form_registry
self.caption = caption
def activate(self, ctx):
"""Send selection to specific Foo instance."""
v = ida_kernwin.get_current_viewer()
widget = ida_kernwin.find_widget(self.caption)
if widget is None:
logger.warning(f"Widget {self.caption} not found")
return 0
ida_kernwin.activate_widget(widget, True)
form = self.form_registry.get(self.caption)
if form and hasattr(form, "w"):
# access some specific model methods on the form
...
else:
logger.warning(f"Cannot populate {self.caption} - unable to access form")
return 1
def update(self, ctx):
"""Enable action when there's a valid selection."""
v = ida_kernwin.get_current_viewer()
if ida_kernwin.get_widget_type(v) not in (
ida_kernwin.BWN_HEXVIEW,
ida_kernwin.BWN_DISASM,
):
# for example: only allow sending from hexview or disassembly view
return ida_kernwin.AST_DISABLE
return ida_kernwin.AST_ENABLE
class foo_plugmod_t(ida_idaapi.plugmod_t):
ACTION_NAME = "foo:create"
SEND_ACTION_NAME = "foo:send_selection"
MENU_PATH = "View/Open subviews/Foo"
def __init__(self):
super().__init__()
self.form_registry: dict[str, FooForm] = {}
...
def register_instance_actions(self):
"""Register actions for all existing widget instances."""
existing = list_widgets("Foo-")
for caption in existing:
action_name = f"foo:send_to_{caption.replace('-', '_').lower()}"
if ida_kernwin.unregister_action(action_name):
pass
ida_kernwin.register_action(
ida_kernwin.action_desc_t(
action_name,
f"Send to {caption}",
send_to_specific_widget_action_handler_t(
self.form_registry, caption
),
None,
f"Send selected bytes to {caption}",
-1,
)
)
def create_viewer(self, caption: str | None = None) -> FooForm:
if caption is None:
caption = find_next_available_caption()
form = FooForm(caption, self.form_registry)
form.Show(form.TITLE)
return form
def register_open_action(self):
ida_kernwin.register_action(
ida_kernwin.action_desc_t(
self.ACTION_NAME,
"Foo",
create_foo_widget_action_handler_t(self),
)
)
# TODO: add icon
ida_kernwin.attach_action_to_menu(
self.MENU_PATH, self.ACTION_NAME, ida_kernwin.SETMENU_APP
)
def unregister_open_action(self):
ida_kernwin.unregister_action(self.ACTION_NAME)
ida_kernwin.detach_action_from_menu(self.MENU_PATH, self.ACTION_NAME)
def init(self):
self.register_open_action()
...
def run(self, arg):
self.create_viewer()
def __del__(self):
...
self.unregister_open_action()
User Defined Prefix
A user defined prefix is a great way to add some contextual data before each disassembly line. Put symbols or numbers here to indicate there's more context available somewhere.
def refresh_disassembly():
ida_kernwin.request_refresh(ida_kernwin.IWID_DISASM)
class FooPrefix(ida_lines.user_defined_prefix_t):
ICON = " β "
def __init__(self, marks: set[int]):
super().__init__(len(self.ICON))
self.marks = marks
def get_user_defined_prefix(self, ea, insn, lnnum, indent, line):
if ea in self.marks:
# wrap the icon in color tags so its easy to identify.
# otherwise, the icon may merge with other spans, which
# makes checking for equality more difficult.
return ida_lines.COLSTR(self.ICON, ida_lines.SCOLOR_SYMBOL)
return " " * len(self.ICON)
class FooPrefixPluginMod(ida_idaapi.plugmod_t):
def __init__(self):
self.marks: set[int] = {1, 2, 3}
self.prefixer: FooPrefix | None = None
def run(self, arg):
# self.prefixer is installed simply by constructing it
self.prefixer = FooPrefix(self.marks)
# since we're updating the disassembly listing by adding the line prefix,
# we need to re-render all the lines.
refresh_disassembly()
def __del__(self):
# gc will clean up prefixer and uninstall it (during plugin termination)
self.prefixer = None
# refresh and remove the prefix entries
refresh_disassembly()
Viewer Hints
A view hint is a really good way to display complex information in a popup hover pane that displays when mousing over particular regions of an IDA view. Use this to show context about a symbol or address, for example: MSDN documentation for API functions.
Use this in combination with User Defined Prefixes that indicate context is available and show the context in the viewer hint (possibly when hovering over the prefix).
class FooHints(ida_kernwin.UI_Hooks):
def __init__(self, notes: dict[int, str], *args, **kwargs):
super().__init__(*args, **kwargs)
self.notes = notes
def get_custom_viewer_hint(self, viewer, place):
if not place:
return
ea = place.toea()
if not ea:
return
if ea not in self.notes:
return
curline = ida_kernwin.get_custom_viewer_curline(viewer, True)
curline = ida_lines.tag_remove(curline)
_, x, _ = ida_kernwin.get_custom_viewer_place(viewer, True)
# example: show on first column
# more advanced: inspect the symbol, and if it matches a query, then show some data
if x == 1:
note = self.notes.get(ea)
if not note:
return
return (f"note: {note}", 1)
class FooHintsPluginMod(ida_idaapi.plugmod_t):
def __init__(self):
self.notes: dict[int, str] = {}
self.hinter: FooHints | None = None
def run(self, arg):
self.hinter = FooHints(self.notes)
self.hinter.hook()
def __del__(self):
if self.hinter is not None:
self.hinter.unhook()
self.hinter = None
Overriding rendering
class ColorHooks(idaapi.IDP_Hooks):
def ev_get_bg_color(self, color, ea):
"""
Get item background color.
Plugins can hook this callback to color disassembly lines dynamically
// background color in RGB
typedef uint32 bgcolor_t;
ref: https://hex-rays.com/products/ida/support/sdkdoc/pro_8h.html#a3df5040891132e50157aee66affdf1de
args:
color: (bgcolor_t *), out
ea: (::ea_t)
returns:
retval 0: not implemented
retval 1: color set
"""
mnem = ida_ua.print_insn_mnem(ea)
if mnem == "call" or mnem == "CALL":
bgcolor = ctypes.cast(int(color), ctypes.POINTER(ctypes.c_int))
bgcolor[0] = 0xDDDDDD
return 1
else:
return 0
def ev_out_mnem(self, ctx) -> int:
"""
Generate instruction mnemonics.
This callback should append the colored mnemonics to ctx.outbuf
Optional notification, if absent, out_mnem will be called.
args:
ctx: (outctx_t *)
returns:
retval 1: if appended the mnemonics
retval 0: not implemented
"""
mnem = ctx.insn.get_canon_mnem()
if mnem == "call":
# you can manipulate this, but note that it affects `ida_ua.print_insn_mnem` which is inconvenient for formatting.
# also, you only have access to theme colors, like COLOR_PREFIX, not arbitrary control.
ctx.out_custom_mnem("CALL")
return 1
else:
return 0
class ColoringPluginMod(ida_idaapi.plugmod_t):
def __init__(self):
self.hooks: ColorHooks | None = None
def run(self, arg):
self.hooks = ColorHooks()
self.hooks.hook()
def __del__(self):
if self.hooks is not None:
self.hooks.unhook()
self.hooks = None
Custom Viewers
Use a custom viewer to show text data, optionally with tags, and respond to basic events (clicks). Use the tagged line concepts to embed and parse metadata about the symbols in a line, such as which address it refers to.
def addr_from_tag(raw: bytes) -> int:
assert raw[0] == 0x01 # ida_lines.COLOR_ON
assert raw[1] == ida_lines.COLOR_ADDR
addr_hex = raw[2 : 2 + ida_lines.COLOR_ADDR_SIZE].decode("ascii")
try:
# Parse as hex address (IDA uses qsscanf with "%a" format)
return int(addr_hex, 16)
except ValueError:
raise
def get_tagged_line_section_byte_offsets(section: ida_kernwin.tagged_line_section_t) -> tuple[int, int]:
# tagged_line_section_t.byte_offsets is not exposed by swig
# so we parse directly from the string representation (puke)
s = str(section)
text_start_index = s.index("text_start=")
text_end_index = s.index("text_end=")
text_start_s = s[text_start_index + len("text_start=") :].partition(",")[0]
text_end_s = s[text_end_index + len("text_end=") :].partition("}")[0]
return int(text_start_s), int(text_end_s)
@dataclass
class TaggedLineSection:
tag: int
string: str
# valid when the found tag section starts with an embedded address
address: int | None
def get_current_tag(line: str, x: int) -> TaggedLineSection:
ret = TaggedLineSection(ida_lines.COLOR_DEFAULT, line, None)
tls = ida_kernwin.tagged_line_sections_t()
if not ida_kernwin.parse_tagged_line_sections(tls, line):
return ret
# find any section at the X coordinate
current_section = tls.nearest_at(x, 0) # 0 = any tag
if not current_section:
# TODO: we only want the section that isn't tagged
# while there might be a section totally before or totally after x.
return ret
ret.tag = current_section.tag
boring_line = ida_lines.tag_remove(line)
ret.string = boring_line[current_section.start : current_section.start + current_section.length]
# try to find an embedded address at the start of the current segment
current_section_start, _ = get_tagged_line_section_byte_offsets(current_section)
addr_section = tls.nearest_before(current_section, x, ida_lines.COLOR_ADDR)
if addr_section:
addr_section_start, _ = get_tagged_line_section_byte_offsets(addr_section)
# addr_section_start initially points just after the address data (ON ADDR 001122...FF)
# so rewind to the start of the tag (16 bytes of hex integer, 2 bytes of tags "ON ADDR")
addr_tag_start = addr_section_start - (ida_lines.COLOR_ADDR_SIZE + 2)
assert addr_tag_start >= 0
# and this should match current_section_start, since that points just after the tag "ON SYMBOL"
# if it doesn't, we're dealing with an edge case we didn't prepare for
# maybe like multiple ADDR tags or something.
# skip those and stick to things we know.
if current_section_start == addr_tag_start:
raw = line.encode("utf-8")
addr = addr_from_tag(raw[addr_tag_start : addr_tag_start + ida_lines.COLOR_ADDR_SIZE + 2])
ret.address = addr
return ret
class foo_viewer_t(ida_kernwin.simplecustviewer_t):
TITLE = "foo"
def __init__(self):
super().__init__()
self.timer: QtCore.QTimer = QtCore.QTimer()
self.timer.timeout.connect(self.on_timer_timeout)
def Create(self):
if not super().Create(self.TITLE):
return False
self.render()
return True
def Show(self, *args):
if not super().Show(*args):
return False
ida_kernwin.attach_action_to_popup(self.GetWidget(), None, some_action_handler_t.ACTION_NAME)
return True
def on_timer_timeout(self):
self.render()
def OnClose(self):
self.timer.stop()
def render(self):
self.ClearLines()
self.AddLine(datetime.datetime.now.isoformat())
self.AddLine(ida_lines.COLSTR(ida_lines.tag_addr(0x401000) + "sub_401000", ida_lines.SCOLOR_CNAME))
def OnDblClick(self, shift):
line = self.GetCurrentLine()
if not line:
return False
_linen, x, _y = self.GetPos()
section = get_current_tag(line, x)
if section.address is not None:
ida_kernwin.jumpto(section.address)
item_address = ida_name.get_name_ea(0, section.string)
if item_address != ida_idaapi.BADADDR:
logger.debug(f"found address for '{section.string}': {item_address:x}")
ida_kernwin.jumpto(item_address)
return True # handled
Packaging IDA Pro Plugins
This skill helps package IDA Pro plugins for distribution via the IDA Plugin Manager and the plugins.hex-rays.com repository. It covers creating and updating the ida-plugin.json manifest, packaging archives, and publishing via GitHub Releases.
Overview
The IDA Plugin Manager is a self-service ecosystem for discovering, installing, and sharing IDA plugins:
- Discovery: A daily indexer scans GitHub for repositories containing
ida-plugin.json - Repository: Published at plugins.hex-rays.com and github.com/HexRaysSA/plugin-repository
- Client: HCLI command-line tool (
hcli plugin install <name>) - Compatibility: IDA Pro 9.0+ (full support)
Critical: Understanding Plugin Root Directory
The ida-plugin.json file defines the root of the plugin. When a plugin is installed, only the directory containing ida-plugin.json (and its subdirectories) is copied to $IDAUSR/plugins/. Nothing outside this directory is included.
Assessing Directory Structure Compatibility
Before packaging, verify that your plugin's structure is self-contained:
# GOOD: All plugin code is in the same directory as ida-plugin.json
my-repo/
├── ida-plugin.json # Plugin root
├── my_plugin.py # Entry point - INCLUDED
├── my_plugin_lib/ # Supporting code - INCLUDED
│ └── helpers.py
├── README.md # Plugin README - INCLUDED (shown on web)
└── assets/
└── logo.png # Logo - INCLUDED
# BAD: Plugin code outside the ida-plugin.json directory
my-repo/
├── plugin/
│ └── ida-plugin.json # Plugin root is here
├── src/ # NOT INCLUDED - outside plugin root!
│ └── my_plugin.py # This file won't be installed!
└── README.md # NOT INCLUDED - wrong directory!
Compatibility Checklist
When assessing an existing plugin, verify:
- Entry point location: Is
entryPointin the same directory asida-plugin.json? - All imports resolvable: Are all Python imports within the plugin root or in
pythonDependencies? - No parent directory references: Does the code use
../to access files outside the plugin root? - Assets included: Are logos, data files, or resources inside the plugin root?
- README placement: Is
README.mdin the plugin root (not repo root) for web display?
Common Restructuring Patterns
Pattern 1: Plugin in subdirectory
If your plugin code is in a subdirectory like src/ or plugin/, move ida-plugin.json into that directory:
# Before # After
my-repo/ my-repo/
├── ida-plugin.json └── src/
└── src/ ├── ida-plugin.json # Moved here
└── my_plugin.py ├── my_plugin.py
└── README.md # Add for web
Pattern 2: Monorepo with IDA plugin
For projects where IDA plugin is one component (e.g., capa), place ida-plugin.json at the plugin code's location:
capa/
├── capa/
│ ├── ida/
│ │ └── plugin/
│ │ ├── ida-plugin.json # Plugin root
│ │ ├── capa_explorer.py # Entry point
│ │ └── README.md # Plugin-specific docs
│ └── main.py # Not included in IDA plugin
└── README.md # Repo README - not the plugin README
README in Plugin Root
Place a README.md file in the same directory as ida-plugin.json to have it displayed on the plugins.hex-rays.com web interface. This is separate from your repository's root README:
my-plugin/
├── ida-plugin.json
├── my_plugin.py
└── README.md # This README appears on plugins.hex-rays.com
The plugin README should focus on:
- What the plugin does
- How to use it within IDA
- Configuration options (if using settings)
- Screenshots or examples
It does not need installation instructions (the Plugin Manager handles that).
The ida-plugin.json Manifest
Every plugin requires an ida-plugin.json file in its root directory. This is the only required file beyond the plugin code itself. Paths in the metadata file are relative to the metadata file, because the metadata file defines the root of the plugin, even if its nested within a ZIP archive.
Complete Schema
{
"IDAMetadataDescriptorVersion": 1,
"plugin": {
"name": "my-plugin",
"version": "1.0.0",
"entryPoint": "my_plugin.py",
"description": "A one-line description of what this plugin does",
"license": "MIT",
"urls": {
"repository": "https://github.com/org/my-plugin",
"homepage": "https://example.com/my-plugin"
},
"authors": [
{"name": "Author Name", "email": "author@example.com"}
],
"maintainers": [
{"name": "Maintainer Name", "email": "maintainer@example.com"}
],
"idaVersions": ["9.0", "9.1", "9.2"],
"platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"],
"categories": ["malware-analysis"],
"keywords": ["analysis", "automation"],
"pythonDependencies": ["requests>=2.0", "pydantic>=2"],
"logoPath": "assets/logo.png",
"settings": []
}
}
Required Fields
| Field | Type | Description |
|---|---|---|
IDAMetadataDescriptorVersion | 1 | Always set to 1 |
plugin.name | string | Unique identifier. ASCII letters, digits, underscores, hyphens only. No leading/trailing _ or -. Used to derive the IDA namespace: __plugins__my_plugin |
plugin.version | string | Semantic version x.y.z format. No leading v |
plugin.entryPoint | string | Entry point filename (e.g., my_plugin.py) or bare name for native plugins |
plugin.urls.repository | string | GitHub URL: https://github.com/org/project |
plugin.authors OR plugin.maintainers | array | At least one contact with email field required |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
plugin.description | string | none | One-line description shown in search results |
plugin.license | string | none | License identifier (e.g., MIT, Apache-2.0, GPL-3.0) |
plugin.urls.homepage | string | none | Homepage URL if different from repository |
plugin.idaVersions | array or string | all versions | Supported IDA versions. Can be explicit list ["9.0", "9.1"] or spec ">=7.4" |
plugin.platforms | array | all platforms | Supported platforms: windows-x86_64, linux-x86_64, macos-x86_64, macos-aarch64 |
plugin.categories | array | [] | See Categories section below |
plugin.keywords | array | [] | Search terms for discoverability |
plugin.pythonDependencies | array or "inline" | [] | PyPI packages. Use "inline" for PEP 723 metadata |
plugin.logoPath | string | none | Relative path to logo image (16:9 aspect ratio recommended) |
plugin.settings | array | [] | Plugin configuration options. See Settings section |
Valid Categories
disassembly-and-processor-modules
file-parsers-and-loaders
decompilation
debugging-and-tracing
deobfuscation
collaboration-and-productivity
integration-with-third-parties-interoperability
api-scripting-and-automation
ui-ux-and-visualization
malware-analysis
vulnerability-research-and-exploit-development
other
Valid IDA Versions
Current/supported: 9.2, 9.1, 9.0sp1, 9.0, ...
Use a version specifier like ">=9.0" to match multiple versions automatically.
Packaging Pure Python Plugins
For simple Python plugins, the directory structure is minimal:
my-plugin/
├── ida-plugin.json
├── README.md # Displayed on plugins.hex-rays.com
├── my_plugin.py # entryPoint
└── my_plugin_lib/ # optional supporting modules
├── __init__.py
└── helpers.py
Minimal Example
{
"IDAMetadataDescriptorVersion": 1,
"plugin": {
"name": "my-simple-plugin",
"version": "1.0.0",
"entryPoint": "my_plugin.py",
"urls": {
"repository": "https://github.com/username/my-simple-plugin"
},
"authors": [
{"name": "Your Name", "email": "you@example.com"}
]
}
}
With Dependencies
{
"IDAMetadataDescriptorVersion": 1,
"plugin": {
"name": "capa",
"version": "9.3.1",
"entryPoint": "capa_explorer.py",
"description": "Identify capabilities in executable files using FLARE's capa framework",
"license": "Apache-2.0",
"idaVersions": ">=7.4",
"categories": ["malware-analysis", "api-scripting-and-automation", "ui-ux-and-visualization"],
"pythonDependencies": ["flare-capa==9.3.1"],
"urls": {
"repository": "https://github.com/mandiant/capa"
},
"authors": [
{"name": "Willi Ballenthin", "email": "wballenthin@hex-rays.com"},
{"name": "Moritz Raabe", "email": "moritzraabe@google.com"}
],
"keywords": ["capability-detection", "malware-analysis", "att&ck", "static-analysis"]
}
}
PEP 723 Inline Dependencies
If your plugin uses PEP 723 inline script metadata, set pythonDependencies to "inline":
{
"pythonDependencies": "inline"
}
Then in your entry point Python file:
# /// script
# dependencies = [
# "requests>=2.0",
# "pydantic>=2"
# ]
# ///
import ida_kernwin
# ... rest of plugin
Packaging Native Plugins
Native plugins require compiled binaries (.dll, .so, .dylib) for each target platform.
Directory Structure
my-native-plugin/
├── ida-plugin.json
├── README.md # Displayed on plugins.hex-rays.com
├── my_plugin.dll # Windows
├── my_plugin.so # Linux
└── my_plugin.dylib # macOS (universal or architecture-specific)
Entry Point Convention
For native plugins, use a bare name without extension:
{
"plugin": {
"entryPoint": "my_plugin",
"platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"]
}
}
IDA will automatically append the correct extension (.dll, .so, .dylib) for the current platform.
Fat Binary Archives
Include all platform binaries in a single archive. The entry point uses the bare name, and the correct binary is selected at install time.
Platform-Specific Archives
Alternatively, create separate archives per platform with explicit extensions:
Windows archive:
{
"plugin": {
"entryPoint": "my_plugin.dll",
"platforms": ["windows-x86_64"]
}
}
Linux archive:
{
"plugin": {
"entryPoint": "my_plugin.so",
"platforms": ["linux-x86_64"]
}
}
Plugin Settings
For plugins requiring user configuration, declare settings in the manifest. Users configure these via hcli plugin config or the IDA GUI.
Settings Schema
{
"settings": [
{
"key": "api_key",
"name": "API Key",
"type": "string",
"required": true,
"documentation": "Your API key for the service"
},
{
"key": "endpoint",
"name": "API Endpoint",
"type": "string",
"required": false,
"default": "https://api.example.com",
"validation_pattern": "^https://.*$"
},
{
"key": "log_level",
"name": "Log Level",
"type": "string",
"required": false,
"choices": ["debug", "info", "warning", "error"],
"default": "info"
},
{
"key": "enable_telemetry",
"name": "Enable Telemetry",
"type": "boolean",
"required": false,
"default": false
}
]
}
Setting Fields
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | Code-level identifier (e.g., api_key) |
name | string | yes | Human-readable label (e.g., API Key) |
type | "string" or "boolean" | yes | Value type |
required | boolean | yes | Whether user must provide a value |
documentation | string | no | Help text for users |
default | string or boolean | no | Default value if not configured |
validation_pattern | string | no | Regex for validating string values |
choices | array of strings | no | Allowed values (mutually exclusive with validation_pattern) |
Accessing Settings in Plugin Code
Use the ida-settings library:
from ida_settings import get_current_plugin_setting
api_key = get_current_plugin_setting("api_key")
log_level = get_current_plugin_setting("log_level")
Validation
Always validate before publishing:
# Validate a directory
hcli plugin lint /path/to/my-plugin
# Validate a ZIP archive
hcli plugin lint /path/to/my-plugin.zip
The linter checks:
- JSON syntax and schema compliance
- Required fields present
- Entry point file exists
- Logo file exists (if declared)
- Platform/binary consistency
- Path safety (no traversals)
Publishing to the Repository
Step 1: Create a GitHub Release
- Tag your commit:
git tag v1.0.0 && git push --tags - Create a GitHub Release from the tag
- Attach your plugin archive (ZIP)
Step 2: Automatic Indexing
The indexer runs daily and automatically discovers:
- Repositories with
ida-plugin.jsonin the root - GitHub Releases with valid plugin archives
No manual registration required. Your plugin appears within 24 hours.
Step 3: Explicit Registration (Optional)
To expedite indexing, add your repository to known-repositories.txt:
- Fork HexRaysSA/plugin-repository
- Add your repo URL to
known-repositories.txt(one per line) - Submit a pull request
Troubleshooting Indexing
Check the indexer log report for errors.
Common issues:
- Invalid JSON syntax
- Missing required fields (especially author email)
- Repository URL doesn't match GitHub pattern
- Entry point file not found in archive
Multi-Plugin Archives
A single archive can contain multiple plugins, each in its own subdirectory:
multi-plugin.zip
├── plugin-a/
│ ├── ida-plugin.json
│ └── plugin_a.py
└── plugin-b/
├── ida-plugin.json
└── plugin_b.py
Each subdirectory must have its own ida-plugin.json.
Version Updates
To release a new version:
- Update
plugin.versioninida-plugin.json - Create a new git tag matching the version
- Create a GitHub Release with the new archive
- The indexer will pick up the new version automatically
Users upgrade via: hcli plugin upgrade <name>
Common Patterns
Minimal Python Plugin Checklist
- Create
ida-plugin.jsonwith required fields - Ensure entry point file exists
- Add author with email
- Run
hcli plugin lint - Create GitHub Release with source archive
Adding Settings to Existing Plugin
- Define settings array in
ida-plugin.json - Add
ida-settingstopythonDependenciesif using the library - Update plugin code to use
get_current_plugin_setting() - Document settings in README
Converting Legacy Plugin
- Assess directory structure: Verify all plugin code is self-contained
- Entry point and all imports within one directory
- No
../references to parent directories - Data files and assets colocated with code
- Restructure if needed: Move
ida-plugin.jsonto where the plugin code lives - Create
ida-plugin.jsonwith required fields - Set correct
entryPoint(relative toida-plugin.json) - Add appropriate
idaVersions(test compatibility!) - Declare
pythonDependenciesfrom requirements.txt - Add
README.mdin plugin root for web display - Validate and test locally:
hcli plugin lint - Create GitHub Release
HCLI Commands Reference
# List available plugins
hcli plugin list
# Search plugins
hcli plugin search <query>
# Install a plugin
hcli plugin install <name>
hcli plugin install <name>==1.0.0
# Upgrade a plugin
hcli plugin upgrade <name>
# Uninstall a plugin
hcli plugin uninstall <name>
# List installed plugins
hcli plugin list --installed
# Configure plugin settings
hcli plugin config <name> set <key> <value>
hcli plugin config <name> get <key>
# Validate plugin
hcli plugin lint /path/to/plugin
Resources
- Plugin Repository: plugins.hex-rays.com
- Documentation: hcli.docs.hex-rays.com
- Repository Source: github.com/HexRaysSA/plugin-repository
- HCLI Source: github.com/HexRaysSA/ida-hcli
- IDA Settings Library: github.com/williballenthin/ida-settings
- Support: github.com/HexRaysSA/ida-hcli/issues
Sponsors
Details
- Marketplace
- HexRaysSA/ida-claude-plugins
- Source
- plugins/ida-plugin-development
- Category
- Community