diff --git a/.gitignore b/.gitignore index 79339b7..ebeacb3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ obj/ -*.pyc \ No newline at end of file +*.pyc +idapyswitch* diff --git a/examples/README.md b/examples/README.md index b9a5c03..3ae4985 100644 --- a/examples/README.md +++ b/examples/README.md @@ -30,3 +30,8 @@ test as well. There should be no such thing as a non-tested example. +## Updating the examples index + +All examples are automatically integrated in the examples index. +In order to show user-friendly & relevant information, a proper +header (docstring) needs to be present. diff --git a/examples/analysis/dump_func_info.py b/examples/analysis/dump_func_info.py index c04e12f..bd4c823 100644 --- a/examples/analysis/dump_func_info.py +++ b/examples/analysis/dump_func_info.py @@ -1,4 +1,11 @@ -# get information about function(s) +""" +summary: dump (some) information about the current function. + +description: + Dump some of the most interesting bits of information about + the function we are currently looking at. +""" + import binascii import ida_kernwin diff --git a/examples/core/actions.py b/examples/core/actions.py index 1beb79a..86274f9 100644 --- a/examples/core/actions.py +++ b/examples/core/actions.py @@ -1,3 +1,23 @@ +""" +summary: custom actions, with icons & tooltips + +description: + How to create user actions, that once created can be + inserted in menus, toolbars, context menus, ... + + Those actions, when triggered, will be passed a 'context' + that contains some of the most frequently needed bits of + information. + + In addition, custom actions can determine when they want + to be available (through their + `ida_kernwin.action_handler_t.update` callback) + +keywords: actions + +see_also: add_hotkey +""" + from __future__ import print_function import ida_kernwin diff --git a/examples/core/add_hotkey.py b/examples/core/add_hotkey.py index b2b5114..a79e146 100644 --- a/examples/core/add_hotkey.py +++ b/examples/core/add_hotkey.py @@ -1,12 +1,23 @@ +""" +summary: triggering bits of code by pressing a shortcut + +description: + `ida_kernwin.add_hotkey` is a simpler, but much less flexible + alternative to `ida_kernwin.register_action` (though it does + use the same mechanism under the hood.) + + It's particularly useful during prototyping, but note that the + actions that are created cannot be inserted in menus, toolbars + or cannot provide a custom `ida_kernwin.action_handler_t.update` + callback. + +keywords: actions + +see_also: actions +""" + from __future__ import print_function -#--------------------------------------------------------------------- -# This script demonstrates the usage of hotkeys. -# -# 'ida_kernwin.add_hotkey' offers a simpler alternative to -# 'ida_kernwin.register_action', but is much less flexible. -# -# Author: IDAPython team -#--------------------------------------------------------------------- + import ida_kernwin def hotkey_pressed(): diff --git a/examples/core/add_idc_hotkey.py b/examples/core/add_idc_hotkey.py index 34eff9d..e17b920 100644 --- a/examples/core/add_idc_hotkey.py +++ b/examples/core/add_idc_hotkey.py @@ -1,12 +1,17 @@ +""" +summary: triggering bits of code by pressing a shortcut (older version) + +description: + This is a somewhat ancient way of registering actions & binding + shortcuts. It's still here for reference, but "fresher" alternatives + should be preferred. + +keywords: actions + +see_also: actions, add_hotkey +""" + from __future__ import print_function -#--------------------------------------------------------------------- -# This script demonstrates the usage of hotkeys, using an alternative API. -# See also: -# add_hotkey.py -# actions.py -# -# Author: Gergely Erdelyi -#--------------------------------------------------------------------- import ida_expr import ida_kernwin diff --git a/examples/core/auto_instantiate_widget_plugin.py b/examples/core/auto_instantiate_widget_plugin.py index ea52fed..a0ae3de 100644 --- a/examples/core/auto_instantiate_widget_plugin.py +++ b/examples/core/auto_instantiate_widget_plugin.py @@ -1,3 +1,28 @@ +""" +summary: better integrating custom widgets in the desktop layout + +description: + This is an example demonstrating how one can create widgets from a plugin, + and have them re-created automatically at IDA startup-time or at desktop load-time. + + This example should be placed in the 'plugins' directory of the + IDA installation, for it to work. + + There are 2 ways to use this example: + 1) reloading an IDB, where the widget was opened + - open the widget ('View > Open subview > ...') + - save this IDB, and close IDA + - restart IDA with this IDB + => the widget will be visible + + 2) reloading a desktop, where the widget was opened + - open the widget ('View > Open subview > ...') + - save the desktop ('Windows > Save desktop...') under, say, the name 'with_auto' + - start another IDA instance with some IDB, and load that desktop + => the widget will be visible + +keywords: desktop +""" import ida_idaapi import ida_kernwin @@ -13,26 +38,7 @@ class auto_inst_t(ida_kernwin.simplecustviewer_t): if not ida_kernwin.simplecustviewer_t.Create(self, title): return False - text = r""" -This is an example demonstrating how one can create widgets from a plugin, -and have them re-created automatically at IDA startup-time or at desktop load-time. - -This example should be placed in the 'plugins' directory of the -IDA installation, for it to work. - -There are 2 ways to use this example: -1) reloading an IDB, where the widget was opened - - open the widget ('View > Open subview > """ + title + """') - - save this IDB, and close IDA - - restart IDA with this IDB - => the widget will be visible - -2) reloading a desktop, where the widget was opened - - open the widget ('View > Open subview > """ + title + """') - - save the desktop ('Windows > Save desktop...') under, say, the name 'with_auto' - - start another IDA instance with some IDB, and load that desktop - => the widget will be visible -""" + text = __doc__ for l in text.split("\n"): self.AddLine(l) return True diff --git a/examples/core/bin_search.py b/examples/core/bin_search.py index 72fc2f4..8a0a892 100644 --- a/examples/core/bin_search.py +++ b/examples/core/bin_search.py @@ -1,14 +1,22 @@ +""" +summary: showcasing `ida_bytes.bin_search` + +description: + IDAPython's ida_bytes.bin_search function is pretty powerful, + but can be tough to figure out at first. This example introduces + + * `ida_bytes.bin_search`, and + * `ida_bytes.parse_binpat_str` + + in order to implement a simple replacement for the + 'Search > Sequence of bytes...' dialog, that lets users + search for sequences of bytes that compose string literals + in the binary file (either in the default 1-byte-per-char + encoding, or as UTF-16.) +""" + from __future__ import print_function -# IDAPython's ida_bytes.bin_search function is pretty powerful, -# but can be tough to figure out at first. This example introduces -# * ida_bytes.bin_search, and -# * ida_bytes.parse_binpat_str -# in order to implement a simple replacement for the -# 'Search > Sequence of bytes...' dialog, that lets users -# search for sequences of bytes that compose string literals -# in the binary file (either in the default 1-byte-per-char -# encoding, or as UTF-16.) import ida_kernwin import ida_bytes diff --git a/examples/core/create_structure_programmatically.py b/examples/core/create_structure_programmatically.py index 705cbde..306c28e 100644 --- a/examples/core/create_structure_programmatically.py +++ b/examples/core/create_structure_programmatically.py @@ -1,3 +1,11 @@ +""" +summary: programmatically create & populate a structure + +description: + Usage of the API to create & populate a structure with + members of different types. +""" + from __future__ import print_function #--------------------------------------------------------------------- # Structure test diff --git a/examples/core/custom_cli.py b/examples/core/custom_cli.py index c2db71e..7eae682 100644 --- a/examples/core/custom_cli.py +++ b/examples/core/custom_cli.py @@ -1,3 +1,14 @@ +""" +summary: a custom command-line interpreter + +description: + Illustrates how one can add command-line interpreters to IDA + + This custom interpreter doesn't actually run any code; it's + there as a 'getting started'. + It provides an example tab completion support. +""" + from __future__ import print_function # ----------------------------------------------------------------------- # This is an example illustrating how to implement a CLI diff --git a/examples/core/custom_data_types_and_formats.py b/examples/core/custom_data_types_and_formats.py index ebfc4fd..796f92b 100644 --- a/examples/core/custom_data_types_and_formats.py +++ b/examples/core/custom_data_types_and_formats.py @@ -1,8 +1,17 @@ +""" +summary: using custom data types & printers + +description: + IDA can be extended to support certain data types that it + does not know about out-of-the-box. + + A 'custom data type' provide information about the type & + size of a piece of data, while a 'custom data format' is in + charge of formatting that data (there can be more than + one format for a specific 'custom data type'.) +""" + from __future__ import print_function -# ----------------------------------------------------------------------- -# This is an example illustrating how to use custom data types in Python -# (c) Hex-Rays -# import ida_bytes import ida_idaapi diff --git a/examples/core/dump_extra_comments.py b/examples/core/dump_extra_comments.py index d3e8687..0a858ce 100644 --- a/examples/core/dump_extra_comments.py +++ b/examples/core/dump_extra_comments.py @@ -1,13 +1,15 @@ +""" +summary: retrieve extra comments + +description: + Use the `ida_lines.get_extra_cmt` API to retrieve anterior + and posterior extra comments. + + This script registers two actions, that can be used to dump + the previous and next extra comments. +""" + from __future__ import print_function -# ----------------------------------------------------------------------- -# This example illustrates how to use the 'get_extra_cmt' API, -# to retrieve anterior and posterior extra comments. -# -# After running this script, use Ctrl+Shift+Y when in the disassembly -# view to print previous extra comment, and Ctrl+Shift+Z to print next -# extra comments. -# -# (c) Hex-Rays import ida_lines import ida_kernwin diff --git a/examples/core/dump_flowchart.py b/examples/core/dump_flowchart.py index f2ceca9..f226138 100644 --- a/examples/core/dump_flowchart.py +++ b/examples/core/dump_flowchart.py @@ -1,4 +1,14 @@ # -*- coding: utf-8 -*- +""" +summary: dump function flowchart + +description: + Dumps the current function's flowchart, using 2 methods: + + * the low-level `ida_gdl.qflow_chart_t` type + * the somewhat higher-level, and slightly more pythonic + `ida_gdl.FlowChart` type. +""" from __future__ import print_function diff --git a/examples/core/dump_selection.py b/examples/core/dump_selection.py index bcea7a7..ad717dc 100644 --- a/examples/core/dump_selection.py +++ b/examples/core/dump_selection.py @@ -1,15 +1,22 @@ +""" +summary: retrieve & dump current selection + +description: + Shows how to retrieve the selection from a listing + widget ("IDA View-A", "Hex View-1", "Pseudocode-A", ...) as + two "cursors", and from there retrieve (in fact, generate) + the corresponding text. + + After running this script: + + * select some text in one of the listing widgets (i.e., + "IDA View-*", "Enums", "Structures", "Pseudocode-*") + * press Ctrl+Shift+S to dump the selection + +""" from __future__ import print_function -# This example illustrates how to accurately retrieve the current selection. -# -# After running this script: -# * select some text in one of the listing widgets (i.e., -# "IDA View-*", "Enums", "Structures", "Pseudocode-*") -# * press Ctrl+Shift+S to dump the selection -# -# (c) Hex-Rays - import ida_kernwin import ida_lines diff --git a/examples/core/extend_idc.py b/examples/core/extend_idc.py index bc6566f..25d45cd 100644 --- a/examples/core/extend_idc.py +++ b/examples/core/extend_idc.py @@ -1,8 +1,20 @@ +""" +summary: add functions to the IDC runtime from IDAPython + +description: + You can add IDC functions to IDA, whose "body" consists of + IDAPython statements! + + We'll register a 'pow' function, available to all IDC code, + that when invoked will call back into IDAPython, and execute + the provided function body. + + After running this script, try switching to the IDC interpreter + (using the button on the lower-left corner of IDA) and executing + `pow(3, 7)` +""" + from __future__ import print_function -# ----------------------------------------------------------------------- -# This is an example illustrating how to extend IDC from Python -# (c) Hex-Rays -# import ida_expr diff --git a/examples/core/idapythonrc.py b/examples/core/idapythonrc.py index 356d792..f2cc0d2 100644 --- a/examples/core/idapythonrc.py +++ b/examples/core/idapythonrc.py @@ -1,9 +1,15 @@ -#--------------------------------------------------------------------- -# Example user initialisation script: idapythonrc.py -# -# Place this script to ~/.idapro/ or to -# %APPDATA%\Hex-Rays\IDA Pro -#--------------------------------------------------------------------- +""" +summary: code to be run right after IDAPython initialization + +description: + The `idapythonrc.py` file: + + * %APPDATA%\Hex-Rays\IDA Pro\idapythonrc.py (on Windows) + * ~/.idapro/idapythonrc.py (on Linux & Mac) + + can contain any IDAPython code that will be run as soon as + IDAPython is done successfully initializing. +""" # Add your favourite script to ScriptBox for easy access # scriptbox.addscript("/here/is/my/favourite/script.py") diff --git a/examples/core/install_user_defined_prefix.py b/examples/core/install_user_defined_prefix.py index 11603ff..1f71d52 100644 --- a/examples/core/install_user_defined_prefix.py +++ b/examples/core/install_user_defined_prefix.py @@ -1,3 +1,13 @@ +""" +summary: inserting information into disassembly prefixes + +description: + By default, disassembly line prefixes contain segment + address + information (e.g., '.text:08047718'), but it is possible to + "inject" other bits of information in there, thanks to the + `ida_lines.user_defined_prefix_t` helper type. +""" + from __future__ import print_function import ida_lines diff --git a/examples/core/list_imports.py b/examples/core/list_imports.py index e19e2e5..8130261 100644 --- a/examples/core/list_imports.py +++ b/examples/core/list_imports.py @@ -1,8 +1,12 @@ +""" +summary: enumerate file imports + +description: + Using the API to enumerate file imports. +""" + from __future__ import print_function -# ----------------------------------------------------------------------- -# This is an example illustrating how to enumerate imports -# (c) Hex-Rays -# + import ida_nalt nimps = ida_nalt.get_import_module_qty() diff --git a/examples/core/list_patched_bytes.py b/examples/core/list_patched_bytes.py index 3a71148..cb6bc42 100644 --- a/examples/core/list_patched_bytes.py +++ b/examples/core/list_patched_bytes.py @@ -1,7 +1,12 @@ +""" +summary: enumerate patched bytes + +description: + Using the API to iterate over all the places in the file, + that were patched using IDA. +""" + from __future__ import print_function -# ------------------------------------------------------------------------- -# This is an example illustrating how to visit all patched bytes in Python -# (c) Hex-Rays import ida_bytes import ida_idaapi diff --git a/examples/core/list_problems.py b/examples/core/list_problems.py index b0376eb..054c240 100644 --- a/examples/core/list_problems.py +++ b/examples/core/list_problems.py @@ -1,3 +1,10 @@ +""" +summary: enumerate problems + +description: + Using the API to list all problem[atic situation]s that IDA + encountered during analysis. +""" import ida_ida import ida_idaapi diff --git a/examples/core/list_segment_functions.py b/examples/core/list_segment_functions.py index 67902a0..e2aa6fa 100644 --- a/examples/core/list_segment_functions.py +++ b/examples/core/list_segment_functions.py @@ -1,3 +1,15 @@ +""" +summary: list all functions (and xrefs) in segment + +description: + List all the functions in the current segment, as well as + all the cross-references to them. + +keywords: xrefs + +see_also: list_segment_functions_using_idautils +""" + from __future__ import print_function # # Reference Lister diff --git a/examples/core/list_segment_functions_using_idautils.py b/examples/core/list_segment_functions_using_idautils.py index 72da004..09e2b9c 100644 --- a/examples/core/list_segment_functions_using_idautils.py +++ b/examples/core/list_segment_functions_using_idautils.py @@ -1,3 +1,18 @@ +""" +summary: list all functions (and xrefs) in segment + +description: + List all the functions in the current segment, as well as + all the cross-references to them. + + Contrary to @list_segment_functions, this uses the somewhat + higher-level `idautils` module. + +keywords: xrefs + +see_also: list_segment_functions +""" + from __future__ import print_function # # Reference Lister diff --git a/examples/core/list_stkvar_xrefs.py b/examples/core/list_stkvar_xrefs.py index 43fa999..bb04db5 100644 --- a/examples/core/list_stkvar_xrefs.py +++ b/examples/core/list_stkvar_xrefs.py @@ -1,14 +1,13 @@ -# -# This example demonstrates how to retrieve all xrefs to -# a stack variable within a function. -# Contrary to (in-memory) data & code xrefs, retrieving -# stack variables xrefs require a bit more work than just -# using ida_xref's first_to(), next_to() (or higher level -# utilities such as idautils.XrefsTo) -# -# Press Ctrl+Shift+F7 to invoke the action that will print xrefs -# to the variable name that's under the cursor. -# +""" +summary: list all xrefs to a function stack variable + +description: + Contrary to (in-memory) data & code xrefs, retrieving stack variables + xrefs requires a bit more work than just using ida_xref's first_to(), + next_to() (or higher level utilities such as idautils.XrefsTo) + +keywords: xrefs +""" ACTION_NAME = "list_stkvar_xrefs:list" ACTION_SHORTCUT = "Ctrl+Shift+F7" diff --git a/examples/core/list_strings.py b/examples/core/list_strings.py index 6edb49e..1b14976 100644 --- a/examples/core/list_strings.py +++ b/examples/core/list_strings.py @@ -1,3 +1,14 @@ +""" +summary: retrieve the strings that are present in the IDB + +description: + This uses `idautils.Strings` to iterate over the string literals + that are present in the IDB. Contrary to @show_selected_strings, + this will not require that the "Strings" window is opened & available. + +see_also: show_selected_strings +""" + from __future__ import print_function import idautils diff --git a/examples/core/produce_c_file.py b/examples/core/produce_c_file.py index a5fa6ad..1c2ebfb 100644 --- a/examples/core/produce_c_file.py +++ b/examples/core/produce_c_file.py @@ -1,15 +1,20 @@ """ -This example demonstrates how one can automate IDA to perform auto-analysis -on a file and, as soon as it is finished, produce a .c file containing the -decompilation of all the functions that the file contains. +summary: decompile entire file -Run like so: - ida -A "-S...path/to/produce_c_file.py" +description: + automate IDA to perform auto-analysis on a file and, + once that is done, produce a .c file containing the + decompilation of all the functions in that file. -where: - -A instructs IDA to run in non-interactive mode - -S holds a path to the script to run (note this is a single token; - there is no space between '-S' and its path.) + Run like so: + + ida -A "-S...path/to/produce_c_file.py" + + where: + + * -A instructs IDA to run in non-interactive mode + * -S holds a path to the script to run (note this is a single token; + there is no space between '-S' and its path.) """ import ida_pro diff --git a/examples/core/produce_lst_file.py b/examples/core/produce_lst_file.py index 035a671..6d54063 100644 --- a/examples/core/produce_lst_file.py +++ b/examples/core/produce_lst_file.py @@ -1,15 +1,19 @@ """ -This example demonstrates how one can automate IDA to perform auto-analysis -on a file and, as soon as it is finished, produce a .lst file containing the -disassembly. +summary: produce listing -Run like so: - ida -A "-S...path/to/produce_lst_file.py" +description: + automate IDA to perform auto-analysis on a file and, + once that is done, produce a .lst file with the disassembly. -where: - -A instructs IDA to run in non-interactive mode - -S holds a path to the script to run (note this is a single token; - there is no space between '-S' and its path.) + Run like so: + + ida -A "-S...path/to/produce_lst_file.py" + + where: + + * -A instructs IDA to run in non-interactive mode + * -S holds a path to the script to run (note this is a single token; + there is no space between '-S' and its path.) """ import ida_auto diff --git a/examples/core/register_timer.py b/examples/core/register_timer.py index dfaf489..dd1988c 100644 --- a/examples/core/register_timer.py +++ b/examples/core/register_timer.py @@ -1,7 +1,11 @@ +""" +summary: using timers for delayed execution + +description: + Register (possibly repeating) timers. +""" + from __future__ import print_function -# ------------------------------------------------------------------------- -# This is an example illustrating how to use timers -# (c) Hex-Rays import ida_kernwin diff --git a/examples/core/trigger_actions_programmatically.py b/examples/core/trigger_actions_programmatically.py index bd21536..3f9e5a7 100644 --- a/examples/core/trigger_actions_programmatically.py +++ b/examples/core/trigger_actions_programmatically.py @@ -1,15 +1,21 @@ +""" +summary: execute existing actions programmatically + +description: + It's possible to invoke any action programmatically, by using + either of those two: + + * ida_kernwin.execute_ui_requests() + * ida_kernwin.process_ui_action() + + Ideally, this script should be run through the "File > Script file..." + menu, so as to keep focus on "IDA View-A" and have the + 'ProcessUiActions' part work as intended. + +keywords: actions +""" + from __future__ import print_function -# ----------------------------------------------------------------------- -# This is an example illustrating how to use -# * ida_kernwin.execute_ui_requests() -# * ida_kernwin.process_ui_action() -# -# Ideally, this script should be run through the "File > Script file..." -# menu, so as to keep focus on "IDA View-A" and have the -# 'ProcessUiActions' part work as intended. -# -# (c) Hex-Rays -# import ida_kernwin diff --git a/examples/debugging/appcall/simple_appcall_linux.py b/examples/debugging/appcall/simple_appcall_linux.py index b37f668..ff4150d 100644 --- a/examples/debugging/appcall/simple_appcall_linux.py +++ b/examples/debugging/appcall/simple_appcall_linux.py @@ -1,20 +1,26 @@ +""" +summary: executing code into the application being debugged (on Linux) + +description: + Using the `ida_idd.Appcall` utility to execute code in + the process being debugged. + + This example will run the test program and stop wherever + the cursor currently is, and then perform an appcall to + execute the `ref4` and `ref8` functions. + + To use this example: + + * run `ida64` on test program `simple_appcall_linux64`, or + `ida` on test program `simple_appcall_linux32`, and wait for + auto-analysis to finish + * select the 'linux debugger' (either local, or remote) + * run this script + + Note: the real body of code is in `simple_appcall_common.py`. +""" + from __future__ import print_function -# -# This sample illustrates how to use appcall, with the -# 'simple_appcall_linux32' or 'simple_appcall_linux64' test -# programs (see subdirectories.) -# -# This example will run the test program and stop wherever -# the cursor currently is, and then perform an appcall to -# `ref4` and `ref8` -# -# To use this example: -# * run `ida64` on test program `simple_appcall_linux64`, or -# `ida` on test program `simple_appcall_linux32`, and wait for -# auto-analysis to finish -# * select the 'linux debugger' (either local, or remote) -# * run this script -# import os import sys diff --git a/examples/debugging/appcall/simple_appcall_win.py b/examples/debugging/appcall/simple_appcall_win.py index a4279ce..3f9bcac 100644 --- a/examples/debugging/appcall/simple_appcall_win.py +++ b/examples/debugging/appcall/simple_appcall_win.py @@ -1,20 +1,26 @@ +""" +summary: executing code into the application being debugged (on Windows) + +description: + Using the `ida_idd.Appcall` utility to execute code in + the process being debugged. + + This example will run the test program and stop wherever + the cursor currently is, and then perform an appcall to + execute the `ref4` and `ref8` functions. + + To use this example: + + * run `ida64` on test program `simple_appcall_win64.exe`, or + `ida` on test program `simple_appcall_win32.exe`, and wait for + auto-analysis to finish + * select the 'windows debugger' (either local, or remote) + * run this script + + Note: the real body of code is in `simple_appcall_common.py`. +""" + from __future__ import print_function -# -# This sample illustrates how to use appcall, with the -# 'simple_appcall_win32.exe' or 'simple_appcall_win64.exe' test -# programs (see subdirectories.) -# -# This example will run the test program and stop wherever -# the cursor currently is, and then perform an appcall to -# `ref4` and `ref8` -# -# To use this example: -# * run `ida64` on test program `simple_appcall_win64.exe`, or -# `ida` on test program `simple_appcall_win32.exe`, and wait for -# auto-analysis to finish -# * select the 'windows debugger' (either local, or remote) -# * run this script -# import os import sys diff --git a/examples/debugging/dbghooks/automatic_steps.py b/examples/debugging/dbghooks/automatic_steps.py index 27283ee..9d58d86 100644 --- a/examples/debugging/dbghooks/automatic_steps.py +++ b/examples/debugging/dbghooks/automatic_steps.py @@ -1,15 +1,13 @@ +""" +summary: programmatically drive a debugging session + +description: + Start a debugging session, step through the first five + instructions. Each instruction is disassembled after + execution. +""" + from __future__ import print_function -#--------------------------------------------------------------------- -# Debug notification hook test -# -# This script start the executable and steps through the first five -# instructions. Each instruction is disassembled after execution. -# -# Original Author: Gergely Erdelyi -# -# Maintained By: IDAPython Team -# -#--------------------------------------------------------------------- import ida_dbg import ida_ida diff --git a/examples/debugging/dbghooks/dbg_trace.py b/examples/debugging/dbghooks/dbg_trace.py index 53e51b4..0ed3aa8 100644 --- a/examples/debugging/dbghooks/dbg_trace.py +++ b/examples/debugging/dbghooks/dbg_trace.py @@ -1,7 +1,13 @@ """ -This script demonstrates using the low-level tracing hook (dbg_trace) -It can be run like: ida[t].exe -B -Sdbg_trace.py -Ltrace.log file.exe +summary: using the low-level tracing hook + +description: + This script demonstrates using the low-level tracing hook + (ida_dbg.DBG_Hooks.dbg_trace). It can be run like so: + + ida[t].exe -B -Sdbg_trace.py -Ltrace.log file.exe """ + import time import ida_dbg diff --git a/examples/debugging/misc/registers_context_menu.py b/examples/debugging/misc/registers_context_menu.py index 3fccaf9..8692cdb 100644 --- a/examples/debugging/misc/registers_context_menu.py +++ b/examples/debugging/misc/registers_context_menu.py @@ -1,3 +1,13 @@ +""" +summary: adding actions to the "registers" widget(s) + +description: + It's possible to add actions to the context menu of + pretty much all widgets in IDA. + + This example shows how to do just that for + registers-displaying widgets (e.g., "General registers") +""" import ida_dbg import ida_idd diff --git a/examples/debugging/show_debug_names.py b/examples/debugging/show_debug_names.py index 0f8f9e6..05ba426 100644 --- a/examples/debugging/show_debug_names.py +++ b/examples/debugging/show_debug_names.py @@ -1,3 +1,11 @@ +""" +summary: retrieving & dumping debuggee symbols + +description: + Queries the debugger (possibly remotely) for the list of + symbols that the process being debugged, provides. +""" + from __future__ import print_function import ida_dbg diff --git a/examples/hexrays/colorize_pseudocode_lines.py b/examples/hexrays/colorize_pseudocode_lines.py index 9a7421c..6c6124d 100644 --- a/examples/hexrays/colorize_pseudocode_lines.py +++ b/examples/hexrays/colorize_pseudocode_lines.py @@ -1,10 +1,16 @@ """ -This example shows how one can dynamically alter the lines background -rendering for pseudocode listings (as opposed to using -ida_hexrays.cfunc_t.pseudocode[N].bgcolor) +summary: interactively color certain pseudocode lines -After running this script, pressing 'M' on a line in a "Pseudocode-?" -widget, will cause that line to be rendered with a special background color. +description: + Provides an action that can be used to dynamically alter the + lines background rendering for pseudocode listings (as opposed to + using `ida_hexrays.cfunc_t.pseudocode[N].bgcolor`) + + After running this script, pressing 'M' on a line in a + "Pseudocode-?" widget, will cause that line to be rendered + with a special background color. + +keywords: colors """ import ida_kernwin diff --git a/examples/hexrays/decompile_entry_points.py b/examples/hexrays/decompile_entry_points.py index 50a56ba..504338b 100644 --- a/examples/hexrays/decompile_entry_points.py +++ b/examples/hexrays/decompile_entry_points.py @@ -1,13 +1,16 @@ -from __future__ import print_function +""" +summary: automatic decompilation of functions -# -# This example tries to load a decompiler plugin corresponding to the current -# architecture (and address size) right after auto-analysis is performed, -# and then tries to decompile the function at the first entrypoint. -# -# It is particularly suited for use with the '-S' flag, for example: -# idat -Ldecompile.log -Sdecompile_entry_points.py -c file -# +description: + Attempts to load a decompiler plugin corresponding to the current + architecture (and address size) right after auto-analysis is performed, + and then tries to decompile the function at the first entrypoint. + + It is particularly suited for use with the '-S' flag, for example: + idat -Ldecompile.log -Sdecompile_entry_points.py -c file +""" + +from __future__ import print_function import ida_ida import ida_auto diff --git a/examples/hexrays/vds1.py b/examples/hexrays/vds1.py index 4097747..6c58827 100644 --- a/examples/hexrays/vds1.py +++ b/examples/hexrays/vds1.py @@ -1,3 +1,7 @@ +""" +summary: decompile & print current function. +""" + from __future__ import print_function import ida_hexrays diff --git a/examples/hexrays/vds10.py b/examples/hexrays/vds10.py index 7fee0cb..bd57153 100644 --- a/examples/hexrays/vds10.py +++ b/examples/hexrays/vds10.py @@ -1,18 +1,18 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample plugin for Hex-Rays Decompiler. -# It installs a custom microcode optimization rule: -# call !DbgRaiseAssertionFailure .0 -# => -# call !DbgRaiseAssertionFailure .0 -# -# To see this plugin in action please use arm64_brk.i64, in the hexrays sdk -# -# This is a rewrite in Python of the vds10 example that comes with hexrays sdk. -# +""" +summary: a custom microcode instruction optimization rule + +description: + Installs a custom microcode instruction optimization rule, + to transform: + + call !DbgRaiseAssertionFailure .0 + + into + + call !DbgRaiseAssertionFailure .0 + + To see this plugin in action please use arm64_brk.i64 +""" import ida_bytes import ida_range diff --git a/examples/hexrays/vds11.py b/examples/hexrays/vds11.py index ac0712e..be84155 100644 --- a/examples/hexrays/vds11.py +++ b/examples/hexrays/vds11.py @@ -1,21 +1,22 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample plugin for Hex-Rays Decompiler. -# It installs a custom block optimization rule: -# -# goto L1 => goto L2 -# ... -# L1: -# goto L2 -# -# In other words we fix a goto target if it points to a chain of gotos. -# This improves the decompiler output in some cases. -# -# This is a rewrite in Python of the vds11 example that comes with hexrays sdk. -# +""" +summary: a custom microcode block optimization rule (resolve `goto` chains) + +description: + Installs a custom microcode block optimization rule, + to transform: + + goto L1 + ... + L1: + goto L2 + + into + + goto L2 + + In other words we fix a goto target if it points to a chain of gotos. + This improves the decompiler output in some cases. +""" import ida_bytes import ida_range diff --git a/examples/hexrays/vds12.py b/examples/hexrays/vds12.py index 456dbf7..05608d6 100644 --- a/examples/hexrays/vds12.py +++ b/examples/hexrays/vds12.py @@ -1,14 +1,10 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample script for Hex-Rays Decompiler. -# It shows list of direct references to a register from the current -# instruction. -# -# This is a rewrite in Python of the vds12 example that comes with hexrays sdk. -# +""" +summary: list instruction registers + +description: + Shows a list of direct references to a register from the + current instruction. +""" import ida_pro import ida_hexrays diff --git a/examples/hexrays/vds13.py b/examples/hexrays/vds13.py index b701b58..be9124f 100644 --- a/examples/hexrays/vds13.py +++ b/examples/hexrays/vds13.py @@ -1,13 +1,9 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample script for Hex-Rays Decompiler. -# It generates microcode for selection and dumps it to the output window. -# -# This is a rewrite in Python of the vds13 example that comes with hexrays sdk. -# +""" +summary: generates microcode for selection + +description: + Generates microcode for selection and dumps it to the output window. +""" import ida_bytes import ida_range diff --git a/examples/hexrays/vds17.py b/examples/hexrays/vds17.py index 246ddd8..1563920 100644 --- a/examples/hexrays/vds17.py +++ b/examples/hexrays/vds17.py @@ -1,15 +1,15 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample plugin for Hex-Rays Decompiler. -# It shows how to use "Select offsets" widget (select_udt_by_offset() call). -# This plugin repeats the Alt-Y functionality. -# Usage: place cursor on the union field and press Shift-T -# -# This is a rewrite in Python of the vds17 example that comes with hexrays sdk. -# +""" +summary: using the "Select offsets" widget + +description: + Registers an action opens the "Select offsets" widget + (select_udt_by_offset() call). + + This effectively repeats the functionality already available + through Alt+Y. + + Place cursor on the union field and press Shift+T +""" import ida_idaapi import ida_hexrays diff --git a/examples/hexrays/vds19.py b/examples/hexrays/vds19.py index 724d8d1..9bbcfa1 100644 --- a/examples/hexrays/vds19.py +++ b/examples/hexrays/vds19.py @@ -1,14 +1,18 @@ -# -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample plugin for Hex-Rays Decompiler. -# It installs a custom microcode optimization rule: -# x | ~x => -1 -# -# To see this plugin in action please use be_ornot_be.idb -# +""" +summary: a custom microcode instruction optimization rule (`x | ~x => -1`) + +description: + Installs a custom microcode instruction optimization rule, + to transform: + + x | ~x + + into + + -1 + + To see this plugin in action please use be_ornot_be.idb +""" import ida_hexrays import ida_idaapi diff --git a/examples/hexrays/vds21.py b/examples/hexrays/vds21.py index aa8bb7d..37b14af 100644 --- a/examples/hexrays/vds21.py +++ b/examples/hexrays/vds21.py @@ -1,26 +1,27 @@ -""" Example: provide custom call type dynamically +""" +summary: dynamically provide a custom call type - This plugin can greatly improve decompilation of indirect calls: +description: + This plugin can greatly improve decompilation of indirect calls: - call [eax+4] + call [eax+4] - For them, the decompiler has to guess the prototype of the called function. - This has to be done at a very early phase of decompilation because - the function prototype influences the data flow analysis. On the other - hand, we do not have global data flow analysis results yet because - we haven't analyzed all calls in the function. It is a chicked-and-egg - problem. + For them, the decompiler has to guess the prototype of the called function. + This has to be done at a very early phase of decompilation because + the function prototype influences the data flow analysis. On the other + hand, we do not have global data flow analysis results yet because + we haven't analyzed all calls in the function. It is a chicked-and-egg + problem. - The decompiler uses various techniques to guess the called function - prototype. While it works very well, it may fail in some cases. + The decompiler uses various techniques to guess the called function + prototype. While it works very well, it may fail in some cases. - To fix, the user can specify the call prototype manually, using - "Edit, Operand types, Set operand type" at the call instruction. - - This plugin illustrates another approach to the problem: - if you happen to be able to calculate the call prototypes dynamically, - this is how to inform the decompiler about them. + To fix, the user can specify the call prototype manually, using + "Edit, Operand types, Set operand type" at the call instruction. + This plugin illustrates another approach to the problem: + if you happen to be able to calculate the call prototypes dynamically, + this is how to inform the decompiler about them. """ import ida_idaapi diff --git a/examples/hexrays/vds3.py b/examples/hexrays/vds3.py index 5cc9bb9..6e1f5eb 100644 --- a/examples/hexrays/vds3.py +++ b/examples/hexrays/vds3.py @@ -1,9 +1,38 @@ -""" Invert the then and else blocks of a cif_t. - -Author: EiNSTeiN_ - -This is a rewrite in Python of the vds3 example that comes with hexrays sdk. """ +summary: invert if/else blocks + +description: + Registers an action that can be used to invert the `if` + and `else` blocks of a `ida_hexrays.cif_t`. + + For example, a statement like + + if ( cond ) + { + statements1; + } + else + { + statements2; + } + + will be displayed as + + if ( !cond ) + { + statements2; + } + else + { + statements1; + } + + The modifications are persistent: the user can quit & restart + IDA, and the changes will be present. + +author: EiNSTeiN_ +""" + from __future__ import print_function import idautils diff --git a/examples/hexrays/vds4.py b/examples/hexrays/vds4.py index 153241c..335b24f 100644 --- a/examples/hexrays/vds4.py +++ b/examples/hexrays/vds4.py @@ -1,9 +1,18 @@ -""" Print user-defined details to the output window. - -Author: EiNSTeiN_ - -This is a rewrite in Python of the vds4 example that comes with hexrays sdk. """ +summary: dump user-defined information + +description: + Prints user-defined information to the "Output" window. + Namely: + + * user defined label names + * user defined indented comments + * user defined number formats + * user defined local variable names, types, comments + +author: EiNSTeiN_ +""" + from __future__ import print_function import ida_kernwin diff --git a/examples/hexrays/vds5.py b/examples/hexrays/vds5.py index e735e06..95d3286 100644 --- a/examples/hexrays/vds5.py +++ b/examples/hexrays/vds5.py @@ -1,3 +1,17 @@ +""" +summary: show ctree graph + +description: + Registers an action that can be used to show the graph of the ctree. + The current item will be highlighted in the graph. + + The command shortcut is `Ctrl+Shift+G`, and is also added + to the context menu. + + To display the graph, we produce a .gdl file, and + request that ida displays that using `ida_gdl.display_gdl`. +""" + from __future__ import print_function import ida_pro diff --git a/examples/hexrays/vds6.py b/examples/hexrays/vds6.py index 6036f01..23510f1 100644 --- a/examples/hexrays/vds6.py +++ b/examples/hexrays/vds6.py @@ -1,10 +1,13 @@ - """ -This is a crude (and not very pythonic) reimplementation of the example -hexrays plugin 'hexrays_sample6.cpp', shipped with the Hex-Rays decompiler. +summary: superficially modify the decompilation output -It modifies the decompilation output: removes some space characters. +description: + modifies the decompilation output in a superficial manner, + by removing some white spaces + + Note: this is rather crude, not quite "pythonic" code. """ + from __future__ import print_function import idautils diff --git a/examples/hexrays/vds7.py b/examples/hexrays/vds7.py index 7782f19..2bfa4d5 100644 --- a/examples/hexrays/vds7.py +++ b/examples/hexrays/vds7.py @@ -1,9 +1,13 @@ -""" It demonstrates how to iterate a cblock_t object. - -Author: EiNSTeiN_ - -This is a rewrite in Python of the vds7 example that comes with hexrays sdk. """ +summary: iterate a cblock_t object + +description: + Using a `ida_hexrays.ctree_visitor_t`, search for + `ida_hexrays.cit_block` instances and dump them. + +author: EiNSTeiN_ +""" + from __future__ import print_function import ida_hexrays diff --git a/examples/hexrays/vds8.py b/examples/hexrays/vds8.py index 7eacfe8..7ac700e 100644 --- a/examples/hexrays/vds8.py +++ b/examples/hexrays/vds8.py @@ -1,14 +1,16 @@ +""" +summary: using `ida_hexrays.udc_filter_t` -# Hex-Rays Decompiler project -# Copyright (c) 2007-2021 by Hex-Rays, support@hex-rays.com -# ALL RIGHTS RESERVED. -# -# Sample script for Hex-Rays Decompiler usage of udc_filter_t -# class: decompile svc 0x900001 and svc 0x9000F8 as function calls to -# svc_exit() and svc_exit_group() respectively. -# NOTE: You will need to have an ARM + Linux IDB for this script to be usable -# -# It is also added into the right-click menu as "vds8.py:Toggle UDC" +description: + Registers an action that uses a `ida_hexrays.udc_filter_t` to decompile + `svc 0x900001` and `svc 0x9000F8` as function calls to + `svc_exit()` and `svc_exit_group()` respectively. + + You will need to have an ARM + Linux IDB for this script to be usable + + In addition to having a shortcut, the action will be present + in the context menu. +""" import ida_idaapi import ida_hexrays diff --git a/examples/hexrays/vds_create_hint.py b/examples/hexrays/vds_create_hint.py index d124f5f..2dea8b6 100644 --- a/examples/hexrays/vds_create_hint.py +++ b/examples/hexrays/vds_create_hint.py @@ -1,10 +1,17 @@ -"""'Hints' example for Hexrays Decompiler +""" +summary: decompiler hints -Handle 'hxe_create_hint' notification using hooks, to return our own. -If the object under the cursor is: - - a function call, prefix the original decompiler hint with "==> " - - a local variable declaration, replace the hint with our own in the form of "!{varname}" (where '{varname}' is replaced w/ the variable name) - - an 'if' statement, replace the hint with our own, saying "condition" +description: + Handle `ida_hexrays.hxe_create_hint` notification using hooks, + to return our own. + + If the object under the cursor is: + + * a function call, prefix the original decompiler hint with `==> ` + * a local variable declaration, replace the hint with our own in + the form of `!{varname}` (where `{varname}` is replaced with the + variable name) + * an `if` statement, replace the hint with our own, saying "condition" """ import ida_idaapi diff --git a/examples/hexrays/vds_hooks.py b/examples/hexrays/vds_hooks.py index 53f78a2..557ab4e 100644 --- a/examples/hexrays/vds_hooks.py +++ b/examples/hexrays/vds_hooks.py @@ -1,5 +1,14 @@ """ -Various hooks for Hexrays Decompiler +summary: various decompiler hooks + +description: + Shows how to hook to many notifications sent by the decompiler. + + This plugin doesn't really accomplish anything: it just prints + the parameters. + + Also, the list of notifications handled below, isn't exhaustive. + Please investigate `ida_hexrays.Hexrays_Hooks` for a full list. """ from __future__ import print_function diff --git a/examples/hexrays/vds_modify_user_lvars.py b/examples/hexrays/vds_modify_user_lvars.py index b58024f..77c52d7 100644 --- a/examples/hexrays/vds_modify_user_lvars.py +++ b/examples/hexrays/vds_modify_user_lvars.py @@ -1,3 +1,10 @@ +""" +summary: modifying local variables + +description: + Use a `ida_hexrays.user_lvar_modifier_t` to modify names, + comments and/or types of local variables. +""" import ida_hexrays import ida_typeinf diff --git a/examples/hexrays/vds_xrefs.py b/examples/hexrays/vds_xrefs.py index d7f22a2..3a41b5d 100644 --- a/examples/hexrays/vds_xrefs.py +++ b/examples/hexrays/vds_xrefs.py @@ -1,12 +1,14 @@ -""" Xref script for Hexrays Decompiler +""" +summary: show decompiler xrefs -Author: EiNSTeiN_ +description: + Show decompiler-style Xref when the `Ctrl+X` key is + pressed in the Decompiler window. -Show decompiler-style Xref when the X key is pressed in the Decompiler window. - -- It supports any global name: functions, strings, integers, etc. -- It supports structure member. + * supports any global name: functions, strings, integers, ... + * supports structure member. +author: EiNSTeiN_ """ from __future__ import print_function diff --git a/examples/idbhooks/operand_changed.py b/examples/idbhooks/operand_changed.py index 9b305be..ad78e80 100644 --- a/examples/idbhooks/operand_changed.py +++ b/examples/idbhooks/operand_changed.py @@ -1,7 +1,11 @@ """ -This example shows notifications whenever the user changes -an instruction's operand, or a data item. +summary: notify the user when an instruction operand changes + +description: + Show notifications whenever the user changes + an instruction's operand, or a data item. """ + import binascii import ida_idp diff --git a/examples/idphooks/ana_emu_out.py b/examples/idphooks/ana_emu_out.py index b7ef163..f33bb26 100644 --- a/examples/idphooks/ana_emu_out.py +++ b/examples/idphooks/ana_emu_out.py @@ -1,7 +1,15 @@ +""" +summary: override some parts of the processor module + +description: + Implements disassembly of BUG_INSTR used in Linux kernel + BUG() macro, which is architecturally undefined and is not + disassembled by IDA's ARM module + + See Linux/arch/arm/include/asm/bug.h for more info +""" + from __future__ import print_function -# this script implements disassembly of BUG_INSTR used in Linux kernel BUG() macro -# normally it's architecturally undefined and is not disassembled by IDA's ARM module -# see Linux/arch/arm/include/asm/bug.h import ida_idp import ida_bytes diff --git a/examples/idphooks/assemble.py b/examples/idphooks/assemble.py index 248952c..9e2d242 100644 --- a/examples/idphooks/assemble.py +++ b/examples/idphooks/assemble.py @@ -1,18 +1,17 @@ +""" +summary: an `ida_idp.IDP_Hooks.assembly` implementation + +description: + We add support for assembling the following pseudo instructions: + + * "zero eax" -> xor eax, eax + * "nothing" -> nop +""" + from __future__ import print_function import ida_idp import idautils -""" - This is a sample script for extending the assemble() hook. - - We add support for assembling the following pseudo instructions: - - "zero eax" -> xor eax, eax - - "nothing" -> nop - - -(c) Hex-Rays -""" - #-------------------------------------------------------------------------- class assemble_idp_hook_t(ida_idp.IDP_Hooks): def assemble(self, ea, cs, ip, use32, line): diff --git a/examples/index.css b/examples/index.css new file mode 100644 index 0000000..8478dec --- /dev/null +++ b/examples/index.css @@ -0,0 +1,28 @@ + +body +{ + margin: 3%; +} + +.exp-col +{ + cursor: pointer; + padding: 0 4px 0 6px; +} + +.collapsed-entry .details +{ + display: none; +} + +.example-entry .details +{ + margin-left: 3%; + padding: 6px; + background-color: #eef; +} + +a +{ + text-decoration: none; +} \ No newline at end of file diff --git a/examples/index.html b/examples/index.html index 5a645be..1bd575f 100644 --- a/examples/index.html +++ b/examples/index.html @@ -2,3361 +2,2456 @@ IDAPython examples - + + - +
- - Switch to MarkDown + View on GitHub +
+
+ Expand all + collapse all

IDAPython examples:

Category: analysis

-
- -
- - dump_func_info: -
-