Description
Hilda is a debugger which combines both the power of LLDB and iPython for easier debugging.
The name originates from the TV show "Hilda", which is the best friend of
Frida. Both Frida and Hilda are meant for pretty much the same purpose, except Hilda takes the
more "
debugger-y" approach (based on LLDB).
Currently, the project is intended for iOS/OSX debugging, but in the future we will possibly add support for the
following platforms as well:
Since LLDB allows abstraction for both platform and architecture, it should be possible to make the necessary changes
without too many modifications.
Pull requests are more than welcome 😊.
If you need help or have an amazing idea you would like to suggest, feel free
to start a discussion 💬.
Installation
Requirements for remote iOS device (not required for debugging a local OSX process):
- Jailbroken iOS device
debugserver
in device's PATH
In order to install please run:
xcrun python3 -m pip install --user -U hilda
⚠️ Please note that Hilda is installed on top of XCode's python so LLDB will be able to use its features.
How to use
Starting a Hilda shell
Attach mode
Use the attach sub-command in order to start an LLDB shell attached to given process.
hilda attach [-p pid] [-n process-name]
After attaching, simply execute hilda
command to enter the hilda shell.
Bare mode
Use "Bare mode" to get a "bare-bones" lldb shell, whereas hilda plugin is already loaded and ready to start. This mode
is useful when you need to have custom commands for attaching to the target process (for example when debugging OSX
processes).
To start this mode simply use:
hilda bare
Please refer to the following help page if you require help on the command available to you within the lldb shell:
lldb command map.
As a cheatsheet, connecting to a remote platform like so:
platform connect connect://ip:port
... and attaching to a local process:
process attach -n proccess_name
process attach -p proccess_pid
When you are ready, just execute hilda
to move to Hilda's iPython shell.
Remote mode
This mode will auto-connect to the remote device and attach to your target process assuming you are trying to debug a
remote jailbroken iOS device.
Please note the following:
- script assumes the connected device already has a running ssh server, which doesn't require a password (you can
use
ssh-copy-id
to achieve this).
From this point the flow diverges into 2 flows:
The connected device is connected via network
Run the following command:
hilda remote HOSTNAME PORT
Usage
Upon starting Hilda shell, you are greeted with:
Hilda has been successfully loaded! 😎
Use the p global to access all features.
Have a nice flight ✈️! Starting an IPython shell...
Here is a gist of methods you can access from p
:
hd
- Print an hexdump of given buffer
lsof
- Get dictionary of all open FDs
bt
- Print an improved backtrace.
disable_jetsam_memory_checks
- Disable jetsam memory checks, prevent raising:
error: Execution was interrupted, reason: EXC_RESOURCE RESOURCE_TYPE_MEMORY (limit=15 MB, unused=0x0).
when evaluating expression.
symbol
- Get symbol object for a given address
objc_symbol
- Get objc symbol wrapper for given address
inject
- Inject a single library into currently running process
rebind_symbols
- Reparse all loaded images symbols
poke
- Write data at given address
peek
- Read data at given address
peek_str
- Peek a buffer till null termination
stop
cont
detach
- Detach from process.
Useful in order to exit gracefully so process doesn't get killed
while you exit
disass
- Print disassembly from a given address
file_symbol
- Calculate symbol address without ASLR
get_register
- Get value for register by its name
set_register
- Set value for register by its name
objc_call
- Simulate a call to an objc selector
call
- Call function at given address with given parameters
monitor
- Monitor every time a given address is called
The following options are available:
regs={reg1: format}
will print register values
Available formats:
x: hex
s: string
cf: use CFCopyDescription() to get more informative description of the object
po: use LLDB po command
User defined function, will be called like `format_function(hilda_client, value)`.
For example:
regs={'x0': 'x'} -> x0 will be printed in HEX format
expr={lldb_expression: format}
lldb_expression can be for example '$x0' or '$arg1'
format behaves just like 'regs' option
retval=format
Print function's return value. The format is the same as regs format.
stop=True
force a stop at every hit
bt=True
print backtrace
cmd=[cmd1, cmd2]
run several LLDB commands, one by another
force_return=value
force a return from function with the specified value
name=some_value
use `some_name` instead of the symbol name automatically extracted from the calling frame
override=True
override previous break point at same location
show_current_source
- print current source code if possible
finish
- Run current frame till its end.
step_into
- Step into current instruction.
step_over
- Step over current instruction.
remove_all_hilda_breakpoints
- Remove all breakpoints created by Hilda
remove_hilda_breakpoint
- Remove a single breakpoint placed by Hilda
force_return
- Prematurely return from a stack frame, short-circuiting exection of newer frames and optionally
yielding a specified value.
proc_info
- Print information about currently running mapped process.
print_proc_entitlements
- Get the plist embedded inside the process' __LINKEDIT section.
bp
show_hilda_breakpoints
- Show existing breakpoints created by Hilda.
show_commands
save
- Save loaded symbols map (for loading later using the load() command)
load
- Load an existing symbols map (previously saved by the save() command)
po
globalize_symbols
- Make all symbols in python's global scope
jump
lldb_handle_command
- Execute an LLDB command
For example:
lldb_handle_command('register read')
objc_get_class
CFSTR
- Create CFStringRef object from given string
ns
- Create NSObject from given data
from_ns
- Create python object from NS object.
evaluate_expression
-
Wrapper for LLDB's EvaluateExpression.
Used for quick code snippets.
Feel free to use local variables inside the expression using format string.
For example:
currentDevice = objc_get_class('UIDevice').currentDevice
evaluate_expression(f'[[{currentDevice} systemName] hasPrefix:@"2"]')
import_module
- Import & reload given python module (intended mainly for external snippets)
set_evaluation_unwind
- Set whether LLDB will attempt to unwind the stack whenever an expression evaluation error occurs.
Use unwind() to restore when an error is raised in this case.
get_evaluation_unwind
- Get evaluation unwind state.
When this value is True, LLDB will attempt unwinding the stack on evaluation errors.
Otherwise, the stack frame will remain the same on errors to help you investigate the error.
set_evaluation_ignore_breakpoints
- Set whether to ignore breakpoints while evaluating expressions
get_evaluation_ignore_breakpoints
- Get evaluation "ignore-breakpoints" state.
unwind
- Unwind the stack (useful when get_evaluation_unwind() == False)
Magic functions
Sometimes accessing the python API can be tiring, so we added some magic functions to help you out!
%objc <className>
- Equivalent to:
className = p.objc_get_class(className)
%fbp <filename> <addressInHex>
- Equivalent to:
p.file_symbol(addressInHex, filename).bp()
UI Configuration
Hilda contains minimal UI for examining the target state.
The UI is divided into views:
- Registers
- Disassembly
- Stack
- Backtrace
This UI can be displayed at any time be executing:
ui.show()
By default step_into
and step_over
will show this UI automatically.
You may disable this behaviour by executing:
ui.active = False
Attentively, if you want to display UI after hitting a breakpoint, you can register ui.show
as callback:
p.symbol(0x7ff7b97c21b0).bp(ui.show)
Try playing with the UI settings by yourself:
ui.views.stack.active = False
ui.views.stack.depth = 10
ui.views.backtrace.depth = 10
ui.views.disassembly.instruction_count = 5
ui.views.disassembly.flavor = 'att'
ui.views.registers.rtype = 'float'
ui.colors.address = 'red'
ui.color.title = 'green'
Symbol objects
In Hilda, almost everything is wrapped using the Symbol
Object. Symbol is just a nicer way for referring to addresses
encapsulated with an object allowing to deref the memory inside, or use these addresses as functions.
In order to create a symbol from a given address, please use:
s = p.symbol(0x12345678)
True == isinstance(s, int)
print(s.file_address)
s = p.file_symbol(0x12345678)
print(s.peek(20))
s.poke('abc')
print(s.po())
print(s.po('char *'))
s(1, "string")
s.item_size = 1
s[0] = 1
s[1] = 1
s += 4
s.item_size = 8
s[0] = 1
s[0] = p.symbol(0x11223344)()
print(p.symbol(0x11223344).lldb_symbol)
s.monitor(bt=True)
s.monitor(regs={'x0': 'x'},
retval='po',
bt=True,
cmd=['thread list'],
)
s.monitor(force_return=0)
s.monitor?
def scripted_breakpoint(hilda, *args):
if hilda.registers.x0.peek(4) == b'\x11\x22\x33\x44':
hilda.registers.x0 = hilda.symbols.malloc(200)
hilda.registers.x0.poke(b'\x22' * 200)
hilda.cont()
s.bp(scripted_breakpoint)
p.bp('symbol_name')
p.bp('symbol_name', module_name='ModuleName')
Globalized symbols
Usually you would want/need to use the symbols already mapped into the currently running process. To do so, you can
access them using symbols.<symbol-name>
. The symbols
global object is of type SymbolsJar
, which is a wrapper
to dict
for accessing all exported symbols. For example, the following will generate a call to the exported
malloc
function with 20
as its only argument:
x = p.symbols.malloc(20)
You can also just write their name as if they already were in the global scope. Hilda will check if no name collision
exists, and if so, will perform the following lazily for you:
x = malloc(20)
malloc = p.symbols.malloc
x = malloc(20)
Searching for the right symbol
Sometimes you don't really know where to start your research. All you have is just theories of how your desired exported
symbol should be called (if any).
For that reason alone, we have the rebind_symbols()
command - to help you find the symbol you are looking for.
p.rebind_symbols()
jar = p.symbols.startswith('mem') - p.symbols.find('cpy')
jar = jar.code()
jar.monitor(regs={'x0': 'x'}, bt=True)
Objective-C Classes
The same as symbols applies to Objective-C classes name resolution. You can either:
d = NSDictionary.new()
NSDictionary = p.objc_get_class('NSDictionary')
d = NSDictionary.new()
%objc
NSDictionary
This is possible only since NSDictionary
is exported. In case it is not, you must call objc_get_class()
explicitly.
As you can see, you can directly access all the class' methods.
Please look what more stuff you can do as shown below:
print(NSDictionary.ivars)
print(NSDictionary.methods)
print(NSDictionary.properties)
print(NSDictionary.symbols_jar.startswith('-[NSDictionary init'))
NSDictionary.symbols_jar.startswith('-[NSDictionary init').monitior(retval='po')
NSDictionary.monitor()
NSDictionary.get_method('valueForKey:').address.monitor(force_return=4)
dictionary = NSDictionary.capture_self(True)
dictionary.show()
Objective-C Objects
In order to work with ObjC objects, each symbol contains a property called
objc_symbol
. After calling, you can work better with each object:
dict = NSDictionary.new().objc_symbol
dict.show()
print(dict.ivars)
print(dict._ivarName)
dict._ivarName = value
arr = dict.objectForKey_('keyContainingNSArray')
newDict = dict.dictionary()
print(arr.po())
Also, working with Objective-C objects like this can be somewhat exhausting, so we created the ns
and from_ns
commands so you are able to use complicated types when parsing values and passing as arguments:
import datetime
function_requiring_a_specfic_dictionary(ns({
'key1': 'string',
'key2': True,
'key3': b'1234',
'key4': datetime.datetime(2021, 1, 1)
}))
normal_python_dict = p.cf({
'key1': 'string',
'key2': True,
'key3': b'1234',
'key4': datetime.datetime(2021, 1, 1)
}).py()
On last resort, if the object is not serializable for this to work, you can just run pure Objective-C code:
abc_string = p.evaluate_expression('[NSString stringWithFormat:@"abc"]')
print(abc_string.po())
Using snippets
Snippets are extensions for normal functionality used as quick cookbooks for day-to-day tasks of a debugger.
They all use the following concept to use:
from hilda.snippets import snippet_name
snippet_name.do_domething()
For example, XPC sniffing can be done using:
from hilda.snippets import xpc
xpc.sniff_all()
This will monitor all XPC related traffic in the given process.
Contributing
Please run the tests as follows before submitting a PR:
xcrun python3 -m tests aggregated
# wait for lldb shell prompt
run_tests