## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Debugging Linux/Windows Applications with PIN Tracer module

## 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.

{% hint style=“info” %} IDA PIN Tool Sources:
The PIN tool for the latest versions of IDA can be found in the Download Center of My Hex-Rays portal, under SDK and Utilities.
For older versions of IDA, refer to the direct links. {% endhint %}

### 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, download PIN, 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:

- Download Center of My Hex-Rays portal (for the latest IDA versions).
- https://hex-rays.com/hubfs/freefile/idapin76.zip (*) for older IDA versions.
  - 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
2. Download the IDA pintool sources from:
   - Download Center of My Hex-Rays portal (for the latest IDA versions).
   - https://hex-rays.com/hubfs/freefile/idapin76.zip (*) for older IDA versions.
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`

    $ make TARGET=ia32

for building the x86 version, or

    $ make TARGET=intel64

for the x64 version.

#### URL Schema

(*) Where ‘$(IDAMAJMIN)’ is the IDA version major/minor. E.g., for IDA 7.6, the final URL would be: https://hex-rays.com/hubfs/freefile/idapin76.zip

NOTE: These URL links are intended for older versions of the PIN tool. To download the PIN tool for the latest versions of IDA, please visit the Download Center in My Hex-Rays portal.

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.

    $ <path-to-pin> -t <path-to-pintool> -p <port> -- <application> <application-options>

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

    $ /usr/local/pin/pin \
      -t /usr/local/pin/source/tools/idapin/obj-intel64/idadbg64.so \
      -p 23947 -- \
      /bin/ls

whereas a 32-bit one hello32 as follows:

    /usr/local/pin/pin \
      -t /usr/local/pin/source/tools/idapin/obj-ia32/idadbg.so \
      -p 23947 -- \
      ./hello32

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

    /usr/local/pin/pin \
      -t64 /usr/local/pin/source/tools/idapin/obj-intel64/idadbg64.so \
      -t /usr/local/pin/source/tools/idapin/obj-ia32/idadbg.so \
      -p 23947 -- \
      /usr/bin/ls

Also you can attach to already running programs:

    $ <path-to-pin> -pid <pid-to-attach> -t <path-to-pintool> -p <port> --

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.