FindSpot is a Pintool that uses the Intel PIN DBI framework to instrument a binary with the intent to locate the binary code functions that correspond to a specific functionality of the binary (for example clicking on a specific button).

The process consists of two easy steps, starting pin and attaching the findspot-cli controller to it. Once attached the target is suspended. It can be continued with unfreeze command.

Once the application is running, FindSpot can be switched into collection mode (see above). The goal is now to capture the behavior of interest (button click, menu click, ...) and as little as possible "noise". Right after switching into collection mode, return to the application and perform the intended action. The binary code executed as a consequence is now logged in FindSpot, but so is lots of noise.

Immediately switch FindSpot into trim mode (see above). We will now chizzle away at that noise. Any code executed now will be removed from the internal log. Take your time and perform various actions in the application, except the one of interest.

The current state of the log can be inspected with the show command. Continue removing noise until candidates for the code of interest are reduced sufficiently.

Hint: The log can be sorted by hit-count and chronologically. See help.

Hint: It might be useful to perform the action of interest X times and then look for code executed X times.

findspot>help
help          -- print this help.
kill          -- kill program (not available with -appdebug).
clear         -- clear all collected data.
freeze        -- freeze target program (all threads).
unfreeze      -- unfreeze target program.
show          -- show stats on collected data.
dump <file>   -- dump current data to file.
mode collect  -- collect all functions called from now on.
mode trim     -- remove all functions called from now on.
mode off      -- dont touch collected data.
mode          -- show current mode.
sort chrono   -- sort output in the order the functions were encountered.
sort hitcount -- sort output by number of times the functions were encountered.
mod           -- display white/blacklist.
mod blacklist <mod> -- add module to blacklist.
mod whitelist <mod> -- add module to whitelist.
mod blacklist remove <mod> -- remove module from blacklist.
mod whitelist remove <mod> -- remove module from whitelist.

FindSpot has three modes:

• collect

  This mode records any binary functions executed by the target into an internal list.

• trim

  This mode removes any binary functions executed by the target from the internal list.

• off (default)

  This mode doesnt touch the internal list at all.

void r1() { std::cout << "wow!"; }
int main()
{
    while(1)
    {
        std::cout << "choose: ";
        int choice = 0;
        std::cin >> choice;
        if(choice == 5)
            r1();
        r2();
    }
}

Above program loops forever, prompting for a number. If the user enters 5, the function r1() is executed, which does something special! Our task: How can we find which function is executed when we enter 5, without looking at the code or disassembly?

1. Download and extract the Intel Pin Framework 3.23: https://www.intel.com/content/www/us/en/developer/articles/tool/pin-a-binary-instrumentation-tool-downloads.html

2. Download a FindSpot binary release and extract it.

3. Navigate to the pin folder and in one terminal start FindSpot: pin -t FindSpot.so -d debug.log -- ./example-1

   Note: -t takes the full path to the FindSpot pin tool (FindSpot.dll on Windows).

4. In a second terminal, start the FindSpot controller ./findspot-cli (findspot-cli.exe on Windows)

5. The controller should attach to the pin tool on the default port automatically:

    using port 8022
    hello from findspot 1.0
    target frozen, type unfreeze to continue execution
   

   Note: 8022 is the hardcoded default port. This can be changed using -p <port>.

6. The target program has been frozen close to the entry point. Switch mode now or continue execution with unfreeze.

    findspot>unfreeze
    target resumed
   

   Hint: Type help to see all available commands.

7. We can play around with the application a bit at this point. Once we get a feel for everything, it's time to start the actual work. In the findspot controller, type mode collect to switch into collection mode (see modes). Freezing the application is not necessary.

8. Switching back to the target, enter 1,2,3,4 followed by 5 six times. As we are in collection mode, any function executed by the program, including r1(), r2() and any OS-API and C++ runtime, was logged by FindSpot!
   Verify this by again switching to findspot-cli and entering show.

   A total of 44 functions were executed on my system, most of them in libc and libstdc++. You can dump all of them to a file with dump take1.log for inspection.

9. Now it's time to break out the chizzle!
   Switch FindSpot to trim mode with mode trim. Again, freezing the target is not necessary. In this mode, we will remove any functions executed from the list of 44 functions we collected so far.
   Remember we are looking to find the function called when we enter the magic number 5.
   Hence, our aim is now to generate as much traffic as possible without hitting the 5-execution path. To accomplish this just enter any number but 5 a couple of times.

10. Then check out the results with monitor show:

    gdb> monitor show
    #            Address       Hits               Module Symbol 
    0       55b8bcad2271          6            example-1 _Z2r1v 
    1       7f030e38c020          1       libstdc++.so.6 .plt 
    Total Count: 2
    

    Only two functions remain! _Z2r1v in example-1 is indeed the decorated name of r1() that we were looking for. Note how it was executed exactly six times.
    Generally, we can rule out the second function here 1) because it was called one time only and 2) because it is located in the c++ runtime.

11. We have now located which function is executed for the magical 5 case without looking at any assembly at all!

We will now demonstrate a more complex example: Finding the function executed when the "bold" ToolBox button is pressed in Libre Office.

TODO with mod whitelisting and sorting

• PIN considers a function/routine only if it is a named location. Hence FindSpot is only useful with full smybols right now, especially on Windows. A mechanism to define custom functions (which can be exported from olly/ida) exists and will be part of a future release...

• The commands kill, clear and dynamic changing of whitelist/blacklist are currently broken.

• Only x64 supported.

2. Do pin -appdebug -t FindSpot.so -d debug.log -- ./targetapp.out.

   Note the additional -appdebug switch.

3. You will get this output, with a unique port number:

    Application stopped until continued from debugger.
    Start GDB, then issue this command at the (gdb) prompt:
        target remote :12345
   

4. In a second terminal, type gdb targetapp.out to start gdb.

5. Then attach to the pintool with target remote :12345 inside gdb.

6. If everything went well, you are now attached to the pin-instrumented process and can issue commands (see commands) or continue execution with continue.

7. Note that commands issued to the pin tool (FindSpot) need to be prefixed with monitor (e.g. monitor help), otherwise the command is handled by gdb.

Note: -appdebug is only available on Linux.

1. Download and extract the Intel Pin Framework 3.23: https://www.intel.com/content/www/us/en/developer/articles/tool/pin-a-binary-instrumentation-tool-downloads.html.

2. Copy the entire FindSpot directory from this repository into %PINDIR%/source/tools/.

3. On Linux: cd to %PINDIR%/source/tools/FindSpot and type 'make'.

4. On Windows: open %PINDIR%/source/tools/FindSpot/FindSpot.vcxproj in Visual Studio (tested with VS2019) and hit build.

5. Now build the controller and optionally the example, cd to %PINDIR%/source/tools/FindSpot/findspot-cli and run make (Linux) or build the findspot-cli.vcxproj (Windows).

Note: Building can be a bit of a hassle on Windows. Make sure FindSpot is located in /source/tools/ and try build->clean + build->rebuild in Visual Studio. Building has been tested with Visual Studio 2019 only. Alternatively use the binary release.

Note: Make sure to build for x64 + release. 32bit is not supported right now.

• clear command is broken
• kill command broken
• dynamic changes to whitelist/blacklist broken
• x86 broken
• import user functions
• attach/detach
• thread whitelist/blacklist