Chapters

Hide chapters

Advanced Apple Debugging & Reverse Engineering

Third Edition · iOS 12 · Swift 4.2 · Xcode 10

Before You Begin

Section 0: 3 chapters
Show chapters Hide chapters

Section III: Low Level

Section 3: 7 chapters
Show chapters Hide chapters

Section IV: Custom LLDB Commands

Section 4: 8 chapters
Show chapters Hide chapters

21. Hello, Script Bridging
Written by Derek Selander

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

LLDB has several ways you can use to create your own customized commands. The first way is through the easy-to-use command alias you saw in Chapter 9, “Persisting and Customizing”. This command simply creates an alias for a static command. While easy to implement, it really only allowed you to execute commands with no input.

After that came the command regex, which let you specify a regular expression to capture input then apply it to a command. You learned about this command in Chapter 10, “Regex Commands”. This command works well when you want to feed input to an LLDB command, but it was inconvenient to execute multiline commands and supplying multiple, optional parameters could get really messy.

Next up in the tradeoff between convenience and complexity is LLDB’s script bridging. With script bridging, you can do nearly anything you like. Script bridging is a Python interface LLDB uses to help extend the debugger to accomplish your wildest debugging dreams.

However, there’s a cost to the script bridging interface. It has a steep learning curve, and the documentation, to put it professionally, sucks. Fortunately, you’ve got this book in your hands to help guide you through learning script bridging. Once you’ve a grasp on LLDB’s Python module, you can do some very cool (and very scary!) things.

Credit where credit’s due

Before we officially begin talking about script bridging, I want to bring up one Python script that has blown my mind. If it wasn’t for this script, this book would not be in your hands.

/Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/macosx/heap.py

This is the script that made me take a deep dive into learning LLDB. I’ve never had a mental butt-kicking as good as I did trying to initially understand what was happening in this code.

This script had it all: finding stack traces for malloc’d objects (malloc_info -s), getting all instances of a particular subclass of NSObject (obj_refs -O), finding all pointers to a particular reference in memory (ptr_refs), finding C strings in memory (cstr_ref).

You can load the contents of this script with the following LLDB command:

(lldb) command script import lldb.macosx.heap

Sadly, this script has fallen a bit out of functionality as the compiler has changed, while this code has not, rendering several of its components unusable.

When you’re done reading this section, I would strongly encourage you to attempt to understand the contents of this script. You can learn a lot from it.

Ok, now back to our regularly scheduled, reading program…

Python 101

As mentioned, LLDB’s script bridge is a Python interface to the debugger. This means you can load and execute Python scripts in LLDB. In those Python scripts, you include the lldb module to interface with the debugger to obtain information such as the arguments to a custom command.

lldb
(lldb) script import sys
(lldb) script print (sys.version)
python --version 
python
python2.7
>>> import sys
>>> print (sys.version)

Playing around in Python

If you are unfamiliar with Python, this section will help you quickly get familiar with the language. If you’re already knowledgeable about Python, feel free to jump to the next section.

python
>>> h = "hello world"
>>> h
'hello world'
>>> h.split(" ")
['hello', 'world']
var h: [Any] = []
>>> h.split(" ").__class__ 
<type 'list'>
>>> h.__class__
<type 'str'>
>>> help (str)
>>> help (str.split)
Help on method_descriptor:

split(...)
    S.split([sep [,maxsplit]]) -> list of strings
    
    Return a list of the words in the string S, using sep as the
    delimiter string.  If maxsplit is given, at most maxsplit
    splits are done. If sep is not specified or is None, any
    whitespace string is a separator and empty strings are
    removed from the result.
>>> h.split(" ", 0)
>>> def test(a):
...
...   print(a + " world!")
>>> test("hello")

Creating your first LLDB Python script

From here on out, you’ll be creating all your LLDB Python scripts in the ~/lldb directory. If you want to have them in a different directory, everytime I say ~/lldb, you’ll need to invoke your “mental symlink” to whatever directory you’ve decided to use.

mkdir ~/lldb
nano ~/lldb/helloworld.py
def your_first_command(debugger, command, result, internal_dict):
  print ("hello world!")
lldb
(lldb) command script import ~/lldb/helloworld.py
(lldb) script import helloworld
(lldb) script dir(helloworld)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', 'your_first_command']
(lldb) command script add -f helloworld.your_first_command yay
(lldb) yay

Setting up commands efficiently

Once the high of creating a custom function in script bridging has worn off, you’ll come to realize you don’t want to type this stuff each time you start LLDB. You want those commands to be there ready for you as soon as LLDB starts.

def __lldb_init_module(debugger, internal_dict):
    debugger.HandleCommand('command script add -f helloworld.your_first_command yay')
(lldb) script help(lldb.SBDebugger.HandleCommand)
HandleCommand(self, *args) unbound lldb.SBDebugger method
    HandleCommand(self, str command)
command script import ~/lldb/helloworld.py
lldb
(lldb) yay
hello world!

Where to go from here?

If you don’t feel comfortable with Python, now is the time to start brushing up on it. If you have past development experience, you’ll find Python to be a fun and friendly language to learn. It’s a great language for quickly building other tools to help with everyday programming tasks.

Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2024 Kodeco Inc.

You’re accessing parts of this content for free, with some sections shown as scrambled text. Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now