The -r command line switch is used to run the built-in debugger without creating a database in advance. The format is this switch is:

  -rdebname{params}:pass@hostname:port+pid

The explanation of the fields:

  debname       Debugger name. Should contain the debugger
                module name. Examples: win32, linux. This prefix
                can be shortened or even completely
                omitted if there is no ambiguity
  params        Optional parameter for the debugger module
                The parameters from the appropriate configuration file
                can be specified here, separated by semicolons.
  pass          Password for the remote debugger server
  hostname      Host name or address of the remote debugger server.
                IPv6 addresses need to be enclosed in [].
  port          Port number to use to connect to the debugger server
  pid           PID of the process to attach

All fields except the first one are optional. Also, the pid field can be specified as '+'. IDA will display the process list to attach. See examples below for typical command lines:

  ida -rwin32 file args
        Run 'file' with command line 'args' in the local debugger
        We have to specify the debugger name to avoid ambiguities.
  ida -rwindbg+450
        Attach to process 450 on the local machine using the windbg backend
  ida -rl:hippy@mycom:4567+
        Connect to the remote linux computer 'mycom' at port 4567 using the
        password 'hippy' and display the list of processes running on it.
        Allow the user to select a process and attach to it.
  ida -rl@mycom /bin/ls e*
        Run '/bin/ls' command on the 'mycom' computer using the remote
        debugger server on Linux. Use an empty password and the
        default port number. Pass "e*" as the parameter to /bin/ls.
  ida -rl@mycom whobase.idb
        Run '/usr/bin/who' command on the 'mycom' computer using the
        remote linux debugger server. Use an empty password and the
        default port number. IDA will extract the name of the
        executable from the whobase.idb file in the local current
        directory. If the database does not exist, then this command
        will fail.
  ida "-rwindbg{MODE=1}@com:port=\\.\pipe\com_1,baud=115200,pipe,reconnect+"
        Attach using windbg in kernel mode. The connection string is
        "com:port=\\.\pipe\com_1,baud=115200,pipe,reconnect". A mini database
        will be created on the fly.

When the -r switch is used, IDA works with the databases in the following way:

        - if a database corresponding to the input file exists and
        the -c switch has not been specified, then IDA will use the
        database during the debugging session

        - otherwise, a temporary database will be created

Temporary databases contain only meta-information about the debugged process and not the memory contents. The user can make a memory snapshot any time before the process stops. If IDA detects that a command will cause the process to exit or detach IDA, it will propose to make a snapshot.

The rest of the command line is passed to the launched process.

In the case there is no input file (when attaching to an existing process, for example), then the temporary database is created in the standard temporary directory. For Windows, this directory is usually "Local Setting\Temp" in the user profile directory.

See also How to launch remote debugging

1. Launch a remote IDA debugger server on the remote host. The remote server is started from the command line and accepts command line parameters. You can specify a password if you want to protect your debugger server from strangers. For example, to launch the server under MS Windows, you could enter:

        win32_remote -Pmy_secret_password

2. Specify the remote debugger parameters in the Debugger, Process options. The file paths must be valid on the remote host. Do not forget to specify the same password as you have specified when launching the server. For example, to debug notepad.exe on the remote computer remote.host.com:

        Application: c:\windows\notepad.exe
        Input file:  c:\windows\notepad.exe
        Directory:   c:\windows
        Hostname:    remote.host.com
        Port:        23946
        Password:    my_secret_password

3. The rest of debugging is the same as with local debugging.

 NOTE

The debugger server can handle one debugger session at once. If you need to debug several applications simultaneously, launch several servers at different network ports.

The following debugger servers are shipped with IDA

 File name             Target system         Debugged programs
 ------------------    ------------------    ----------------------------
 android_server        ARM Android           32-bit ELF files
 android_server64      AArch64 Android       64-bit ELF files
 android_x64_server    x86 Android 32-bit    32-bit ELF files
 android_x86_server    x86 Android 64-bit    64-bit ELF files
 armlinux_server       ARM Linux             32-bit ELF files
 armlinux_server64     AArch64 Linux         64-bit ELF files
 linux_server          Linux 32-bit          32-bit ELF files
 linux_server64        Linux 64-bit          64-bit ELF files
 mac_server            Mac OS X              32-bit Mach-O files (x86)
 mac_server64          Mac OS X/macOS 11     64-bit Mach-O files (x64)
 mac_server_arm64      ARM macOS 11          64-bit Mach-O files (arm64)
 mac_server_arm64e     ARM macOS 11          64-bit Mach-O files (arm64e)
 win32_remote.exe      MS Windows 32-bit     32-bit PE files
 win64_remote64.exe    MS Windows 64-bit     64-bit PE files

An appropriate server must be started on the remote computer before starting a debug session.

See also

• Start process

• Debugger submenu

• Debugger for Linux

• Debugger for macOS

• Debugger for Android native code

• Remote iOS debugger

The Remote iOS Debugger allows for debugging iOS applications directly from IDA.

IDA's iOS debugger acts as a client to Apple's debugserver. So, you must ensure that the debugserver is already installed on your device for the debugger to work.

See: https://www.hex-rays.com/products/ida/support/tutorials/ios_debugger_tutorial.pdf

for a detailed tutorial on getting started with iOS.

See also

• Remote GDB Debugger

• Debugger for macOS

• How to launch remote debugging

VMWare Workstation 6.5 is recommended for debugging, though earlier versions may work too. Only 32-bit debugging is supported.

In order to enable debugging with GDB protocol, add the following lines to the .vmx file of the virtual machine:

To debug the VM startup, use:

Please note that the execution will start in the BIOS.

To accept connections from remote computers, the following line must be specified:

VMWare Workstation will listen on port 8832.

Tips:

Since the GDB server does not report the memory layout, it must be specified manually. For example, to debug BIOS startup code, create a 16-bit segment from F0000 to 10000 with base F000.

Use the to get extra info about the registers. For example, use "r cr0" to see current value of the cr0 register or "r cs" to see the base, limit and other attributes of the CS selector in protected mode.

Back to

Make sure the following line is present in the .cfg file for your target:

Edit the port number if necessary. Specify that port in the process options and use the Debugger, Attach command.

Tips: Use the to send commands directly to OpenOCD interpreter. Back to

Max packet size

        Maximum packet size supported by the GDB stub (in bytes).
        Some stubs can crash on big packets, e.g. memory reads. IDA
        will try to split such requests in smaller chunks so that
        replies should fit in this size. You can enter -1 to
        autodetect (in this case IDA will use the size of the
        "g" packet reply as the max packet size).

Timeout

        Default timeout in milliseconds for remote GDB stub responses.
        Some targets can be slow to respond, so increase this value
        when having problems, e.g. with disappearing memory bytes.

Run a program before starting debugging Check to enable external program options. Processor This option is only visible when starting debugger without a database. Use it to specify on which CPU the target is running. For some processors you can also specify the endianness. Software breakpoints at EIP+1

        Most GDB stubs for x86 report software breakpoint hits with EIP one byte after
        the breakpoint address. However, some emulators report the actual breakpoint
        address. This option allows IDA to recognize such situations.
        Recommendations: uncheck for QEMU, check for others.

Use CS:IP in real mode

        When debugging real-mode (16-bit) code, the stub can send either
        just 16 bits of IP register or the full EIP (CS<<4 + IP).
        Enable this option in the former case.
        Recommendations: check for QEMU, uncheck for others.

See also

• Instant debugger

• Remote GDB Debugger

gdbserver is a GDB stub implemented as a separate program. It runs a program to be debugged or attaches to a process and then waits for commands. The remote GDB debugger module has been tested with gdbserver available with Cygwin and Linux.

To debug a specific program from the start, run the following command:

    gdbserver localhost:23946 <program>

and then choose Debugger,Attach,<process running on target> in IDA.

To debug a running process:

    gdbserver --multi localhost:23947

then choose Debugger,Attach,<enter PID to attach> in IDA and enter the PID of the process to attach to.

Another method of debugging a running process is:

    gdbserver localhost:23947 --attach <PID>

then choose Debugger,Attach,<process running on target> in IDA.

To start a program from inside IDA, first launch the debugger server:

    gdbserver --multi localhost:23947

Then use Debugger,Start process or Debugger,Run in IDA.

 NOTE

The --multi option is only available in GDB 6.8 or higher.

Back to Remote GDB Debugger

The Android debugger has the following particularities and limitations:

- Android on ARM is supported (not on x86)

- Both ARM and Thumb mode code is supported

- Multithreaded applications can be debugged. However, since the operating system does not report thread deaths, they are reported only when the debugger notices that the thread is missing (for example, because there is an error when we try to suspend it)

- Apparently Android reports applications that are currently executing a system call as executing "LDMFD SP!, {R4,R7}" before the syscall. Once the syscall completes, the next instruction is reached.

- Hardware breakpoints are not supported. See also

• Start process

• Debugger submenu

• How to launch remote debugging

Remote GDB Debugger module allows for debugging code using the GDB remote serial protocol. For this, the debuggee must contain a so-called "GDB stub" that controls the execution and handles the remote protocol commands. There are many implementations of such stubs available with different capabilities. The module has been tested with the following GDB stubs: : Windows (Cygwin), Linux (ARM, MIPS, PowerPC) : x86 (16/32 bit) : x86 (16/32 bit), ARM, MIPS, PowerPC : ARM It is quite possible that the module will work with other stubs. Note that only x86, ARM, MIPS and PowerPC processors are supported at the moment.

Some GDB stubs support so-called "monitor" commands. For example, VMWare stub can return extra info about system registers. Use the command line at the bottom of the main IDA window to send such commands. The output will be displayed in the message window. Hint: most stubs have a "help" command (if they support any commands at all).

The module also makes the following function available from IDC: string (string command);

When using , you will need to tell IDA on which CPU the target is running. This is done in the dialog, available via "Debugger specific options" button in the Process options dialog shown when you choose Remote GDB Debugger from the Run or Attach menu.

Many GDB stubs do not report the address that triggered a hardware breakpoint. In this case, IDA will report a memory breakpoint hit as a generic TRAP signal. Examine the previous instruction to see if it referenced a memory location with breakpoint. When continuing from such a breakpoint, choose not to pass the signal to the program.

IDA can be used together with a J-Link debug probe from SEGGER Microcontroller GmbH:

See also

• .

Using the option it is easy to debug small ARM, MIPS or PowePC code snippets directly from inside IDA.

1) Download and install QEMU. Win32 builds can be downloaded from

2) Edit cfg\gdb_arch.cfg file and change the "set QEMUPATH" line to point to the install directory of QEMU.

3) In (Debugger|Debugger options, Set specific options), enable "Run a program before debugging".

4) Click "Choose a configuration" and choose a predefined configuration. Choose "for snippets", if mentioned.

5) If necessary, edit the command line or memory map.

6) Click OK, OK to confirm and close the options dialog.

7) In Debugger|Process options make sure that Hostname is set to "localhost" and port is non-zero.

8) Select the code range to emulate or at least the first instruction. Alternatively, you can rename the starting address "ENTRY" and end address as "EXIT".

9) Choose Debugger|Run or press F9.

IDA will write the database into an ELF file (if %e was specified), start QEMU with the specified command line and connect to its GDB stub. It will set the SP and PC values so that the code can be stepped through.

NOTE

While it can be very useful, QEMU emulation has certain limitations:

1) the memory map is usually fixed at compile time. So if your program addresses intersect some of the system regions as specified by the memory map, IDA will refuse to start debugging. In that case, you can either rebase the program so that it fits into RAM regions or check other QEMU board configurations for a compatible memory layout.

2) the emulation starts at the system (kernel) level when there is no OS loaded. That means that system calls and imported functions will not work.

3) the hardware access will only work to the extent emulated by QEMU. If the code you are emulating does not match the chosen board configuration of QEMU, the code accessing the hardware most likely will not work properly, if at all.

See also

The "Run a program before debugging" option in Remote GDB Debugger options allows to automatically run a program (such as a debugging server) when starting a debugging session. If you enable it, the following options become available:

Command line

        Command line of the program to run. The following special symbols can be used:

%i: input file name from the Process options dialog %p: port number from the Process options dialog %e: file name of a temporary ELF file created from the database contents Initial SP

        IDA will set the SP (or a similar register) after connecting to the server

Choose a configuration

        Load one of the pre-defined configurations (command line, memory map and SP value)
        described in the gdb_arch.cfg file.

Memory map

        Edit the memory map for the external server. It will be used during debugging.

One use of these options is to debug small code snippets using the QEMU emulator.

See also

• Remote GDB Debugger options

• Debugger submenu.

The PIN debugger is a remote debugger plugin used to record execution traces. It allows to record traces on Linux and Windows (x86 and x86_64) from any of the supported IDA platforms (Windows, Linux and MacOSX). Support for MacOSX targets is not yet available. Please see the section PIN support for MacOSX for more details on this subject.

To use the PIN debugger plugin the following steps must be carried out:

• Download the appropriate version of PIN from http://www.pintool.org

• Build the PIN tool

  Copy

  - Configure the debugger specific options in
    Debugger Options, Set specific options.
  
  PIN debugger plugin has the following configuration options:

- PIN Binary Path: Full path to the pin binary.

• PIN Tool Path: Directory where the idadbg.so or .dll PIN tool resides.

• Tracing options:

• Instruction tracing: trace individual instructions

• Basic block tracing: trace basic blocks

• Function tracing: trace functions

• Recording of register values: record register values or not. If this option is disabled, only EIP/RIP will be recorded.

• PIN Tool options:

• Autolaunch pin for "localhost": When this option is set and the host name specified in Debugger, Process Options is "localhost", the PIN tool will be executed by IDA. Otherwise IDA expects the PIN tool to be already running and listening. Please refer to Connecting a remote PIN tool instance from IDA for more details.

• Debug mode: This flag allows one to see what's happening in the PIN tool side. It prints out some debugging information.

• Extra-arguments: Additional command line arguments to be used when constructing the command line to launch PIN locally. The extra arguments can be added before the PIN tool specification (before '-t /path/to/pin/tool) or after the PIN tool (after '-t /path/to/pin/tool' but before '-- application'). Please consult the section "Command Line Switches" of the Intel PIN manual for more details. Optionally you can launch PIN yourself and connect to it from IDA. See Connecting a remote PIN tool instance from IDA for more details.

Before using the PIN tracer the PIN tool module (distributed only in source code form) must be built as the Intel PIN license disallows redistributing PIN tools in binary form.

Please refer to

https://www.hex-rays.com/products/ida/support/tutorials/pin/pin_tutorial.pdf

to learn how to build our PIN tool.

Run QEMU with -s switch to enable its GDB stub. The default port number is 1234. If desired, the -p command line switch can be used to change it. The -S command line switch causes the execution to be suspended at startup. For example:

 qemu.exe -s -S -L . -m 128 -hda linux.img -soundhw all -localtime -M pc

For better debugging, make sure to set the following options in GDB Debugger options:

 Software breakpoints at EIP+1: disabled
 Use CS:IP in real mode: enabled (when debugging 16-bit (real-mode) code)

In other aspects debugging with QEMU is the same as debugging for other targets.

Back to Remote GDB Debugger

For local debugging the PIN tool can be automatically launched by IDA. For remote debugging it must be launched manually, as in the following example:

  $ /path/to/pin -t /path/to/idadbg/lib -p PORT -- APPLICATION [ARGUMENTS]

Where PORT is the port that the PIN tool will listen for incoming connections from IDA. APPLICATION is the target application to be traced and the optional parameter ARGUMENTS are the arguments to be passed to the target application. Please note that on Win64 it may be required to specify the path to specific x64 binary instead to the pin.bat batch file.

To attach to an already running process instead of starting a new one a command like the following one must be executed:

  $ /path/to/pin -pid PID -t /full/path/to/idadbg/lib/with.extension -p PORT

Where PID is the pid of the running process to attach and PORT the port that the PIN tool will listen for incoming connections.

The hostname and port where the PIN tool is listening for incoming connections should be specified in IDA. See the Debugger, Process options dialog.

After successfully launching the PIN tool the IDA debugger can be launched by pressing F9 or selecting Debugger, Start Process.

PIN accepts the following optional environment variables and command line arguments:

  - Environment variables:
    IDAPIN_DEBUG: Set this environment variable to 1 or higher to print
    debugging information.

  - Command line arguments:
    -p number: Port where the PIN tool will listen for incoming connections from IDA
    -idadbg [0|1|2]: Same as the IDAPIN_DEBUG environment variable

The replayer debugger is a pseudo-debugger used to replay recorded traces.

The replayer debugger supports replaying traces recorded with any of the currently supported debuggers, ranging from local Linux or win32 debuggers to remote GDB targets. Currently supported targets include x86, x86_64, ARM, MIPS and PPC.

To use the replayer debugger you will need first to record a trace by enabling , or with another debugger. Then, after a recorded trace in the , select the replay debugger from the debugger's dropdown list and start the debugger normally as you would do with any other debugger.

One of the advantages of the replay debugger module over re-executing the debuggee is that in the replayer debugger it is possible to step not only forward, but also backwards, making it easier to analyze what happened during the execution of the recorded trace.

There are two types of traces that can be replayed: instruction level traces or partial traces. Instruction level traces are recorded by enabling and partial traces are recorded using either or tracing. When a trace is recorded with instruction tracing enabled all register values are saved. With basic block or function level tracing only the instruction pointer is saved. Additionally, in basic block tracing the register values are also saved when the last instruction of a basic block is reached or a call in the middle of a basic block is about to be executed.

The replayer debugger module adds a new menu item: Debugger, Step Back command. It can be used to step back to the previous instruction when replaying a recorded trace.

The PE operation mode can be used to load PE files and debug them in a MS Windows like environment.

The current limitations include:

  - Thread or process manipulation are not supported

  - Limited support for PE+

  - We provide implementations of a limited number of system calls. Feel
    free to implement missing functions using IDC scripts or DLLs.

  - LoadLibrary() will fail on unknown DLLs: the list of desired DLLs must
    be specified before running the debugger in the startup.idc file

  - Limited emulation environment: IDA does not emulate the complete MS Windows
    operating system: it just provides the basic environment for a
    32bit PE file to run (please check the features below). There are many
    ways how the debugged program can detect that it runs in an emulated
    environment.

PE executables feature list:

- SEH support: we try to mimic MS Windows as much as possible. For example, the ICEBP instruction is a privileged instruction, but Windows reports back a single step exception. Similarly, MS Windows does not distinguish between 0xCC and 0xCD 0x03, so when an exception occurs, it reports that the exception address is always one byte before the trap. So if it was an INT 0x3 (CD03), the exception address will point to the 0x03 (in the middle of the instruction).

- TLS callbacks: TLS callbacks are normally parsed by IDA and presented as entry points. They will be called by the debugger before jumping to the main entry point of the application. Turning on the "Debugger Setup/Suspend on debugging start" may be a good idea since it will make all this logic clearly visible.

- Emulation of NT structures: Some malware do not use GetProcAddress() or GetModuleHandle(). Instead, they try to parse the system structures and deduce these values. For this we also provide and build the basic structure of TIB, PEB, PEB_LDR_DATA, LDR_MODULE(s) and RTL_USER_PROCESS_PARAMETERS. Other structures can be built in the bochs_startup() function of the startup.idc file.

PE/PE+ executables feature list:

- Extensible API emulation: The user may provide an implementation of a any API function using scripts. The plugin supports IDC language by default, but if there are any other registered and active external languages, then external language will be used. Currently, the plugin ships with preconfigured IDC and Python scripts (please refer to startup.idc/startup.py).

It is also possible to take a copy of all the API and startup scripts and place them next to the database in question. This will tell the Bochs debugger plugin that these scripts are to be used with the current database directory. Such mechanism makes it possible to customize API/startup scripts for different databases.

In the following example, kernel32!GlobalAlloc is implemented via IDC like this:

 (file name: api_kernel32.idc)
 ///func=GlobalAlloc entry=k32_GlobalAlloc purge=8
 static k32_GlobalAlloc()
 {
   eax = BochsVirtAlloc(0, BochsGetParam(2), 1);
   return 0;
 }
 ///func=GlobalFree entry=k32_GlobalFree purge=4
 static k32_GlobalFree()
 {
   eax = BochsVirtFree(BochsGetParam(1), 0);
   return 0;
 }

A simple MessageBoxA replacement can be:

 (file name: api_user32.idc)
 ///func=MessageBoxA entry=messagebox purge=0x10
 static messagebox()
 {
   auto param2; param2 = BochsGetParam(2);
   msg("MessageBoxA has been called: %s\n",
        get_strlit_contents(param2, -1, STRTYPE_C));

   // Supply the return value
   eax = 1;

   // Continue execution
   return 0;
 }

To access the stack arguments passed to a given IDC function, please use the BochsGetParam() IDC function.

For a full reference on using IDC to implement API calls, please refer to ida\plugins\bochs\api_kernel32.idc file.

- Remap a DLL path (from the startup.idc script):

    /// map /home/johndoe/sys_dlls/user32.dll=d:\winnt\system32\user32.dll
    /// map /home/johndoe/sys_dlls/kernel32.dll=d:\winnt\system32\kernel32.dll

- Specify additional DLL search path (and optionally change the mapping):

    /// map /home/johndoe/sys_dlls/=d:\winnt\system32
  Or:

    /// map c:\projects\windows_xpsp2_dlls\=c:\windows\system32
  Or just as a search path without mapping:

    /// map c:\program files\my program
  You need to add the appropriate terminating slashes

- Redefine the environment variables: the environment variables can be redefined in startup.idc

    /// env PATH=c:\windows\system32\;c:\programs    /// env USERPROFILE=c:\Users\Guest

  In Linux, if no environment variable is defined in the startup file then no environment strings will be present.
  In Windows, we take the environment variables from the system if none were defined.

- Use native code: it is possible to write a custom Win32/64 DLL and map it into the process space.

Existing APIs can then be redirected to custom written functions. For example:

  ///func=GetProcAddress entry=bochsys.BxGetProcAddress
  ///func=ExitProcess entry=bochsys.BxExitProcess
  ///func=GetModuleFileNameA entry=bochsys.BxGetModuleFileNameA
  ///func=GetModuleHandleA entry=bochsys.BxGetModuleHandleA

Here we redirect some functions to bochsys.dll that modify the memory space of the application. Please note that bochsys.dll is a special module, IDA is aware of it. Custom functions are declared like this:

  (file name: api_kernel32.idc)
  ///func=GetCommandLineA entry=mydll.GetCommandLineA purge=0

Then in startup.idc file, the following line must be added:

   /// load mydll.dll

Custom DLLs are normal DLLs that can import functions from any other DLL. However, it is advisable that the custom DLL is kept small in size and simple, by not linking it to the runtime libraries.

- Helper IDC functions: a set of helper IDC functions are available when the debugger is active. For more information, please refer to "startup.idc".

- Less demanding PE loader: Most PE files can be loaded and run, including system drivers, DLL and some PE files that cannot be run by the operating system.

- Dependency resolution: In the PE operation mode, the plugin will recursively load all DLLs referenced by the program. All DLLs that are not explicitly marked with "stub" in startup.idc will be loaded as is. It is important to "stub" all system DLLs for faster loading. The PE loader creates empty stubs for undefined functions in stubbed DLLs. For example, the following line defines a stub that will always return 0 for CreateFileA:

  /// func=CreateFileA retval=0

Since CreateFileA is mentioned in the IDS files and IDA knows how many bytes it purges from the stack, there is no need to specify the "purge" value. For other functions that are not known to IDA, a full definition line would look like:

  /// func=FuncName purge=N_bytes retval=VALUE

- Startup and Exit scripts: It is possible to assign IDC functions that run when the debugging session starts or is about to terminate (before the application continues from the PROCESS_EXITED event). In addition to running code at startup, the startup script serves a role in telling the PE loader which DLLs are to be mapped for the current debugging session. For example:

  /// stub ntdll.dll
  /// stub kernel32.dll
  /// stub user32.dll
  /// stub shell32.dll
  /// stub shlwapi.dll
  /// stub wininet.dll

These lines list the DLLs that will be used during the debugging session. IDA creates empty stubs for all functions from these DLLs. Non-trivial implementations of selected functions can be specified in api_xxxx.idc files, where xxxx is the module name.

API and startup scripts are searched first in the current directory and then in the ida/plugins/bochs directory.

- Memory allocation limit: The PE loader has a simple memory manager. It is used for the initial memory allocation at the loading stage and for dynamic memory allocation during the debugging session. No memory limits are applied at the loading stage: the loader will load all modules regardless of their size. However, when the debugging session starts, a limit applies on how much memory can be dynamically allocated. This limit is specified in the debugger specific options as "Max allocatable memory". Memory allocation will fail once this limit is reached.

Some notes on bochsys.dll:

- BxIDACall: This exported function is used as a trap to suspend the code execution in Bochs and perform some actions in IDA. For example, when the target calls kernel32.VirtualAlloc, it is redirected to bochsys.BxVirtualAlloc, which calls BxIDACall, which triggers IDA:

  kernel32.VirtualAlloc -> bochsys.BxVirtualAlloc -> BxIDACall -> IDA bochs plugin

A breakpoint can be set on this function to monitor all API calls that are handled by IDA.

- BxUndefinedApiCall: This exported function is executed when the application calls an unimplemented function. Setting a breakpoint on it will allow discovering unimplemented functions and eventually implementing them as IDC or DLL functions. It can also be used to determine when unpacking/decryption finishes (provided that all functions used by the unpacker have been defined).

See also:

• Bochs debugger

• Bochs plugin operation mode FAQ

The Bochs debugger plugin uses the Bochs internal command line debugger. For more about the internal debugger:

To use the Bochs debugger plugin, the following steps must be carried out:

• Download and install Bochs v2.6.x from: For Mac OS or Linux, please refer to the following guide:

Because the debugger plugin uses the Bochs command line debugger, it has the following limitations:

There are ways to overcome some of the limitations mentioned above by downloading Bochs source code and modifying it. For example, the number of allowed breakpoints can be increased.

The Bochs debugger configuration dialog box has the following entries:

Default configuration parameters are taken from ida\cfg\dbg_bochs.cfg.

The Bochs debugger module adds a new menu item: Debugger, Bochs Command. It can be used to send arbitrary commands to Bochs. The command output is displayed in the message window (there is also an IDC counterpart of this function, please refer to "startup.idc" file). This command is very useful but may interfere with IDA, especially if the user modifies breakpoints or resume execution outside IDA.

See also:

The IDB operation mode, as its name implies, takes the current database as the input and runs it under the Bochs debugger. This mode can be used to debug any x86 32 or 64-bit code. Please note that the code executes with privilege ring 3.

The following parameters can be specified in the IDB operation mode:

It may also prove useful to enable the "Debugger Setup/Suspend on debugging start" so that IDA automatically suspends the process before executing the first instruction.

While debugging, exceptions may occur and are caught by IDA. Please note that these exceptions are raw machine exceptions. For example, instead of an access violation exception, a page fault exception is generated.

See also:

The Dalvik debugger is a plugin to debug Android applications written for the Dalvik Virtual Machine. It includes the source level debugging too.

Dalvik debugger specific options:

    ADB executable

        IDA needs to know where the 'adb' utility resides, and tries various
        methods to locate it automatically. Usually IDA finds the path to adb,
        but if it fails then we can define the ANDROID_SDK_HOME or the
        ANDROID_HOME environment variable to point to the directory where the
        Android SDK is installed to. Or set the path to 'adb' here.

    Emulator/device serial number

        If multiple emulator/device instances are running, you must specify
        the target instance to connect to.

    Package name

        Set the package name for the application as specified in
        AndroidManifest.xml. It is a mandatory option to start an application.
        If you plan to use "Attach to process" debugger action then you may
        leave this field empty.

    Activity

        If your want to start an application using the "Start process"
        debugger action then you have to set this option too. Copy it from
        AndroidManifest.xml. If you plan to use the "Attach to process"
        debugger action then you may leave this field empty.

    Command line arguments

        Every object inside Dalvik VM has an ID. It is the 64-bit number.
        If you want to see it in "Locals"/"Watches" windows then set this
        checkbox.

Source-level debugging

    In order to use source-level debugging you have to set paths to the
    application source code files. Do it using "Options/Sources path"
    menu item.

    Our dalvik debugger presumes that the application sources reside
    in the current (".") directory.  If this is not the case, you can
    map current directory (".") to the directory where the source files
    are located.

List of special things about our Dalvik debugger:

  - In Dalvik there is no stack and there is no SP register.
    The only available register is IP.
  - The method frame registers and slots (v0, v1, ...) are represented as
    local variables in IDA.
    We can see them in the Debugger/Debugger Windows/Locals window
  - The stack trace is available from "Debugger/Windows/Stack trace"
  - When the application is running, it may execute some system code.
    If we break the execution by clicking on the "Cancel" button,
    quite often we may find ourselves outside of the application,
    in the system code. The value of the IP register is 0xFFFFFFFF in this
    case, and stack trace shows only system calls and a lot of 0xFFFFFFFFs.
    It means that IDA could not locate the current execution position inside
    the application. We recommend to set more breakpoints inside the
    application, resume the execution and interact with application by
    clicking on its windows, selecting menu items, etc.
    The same thing can occur when we step out the application or
    step into the system code. In the last case we can use "Run until
    return" debugger command to return to the application code.

Locals window

    IDA considers the method frame registers, slots, and
    variables (v0, v1, ...) as local variables.
    To see their values we have to open the "Locals" window
    from the "Debugger/Debugger windows/Locals" menu item.

    If the information about the frame is available (the symbol table is
    intact) then IDA shows the method arguments, the method local variables
    with names and other non-named variables.
    Otherwise some variable values will not be displayed because IDA
    does not know their types. Variables without type information are
    marked with "Bad type" in the "Locals" window.
    To see the variable value in this case please use the "Watches" window.

Watches window

    To open the "Watches" window please select the "Debugger/Windows/Watches"
    menu item. In this window we can add any variable to watch its value.

    Please note that we have to specify type of variable if it is not known.
    Use C-style casts:
        (Object*)v0
        (String)v6
        (char*)v17
        (int)v7

    We do not need to specify the real type of an object variable,
    the "(Object*)" cast is enough.  IDA can derive the real object type
    itself.

    ATTENTION! An incorrect type may cause the Dalvik VM to crash.

    There is not much we can do about it. Our recommendation is to never
    cast an integer variable to an object type, the Dalvik VM usually
    crashes if we do that. But the integer cast "(int)" is safe in practice.

    Keeping the above in the mind, do not leave the cast entries
    in the "Watches" window for a long time. Delete them before any
    executing instruction that may change the type of the watched variable

See also Debugger submenu.

The WinDbg debugger plugin uses Microsoft's Debugging Engine COM interfaces from the Debugging Tools package.

To use the WinDbg debugger plugin, the following steps must be carried out:

• Please download the latest debugging tools from http://www.microsoft.com/whdc/devtools/debugging/default.mspx

  Copy

  - Configure the debugger specific options in
        Debugger Options, Set specific options.
  
  Windbg debugger plugin has the following configuration options:
  
  - The Debugging Tools folder: This should be configured to point to the same
  folder where Microsoft Debugging Tools are installed. The plugin will try to
  guess where the tools are, but if it fails, a manual intervention will be required.
  If this option is not set, then the plugin will try to use dbgeng.dll from
  MS Windows system folder, while normal debug operations will work, extensions will not.
  
  - Kernel mode debugging: Check this option when debugging the kernel.
  
  - User-mode debugging: Check this option to debug MS Windows applications.
  
  - Non-Invasive debugging: Check this option to enable attaching to user-mode
  processes non-invasively
  
  - Kernel mode debugging with reconnect and initial break: Select this option
  when debugging a kernel and when the connection string contains 'reconnect'. This option
  will assure that the debugger breaks as soon as possible after a reconnect.
  
  - Output flags: These flags tell the debugging engine which kind of output
  messages to display and which to omit

The WinDbg debugger plugins has the following features:

  - Send commands to the debugger engine when the debugging session starts.
  Use the "." key to switch to the command line and start typing commands.
  Please note that while it is possible to send any command to the engine, only the
  commands that change the execution status should not be used:
  go ("g"), step ("t"), step into ("p"), etc...

- Symbol information: If the symbol path is configured properly, then the debugger engine will fetch debug symbols from the appropriate location (symbol server, cache, etc...) For example, setting the following environment variable before starting IDA: _NT_SYMBOL_PATH=srv*c:\pdb_cache*http://msdl.microsoft.com/download/symbols

  - Multi-processor support: Debugger Engine will create a virtual thread for
  each processor that it finds. Similarly, IDA will present these processors as threads.

  - Remote debugging support: It is possible to use the process server "dbgsrv.exe"
  to enable remote debugging. For example:

    1. Run "dbgsrv -t tcp:port=PORT_NUM,server=HOST_NAME"

    2. Verify that the server is correctly running by listing all process
    servers on the given HOST_NAME:

      cdb -QR \\HOST_NAME

    3. Finally, run IDA and specify the following connection string:
      tcp:port=PORT_NUM,server=HOST_NAME

  - Use WinDbg extensions: it is possible to use the extension commands that
  usually work with WinDbg. Make sure that the "Debugging Tools folder" setting
  is properly set so that this feature works.

  - Kernel Debugging: It is possible to debug the kernel the same way as it is
  done with WinDbg. Simply setup the target kernel and configure the WinDbg
  plugin by checking the "kernel mode debugging" option and by typing a correct
  connection string. If the user detaches from a kernel session (using Debugger/Detach Process),
  the debugged kernel will resume. However, if the user selects Debugger/Terminate Process,
  the kernel will be suspended (it will wait until another client attaches to it).

- Dump files support: It is possible to load into IDA dump files generated either manually (using the ".dump" command) or crash dumps generated from a crashed process or kernel. Please refer check the windmp file loader reference.

  After the dump has been loaded, it is possible to run the debugger and investigate about
  the crash by typing Windbg commands into the command line window.
  For example, one could check the call-stack or use any other Windbg extension.

  - External breakpoints: it is possible to use the command line to create breakpoints
  that are not supported by IDA but supported by the debugging engine: in that
  case, all unknown (external) breakpoints will suspend IDA when they trigger.

The WinDbg debugger can be used to debug local programs as well as remote programs. This is controlled via the connection string in the "Process Option" dialog. If it is left blank,it means that a local debugging is in effect. Otherwise, a debug engine compatible connection string is expected. IDA will display an error message if the connection string could not be accepted: in that case, try using the same connection string with "cdb", or "windbg" and see if it works.

The WinDbg debugger module adds a new menu item: Debugger, WinDbg command. It can be used to send arbitrary commands to the debugger engine. The command output is displayed in the message window.

Additional IDC functions provided by the WinDbg debugger

On macOS, the suggested approach is to use with one of the mac_server* binaries that are shipped with IDA - even when debugging apps on your local machine.

Using a standalone debug server application makes it easier to get around the codesigning and debugging restrictions that are built into macOS. Note that this is also the approach used by lldb. Internally lldb uses a dedicated debugserver that implements the core debugger engine - so IDA does the same.

It is possible to use the Local Mac OS X Debugger in ida.app, but you must run IDA as root.

For a deeper dive into macOS debugging, see our tutorial:

See also

The disk image operation mode is used to run Bochs with any Bochs disk image.

A simple way to get started is to launch IDA and disassemble the bochsrc file associated with your disk image. IDA will recognize bochsrc files, parse the contents, determine the associated disk image and create a new database containing the first sector of the disk image (usually the boot sector).

The database does not have to correspond to the disk image: it could in fact start as an empty database, then user could convert the needed segments to loader segments for later analysis. The following script can be used for that purpose:

If the disk image switches to protected mode with memory paging enabled, IDA will use the page table mapping to display segments. For 16-bit applications, IDA automatically creates a default DOS memory map (Interrupt vector table, Bios Data Area, User Memory and BIOS ROM). Also, the Bochs Debugger plugin will try to guess the debugger segment bitness, nonetheless the user can edit the bitness manually.

Moreover, the Bochs internal debugger provides the ability to add hardware like breakpoints, known as watchpoints, but the addresses must be physical addresses. In order to use the disk image operation mode in a more convenient way, the plugin will convert the virtual addresses to physical addresses (if page table information is present) before adding the hardware breakpoint. This mechanism will not always work, please check the for more information. For hardware breakpoint on execute, the plugin will use the selected address as-is and create a physical breakpoint.

The following parameters can be specified for the disk image operation mode:

This is a small example on how to debug a given disk image:

1. Prepare the needed bochs virtual machine files (bochsrc, disk image, floppy image if needed, etc...)

2. Load the bochsrc file into IDA. IDA will automatically create a database.

(Step 2, is optional. It is possible to use a database of your choice, but remember to point its "Debugger->Process Options->Input file" to the bochsrc file)

3. Make sure the "Disk image" operation mode is selected (If Step 2 was used, then Disk image operation mode will be selected automatically)

4. Enable "Debugger Options->Suspend on debugging start", and start debugging!

In the disk image operation mode, the Bochs debugger plugin does not handle or report exceptions, if they must be caught and handled, please put breakpoints in the IDT or IVT entries.

See also:

You may either start a local debugging session on a new process or start a local debugging session and attach it to an existing process. Both options are accessible through the command line.

idal -rlinux MY_PROGRAM

will start the program, create a temporary database that allows the user to work with the target at once.

The command

idal -rlinux+

will offer you a choice of running processes to connect to.

and we can proceed with our local Linux debugging session.

The IDA Debugger allows you to either start a new process (Run) or attach itself to an existing process (Attach)

Let's select "attach to local win32". What we get is a list of currently running processes to which we can attach with a simple click.

and here is the result once we are attached to the program.

The Linux debugger has the following particularities and limitations:

- The debugger server can handle only one IDA client at a time

- By default, the 64-bits debugger will try to load "libunwind-x86_64.so.8" and "libunwind-ptrace.so.0" in order to help with stack recovery.

- ARMLinux: hardware breakpoints are not supported

- ARMLinux: The THUMB mode is not supported

- Configure the debugger specific options (for 64 bits only) in Debugger Options, Set specific options.

  - Path to libunwind:
    - "libunwind-x64_64.so.8" (the default): the debugger will try to load
      libunwind "libunwind-x86_64.so.8" + "libunwind-ptrace.so.0" pair
      using the regular 'ld' search path.
    - "libunwind-x64_64.so" (note the lack of ".8" at the end): like the
      default, except the debugger will look for "libunwind-x86_64.so"
      and "libunwind-ptrace.so" (this is particularly useful for working
      with libunwind "dev" packages)
    - absolute path to libunwind-x64_64.so.8 or libunwind-x64_64.so: Linux debugger
      will try to load libunwind only from the provided path.
    - absolute path to "libunwind-x64_64.so[.8]": the debugger will try
      to load the two libraries from there (the absolute path to
      "libunwind-ptrace.so[.0]" will be derived from that of
      "libunwind-x64_64.so[.8]")
    - left blank: don't use libunwind to collect stack traces.

  By default this is set to libunwind-x86_64.so meaning the default
  path will be used to load libunwind-x86_64.so(.8) and libunwind-ptrace.so(.0). If an absolute
  path is provided, both libraries will be loaded from this path. If left emtpy, the call
  stack will be analyzed by Ida and not libunwind.

See also

• Start process

• Debugger submenu

• How to launch remote debugging

General:

- How are breakpoints treated by IDA Bochs Plugin: Bochs debugger does not use breakpoints by inserting 0xCC at the given address. Instead, since it is an emulator, it constantly compares the current instruction pointer against the breakpoint list. Data breakpoints are supported by Bochs and are known as "watchpoints". If the user creates hardware breakpoints, IDA will automatically create Bochs watchpoints.

- How to select the Bochs operation mode programmatically: using IDC: it is possible to use process_config_line() function to pass a key=value. For example, process_config_line("DEFAULT_MODE=1") will select the disk image operation mode. (Please refer to cfg\dbg_bochs.cfg for list of configurable options).

- When debugging, IDA undefines instructions: if the "Debugger options / Reconstruct stack" is checked and the stack pointer is in the same segment as the currently executing code, then IDA might undefine instructions. To solve this program, uncheck the reconstruct stack option.

- How to convert from physical to linear addresses and vice versa: Bochs internal debugger provides two useful commands for this: "info tab" and "page".

Disk image operation mode:

- Data/Software breakpoints are not always triggered: During a debugging session, when a breakpoint is created while the protected mode/paging is enabled, the page table information is used to translate addresses and correctly create the breakpoint. When debugging session is started again, IDA cannot access translation tables to re-create the same breakpoint, thus the breakpoint will be created without any translation information (it will be treated as physical addresses) This is why those breakpoints are not triggered. As a workaround, we suggest disabling those breakpoints and re-enable them when paging is enabled. This problem can also arise when the "use virtual breakpoints" option is enabled.

IDB/PE operation mode:

- Cannot map VA: Sometimes, IDA may display a message stating that a given VA could not be mapped. This mainly happens because both IDB/PE operation modes use virtual addresses from 0x0 to 0x9000 and from 0xE0000000 to 0xFFFFFFFF internally. To solve the problem, please rebase the program to another area:

  - IDB operation mode: use Edit, Segment, Rebase program
  - PE operation mode: rebase the input file using a third party utility

PE operation mode:

- Dynamic DLL loading: sometimes, when running a program, the plugin may attempt to load a DLL that is not declared in the stub or load section of the startup script. In this case, please write down the name of the DLL, then add it to the startup script, and restart the debug session. It is possible to create a local copy, next to your database, of startup scripts so that these scripts will be used with this database only.

- Disk image loading slow: The disk image produced in the PE operation mode can be as big as 20MB. The reason for this slow loading is most probably because the plugin tries to load all referenced DLLs instead of stubbing them. To fix this, when the process starts, please take note of the loaded DLLs list (using IDA / Modules List) then add the desired module names in the startup.* / "stub" section. See also: Bochs debugger

Here you can find a comprehensive set of step-by-step tutorials categorized by different debugging types and platforms.

General introduction into debugging with IDA

• Overview of Linux debugging with IDA

• Overview of Windows debugging with IDA

• Debugging a Windows executable locally and remotely

• IDA scriptable debugger: Overview and scriptability

Local debugging tutorials

Windows local debugging:

• IDA Win32 local debugging

• Debugging Windows applications with IDA Bochs plugin

Linux local debugging:

• Debugging Linux applications locally

• IDA Linux local debugging

• Using the Bochs debugger plugin in Linux

Remote debugging tutorials

• General remote debugging with IDA Pro

• Debugging Mac OSX Applications with IDA Pro

• Debugging iOS Applications with IDA Pro

• Debugging a Windows executable remotely

• IDA Win32 to Win32 debugging

• IDA Win32 to Win64 debugging

• Debugging Windows Kernel with VMWare and IDA WinDbg plugin

• Debugging Linux Kernel under VMWare using IDA GDB debugger

PIN Tracer:

• Debugging Linux/Windows applications with PIN Tracer module

Other specialized debugging tutorials

Android/Dalvik debugging:

• Debugging Dalvik programs

XNU debugging:

• Debugging the XNU Kernel with IDA Pro

QEMU debugging:

• Debugging code snippets with QEMU debugger (a la IDA Bochs debugger)

Trace and replay debugger features:

• Trace Replayer and Managing Traces

• Using IDA Pro's tracing features

Appcall mechanism:

• • Appcall

Recording traces on MacOSX target is not supported yet. Versions equal or prior to 2.12-55942 does not have support for the API PIN_SpawnInternalThread, which is needed by IDA to communicate with the PIN tool.

However, it's possible to record traces from a Linux or Windows target using the MacOSX version of IDA.

Last updated on September 27, 2023 — v0.3

Preface

Starting with version 6.6, IDA Pro can debug Android applications written for the Dalvik Virtual Machine. This includes source level debugging too. This tutorial explains how to set up and start a Dalvik debugging session.

Installing Android Studio

First of all we have to install the Android SDK from the official site Android Studio.

Environment Variables

IDA needs to know where the adb utility resides, and tries various methods to locate it automatically. Usually IDA finds the path to adb, but if it fails then we can define the ANDROID_SDK_HOME or the ANDROID_HOME environment variable to point to the directory where the Android SDK is installed to.

Android Device

Start the Android Emulator or connect to the Android device.

Information about preparing a physical device for development can be found at Using Hardware Devices.

Check that the device can be correctly detected by adb:

$ adb devices
List of devices attached
emulator-5554 device

Installing the App

IDA assumes that the debugged application is already installed on the Android emulator/device.

Please download:

and

from our site. We will use this application in the tutorial.

We will use adb to install the application:

$ adb -s emulator-5554 install MyFirstApp.apk

Loading Application into IDA

IDA can handle both .apk app bundles, or just the contained .dex files storing the app’s bytecode. If we specify an .apk file, IDA can either extract one of the contained .dex files by loading it with the ZIP load option, or load all classes*.dex files when using the APK loader.

Dalvik Debugger Options

The main configuration of the dalvik debugger happens resides in "Debugger > Debugger Options > Set specific options":

Connection Settings

ADB executable

As mentioned above IDA tries to locate the adb utility. If IDA failed to find it then we can set the path to adb here.

Connection string

Specifies the argument to the adb connect command. It is either empty (to let adb figure out a meaningful target) or a <host>[:<port>] combination to connect to a remote device somewhere on the network.

Emulator/device serial number

Serial number of an emulator or a device. Passed to adb``'s -s option. This option is useful if there are multiple potential target devices running. For the official Android emulator, it is typically emulator-5554.

Start Application

Fill from AndroidManifest.xml

Press button and point IDA to either the APK or the AndroidManifest.xml file of the mobile app. IDA then automatically fetches the package name and application start activity, as well as the debuggable flag from the specified file.

Package Name

Package name containing the activity to be launched by the debugger.

Activity

Start activity to be launched by the debugger.

Alternative Start Command

Usually IDA builds the start command from the package and activity name and launches the APK from the command line as follows:

am start -D -n '<package>/<activity>' -a android.intent.action.MAIN -c android.intent.category.LAUNCHER

If that does not match your desired debugging setup, you can enter an alternative start command here. Note that you have to provide package and activity as part of the startup command.

APK Debuggable

The value of the debuggable flag, as extracted from the AndroidManifest.xml or the APK. APKs that do not have the debuggable flag set (most do not) cannot be started on unpatched phones. Hence, while this value is false, IDA will display a (silencable) warning when starting a debugging session. To produce a debuggable APK that has the flag set to true, please revert to third-party tooling.

Detect Local Variable Types

This controls the behavior of IDA’s type guessing engine. "Always" and "Never" are pretty self-explanatory: The options force-enable or force-disable type guessing. "Auto" means that type guessing is disabled for Android APIs < 28 and enabled on APIs >= 28. If you work with very old (i.e. API 23 and lower) Android devices and experience crashes during debugging, set this option to "Never". Note that when type guessing is disabled, IDA automatically assumes int for unknown variable types, which causes warnings on API 30 and above.

Local Variables with Type Guessing Deactivated

Local Variables with Type Guessing Activated

Other Options

Show object ID

If active, IDA shows the object ID assigned by the Java VM for composite (non-trivial) types in the local variables window.

Preset BPTs

If active, IDA sets breakpoints at the beginning of all (non-synthetic, non-empty) methods of the start activity class specified in the Activity field above.

Path to Sources

To use source-level debugging we have to set paths to the application source files. We can do it using the "Options > Sources path" menu item.

Our Dalvik debugger presumes that the application sources reside in the current (".") directory. If this is not the case, we can map current directory (".") to the directory where the source files are located.

Let us place the source files DisplayMessageActivity.java and MainActivity.java in the same directory as the MyFirstApp.apk package. This way we do not need any mapping.

Setting Breakpoints

Before launching the application it is reasonable to set a few breakpoints. We can rely on the decision made by IDA (see above the presetBPTs option) or set breakpoints ourselves. A good candidate is the onCreate method of the application’s main activity.

We can use the activity name and the method name onCreate to set a breakpoint:

Naturally, we can set any other breakpoints any time. For example, we can do it later, when we suspend the application.

Starting the Debugger

At last we can start the debugger. Check that the Dalvik debugger backend is selected. Usually it should be done automatically by IDA:

If the debugger backend is correct, we are ready to start a debugger session. There are two ways to do it:

• Launch a new copy of the application (Start process)

• Attach to a running process (Attach to process)

Launching the App

To start a new copy of the application just press <F9> or use the "Debugger > Start process" menu item. The Dalvik debugger will launch the application, wait until application is ready and open a debugger session to it.

We may wait for the execution to reach a breakpoint or press the “Cancel” button to suspend the application.

In our case let us wait until execution reach of onCreate method breakpoint.

Attaching to a Running App

Instead of launching a new process we could attach to a running process and debug it. For that we could have selected the "Debugger > Attach to process…​" menu item. IDA will display a list of active processes.

We just select the process we want to attach to.

Particularities of Dalvik Debugger

All traditional debug actions like Step into, Step over, Run until return and others can be used. If the application sources are accessible then IDA will automatically switch to the source-level debugging.

Below is the list of special things about our Dalvik debugger:

• In Dalvik there is no stack and there is no SP register. The only available register is IP.

• The method frame registers and slots (v0, v1, …​) are represented as local variables in IDA. We can see them in the "Debugger > Debugger Windows > Locals" window (see below)

• The stack trace is available from "Debugger > Debugger windows > Stack trace" (the hot key is <Ctrl-Alt-S>).

• When the application is running, it may execute some system code. If we break the execution by clicking on the “Cancel” button, quite often we may find ourselves outside of the application, in the system code. The value of the IP register is 0xFFFFFFFF in this case, and stack trace shows only system calls and a lot of 0xFFFFFFFF. It means that IDA could not locate the current execution position inside the application. We recommend to set more breakpoints inside the application, resume the execution and interact with application by clicking on its windows, selecting menu items, etc. The same thing can occur when we step out the application.

• Use “Run until return” command to return to the source-level debugging if you occasionally step into a method and the value of the IP register becomes 0xFFFFFFFF.

Locals Window

IDA considers the method frame registers, slots, and variables (v0, v1, …​) as local variables. To see their values we have to open the "Locals" window from the "Debugger > Debugger windows > Locals" menu item.

At the moment the debugger stopped the execution at the breakpoint which we set on onCreate method.

Perform “Step over” action (the hot key is <F8>) two times and open the "Locals" window, we will see something like the following:

If information about the frame is available (the symbol table is intact) or type guessing is enabled then IDA shows the method arguments, the method local variables with names and other non-named variables. Otherwise some variable values will not be displayed because IDA does not know their types.

Variables without type information are marked with "Bad type" in the "Locals" window. To see the variable value in this case please use the "Watch view" window and query them with an explicit type (see below).

Watch View Window

To open the "Watch view" window select the "Debugger > Debugger windows > Watch view" menu item. In this window we can add any variable to watch its value.

note that we have to specify type of variable if it is not known. Use C-style casts:

• (Object*)v0

• (String)v6

• (char*)v17

• (int)v7

We do not need to specify the real type of an object variable, the “(Object*)” cast is enough. IDA can derive the real object type itself.

Attention! On Android API versions 23 and below an incorrect type may cause the Dalvik VM to crash. There is not much we can do about it. Our recommendation is to never cast an integer variable to an object type, the Dalvik VM usually crashes if we do that. But the integer cast “(int)” is safe in practice.

Keeping the above in the mind, do not leave the cast entries in the "Watch view" window for a long time. Delete them before any executing instruction that may change the type of the watched variable.

Overall we recommend to debug on a device that runs at least Android API 24.

Troubleshooting

• Check the path to adb in the "Debugger specific options"

• Check the package and activity names

• Check that the emulator is working and was registered as an adb device. Try to restart the adb daemon.

• Check that the application was successfully installed on the emulator/device

• Check the output window of IDA for any errors or warnings

• Turn on more debug print in IDA with the -z50000 command line switch.

• Android APIs 24 and 25 are known to return wrong instruction sizes during single stepping. Try migrating to a different Android API if you have trouble with single steps.

• IDA exposes a subset of the JDWP specification as IDC commands. (Usually the name from the specification prefixed with JDWP_).

• Android APIs 23 and below crash if type guessing is enabled. Remedy this by setting the Detect Local Variable Types option to Never or migrate to a newer Android API.

Debugging Mac OSX Applications with IDA Pro

Last updated on March 6, 2021 — v2.0

Overview

IDA Pro fully supports debugging native macOS applications.

Intel x86/64 debugging has been supported since IDA 5.6 (during OSX 10.5 Leopard), but due to IDA’s use of libc++ we can only officially support debugging on OSX 10.9 Mavericks and later. Apple Silicon arm64 debugging for macOS11 is also supported since IDA 7.6.

Note that this task is riddled with gotchas, and often times it demands precise workarounds that are not required for other platforms. In this tutorial we will purposefully throw ourselves into the various pitfalls of debugging on a Mac, in the hopes that learning things the hard way will ultimately lead to a smoother experience overall.

Begin by downloading samples:

which contains the sample applications used in this writeup.

Codesigning & Permissions

It is important to note that a debugger running on macOS requires special permissions in order to function properly. This means that the debugger itself must be codesigned in such a way that MacOS allows it to inspect other processes.

The main IDA Pro application is not codesigned in this way. Later on we’ll discuss why.

To quickly demonstrate this, let’s open a binary in IDA Pro and try to debug it. In this example we’ll be debugging the helloworld app from samples.zip:

on MacOSX 10.15 Catalina using IDA 7.5. Begin by loading the file in IDA:

$ alias ida64="/Applications/IDA\ Pro\ 7.5/ida64.app/Contents/MacOS/ida64"
$ ida64 helloworld

Now go to menu Debugger>Select debugger and select Local Mac OS X Debugger:

Immediately IDA should print a warning message to the Output window:

This program must either be codesigned or run as root to debug mac applications.

This is because IDA is aware that it is not codesigned, and is warning you that attempting to debug the target application will likely fail. Try launching the application with shortcut F9. You will likely get this error message:

Codesigning IDA Pro might resolve this issue, but we have purposefully decided not to do this. Doing so would require refactoring IDA’s internal plugin directory structure so that it abides by Apple’s bundle structure guidelines. This would potentially break existing plugins as well as third-party plugins written by users. We have no plans to inconvenience our users in such a way.

Also note that running IDA as root will allow you to use the Local Mac OS X Debugger without issue, but this is not advisable.

A much better option is to use IDA’s mac debug server - discussed in detail in the next section.

Using the Mac Debug Server

A good workaround for the debugging restrictions on macOS is to use IDA’s debug server - even when debugging local apps on your mac machine. The mac debug server is a standalone application that communicates with IDA Pro via IPC, so we can ship it pre-codesigned and ready for debugging right out of the box:

$ codesign -dvv /Applications/IDA\ Pro\ 7.5/idabin/dbgsrv/mac_server64
Executable=/Applications/IDA Pro 7.5/ida.app/Contents/MacOS/dbgsrv/mac_server64
Identifier=com.hexrays.mac_serverx64
Format=Mach-O thin (x86_64)
CodeDirectory v=20100 size=6090 flags=0x0(none) hashes=186+2 location=embedded
Signature size=9002
Authority=Developer ID Application: Hex-Rays SA (ZP7XF62S2M)
Authority=Developer ID Certification Authority
Authority=Apple Root CA
Timestamp=May 19, 2020 at 4:13:31 AM

Let’s try launching the server:

$ /Applications/IDA\ Pro\ 7.5/idabin/dbgsrv/mac_server64
IDA Mac OS X 64-bit remote debug server(MT) v7.5.26. Hex-Rays (c) 2004-2020
Listening on 0.0.0.0:23946...

Now go back to IDA and use menu Debugger>Switch debugger to switch to remote debugging:

Now use Debugger>Process options to set the Hostname and Port fields to localhost and 23946.

(Note that the port number was printed by mac_server64 after launching it):

Also be sure to check the option Save network settings as default so IDA will remember this configuration.

Now go to _main in the helloworld disassembly, press F2 to set a breakpoint, then F9 to launch the process. Upon launching the debugger you might receive this prompt from the OS:

macOS is picky about debugging permissions, and despite the fact that mac_server is properly codesigned you still must explicitly grant it permission to take control of another process. Thankfully this only needs to be done once per login session, so macOS should shut up until the next time you log out (we discuss how to disable this prompt entirely in the Debugging Over SSH section below).

After providing your credentials the debugger should start up without issue:

Using a Launch Agent

To simplify using the mac server, save the following XML as com.hexrays.mac_server64.plist in ~/Library/LaunchAgents/:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hexrays.mac_server64</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/IDA Pro 7.5/dbgsrv/mac_server64</string>
        <string>-i</string>
        <string>localhost</string>
    </array>
    <key>StandardOutPath</key>
    <string>/tmp/mac_server64.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/mac_server64.log</string>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Now mac_server64 will be launched in the background whenever you log in. You can connect to it from IDA at any time using the Remote Mac OS X Debugger option. Hopefully this will make local debugging on macOS almost as easy as other platforms.

Debugging System Applications

There are some applications that macOS will refuse to allow IDA to debug.

For example, load /System/Applications/Calculator.app/Contents/MacOS/Calculator in IDA and try launching the debugger. You will likely get this error message:

Despite the fact that mac_server64 is codesigned, it still failed to retrieve permission from the OS to debug the target app. This is because Calculator.app and all other apps in /System/Applications/ are protected by System Integrity Protection and they cannot be debugged until SIP is disabled. Note that the error message is a bit misleading because it implies that running mac_server64 as root will resolve the issue - it will not. Not even root can debug apps protected by SIP.

Disabling SIP allows IDA to debug applications like Calculator without issue:

The effects of SIP are also apparent when attaching to an existing process. Try using menu Debugger>Attach to process, with SIP enabled there will likely only be a handful of apps that IDA can debug:

Disabling SIP makes all system apps available for attach:

It is unfortunate that such drastic measures are required to inspect system processes running on your own machine, but this is the reality of MacOS. We advise that you only disable System Integrity Protection when absolutely necessary, or use a virtual machine that can be compromised with impunity.

Debugging System Libraries

With IDA you can debug any system library in /usr/lib/ or any framework in /System/Library/.

This functionality is fully supported, but surprisingly it is one of the hardest problems the mac debugger must handle. To demonstrate this, let’s try debugging the _getaddrinfo function in libsystem_info.dylib.

Consider the getaddrinfo application from samples.zip:

#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <string.h>
#include <stdio.h>

int main(int argc, char **argv)
{
  if ( argc != 2 )
  {
    fprintf(stderr, "usage: %s <hostname>\n", argv[0]);
    return 1;
  }

  struct addrinfo hints;
  memset(&hints, 0, sizeof(hints));

  hints.ai_family = AF_INET;
  hints.ai_flags |= AI_CANONNAME;

  struct addrinfo *result;
  int code = getaddrinfo(argv[1], NULL, &hints, &result);
  if ( code != 0 )
  {
    fprintf(stderr, "failed: %d\n", code);
    return 2;
  }

  struct sockaddr_in *addr_in = (struct sockaddr_in *)result->ai_addr;
  char *ipstr = inet_ntoa(addr_in->sin_addr);
  printf("IP address: %s\n", ipstr);

  return 0;
}

Try testing it out with a few hostnames:

$ ./getaddrinfo localhost
IP address: 127.0.0.1
$ ./getaddrinfo hex-rays.com
IP address: 104.26.10.224
$ ./getaddrinfo foobar
failed: 8

Now load libsystem_info.dylib in IDA and set a breakpoint at _getaddrinfo:

$ ida64 -o/tmp/libsystem_info /usr/lib/system/libsystem_info.dylib

Choose Remote Mac OS X Debugger from the Debugger menu and under Debugger>Process options be sure to provide a hostname in the Parameters field. IDA will pass this argument to the executable when launching it:

Before launching the process, use Ctrl+S to pull up the segment list for libsystem_info.dylib. Pay special attention to the __eh_frame and __nl_symbol_ptr segments. Note that they appear to be next to each other in memory:

This will be important later.

Finally, use F9 to launch the debugger and wait for our breakpoint at _getaddrinfo to be hit. We can now start stepping through the logic:

Everything appears to be working normally, but use Ctrl+S to pull up the segment information again. We can still see __eh_frame, but it looks like __nl_symbol_ptr has gone missing:

It is actually still present, but we find it at a much higher address:

Recall that we opened the file directly from the filesystem (/usr/lib/system/libsystem_info.dylib). However this is actually not the file that macOS loaded into memory. The libsystem_info image in process memory was mapped in from the dyld_shared_cache, and the library’s segment mappings were modified before it was inserted into the cache.

IDA was able to detect this situation and adjust the database so that it matches the layout in process memory. This functionality is fully supported, but it is not trivial. Essentially the debugger must split your database in half, rebase all code segments to one address, then rebase all data segments to a completely different address.

It is worth noting there is another approach that achieves the same result, but without so much complexity.

Debugging Modules in dyld_shared_cache

As an alternative for the above example, note that you can load any module directly from a dyld_shared_cache file and debug it. For example, open the shared cache in IDA:

$ ida64 -o/tmp/libsystem_info2 /var/db/dyld/dyld_shared_cache_x86_64h

When prompted, select the "single module" option:

Then choose the libsystem_info module:

Select the Remote Mac OS X Debugger and for Debugger>Process options use the exact same options as before:

Now set a breakpoint at _getaddrinfo and launch the process with F9.

After launching the debugger you might see this warning:

This is normal. Modules from the dyld_shared_cache will contain tagged pointers, and IDA patched the pointers when loading the file so that analysis would not be hindered by the tags. IDA is warning us that the patches might cause a discrepancy between the database and the process, but in this case we know it’s ok. Check Don’t display this message again and don’t worry about it.

Launching the process should work just like before, and we can start stepping through the function in the shared cache:

This time there was no special logic to map the database into process memory. Since we loaded the module directly from the cache, segment mappings already match what’s expected in the process. Thus only one rebasing operation was required (as apposed to the segment scattering discussed in the previous example).

Both techniques are perfectly viable and IDA goes out of its way to fully support both of them. In the end having multiple solutions to a complex problem is a good thing.

Debugging Objective-C Applications

When debugging macOS applications it is easy to get lost in some obscure Objective-C framework. IDA’s mac debugger provides tools to make debugging Objective-C code a bit less painful.

Consider the bluetooth application from samples.zip:

#import <IOBluetooth/IOBluetooth.h>

int main(void)
{
  NSArray *devices = [IOBluetoothDevice pairedDevices];
  int count = [devices count];
  for ( int i = 0; i < count; i++ )
  {
    IOBluetoothDevice *device = [devices objectAtIndex:i];
    NSLog(@"%@:\n", [device name]);
    NSLog(@"  paired:    %d\n", [device isPaired]);
    NSLog(@"  connected: %d\n", [device isConnected]);
  }
  return 0;
}

The app will print all devices that have been paired with your host via Bluetooth. Try running it:

$ ./bluetooth
2020-05-22 16:27:14.443 bluetooth[17025:15645888] Magic Keyboard:
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   paired:    1
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   connected: 1
2020-05-22 16:27:14.443 bluetooth[17025:15645888] Apple Magic Mouse:
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   paired:    1
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   connected: 1
2020-05-22 16:27:14.443 bluetooth[17025:15645888] iPhone SE:
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   paired:    0
2020-05-22 16:27:14.443 bluetooth[17025:15645888]   connected: 0

Let’s try debugging this app. First consider the call to method +[IOBluetoothDevice pairedDevices]:

If we execute a regular instruction step with F7, IDA will step into the _objc_msgSend function in libobjc.A.dylib, which is probably not what we want here. Instead use shortcut Shift+O. IDA will automatically detect the address of the Objective-C method that is being invoked and break at it:

This module appears to be Objective-C heavy, so it might be a good idea to extract Objective-C type info from the module using right click -> Load debug symbols in the Modules window:

This operation will extract any Objective-C types encoded in the module, which should give us some nice prototypes for the methods we’re stepping in:

Let’s continue to another method call - but this time the code invokes a stub for _objc_msgSend that IDA has not analyzed yet, so its name has not been properly resolved:

In this case Shift+O should still work:

Shift+O is purposefully flexible so that it can be invoked at any point before a direct or indirect call to _objc_msgSend. It will simply intercept execution at the function in libobjc.A.dylib and use the arguments to calculate the target method address.

However, you must be careful. If you use this action in a process that does not call _objc_msgSend, you will lose control of the process. It is best to only use it when you’re certain the code is compiled from Objective-C and an _objc_msgSend call is imminent.

Decompiling Objective-C at Runtime

The Objective-C runtime analysis performed by Load debug symbols will also improve decompilation.

Consider the method -[IOBluetoothDevice isConnected]:

Before we start stepping through this method we might want to peek at the pseudocode to get a sense of how it works. Note that the Objective-C analysis created local types for the IOBluetoothDevice class, as well as many other classes:

This type info results in some sensible pseudocode:

We knew nothing about this method going in - but it’s immediately clear that device connectivity is determined by the state of an io_service_t handle in the IOBluetoothObject superclass, and we’re well on our way.

Debugging Over SSH

In this section we will discuss how to remotely debug an app on a mac machine using only an SSH connection. Naturally, this task introduces some unique complications.

To start, copy the mac_server binaries and the bluetooth app from samples.zip:

to the target machine:

$ scp <IDA install dir>/dbgsrv/mac_server* user@remote:
$ scp bluetooth user@remote:

Now ssh to the target machine and launch the mac_server:

$ ssh user@remote
user@remote:~$ ./mac_server64
IDA Mac OS X 64-bit remote debug server(MT) v7.5.26. Hex-Rays (c) 2004-2020
Listening on 0.0.0.0:23946...

Now open the bluetooth binary on the machine with your IDA installation, select Remote Mac OS X Debugger from the debugger menu, and for Debugger>Process options set the debugging parameters. Be sure to replace <remote user> and <remote ip> with the username and ip address of the target machine:

Try launching the debugger with F9. You might get the following error message:

This happened because debugging requires manual authentication from the user for every login session (via the Take Control prompt discussed under Using the Mac Debug Server, above).

But since we’re logged into the mac via SSH, the OS has no way of prompting you with the authentication window and thus debugging permissions are refused.

Note that mac_server64 might have printed this workaround:

WARNING: The debugger could not acquire the necessary permissions from the OS to
debug mac applications. You will likely have to specify the proper credentials at
process start. To avoid this, you can set the MAC_DEBMOD_USER and MAC_DEBMOD_PASS
environment variables.

But this is an extreme measure. As an absolute last resort you can launch the mac_server with your credentials in the environment variables, which should take care of authentication without requiring any interaction with the OS. However there is a more secure workaround.

In your SSH session, terminate the mac_server process and run the following command:

$ security authorizationdb read system.privilege.taskport > taskport.plist

Edit taskport.plist and change the authenticate-user option to false:

<key>authenticate-user</key>
<false/>

Then apply the changes:

$ sudo security authorizationdb write system.privilege.taskport < taskport.plist

This will completely disable the debugging authentication prompt (even across reboots), which should allow you to use the debug server over SSH without macOS bothering you about permissions.

Dealing With Slow Connections

When debugging over SSH you might experience some slowdowns. For example you might see this dialog appear for several seconds when starting the debugger:

During this operation IDA is fetching function names from the symbol tables for all dylibs that have been loaded in the target process. It is a critical task (after all we want our stack traces to look nice), but it is made complicated by the sheer volume of dylibs loaded in a typical macOS process due to the dyld_shared_cache. This results in several megabytes of raw symbol names that mac_server must transmit over the wire every time the debugger is launched.

We can fix this by using the same trick that IDA’s Remote iOS Debugger uses to speed up debugging - by extracting symbol files from the dyld cache and parsing them locally. Start by downloading the ios_deploy utility from our downloads page, and copy it to the remote mac:

$ scp ios_deploy user@remote:

Then SSH to the remote mac and run it:

$ ./ios_deploy symbols -c /var/db/dyld/dyld_shared_cache_x86_64h -d mac_symbols
Extracting symbols from /var/db/dyld/dyld_shared_cache_x86_64h => mac_symbols
Extracting symbol file: 1813/1813
mac_symbols: done
$ zip -r mac_symbols.zip mac_symbols

Copy mac_symbols.zip from the remote machine to your host machine and unzip it. Then open Debugger>Debugger options>Set specific options and set the Symbol path field:

Now try launching the debugger again, it should start up much faster.

Also keep the following in mind:

• Use /var/db/dyld/dyld_shared_cache_i386 if debugging 32-bit apps

• You must perform this operation after every macOS update. Updating the OS will update the dyld_shared_cache, which invalidates the extracted symbol files.

• The ios_deploy utility simply invokes dyld_shared_cache_extract_dylibs_progress from the dsc_extractor.bundle library in Xcode. If you don’t want to use ios_deploy there are likely other third-party tools that do something similar.

Debugging arm64 Applications on Apple Silicon

IDA 7.6 introduced the ARM Mac Debugger, which can debug any application that runs natively on Apple Silicon.

On Apple Silicon, the same rules apply (see Codesigning & Permissions above). The Local ARM Mac Debugger can only be used when run as root, so it is better to use the Remote ARM Mac Debugger with the debug server (mac_server_arm64), which can debug any arm64 app out of the box (see Using the Mac Debug Server).

We have included arm64 versions of the sample binaries used in the previous examples. We encourage you to go back and try them. They should work just as well on Apple Silicon.

Debugging arm64e System Applications

Similar to Intel Macs, IDA cannot debug system apps on Apple Silicon until System Integrity Protection is disabled.

But here macOS introduces another complication. All system apps shipped with macOS are built for arm64e - and thus have pointer authentication enabled. This is interesting because ptruath-enabled processes are treated much differently within the XNU kernel. All register values that typically contain pointers (PC, LR, SP, and FP) will be signed and authenticated by PAC.

Thus, if a debugger wants to modify the register state of an arm64e process, it must know how to properly sign the register values. Only arm64e applications are allowed to do this (canonically, at least).

You may have noticed that IDA 7.6 ships with two versions of the arm64 debug server:

mac_server_arm64e is built specifically for the arm64e architecture, and thus will be able to properly inspect other arm64e processes. We might want to try running this version right away, but by default macOS will refuse to run any third-party software built for arm64e:

According to Apple, this is because the arm64e ABI is not stable enough to be used generically. In order to run third-party arm64e binaries you must enable the following boot arg:

$ sudo nvram boot-args=-arm64e_preview_abi

After rebooting you can finally run mac_server_arm64e:

This allows you to debug any system application (e.g. /System/Applications/Calculator.app) without issue:

Also note that the arm64e ABI limitation means you cannot use the Local ARM Mac Debugger to debug system arm64e apps, since IDA itself is not built for arm64e. It is likely that Apple will break the arm64e ABI in the future and IDA might cease to work. We want to avoid this scenario entirely.

Using the Remote ARM Mac Debugger with mac_server_arm64e is a nice workaround. It guarantees ida.app will continue to work normally regardless of any breakages in the arm64e ABI, and we can easily ship new arm64e builds of the server to anybody who needs it.

Apple Silicon: TL;DR

To summarize:

• Use mac_server_arm64 if you’re debugging third-party arm64 apps that aren’t protected by SIP

• Use mac_server_arm64e if you’re feeling frisky and want to debug macOS system internals. You must disable SIP and enable nvram boot-args=-arm64e_preview_abi, then you can debug any app you want (arm64/arm64e apps, system/non-system apps, shouldn’t matter).

Support

If you have any questions about this writeup or encounter any issues with the debugger itself in your environment, don’t hesitate to contact us at support@hex-rays.com.

Our Mac support team has years of experience keeping the debugger functional through rapid changes in the Apple developer ecosystem. It is likely that we can resolve your issue quickly.

Copyright 2020 Hex-Rays SA

Overview

This tutorial discusses optimal strategies for debugging native iOS applications with IDA Pro.

IDA Pro supports remote debugging on any iOS version since iOS 9 (including iPadOS). Debugging is generally device agnostic so it shouldn't matter which hardware you're using as long as it's running iOS. The debugger itself can be used on any desktop platform that IDA supports (Mac/Windows/Linux), although using the debugger on Mac makes more features available.

Note that IDA supports debugging on both jailbroken and non-jailbroken devices. Each environment provides its own unique challenges and advantages, and we will discuss both in detail in this writeup.

Getting Started

The quickest way to get started with iOS debugging is to use Xcode to install a sample app on your device, then switch to IDA to debug it.

In this example we'll be using an iPhone SE 2 with iOS 13.4 (non-jailbroken) while using IDA 7.5 SP1 on OSX 10.15 Catalina. Start by launching Xcode and use menu File>New>Project... to create a new project from one of the iOS templates, any of them will work:

After selecting a template, set the following project options:

Note the bundle identifier primer.idatest, it will be important later. For the Team option choose the team associated with your iOS Developer account, and click OK. Before building be sure to set the target device in the top left of the Xcode window:

Now launch the build in Xcode. If it succeeds then Xcode will install the app on your device automatically.

Preparing a Debugging Environment

Now that we have a test app installed on our device, let's prepare to debug it. First we must ensure that the iOS debugserver is installed on the device. Since our device is not jailbroken, this is not such a trivial task. By default iOS restricts all remote access to the device, and such operations are managed by special MacOS Frameworks.

Fortunately Hex-Rays provides a solution. Download the ios_deploy utility from our downloads page. This is a command-line support utility that can perform critical tasks on iOS devices without requiring a jailbreak. Try running it with the listen phase. If ios_deploy can detect your device it will print a message:

$ ios_deploy listen
Device connected:
- name:    iPhone SE 2
- model:   iPhone SE 2
- ios ver: 13.4
- build:   17E8255
- arch:    arm64e
- id:      XXXXXXXX-XXXXXXXXXXXXXXXX

Use the mount phase to install DeveloperDiskImage.dmg, which contains the debugserver:

$ export DEVELOPER=/Applications/Xcode.app/Contents/Developer
$ export DEVTOOLS=$DEVELOPER/Platforms/iPhoneOS.platform/DeviceSupport
$ ios_deploy mount -d $DEVTOOLS/13.4/DeveloperDiskImage.dmg

The device itself is now ready for debugging. Now let's switch to IDA and start configuring the debugger. Load the idatest binary in IDA, Xcode likely put it somewhere in its DerivedData directory:

$ alias ida64="/Applications/IDA\ Pro\ 7.5\ sp1/ida64.app/Contents/MacOS/ida64"
$ export XCDATA=~/Library/Developer/Xcode/DerivedData
$ ida64 $XCDATA/idatest/Build/Products/Debug-iphoneos/idatest.app/idatest

Then go to menu Debugger>Select debugger... and select Remote iOS Debugger:

When debugging a binary remotely, IDA must know the full path to the executable on the target device. This is another task that iOS makes surprisingly difficult. Details of the filesystem are not advertised, so we must use ios_deploy to retrieve the executable path. Use the path phase with the app's bundle ID:

$ ios_deploy path -b primer.idatest
/private/var/containers/Bundle/Application/<UUID>/idatest.app/idatest

Use this path for the fields in Debugger>Process options...

<img style="border:1px solid grey;" src="process_options1.png", width="600">

NOTE: the path contains a hex string representing the application's 16-byte UUID. This id is regenerated every time you reinstall the app, so you must update the path in IDA whenever the app is updated on the device.

Now go to Debugger>Debugger options>Set specific options... and ensure the following fields are set:

<img style="border:1px solid grey;" src="ios_options1.png", width="600">

Make special note of the Symbol path option. This directory contains symbol files extracted from your device. Both IDA and Xcode use these files to load symbol tables for system libraries during debugging (instead of reading the tables in process memory), which will dramatically speed up debugging.

Xcode likely already created this directory when it first connected to your device, but if not you can always use ios_deploy to create it yourself:

$ ios_deploy symbols
Downloading /usr/lib/dyld
Downloading 0.69 MB of 0.69 MB
Downloading /System/Library/Caches/com.apple.dyld/dyld_shared_cache_arm64e
Downloading 1648.38 MB of 1648.38 MB
Extracting symbol file: 1866/1866
/Users/troy/Library/Developer/Xcode/iOS DeviceSupport/13.4 (17E8255)/Symbols: done

Also ensure that the Launch debugserver automatically option is checked. This is required for non-jailbroken devices since we have no way to launch the server manually. This option instructs IDA to establish a connection to the debugserver itself via the MacOS Frameworks, which will happen automatically at debugging start.

Lastly, Xcode might have launched the test application after installing it. Use the proclist phase to retreive the app's pid and terminate it with the kill phase:

$ ios_deploy proclist -n idatest
32250
$ ios_deploy kill -p 32250

Finally we are ready to launch the debugger. Go to main in IDA's disassembly view, use F2 to set a breakpoint, then F9 to launch the process, and wait for the process to hit our breakpoint:

You are free to single step, inspect registers, and read/write memory just like any other IDA debugger.

Source Level Debugging

You can also use IDA to debug the source code of your iOS application. Let's rebuild the idatest application with the DWARF with dSYM File build setting:

Since the app is reinstalled, the executable path will change. We'll need to update the remote path in IDA:

$ ios_deploy path -b primer.idatest

Be sure to enable Debugger>Use source-level debugging, then launch the process. At runtime IDA will be able to load the DWARF source information:

Note that the debugserver does not provide DWARF information to IDA - instead IDA looks for dSYM bundles in the vicinity of the idb on your local filesystem. Thus if you want IDA to load DWARF info for a given module, both the module binary and its matching dSYM must be in the same directory as the idb, or in the idb's parent directory.

For example, in the case of the idatest build:

$ tree
.
├── idatest.app
│   ├── idatest
│   └── idatest.i64
└── idatest.app.dSYM
    └── Contents
        └── Resources
            └── DWARF
                └── idatest

IDA was able to find the idatest binary next to idatest.i64, as well as the dSYM bundle next to the parent app directory.

If IDA can't find DWARF info on your filesystem for whatever reason, try launching IDA with the command-line option -z440010, which will enable much more verbose logging related to source-level debugging:

Looking for Mach-O file "idatest.app/idatest.dSYM/Contents/Resources/DWARF/idatest"
File "idatest.app/idatest.dSYM/Contents/Resources/DWARF/idatest" exists? -> No.
Looking for Mach-O file "idatest.app.dSYM/Contents/Resources/DWARF/idatest"
File "idatest.app.dSYM/Contents/Resources/DWARF/idatest" exists? -> Yes.
Looking for cpu=16777228:0, uuid=7a09f307-7503-3c0d-a182-ab552c1bf182.
Candidate: cpu=16777228:0, uuid=7a09f307-7503-3c0d-a182-ab552c1bf182.
Found, with architecture #0
DWARF: Found DWARF file "idatest.app.dSYM/Contents/Resources/DWARF/idatest"

Debugging DYLD

IDA can also be used to debug binaries that are not user applications. For example, dyld.

The ability to debug dyld is a nice advantage because it allows us to observe critical changes in the latest versions of iOS (especially regarding the shared cache) before a jailbreak is even available. We document this functionality here in the hopes it will be useful to others as well.

In this example we'll be using IDA to discover how dyld uses ARMv8.3 Pointer Authentication to perform secure symbol bindings. Start by loading the dyld binary in IDA. It is usually found here:

~/Library/Developer/Xcode/iOS DeviceSupport/13.4 (17E8255)/Symbols/usr/lib/dyld

The target application will be a trivial helloworld program:

#include <stdio.h>

int main(void)
{
  puts("hello, world!\n");
  return 0;
}

Compile and install this app on your device, then set the following fields in Debugger>Process options...

Under Debugger>Debugger options, enable Suspend on debugging start. This will instruct IDA to suspend the process at dyld's entry point, before it has begun binding symbols. Now launch the process with F9 - immediately the process will be suspended at __dyld_start:

Double-click on the helloworld module to bring up its symbol list and go to the _main function:

Note that function sub_1009CBF98 is the stub for puts:

The stub reads a value from off_109CC000, then performs a branch with pointer authentication. We can assume that at some point, dyld will fill off_109CC000 with an authenticated pointer to puts. Let's use IDA to quickly track down this logic in dyld.

The iOS debugger supports watchpoints. Now would be a good time to use one:

ida_dbg.add_bpt(0x1009CC000, 8, BPT_WRITE)

Resume the process and wait for dyld to trigger our watchpoint:

The instruction STR X21 [X19] triggered the watchpoint, and note the value in X21 (BB457A81BA95ADD8) which is the authenticated pointer to puts. Where did this value come from? We can see that X21 was previously set with MOV X21, X0 after a call to this function:

dyld3::MachOLoaded::ChainedFixupPointerOnDisk::Arm64e::signPointer

It seems like we're on the right track. Also note that IDA was able to extract a nice stack trace despite dyld's heavy use of PAC instructions to authenticate return addresses on the stack:

Address    Module  Function
100CA5E14  dyld    ____ZNK5dyld311MachOLoaded21fixupAllChainedFixups_block_invoke
100CA5EEC  dyld    dyld3::MachOLoaded::walkChain
100CA5BF0  dyld    dyld3::MachOLoaded::forEachFixupInAllChains
100CA5B50  dyld    dyld3::MachOLoaded::fixupAllChainedFixups
100CA2210  dyld    ____ZN5dyld36Loader18applyFixupsToImage_block_invoke.68
100CB0218  dyld    dyld3::MachOAnalyzer::withChainStarts
100CA2004  dyld    ____ZN5dyld36Loader18applyFixupsToImage_block_invoke_3
100CB3314  dyld    dyld3::closure::Image::forEachFixup
100CA15EC  dyld    dyld3::Loader::applyFixupsToImage
100CA0A00  dyld    dyld3::Loader::mapAndFixupAllImages
100C88784  dyld    dyld::launchWithClosure
100C86BE0  dyld    dyld::_main
100C81228  dyld    dyldbootstrap::start
100C81034  dyld    __dyld_start

This leads us to the following logic in the dyld-733.6 source:

// authenticated bind
newValue = (void*)(bindTargets[fixupLoc->arm64e.bind.ordinal]);
if (newValue != 0)
	newValue = (void*)fixupLoc->arm64e.signPointer(fixupLoc, newValue);

Here, fixupLoc (off_109CC00) and newValue (address of puts) are passed as the loc and target arguments for Arm64e::signPointer:

uint64_t discriminator = authBind.diversity;
if ( authBind.addrDiv )
	discriminator = __builtin_ptrauth_blend_discriminator(loc, discriminator);
switch ( authBind.key ) {
  case 0: // IA
    return __builtin_ptrauth_sign_unauthenticated(target, 0, discriminator);
  case 1: // IB
    return __builtin_ptrauth_sign_unauthenticated(target, 1, discriminator);
  case 2: // DA
    return __builtin_ptrauth_sign_unauthenticated(target, 2, discriminator);
  case 3: // DB
    return __builtin_ptrauth_sign_unauthenticated(target, 3, discriminator);
}

Thus, the pointer to puts is signed using its destination address in helloworld:__auth_got as salt for the signing operation. This is quite clever because the salt value is subject to ASLR and therefore cannot be guessed, but at this point the executable has already been loaded into memory – so it won’t change by the time the pointer is verified in the stub.

To see this in action, use F4 to run to the BRAA instruction in the stub and note the values of the operands:

The branch will use the operands to verify that the target address has not been modified after it was originally calculated by dyld. Since we haven't done anything malicious, one more single step should take us right to puts:

Just for fun, let's rewind the process back to the start of the stub:

IDC>PC = 0x1009CBF98

Then overwrite the authenticated pointer to puts with a raw pointer to printf:

ida_bytes.put_qword(0x1009CC000, ida_name.get_name_ea(BADADDR, "_printf"))

Now when we step through the stub, the BRAA instruction should detect that the authenticated pointer has been modified, and it will purposefully crash the application by setting PC to an invalid address:

Any attempt to resume execution will inevitably fail:

It seems we now have an understanding of secure symbol bindings in dyld. Fascinating!

Debugging the DYLD Shared Cache

This section discusses how to optimally debug system libraries in a dyld_shared_cache.

NOTE: full support for dyld_shared_cache debugging requires IDA 7.5 SP1

Debugging iOS system libraries is a challenge because the code is only available in the dyld cache. IDA allows you to load a library directly from the cache, but this has its own complications. A single module typically requires loading several other modules before the analysis becomes useful. Fortunately IDA is aware of these annoyances and allows you to debug such code with minimal effort.

To start, consider the following sample application that uses the CryptoTokenKit framework:

#import <CryptoTokenKit/CryptoTokenKit.h>

int main(void)
{
  TKTokenWatcher *watcher = [[TKTokenWatcher alloc] init];
  NSArray *tokens = [watcher tokenIDs];
  for ( int i = 0; i < [tokens count]; i++ )
    printf("%s\n", [[tokens objectAtIndex:i] UTF8String]);
  return 0;
}

Assume this program has been compiled and installed on the device as ctk.app.

Instead of debugging the test application, let's try debugging the CryptoTokenKit framework itself - focusing specifically on the -[TKTokenWatcher init] method.

Initial Analysis

First we'll need access to the dyldcache that contains the CryptoTokenKit framework. The best way to obtain the cache is to extract it from the ipsw package for your device/iOS version. This ensures that you are working with the original untouched cache that was installed on your device.

When opening the cache in IDA, choose the load option Apple DYLD cache for arm64e (single module) and select the CryptoTokenKit module:

Wait for IDA to finish the initial analysis of CryptoTokenKit. Immediately we might notice that the analysis suffers because of references to unloaded code. Most notably many Objective-C methods are missing a prototype, which is unusual:

However this is expected. Modern dyld caches store all Objective-C class names and method selectors inside the libobjc module. Objective-C analysis is practically useless without these strings, so we must load the libobjc module to access them. Since a vast majority of modules depend on libobjc in such a way, it is a good idea to automate this in a script.

For a quick fix, save the following idapython code as init.py:

# improve functions with branches to unloaded code
idaapi.cvar.inf.af &= ~AF_ANORET

def dscu_load_module(module):
    node = idaapi.netnode()
    node.create("$ dscu")
    node.supset(2, module)
    load_and_run_plugin("dscu", 1)

# load libobjc, then analyze objc types
dscu_load_module("/usr/lib/libobjc.A.dylib")
load_and_run_plugin("objc", 1) 

Then reopen the cache with:

$ ida64 -Sinit.py -Oobjc:+l dyld_shared_cache_arm64e

This will tell IDA to load libobjc immediately after the database is created, then perform the Objective-C analysis once all critical info is in the database. This should make the initial analysis acceptable in most cases. In the case of CryptoTokenKit, we see that the Objective-C prototypes are now correct:

Now let's go to the -[TKTokenWatcher init] method invoked by the ctk application:

If we right-click on the unmapped address 0x1B271C01C, IDA provides two options in the context menu:

In this case the better option is Load ProVideo:__auth_stubs, which loads only the stubs from the module and properly resolves the names:

This is a common pattern in the latest arm64e dyldcaches, and it is quite convenient for us. Loading a handful of __auth_stubs sections is enough to resolve most of the calls in CryptoTokenKit, which gives us some nice analysis for -[TKTokenWatcher init] and its helper method:

Debugger Configuration

Now that the static analysis is on par with a typical iOS binary, let's combine it with dynamic analysis. We can debug this database by setting the following options in Debugger>Process options:

Here we set the Input file field to the full path of the CryptoTokenKit module. This allows IDA to easily detect the dyldcache slide at runtime. When CryptoTokenKit is loaded into the process, IDA will compare its runtime load address to the imagebase in the current idb, then rebase the database accordingly.

By default the imagebase in the idb corresponds to the first module that was loaded:

IDC>msg("%a", get_imagebase())
CryptoTokenKit:HEADER:00000001B8181000

Thus, it is easiest to set Input file to the module corresponding to the default imagebase.

Note however that we could also use this configuration:

Provided that we update the imagebase in the idb to the base of the libobjc module:

ida_nalt.set_imagebase(ida_segment.get_segm_by_name("libobjc.A:HEADER").start_ea)

This will result in the same dyld slide and should work just as well, because the the imagebase and the Input file field both correspond to the same module. This is something to keep in mind when debugging dyldcache idbs that contain multiple libraries.

Now let's try launching the debugger. Set a breakpoint at -[TKTokenWatcher initWithClient:], use F9 to launch the process, then wait for our breakpoint to be hit:

IDA was able to map our database (including CryptoTokenKit, libobjc, and the satellite __auth_stubs sections) into process memory. We can single step, resume, inspect registers, and perform any other operation that is typical of an IDA debugging session.

Further Analysis

Note that after terminating the debugging session you can continue to load new modules from the cache. If a dyld slide has been applied to the database, new modules will be correctly loaded into the rebased address space. This did not work in previous versions of IDA.

For example, after a debugging session we might notice some more unresolved calls:

IDA is aware that the address space has shifted, and it will load the new code at the correct address:

You are free to load new modules and relaunch debugging sessions indefinitely.

\

Debugging System Applications

The previous examples used custom applications to demonstrate IDA's debugging capabilities. In this case IDA can utilize the debugserver included in Apple's iOS developer tools, but there are situations in which this server is not sufficient for our needs.

The debugserver will refuse to debug any application that we didn't build ourselves. To demonstrate this, try launching IDA with an empty database and use Debugger>Attach>Remote iOS Debugger to attach to one of the system daemons:

You will likely get this error message:

It is possible to install a custom version of the debugserver that can debug system processes, but this requires a jailbroken device. We document the necessary steps and IDA configuration here. The device used in this example is an iPhone 8 with iOS 13.2.2, jailbroken with checkra1n 0.10.1.

Patching the debugserver

First we must obtain a copy of the debugserver binary from the DeveloperDiskImage.dmg:

$ export DEVELOPER=/Applications/Xcode.app/Contents/Developer
$ export DEVTOOLS=$DEVELOPER/Platforms/iPhoneOS.platform/DeviceSupport
$ hdiutil mount $DEVTOOLS/13.2/DeveloperDiskImage.dmg
$ cp /Volumes/DeveloperDiskImage/usr/bin/debugserver .

Now save the following xml as entitlements.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/ PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>task_for_pid-allow</key> <true/>
	<key>get-task-allow</key> <true/>
	<key>platform-application</key> <true/>
	<key>com.apple.springboard.debugapplications</key> <true/>
	<key>run-unsigned-code</key> <true/>
	<key>com.apple.system-task-ports</key> <true/>
</dict> 
</plist>

Then use ldid to codesign the server:

$ ldid -Sentitlements.plist debugserver

This will grant the debugserver permission to debug any application, including system apps. Now we can copy the server to the device and run it:

$ scp debugserver root@iphone-8:/usr/bin/
$ ssh root@iphone-8
iPhone-8:~ root# /usr/bin/debugserver 192.168.1.7:1234
debugserver-@(#)PROGRAM:LLDB  PROJECT:lldb-900.3.98 for arm64.
Listening to port 1234 for a connection from 192.168.1.7...

Note that we specified 192.168.1.7 which is the IP of the host machine used in this example. Be sure to replace this with the IP of your host so that the server will accept incoming connections from IDA.

IDA Configuration

To enable debugging with the patched debugserver, set the following options in dbg_ios.cfg:

// don't launch the debugserver. we did it manually
AUTOLAUNCH = NO
// your device's UUID. this is used when fetching the remote process list
DEVICE_ID = "";
// debugging symbols extracted by Xcode
SYMBOL_PATH = "~/Library/Developer/Xcode/iOS DeviceSupport/13.2.2 (17B102)/Symbols";

We're now ready to open a binary in IDA and debug it. Copy the itunesstored binary from your device, it is typically found here:

/System/Library/PrivateFrameworks/iTunesStore.framework/Support/itunesstored

After loading the binary use Debugger>Select debugger and choose Remote iOS Debugger, then under Debugger>Process options set the following fields:

Since we set AUTOLAUNCH = NO, IDA now provides the Hostname and Port fields so we can specify how to connect to our patched debugserver instance.

Now use Debugger>Attach to process and choose itunesstored from the process list. Since we have modified the debugserver it should agree to debug the target process, allowing IDA to create a typically robust debugging environment:

Note that although we're not using the debugserver from DeveloperDiskImage.dmg, IDA still depends on other developer tools to query the process list. We discuss how to install the DeveloperDiskImage in the Getting Started section above, but for a quick workaround you can always just specify the PID manually:

Now that we've successfully attached to a system process, let's do something interesting with it. Consider the method -[PurchaseOperation initWithPurchase:]. This logic seems to be invoked when a transaction is performed in the AppStore. Set a breakpoint at this method, then open the AppStore on your device and try downloading an app (it can be any app, even a free one).

Immediately our breakpoint is hit, and we can start unwinding the logic that brought us here:

Stepping through this function, we see many Objective-C method call sites:

Instead of using F7 to step into the _objc_msgSend function, we can use shortcut Shift-O to take us directly to the Objective-C method that is being invoked:

We discuss the Shift-O action in detail in our mac debugger primer, but it is worth demonstrating that this action works just as well in arm64/iOS environments.

It seems that we're well on our way to reverse-engineering transactions in the AppStore. The remaining work is left as an exercise for the reader :)

Conclusion

Hopefully by now we've shown that IDA's iOS Debugger is quite versatile. It can play by Apple's rules when debugging on a non-jailbroken device, and it can also be configured to use an enhanced debugserver when a jailbreak is available.

Also keep in mind that all previous examples in this writeup should work equally well with the patched debugserver. We encourage you to go back and try them.

\

Troubleshooting

IDA uses the Remote GDB Protocol to communicate with the iOS debugserver. Thus, the best way to diagnose possible issues is to log the packets transmitted between IDA and the server. You can do this by running IDA with the -z10000 command-line option:

$ ida64 -z10000 -L/tmp/ida.log

Often times these packets contain messages or error codes that provide clues to the issue.

For more enhanced troubleshooting, you can also enable logging on the server side. Go to Debugger>Debugger options>Set specific options and set the Syslog flags field:

This will instruct the debugserver to log details about the debugging session to the iOS system log (all valid flags are documented under the SYSLOG_FLAGS option in dbg_ios.cfg).

Start collecting the iOS system log with:

$ ios_deploy syslog -f /tmp/sys.log

Then launch the debugger. Now both the client (/tmp/ida.log) and the server (/tmp/sys.log) will log important events in the debugger session, which will often times reveal the issue.`

Notes

This tutorial replaces the old iOS debugging tutorial, which is available here.

Quick overview:

The Windbg debugger plugin is an IDA Pro debugger plugin that uses Microsoft's debugging engine (dbgeng) that is used by Windbg, Cdb or Kd.

To get started, you need to install the latest Debugging Tools from Microsoft website: https://msdn.microsoft.com/en-us/windows/hardware/hh852365

or from the Windows SDK / DDK package.

Please make sure you should install the x86 version of the debugging tools which is used by both IDA Pro and IDA Pro 64. The x64 version will NOT work.

After installing the debugging tools, make sure you select « Debugger / Switch Debugger » and select the WinDbg debugger.

Also make sure you specify the correct settings in the “Debugger specific options” dialog:

• User mode: Select this mode for user mode application debugging (default mode)

• Kernel mode: Select this mode to attach to a live kernel.

• Non Invasive debugging: Select this mode to attach to a process non-invasively

• Output flags: These flags tell the debugging engine which kind of output messages to display and which to omit

• Kernel mode debugging with reconnect and initial break: Select this option when debugging a kernel and when the connection string contains 'reconnect'. This option will assure that the debugger breaks as soon as possible after a reconnect.

  To make these settings permanent, please edit the IDA\cfg\dbg_windbg.cfg file.

  ** To specify the debugging tools folde**r you may add to the PATH environment variable the location of Windbg.exe or edit %IDA%\cfg\ida.cfg and change the value of the DBGTOOLS key.

  After the debugger is properly configured, edit the process options and leave the connection string value empty because we intend to debug a local user-mode application.

Now hit F9 to start debugging:

The Windbg plugin is very similar to IDA Pro's Win32 debugger plugin, nonetheless by using the former, one can benefit from the command line facilities and the extensions that ship with the debugging tools.

For example, one can type “!chain” to see the registered Windbg extensions:

“!gle” is another command to get the last error value of a given Win32 API call.

Another benefit of using the Windbg debugger plugin is the use of symbolic information.

Normally, if the debugging symbols path is not set, then the module window will only show the exported names. For example kernel32.dll displays 1359 names:

Let us configure a symbol source by adding this environment variable before running IDA:

set _NT_SYMBOL_PATH=srv*C:\Temp\pdb*http://msdl.microsoft.com/download/symbols

It is also possible to set the symbol path directly while debugging:

and then typing “.reload /f” to reload the symbols.

Now we try again and notice that more symbol names are retrieved from kernel32.dll:

Now we have 5818 symbols instead!

It is also possible to use the “x” command to quickly search for symbols:

(Looking for any symbol in any module that contains the word “continue”)

Debugging a remote process

We have seen how to debug a local user mode program, now let us see how to debug a remote process.

First let us assume that “pcA” is the target machine (where we will run the debugger server and the debugged program) and “pcB” is the machine where IDA Pro and the debugging tools are installed.

To start a remote process:

• On “pcA”, type:

• dbgsrv -t tcp:port=5000

(change the port number as needed)

• On “pcB”, setup IDA Pro and Windbg debugger plugin:

  • “Application/Input file”: these should contain a path to the debuggee residing in “pcA”

  • Connection string: tcp:port=5000,server=pcA

Now run the program and debug it remotely.

To attach to a remote process, use the same steps to setup “pcA” and use the same connection string when attaching to the process.

More about connection strings and different protocols (other than TCP/IP) can be found in “debugger.chm” in the debugging tools folder.

Debugging the kernel with VMWare

We will now demonstrate how to debug the kernel through a virtual machine.

In this example we will be using VMWare 6.5 and Windows XP SP3.

Configuring the virtual machine:

Run the VM and then edit “c:\boot.ini” file and add one more entry (see in bold):

[operating systems]

multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /noexecute=optin /fastdetect multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Local debug" /noexecute=optin /fastdetect /debug /debugport=com1 /baudrate=115200

For MS Windows Vista please see: http://msdn.microsoft.com/en-us/library/ms791527.aspxp

Actually the last line is just a copy of the first line but we added the “/debug” switch and some configuration values.

Now shutdown the virtual machine and edit its hardware settings and add a new serial port with option “use named pipes”:

Press “Finish” and start the VM. At the boot prompt, select “Local debug” from the boot menu:

Configuring Windbg debugger plugin:

Now run IDA Pro and select Debugger / Attach / Windbg

Then configure it to use “Kernel mode” debugging and use the following connection string:

com:port=\.\pipe\com_1,baud=115200,pipe

It is possible to use the 'reconnect' keyword in the connection string:

com:port=\.\pipe\com_1,baud=115200,pipe,reconnect

Also make sure the appropriate option is selected from the debugger specific options.

Please note that the connection string (in step 1) refers to the named pipe we set up in the previous steps.

Finally, press OK to attach and start debugging.

When IDA attaches successfully, it will display something like this:

If you do not see named labels then try checking your debugging symbols settings.

Note: In kernel mode IDA Pro will display one entry in the threads window for each processor.

For example a two processor configuration yields:

This screenshot shows how we are debugging the kernel and changing the disassembly listing (renaming stack variables, or using structure offsets):

At the end you can detach from the kernel and resume it or detach from the kernel and keep it suspended.

To detach and resume, simply select the “Debugger / Detach”, however to detach and keep the kernel suspended select “Debugger / Terminate Process”.

Debugging the kernel through kdsrv.exe

In some cases, when debugging a 64bit kernel using a 1394 cable then 64bit drivers are needed, thus dbgeng (32bits) will not work. To workaround this problem we need to run the kernel debugger server from the x64 debugging tools folder and connect to it:

• Go to “Debugging Tools (x64)” installation

• Run kdsrv.exe (change the port number/transport appropriately):

  • kdsrv -t tcp:port=6000

• Now run ida64 and specify the following connection string (change the transport value appropriately):

  • kdsrv:server=@{tcp:port=6000,server=127.0.0.1},trans=@{com:port=\.\pipe\com_3,baud=115200,pipe}

The IDA Win32 debugger allows remote debugging of Windows32 executables. This is especially suited to the safe analysis of unknown hostile code. Our remote debugger server must first be started on the target machine.

we select attach to remote win32

and of course specify our password and the port we'll use for the session.

the connection screen is indentical to the local one.

and we are now connected to a program running on the remote machine.

Check the tutorial about debuggind Windows apps with IDA Bochs:

Debugging the Windows Kernel with VMWare and IDA WinDbg Plugin

We will now demonstrate how to debug the kernel through a virtual machine.

In this example we will be using VMware Workstation 15 Player and Windows 7.

It is highly recommended to read the article

Configuring the virtual machine

Run the VM and use the bcedit to configure the boot menu as stated in the article.

Edit the VM hardware settings and add a new serial port with option use named pipe:

Restart the VM to debug. At the boot prompt, select the menu item containing [debugger enabled] from the boot menu.

Configuring Windbg debugger plugin

The connection string com:port=\\.\pipe\com_2,baud=115200,pipe,reconnect for Windbg plugin should refer to the named pipe we set up in the previous steps.

Starting the debugger step by step

Start IDA Pro with an empty database:

Select the Windbg debugger using "Debugger > Select debugger":

Then configure it to use “Kernel mode debugging” debugging in the “Debugger specific options” dialog:

After the debugger is properly configured, edit the process options and set the connection string:

Finally, start debugging using "Debugger > Attach to process":

IDA Pro may display a wait box "Refreshing module list" for some time. Then it will display something like this:

Starting the debugger using a command line option

The simplest way to start WinDbg Plugin is to run IDA Pro with the following option:

• {MODE=1} means "Kernel mode"

• +0 means the "<Kernel>" process

Debugging

In kernel mode IDA Pro will display one entry in the threads window for each processor.

This screenshot shows how we are debugging the kernel and changing the disassembly listing (renaming stack variables, or using structure offsets):

At the end you can detach from the kernel and resume it or detach from the kernel and keep it suspended.

To detach and resume, simply select the “Debugger > Detach from process”, however to detach and keep the kernel suspended select “Debugger > Terminate Process”.

Debugging the kernel through kdsrv.exe

In some cases, when debugging a 64bit kernel using a 1394 cable then 64bit drivers are needed, thus dbgeng (32bits) will not work. To workaround this problem we need to run the kernel debugger server from the x64 debugging tools folder and connect to it:

• Go to “Debugging Tools (x64)” installation

• Run kdsrv.exe (change the port number/transport appropriately):

  • kdsrv -t tcp:port=6000

• Now run ida64 and specify the following connection string (change the transport value appropriately):

  • kdsrv:server=@{tcp:port=6000,server=127.0.0.1},trans=@{com:port=\\.\pipe\com_3,baud=115200,pipe}

Introduction

This guide illustrates how to configure the Bochs debugger plugin under Linux/MacOS. Downloading and compiling Bochs Please download the Bochs source code tarball and extract it.

Run the 'configure' script (it is possible to pass other switches) and make sure that the switches marked in bold are present:

Note: under MacOS Lion 10.7.3 use the following switches:

For a complete installation guide please check: http://bochs.sourceforge.net/doc/docbook/user/compiling.html. Now run "make" and "make install". Then type "whereis bochs" to get something like:

Configuring IDA and the Bochs debugger plugin

Opening a database and selecting the Bochs debugger

After installing Bochs, run IDA Pro and open a Windows PE file and select 'Debugger -> switch debugger' and select "Local Bochs Debugger": If a PE file was loaded, then the Bochs debugger plugin will operate in "PE mode":

In case the other two modes (IDB or Disk Image mode) are used then there is no need to specify any additional configurations options, otherwise please continue reading this guide. Before launching the debugger with F9, the Bochs debugger plugin needs to know where to find the MS Windows DLLs and which environment variables to use. Attempting to run the debugger without configuring it may result in errors like this:

Here is a basic list of DLLs that are needed by most programs: • advapi32.dll • comctl32.dll • comdlg32.dll • gdi32.dll • kernel32.dll • msvcrt.dll • mswsock.dll • ntdll.dll • ntoskrnl.exe • shell32.dll • shlwapi.dll • urlmon.dll • user32.dll • wininet.dll • ws2_32.dll • wsock32.dll Let us create a directory in $HOME/bochs_windir/ and place those DLLs there. Specifying the Windows DLL path and environment variables using the startup file The startup file is a script file found in idadir\plugins\bochs directory. If IDC was the currently active language then startup.idc is used, otherwise startup.ext (where ext is the extension used by the currently selected extlang). In this tutorial we will be working with IDC, so we will edit the startup.idc file. (Please note that changes to this file will affect all databases. For local changes (database specific configuration) take a copy of the startup script file and place it in the same directory as the database then modify it). It is possible to specify a path map for a complete directory, for example:

This line means that /home/lallous/bochs_windir/* will be visible to the debugged program as c:\windows\system32* (for example /home/lallous/bochs_windir/ntdll.dll will be visible as c:\windows\system32\ntdll.dll)

If all DLLs referenced by the program are in the bochs_windir directory, then running the process again should work: (Bochs has already started and IDA switched to debugging mode.) There are two things that should be configured. Press “.” to switch to the output window (or use the Debugger / Modules list window to inspect the modules list):

Now, after we run the program again we should get a more correct module list:

It is equally important to specify some environment variables. We will use the env keyword to define all the environment variables:

Specifying the Windows DLL path and environment variables using environment variables An alternative way of configuring the DLLs path and environment variables is to use the IDABXPATHMAP and the IDABXENVMAP environment variables. To specify the path map, export the following environment variable:

(Please note that the forward slash (/) will be replaced with a backslash automatically by the plugin) Similarly, specify the environment variables with the IDABXENVMAP environment variable:

(Please note that we used the ++ to separate between multiple variables)

In case you require to do specific changes (per database) to the startup file then please take a copy of it and place it in the same directory as the database. Refer to the help IDA Pro help file for more information.

Debugging Linux Applications with IDA Pro, locally

Last updated on July 29, 2020 — v0.1

You may already know that IDA lets you debug an application from an already existing IDB, by selecting the debugger using the drop-down debugger list.

However, it is also possible to start IDA in a way that it will initially create an empty IDB, and then either:

• start a new process under its control

• attach to an existing process

Launch IDA with a fresh new process

To do so, you will have to launch IDA from the command line, like so:

IDA will then launch the /bin/ls program, and break at its entrypoint

Attaching IDA to an existing process

For this example, we’ll launch, from a shell, a /usr/bin/yes process, and attach to.

Now, we’ll launch IDA so it offers a selection of processes to (and use quick filtering (Ctrl+F) to quickly find our process):

IDA will then attach to the selected process, and leave it suspended at the place it was when it was attached to:

Current versions of VMWare Workstation include a GDB stub for remote debugging of the virtual machines running inside it. In version 5.4, IDA includes a debugger module which supports the remote GDB protocol. This document describes how to use it with VMWare. As an example, we'll debug a Linux kernel.

Debugging a Linux kernel

Let's assume that you already have a VM with Linux installed. Before starting the debugging, we will copy symbols for the kernel for easier navigation later. Copy either /proc/kallsyms or /boot/Sytem.map* file from the VM to host.

Now edit the VM's .vmx file to enable GDB debugger stub:

Add these lines to the file:

debugStub.listen.guest32 = "TRUE"

debugStub.hideBreakpoints= "TRUE"

monitor.debugOnStartGuest32 = "TRUE"

Save the file.

In VMWare, click "Power on this virtual machine" or click the green Play button on the toolbar.

A black screen is displayed since VMWare is waiting for a debugger to connect.

Start IDA.

If you get the welcome dialog, choose "Go".

Choose Debugger | Attach | Remote GDB debugger.

Enter "localhost" for hostname and 8832 for the port number.

Choose <attach to the process started on target> and click OK.

We land in the BIOS, but since we're not interested in debugging it, we can skip directly to the kernel. Inspect the kallsyms or System.map file you downloaded from the guest and search for the start_kernel symbol:

Press F2 or choose "Add breakpoint" from the context menu.

Press F9. You will see loading messages and then the execution will stop at the entrypoint.

Adding symbols

Symbols are very useful during debugging, and we can use the kallsyms or System.map file to add them to IDA. Go to File | Python command... and paste the following short script (don't forget to edit the file path):

Click OK and wait a bit until it finishes. After that you should see the symbols in the disassembly and name list:

Happy debugging!

Copyright 2009 Hex-Rays SA

Introduction

The PIN tracer is a remote debugger plugin used to record execution traces. It allows to record traces on Linux and Windows (x86 and x86_64) from any of the supported IDA platforms (Windows, Linux and MacOSX). Support for MacOSX targets is not yet available.

PIN support for MacOSX

Recording traces on MacOSX target is not supported yet.

However, it’s possible to record traces from a Linux or Windows target using the MacOSX version of IDA.

Building the PIN tool

Before using the PIN tracer the PIN tool module (distributed only in source code form) must be built as the Intel PIN license disallows redistributing PIN tools in binary form.

First of all download PIN from , and unpack it on your hard drive.

the PIN tools are a little sensitive to spaces in paths. Therefore, we recommend unpacking in a no-space path. E.g., "C:\pin", but not "C:\Program Files (x86)\.

The building process of the PIN tool is different for Windows and Linux.

Building on Windows

1. Install Visual Studio. It is possible to build the PIN tool with the Express version of Visual Studio for C++.

2. Download the IDA pintool sources from: (*)

   pintool 6.9 and higher should be built with PIN version 3.0 and higher, for earlier versions of pintool you should use PIN build 65163.

3. Unpack the .zip file into /path/to/pin/source/tools/

4. Open /path/to/pin/source/tools/idapin/IDADBG.sln in Visual Studio, select the correct build configuration (either Win32 or x64) and build the solution.

Alternatively you can use GNU make:

1. Install GNU make as a part of cygwin or MinGW package

2. Unpack the .zip file into /path/to/pin/source/tools/

3. Prepare Visual Studio environment (e.g. %VCINSTALLDIR%\Auxiliary\Build\vcvars32.bat for 32-bit pintool or %VCINSTALLDIR%\Auxiliary\Build\vcvars64.bat for 64-bit one)

4. cd /path/to/pin/source/tools/idapin

5. make

Building on Linux

1. Install GCC 3.4 or later

3. Unpack the .zip file into /path/to/pin/source/tools/

4. Open a console, and do the following (only for versions of PIN prior to 3.0):

   1. cd /path/to/pin/ia32/runtime

   2. ln -s libelf.so.0.8.13 libelf.so

   3. cd /path/to/pin/intel64/runtime

   4. ln -s libelf.so.0.8.13 libelf.so

   5. cd /path/to/pin/source/tools/Utils

   6. ls testGccVersion 2>/dev/null || ln -s ../testGccVersion testGccVersion

5. cd /path/to/pin/source/tools/idapin

for building the x86 version, or

for the x64 version.

Pintool 6.9 and higher are compatible with versions 6.5-6.8 of IDA so currently you can use them.

Start process

Once the PIN tool module is built we can use it in IDA. Open a binary in IDA and wait for the initial analysis to finish. When it’s done select the PIN tracer module from the debuggers drop down list or via Debugger > Select debugger:

After selecting the PIN tracer module select the menu Debugger > Debugger options > Set specific options. The following new dialog will be displayed:

In this dialog at least the following options are mandatory:

1. PIN executable: This is the full path to the PIN binary (including the “pin.exe” or “pin” file name). In some versions “pin.sh” may exist – in this case you should use it.

2. Directory with idadbg: This is the directory where the idadbg.so or idadbg.dll PIN tool resides. Please note that only the directory must be specified.

Fill the form with the correct paths and press OK in this dialog and enable option Autolaunch PIN for localhost.

We can interact with the PIN tracer like with any other debugger module: add breakpoints and step into or step over functions by pressing F7 or F8 alternatively.

Now we put a breakpoint in the very first instruction of function main

and launch the debugger by pressing the F9 key or by clicking the Start button in the debugger toolbar.

Make several steps by pressing F8. We can see all the instructions that were executed changed their color:

Now let the application run and finish by pressing F9 again. After a while the process will terminate and IDA will display a dialog telling us that is reading the recorded trace. Once IDA reads the trace the debugger will stop and the instructions executed will be highlighted (like with the built-in tracing engine) as in the following picture:

We can see in the graph view mode the complete path the application took in some specific function by switching to the graph view, pressing space bar and then pressing “w” to zoom out:

Attach to an existing process

Instead of launching a new process we could attach to a running process and debug it. For that we could have selected the "Debugger > Attach to process…​" menu item. IDA will display a list of active processes.

We just select the process we want to attach to. IDA will then attach to the selected process, and leave it suspended at the place it was when it was attached to:

Remote debugging

In case of remote debugging you can run IDA and PIN backend on different platforms.

Starting the remote PIN backend

The first thing to do, is to start the PIN debugging backend on the target machine. Command line depends of bitness of the target application.

For example, a 64-bit application ls would be started for debugging by the following comand:

whereas a 32-bit one hello32 as follows:

there is a more complicated way to start an application regardless bitness:

Also you can attach to already running programs:

For example:

Connecting IDA to the backend

The next step is to select PIN tracer module in IDA via Debugger > Select debugger and switch IDA to remote PIN backend. For this you should disable option Autolaunch PIN for localhost in the PIN options dialod (Debugger > Debugger options > Set specific options):

and then tell IDA about the backend endpoint, through the menu action Debugger > Process options…​

Once IDA knows what host to contact (and on what port), debugging an application remotely behaves exactly the same way as if you were debugging it locally.

In order to remotely debug a 64 bit process running on Windows64, we start the remote debugging server on the target machine.

We start IDAG64 (the 32-bit hosted version of IDA that is fully 64 bit capable) and use the "attach to remote win64" command .

IDA displays a list of the processes running on the 64 bit machines, we choose, click...

and, here we are, welcome to the fancy world of 64 bit debugging! Yes, the registers are a bit wide... but we are looking into a fancy compression scheme that...

Since 2003 IDA offers a debugger that complements the static analysis nicely. In many cases, one just can't beat dynamic analysis. The IDA Debugger now supports 32-bit and 64-bit MS Windows executablesMS Windows, Linux, Mac OS X both locally and remotely. However, because the debugger API requires the mastery of our SDK and uses an event based model, it has proved quite difficult to use for some of our users.

• because the API uses an event based model makes it hard to program a linear sequence of actions in a natural way. The user is forced to install an event handler and to implement a finite state machine that implements the core logic of his plugin. While this may, in many ways, be a more powerful approach, this is probably too complex for more mundane tasks.

• because the API is only available at the plugin level, the simplest debugger actions requires writing a plugin which is a much bigger investment of time and efforts than writing a small IDC script.

IDA 5.2 will address both issues. The old event based model will remain available, but a simpler linear model will become available thanks to the function get_debugger_event(). This function pauses the execution of the plugin (or the script) until a new debugger event happens. The user can specify if she is interested only in the events that suspend the process or in all events. A timeout can also be confifured, after which the execution will continue if no event arose.

The new function allows us to drop the event based model (except in the cases when it is superior to linear logic) and write IDC scripts to control the debugger. For example, to launch the debugger, run to a specific location, print some data and single step twice, the following lines will suffice:

  AppBpt(some_address);
  StartDebugger("","","");         // start debugger with default params
  GetDebuggerEvent(WFNE_SUSP, -1); // ... and wait for bpt
  Message ("Stopped at %a, event code is %x\n", GetEventEA(), GetEventId());
  StepInto();                      // request a single step
  GetDebuggerEvent(WFNE_SUSP, -1); // ... and wait for app to execute
  StepInto();                      // request a single step
  GetDebuggerEvent(WFNE_SUSP, -1); // ... and wait for app to execute

In IDA 5.1 this would have required a event handler and a small finite state automata, for a total more than 200 lines of code. Please note that, in the above example, the error handling code is omitted for clarity. In real life, you might want to check for unexpected conditions like an exception happening after StepInto().

To illustrate how easier it is to write scripts with the new approach, we rewrote the core functionality of the UUNP unpacker plugin. The original program requires about 600 lines of code and has a rather complex logic. The new script only requires 100 lines of code (almost half of them being comments and empty lines). More importantly, the script is easy to understand and modify for your needs.

This is a reimplementation of the uunp universal unpacker in IDC. It illustrates the use of the new debugger functions in IDA v5.2

#include <idc.idc>

//--------------------------------------------------------------------------
static main()
{
  auto ea, bptea, tea1, tea2, code, minea, maxea;
  auto r_esp, r_eip, caller, funcname;

  // Calculate the target IP range. It is the first segment.
  // As soon as the EIP register points to this range, we assume that
  // the unpacker has finished its work.
  tea1 = FirstSeg();
  tea2 = SegEnd(tea1);

  // Calculate the current module boundaries. Any calls to GetProcAddress
  // outside of these boundaries will be ignored.
  minea = MinEA();
  maxea = MaxEA();

  // Launch the debugger and run until the entry point
  if ( !RunTo(BeginEA()) )
    return Failed(-1);

  // Wait for the process to stop at the entry point
  code = GetDebuggerEvent(WFNE_SUSP, -1);
  if ( code <= 0 )
    return Failed(code);

  // Set a breakpoint at GetProcAddress
  bptea = LocByName("kernel32_GetProcAddress");
  if ( bptea == BADADDR )
    return Warning("Could not locate GetProcAddress");
  AddBpt(bptea);

  while ( 1 )
  {
    // resume the execution and wait until the unpacker calls GetProcAddress
    code = GetDebuggerEvent(WFNE_SUSP|WFNE_CONT, -1);
    if ( code <= 0 )
      return Failed(code);

    // check the caller, it must be from our module
    r_esp = GetRegValue("ESP");
    caller = Dword(r_esp);
    if ( caller < minea || caller >= maxea )
      continue;

    // if the function name passed to GetProcAddress is not in the 
    // ignore-list, then switch to the trace mode
    funcname = GetString(Dword(r_esp+8), -1, ASCSTR_C);
    // ignore some api calls because they might be used by the unpacker
    if ( funcname == "VirtualAlloc" )
      continue;
    if ( funcname == "VirtualFree" )
      continue;

    // A call to GetProcAddress() probably means that the program has been
    // unpacked in the memory and now is setting up its import table
    break;
  }

  // trace the program in the single step mode until we jump to
  // the area with the original entry point.
  DelBpt(bptea);
  EnableTracing(TRACE_STEP, 1);
  for ( code = GetDebuggerEvent(WFNE_ANY|WFNE_CONT, -1); // resume
        code > 0;
        code = GetDebuggerEvent(WFNE_ANY, -1) )
  {
    r_eip = GetEventEa();
    if ( r_eip >= tea1 && r_eip < tea2 )
      break;
  }
  if ( code <= 0 )
    return Failed(code);

  // as soon as the current ip belongs OEP area, suspend the execution and
  // inform the user
  PauseProcess();
  code = GetDebuggerEvent(WFNE_SUSP, -1);
  if ( code <= 0 )
    return Failed(code);

  EnableTracing(TRACE_STEP, 0);

  // Clean up the disassembly so it looks nicer
  MakeUnknown(tea1, tea2-tea1, DOUNK_EXPAND|DOUNK_DELNAMES);
  MakeCode(r_eip);
  AutoMark2(tea1, tea2, AU_USED);
  AutoMark2(tea1, tea2, AU_FINAL);
  TakeMemorySnapshot(1);
  MakeName(r_eip, "real_start");
  Warning("Successfully traced to the completion of the unpacker code\n"
          "Please rebuild the import table using renimp.idc\n"
          "before stopping the debugger");
}
//--------------------------------------------------------------------------
// Print an failure message
static Failed(code)
{
  Warning("Failed to unpack the file, sorry (code %d)", code);
  return 0;
}

IDA Pro - Appcall user guide

Copyright 2023 Hex-Rays SA

Introduction

Appcall is a mechanism to call functions under a debugger session in the context of the debugged program using IDA's CLI (Command Line Interpreter) or from a script. Such a mechanism can be used for seamless blackbox function calling and use, fuzzing, process instrumentation, DLL injection, testing or extending applications.

Appcall mechanism highly depends on the type information of the called function. For that reason, it is necessary to have a correct function prototype before doing an Appcall, otherwise different or incorrect results may be returned.

In a nutshell, Appcall works by first hijacking the current thread's stack (please do switch threads explicitly if you want to Appcall in a different context), then pushing the arguments, and then temporarily adjusting the instruction pointer to the beginning of the called function. After the function returns (or an exception occurs), the original stack, instruction pointer, and other registers are restored, and the result is returned to the caller.

Please note that while most of the examples in this document are illustrated using a Windows user mode application, Appcall is not limited to Windows and can be used with any platform supported by IDA debuggers.

Quick start

Let's start explaining the basic concepts of Appcall using the IDC CLI. Let's imagine we have the following printf() in the disassembly somewhere:

.text:00000001400015C0 ; __int64 printf(const char *, ...)
.text:00000001400015C0 _printf         proc near               
.text:00000001400015C0                                         
.text:00000001400015C0
.text:00000001400015C0 arg_0           = qword ptr  8
.text:00000001400015C0 arg_8           = qword ptr  10h
.text:00000001400015C0 arg_10          = qword ptr  18h
.text:00000001400015C0 arg_18          = qword ptr  20h
.text:00000001400015C0
.text:00000001400015C0                 mov     [rsp+arg_0], rcx
.text:00000001400015C5                 mov     [rsp+arg_8], rdx
.text:00000001400015CA                 mov     [rsp+arg_10], r8
.text:00000001400015CF                 mov     [rsp+arg_18], r9
...

It can be called by simply typing the following in the IDC CLI (press "." to jump to the CLI):

_printf("hello world\n");

As you noticed, we invoked an Appcall by simply treating _printf as if it was a built-in IDC function. If the application had a console window, then you should see the message printed in it.

If you have a function with a mangled name or with characters that cannot be used as an identifier name in the IDC language, such as "_my_func@8", then you can use the LocByName function to get its address given its name, then using the address variable (which is callable) we issue the Appcall:

auto myfunc = LocByName("_my_func@8");
myfunc("hello", "world");

Or simply directly as:

LocByName("_my_func@8")("hello", "world");

Using AppCall with IDC

Apart from calling Appcall naturally as shown in the previous section, it is possible to call it explicitly using the dbg_appcall function:

// Call application function
//      ea - address to call
//      type - type of the function to call. can be specified as:
//              - declaration string. example: "int func(void);"
//              - typeinfo object. example: get_tinfo(ea)
//              - zero: the type will be retrieved from the idb
//      ... - arguments of the function to call
// Returns: the result of the function call
// If the call fails because of an access violation or other exception,
// a runtime error will be generated (it can be caught with try/catch)
// In fact there is rarely any need to call this function explicitly.
// IDC tries to resolve any unknown function name using the application labels
// and in the case of success, will call the function. For example:
//      _printf("hello\n")
// will call the application function _printf provided that there is
// no IDC function with the same name.

anyvalue dbg_appcall(ea, type, ...);    

The Appcall IDC function requires you to pass a function address, function type information (various forms are accepted) and the parameters (if any):

auto msgbox;
msgbox = LocByName("__imp_MessageBoxA");
// Pass "0" for the type to deduce it from the database
dbg_appcall(msgbox, 0, 0, "Hello world", "Info", 0);

We've seen so far how to call a function if it already has type information, now suppose we have a function that does not:

user32.dll:00007FFF3AD730F0 user32_FindWindowA proc near
user32.dll:00007FFF3AD730F0      mov     r9, rdx
user32.dll:00007FFF3AD730F3      mov     r8, rcx
user32.dll:00007FFF3AD730F6      xor     edx, edx
user32.dll:00007FFF3AD730F8      xor     ecx, ecx
user32.dll:00007FFF3AD730FA      jmp     sub_7FFF3ADC326C
user32.dll:00007FFF3AD730FA user32_FindWindowA endp  

Before calling this function with dbg_appcall we have two options:

1. Pass the prototype as a string

2. Or, parse the prototype separately and pass the returned type info object.

This is how we can do it using the first option:

auto window_handle;
window_handle = dbg_appcall(
    LocByName("user32_FindWindowA"),
    "long __stdcall FindWindow(const char *cls, const char *wndname)",
    0,
    "Calculator");
    
msg("handle=%d\n", window_handle);

As for the second option, we can use parse_decl() first, then proceed as usual:

auto window_handle, tif;

tif = parse_decl("long __stdcall FindWindow(const char *cls, const char *wndname)", 0);

window_handle = dbg_appcall(
    LocByName("user32_FindWindowA"),
    tif,
    0,
    "Calculator");
    
msg("handle=%d\n", window_handle);
  

Note that we used parse_decl() function to construct a typeinfo object that we can pass to dbg_appcall.

It is possible to permanently set the prototype of a function programmatically using apply_type():

auto tif;
tif = parse_decl("long __stdcall FindWindow(const char *cls, const char *wndname)", 0);
apply_type(
    LocByName("user32_FindWindowA"),
    tif);

In the following sections, we are going to cover different scenarios such as calling by reference, working with buffers and complex structures, etc.

Passing arguments by reference

To pass function arguments by reference, it suffices to use the & symbol as in the C language.

• For example to call this function:

void ref1(int *a)
{
  if (a == NULL)
    return;
  int o = *a;
  int n = o + 1;
  *a = n;
  printf("called with %d and returning %d\n", o, n);
}

We can use this code from IDC:

auto a = 5;
msg("a=%d", a);
ref1(&a);
msg(", after the call=%d\n", a);

• To call a C function that takes a string buffer and modifies it:

/* C code */
int ref2(char *buf)
{
  if (buf == NULL)
    return -1;

  printf("called with: %s\n", buf);
  char *p = buf + strlen(buf);
  *p++ = '.';
  *p = '\0';
  printf("returned with: %s\n", buf);
  int n=0;
  for (;p!=buf;p--)
    n += *p;
  return n;
}

We need to create a buffer and pass it by reference to the function:

auto s = strfill('\x00', 20); // create a buffer of 20 characters
s[0:5] = "hello"; // initialize the buffer
ref2(&s); // call the function and pass the string by reference

// check if the string has a dot appended to it
if (s[5] != ".")
{
  msg("not dot\n");
}  
else
{
  msg("dot\n");
}

__usercall calling convention

It is possible to Appcall functions with non standard calling conventions, such as routines written in assembler that expect parameters in various registers and so on. One way is to use the __usercall calling convention.

Consider this function:

/* C code */
// eax = esi - edi
int __declspec(naked) asm1()
{
  __asm
  {
    mov eax, esi
    sub eax, edi
    ret
  }
}

And from IDC:

auto x = dbg_appcall(
  LocByName("asm1"),
  "int __usercall asm1@<eax>(int a@<edi>, int b@<esi>);",
  1,
  5);
msg("result = %d\n", x);

Variadic functions

In C:

int va_altsum(int n1, ...)
{
  va_list va;
  va_start(va, n1);

  int r = n1;
  int alt = 1;
  while ( (n1 = va_arg(va, int)) != 0 )
  {
    r += n1*alt;
    alt *= -1;
  }

  va_end(va);
  return r;
}

And in IDC:

auto result = va_altsum(5, 4, 2, 1, 6, 9, 0);

Calling functions that might cause exceptions

Exceptions may occur during an Appcall. To capture them, use the try/catch mechanism:

auto e;
try
{
  dbg_appcall(some_func_addr, func_type, args...);
  // Or equally:
  // some_func_name(arg1, arg2, ...);
}
catch (e)
{
  // Exception occured .....
}

The exception object "e" will be populated with the following fields:

• description: description text generated by the debugger module while it was executing the Appcall

• file: The name of the file where the exception happened.

• func: The IDC function name where the exception happened.

• line: The line number in the script

• qerrno: The internal code of last error occurred

For example, one could get something like this:

description: "Appcall: The instruction at 0x401012 referenced memory at 0x0. The memory could not be written"
file: ""
func: "___idcexec0"
line:           4.        4h           4o 
qerrno:          92.       5Ch         134o 

In some cases, the exception object will contain more information.

Functions that accept or return structures

Appcall mechanism also works with functions that accept or return structure types. Consider this C code:

#pragma pack(push, 1)
struct UserRecord 
{
  int id;
  char name[50];
  struct UserRecord* next;
};
#pragma pack(pop)

// Function to create a new record
UserRecord *makeRecord(char name[], int id) 
{
  UserRecord* newRecord = (UserRecord*)malloc(sizeof(UserRecord));
  strcpy(newRecord->name, name);
  newRecord->id = id;
  newRecord->next = NULL;
  return newRecord;
}

void printRecord(UserRecord* record) 
{
  printf("Id: %d ; Name: %s\n", record->id, record->name);
}

// Function to list all student records in the linked list
void listRecords(UserRecord* head) 
{
  if (head == NULL) 
  {
      printf("No records found.\n");
      return;
  }

  printf("Records:\n"
         "--------\n");
  while (head != NULL) 
  {
      printRecord(head);
      head = head->next;
  }
}

We can create a couple of records and link them up together:

auto rec1, rec2, rec3;
// Create records
rec1 = makeRecord("user1", 1);
rec2 = makeRecord("user2", 2);
rec3 = makeRecord("user3", 3);
// Link them up
rec1.next = rec2;
rec2.next = rec3;
// Display them
listRecords(rec1);

Because we issued an Appcall, when listRecords is called, we expect to see the following output in the console:

Records:
--------
Id: 1 ; Name: user1
Id: 2 ; Name: user2
Id: 3 ; Name: user3

We can then access the fields naturally (even the linked objects). We can verify that if we just dump the first record through the IDC CLI (or just by calling IDC's print function):

IDC>rec1
object
  id:           1.        1h           1o
  name: "user1\x00"
  next: object
    id:           2.        2h           2o
    name: "user2\x00"
    next: object
      id:           3.        3h           3o 
      name: "user3\x00"
      next: 0x0i64

Notice how when rec1 is dumped, its next field is automatically followed and properly displayed. The same happens for rec2 and rec3.

We can also directly access the fields of the structure from IDC and have those changes reflected in the debugee's memory:

rec1.id = 11;
rec1.name = "hey user1";
rec1.next.name = "hey user2";
rec1.next.id = 21;
rec1.next.next.name = "hey user3";
rec1.next.next.id = 31;
// Display them
listRecords(rec1);

Notable observations:

• Objects are always passed by reference (no need to use the &)

• Objects are created on the stack

• Objects are untyped

• Missing object fields are automatically created by IDA and filled with zero

Calling an API that receives a structure and its size

Let us take another example where we call the GetVersionExA API function: