hilda 3.0.1__tar.gz → 3.2.0__tar.gz

{hilda-3.0.1 → hilda-3.2.0}/.github/workflows/python-app.yml

@@ -39,4 +39,4 @@ jobs:
           xcrun python3 -m pip install -e ".[test]"
       - name: Run pytest
         run: |
-          sudo xcrun python3 -m pytest -k "not set_implementation"
+          sudo xcrun python3 -m pytest -k "not set_implementation" -vvv

{hilda-3.0.1 → hilda-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: hilda
-Version: 3.0.1
+Version: 3.2.0
 Summary: LLDB wrapped and empowered by iPython's features
 Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
 Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
@@ -55,6 +55,7 @@ Requires-Dist: inquirer3
 Requires-Dist: traitlets
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
 
 # Hilda
 
@@ -128,7 +129,7 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
 - `hilda attach [-p pid] [-n process-name]`
   - Attach to an already running process on current host (specified by either `pid` or `process-name`)
 - `hilda remote HOSTNAME PORT`
-  - Attach to an already running process on a target host (sepcified by `HOSTNAME PORT`)
+  - Attach to an already running process on a target host (specified by `HOSTNAME PORT`)
 - `hilda bare`
   - Only start an LLDB shell and load Hilda as a plugin.
   - Please refer to the following help page if you require help on the command available to you within the lldb shell:
@@ -144,173 +145,101 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
     ... and attaching to a local process:
 
     ```shell
-    process attach -n proccess_name
-    process attach -p proccess_pid
+    process attach -n process_name
+    process attach -p process_pid
     ```
 
     When you are ready, just execute `hilda` to move to Hilda's iPython shell.
 
 ### Inside a Hilda shell
 
-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 a 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
-- `peek_std_str`
-  - Peek a `std::string`
-- `stop`
-  - Stop process.
-- `cont`
-  - Continue process.
-- `run_for`
-  - Run the process for given interval.
-- `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` or `breakpoints.add_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.
-- `breakpoints.clear`
-  - Remove all breakpoints
-- `breakpoints.remove`
-  - Remove a single breakpoint
-- `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` or `breakpoints.add`
-  - Add a breakpoint
-- `breakpoints.show`
-  - Show existing breakpoints
-- `po`
-  - Print given object using LLDB's po command
-      Can also run big chunks of native code:
-
-      po('NSMutableString *s = [NSMutableString string]; [s appendString:@"abc"]; [s description]')
-- `globalize_symbols`
-  - Make all symbols in python's global scope
-- `jump`
-  - jump to given symbol
-- `lldb_handle_command`
-  - Execute an LLDB command
-      For example:
-      lldb_handle_command('register read')
-- `objc_get_class`
-  - Get ObjC class object
-- `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)
-- `unwind`
-  - Unwind the stack (useful when get_evaluation_unwind() == False)
-- `set_selected_thread`
-  - sets the currently selected thread, which is used in other parts of the program, such as displaying disassembly or
-      checking registers.
-      This ensures the application focuses on the specified thread for these operations.
-- `wait_for_module`
-  - Wait for a module to be loaded (`dlopen`) by checking if given expression is contained within its filename
-
-All these methods are available from the global `p` within the newly created IPython shell. In addition, you may invoke any of the exported APIs described in the [Python API](#python-api)
+Upon starting Hilda, you are welcomed into an IPython shell.
+You can access following methods via the variable `p`.
+
+Basic flow control:
+
+- `stop` - Stop process
+- `cont` - Continue process
+- `finish` - Run current function until return
+- `step_into` - Step into current instruction
+- `step_over` - Step over current instruction.
+- `run_for` - Run the process for given interval
+- `force_return` - Prematurely return from a stack frame, short-circuiting execution of inner
+  frames and optionally yielding a specified value.
+- `jump` - Jump to given symbol
+- `wait_for_module` - Wait for a module to be loaded (`dlopen`) by checking if given expression is contained within its filename
+- `detach` - Detach from process (useful for exiting gracefully so the
+  process doesn't get killed when you exit)
+
+Breakpoints:
+- `bp` or `breakpoints.add` - Add a breakpoint
+- `breakpoints.show` - Show existing breakpoints
+- `breakpoints.remove` - Remove a single breakpoint
+- `breakpoints.clear` - Remove all breakpoints
+- `monitor` or `breakpoints.add_monitor` - Creates a breakpoint whose callback implements the requested features (print register values, execute commands, mock return value, etc.)
+
+Basic read/write:
+
+- `get_register` - Get register value
+- `set_register` - Set register value
+- `poke` - Write data at address
+- `peek[_str,_std_str]` - Read buffer/C-string/`std::string` at address
+- `po` - Print object using LLDB's `po` command
+  Can also run arbitrary native code:
+
+  ```python
+  p.po('NSMutableString *s = [NSMutableString string]; [s appendString:@"abc"]; [s description]')
+  ```
+- `disass` - Print disassembly at address
+- `show_current_source` - Print current source code (if possible)
+- `bt` - Get backtrace
+- `lsof` - Get all open FDs
+- `hd` - Hexdump a buffer
+- `proc_info` - Print information about currently running mapped process
+- `print_proc_entitlements` - Get the plist embedded inside the process' __LINKEDIT section.
+
+Execute code:
+
+- `call` - Call function at given address with given parameters
+- `objc_call` - Simulate a call to an objc selector
+- `inject` - Inject a single library into currently running process
+- `disable_jetsam_memory_checks` -
+   Disable jetsam memory checks (to prevent raising
+   `error: Execution was interrupted, reason: EXC_RESOURCE RESOURCE_TYPE_MEMORY (limit=15 MB, unused=0x0).`
+   when evaluating expressions).
+
+Hilda symbols:
+
+- `symbol` - Get symbol object for a given address
+- `objc_symbol` - Get objc symbol wrapper for given address
+- `file_symbol` - Calculate symbol address without ASLR
+- `save` - Save loaded symbols map (for loading later using the load() command)
+- `load` - Load an existing symbols map (previously saved by the save() command)
+- `globalize_symbols` - Make all symbols in python's global scope
+
+Advanced:
+
+- `lldb_handle_command` - Execute an LLDB command (e.g., `p.lldb_handle_command('register read')`)
+- `evaluate_expression` - Use for quick code snippets (wrapper for LLDB's `EvaluateExpression`)
+
+  Take advantage of local variables inside the expression using format string, e.g.,
+
+  ```python
+  currentDevice = p.objc_get_class('UIDevice').currentDevice
+  p.evaluate_expression(f'[[{currentDevice} systemName] hasPrefix:@"2"]')
+  ```
+- `import_module` - Import & reload given python module (intended mainly for external snippets)
+- `unwind` - Unwind the stack (useful when get_evaluation_unwind() == False)
+- `set_selected_thread` - sets the currently selected thread, which is used in other parts of the program, such as displaying disassembly or
+  checking registers.
+  This ensures the application focuses on the specified thread for these operations.
+
+Objective-C related:
+
+- `objc_get_class` - Get ObjC class object
+- `CFSTR` - Create CFStringRef object from given string
+- `ns` - Create NSObject from given data
+- `from_ns` - Create python object from NS object.
 
 #### Magic functions
 
@@ -363,7 +292,7 @@ ui.show()
 ```
 
 By default `step_into` and `step_over` will show this UI automatically.
-You may disable this behaviour by executing:
+You may disable this behavior by executing:
 
 ```python
 ui.active = False
@@ -487,7 +416,7 @@ s[0] = 1
 s[0] = p.symbol(0x11223344)()  # calling symbols also returns symbols 
 
 # attempt to resolve symbol's name
-print(p.symbol(0x11223344).lldb_symbol)
+print(p.symbol(0x11223344).lldb_address)
 
 # monitor each time a symbol is called into console and print its backtrace (`bt` option)
 # this will create a scripted breakpoint which prints your desired data and continue
@@ -537,8 +466,8 @@ p.bp(('symbol_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
+access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolList`, which acts like
+`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:
 
 ```python
@@ -561,22 +490,17 @@ x = malloc(20)
 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.
-
 ```python
-p.rebind_symbols()  # this might take some time
-
 # find all symbols prefixed as `mem*` AND don't have `cpy`
 # in their name
-jar = p.symbols.startswith('mem') - p.symbols.find('cpy')
+l = p.symbols.filter_startswith('mem') - p.symbols.filter_name_contains('cpy')
 
 # filter only symbols of type "code" (removing data global for example)
-jar = jar.code()
+l = l.filter_code_symbols()
 
 # monitor every time each one is called, print its `x0` in HEX
 # form and show the backtrace
-jar.monitor(regs={'x0': 'x'}, bt=True)
+l.monitor(regs={'x0': 'x'}, bt=True)
 ```
 
 #### Objective-C Classes
@@ -608,21 +532,21 @@ print(NSDictionary.ivars)
 # show the class' methods
 print(NSDictionary.methods)
 
-# show the class' proprties
+# show the class' properties
 print(NSDictionary.properties)
 
 # view class' selectors which are prefixed with 'init'
-print(NSDictionary.symbols_jar.startswith('-[NSDictionary init'))
+print(NSDictionary.methods.filter_startswith('init'))
 
-# you can of course use any of `SymbolsJar` over them, for example:
+# you can of course use any of `SymbolList` over them, for example:
 # this will `po` (print object) all those selectors returned value
-NSDictionary.symbols_jar.startswith('-[NSDictionary init').monitior(retval='po')
+NSDictionary.methods.filter_startswith('init').monitor(retval='po')
 
 # monitor each time any selector in NSDictionary is called
 NSDictionary.monitor()
 
 # `force_return` for some specific selector with a hard-coded value (4)
-NSDictionary.get_method('valueForKey:').address.monitor(force_return=4)
+NSDictionary.methods.get('valueForKey:').address.monitor(force_return=4)
 
 # capture the `self` object at the first hit of any selector
 # `True` for busy-wait for object to be captured
@@ -672,7 +596,7 @@ commands so you are able to use complicated types when parsing values and passin
 import datetime
 
 # using the `ns` command we can just pass a python-native dictionary
-function_requiring_a_specfic_dictionary(ns({
+function_requiring_a_specfic_dictionary(p.cf({
     'key1': 'string',  # will convert to NSString
     'key2': True,  # will convert to NSNumber
     'key3': b'1234',  # will convert to NSData
@@ -707,7 +631,7 @@ They all use the following concept to use:
 ```python
 from hilda.snippets import snippet_name
 
-snippet_name.do_domething()  
+snippet_name.do_something()
 ```
 
 For example, XPC sniffing can be done using: