hilda 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

hilda/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.0.1'
-__version_tuple__ = version_tuple = (2, 0, 1)
+__version__ = version = '2.0.3'
+__version_tuple__ = version_tuple = (2, 0, 3)

hilda/cli.py

@@ -1,12 +1,14 @@
 import logging
 from pathlib import Path
-from typing import List, Mapping, Optional
+from typing import List, Optional
 
 import click
 import coloredlogs
 
 from hilda import launch_lldb
 from hilda._version import version
+from hilda.launch_lldb import create_hilda_client_using_attach_by_name, create_hilda_client_using_attach_by_pid, \
+    create_hilda_client_using_launch, create_hilda_client_using_remote_attach
 
 DEFAULT_HILDA_PORT = 1234
 
@@ -18,7 +20,7 @@ def cli():
     pass
 
 
-startup_files_option = click.option('-f', '--startup_files', multiple=True, default=None, help='Files to run on start')
+startup_files_option = click.option('-f', '--startup_files', multiple=True, help='Files to run on start')
 
 
 def parse_envp(ctx: click.Context, param: click.Parameter, value: List[str]) -> List[str]:
@@ -36,54 +38,59 @@ def parse_envp(ctx: click.Context, param: click.Parameter, value: List[str]) ->
 @click.argument('hostname', default='localhost')
 @click.argument('port', type=click.INT, default=DEFAULT_HILDA_PORT)
 @startup_files_option
-def remote(hostname: str, port: int, startup_files: Optional[List[str]] = None) -> None:
+def remote(hostname: str, port: int, startup_files: List[str]) -> None:
     """ Connect to remote debugserver at given address """
-    launch_lldb.remote(hostname, port, startup_files)
+    with create_hilda_client_using_remote_attach(hostname, port) as hilda_client:
+        hilda_client.interact(startup_files=startup_files)
 
 
 @cli.command('attach')
 @click.option('-n', '--name', help='process name to attach')
 @click.option('-p', '--pid', type=click.INT, help='pid to attach')
 @startup_files_option
-def attach(name: str, pid: int, startup_files: Optional[List[str]] = None) -> None:
+def attach(name: Optional[str], pid: Optional[int], startup_files: List[str]) -> None:
     """ Attach to given process and start a lldb shell """
-    launch_lldb.attach(name=name, pid=pid, startup_files=startup_files)
+    if name is not None:
+        hilda_client = create_hilda_client_using_attach_by_name(name)
+    elif pid is not None:
+        hilda_client = create_hilda_client_using_attach_by_pid(name)
+    else:
+        raise click.UsageError('You must specify a process name or pid')
+    hilda_client.interact(startup_files=startup_files)
+    hilda_client.detach()
+
+
+@cli.command('bare')
+def cli_bare() -> None:
+    """ Just start a lldb shell """
+    commands = [f'command script import {Path(__file__).resolve().parent / "lldb_entrypoint.py"}']
+    commands = '\n'.join(commands)
+    launch_lldb.execute(f'lldb --one-line "{commands}"')
 
 
 @cli.command('launch')
 @click.argument('exec_path')
 @click.option('--argv', multiple=True, help='Command line arguments to pass to the process')
 @click.option('--envp', multiple=True, callback=parse_envp, help='Environment variables in the form KEY=VALUE')
-@click.option('--stdin', type=Path, help='Redirect stdin from this file path')
-@click.option('--stdout', type=Path, help='Redirect stdout to this file path')
-@click.option('--stderr', type=Path, help='Redirect stderr to this file path')
-@click.option('--cwd', type=Path, help='Set the working directory for the process')
+@click.option('--stdin', help='Redirect stdin from this file path')
+@click.option('--stdout', help='Redirect stdout to this file path')
+@click.option('--stderr', help='Redirect stderr to this file path')
+@click.option('--cwd', help='Set the working directory for the process')
 @click.option('--flags', type=click.INT, default=0, help='Launch flags (bitmask)')
 @click.option('--stop-at-entry', is_flag=True, help='Stop the process at the entry point')
 @startup_files_option
-def launch(exec_path: str, argv: Optional[List] = None, envp: Optional[Mapping] = None,
-           stdin: Optional[Path] = None,
-           stdout: Optional[Path] = None, stderr: Optional[Path] = None, cwd: Optional[Path] = None,
-           flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False,
-           startup_files: Optional[List[str]] = None) -> None:
+def launch(exec_path: str, argv: List[str], envp: List[str], stdin: Optional[Path],
+           stdout: Optional[Path], stderr: Optional[Path], cwd: Optional[Path], flags: Optional[int],
+           stop_at_entry: Optional[bool], startup_files: List[str]) -> None:
     """ Attach to given process and start a lldb shell """
-    if not argv:
-        argv = None
-    if not envp:
-        envp = None
-    launch_lldb.launch(exec_path, argv, envp, stdin, stdout, stderr, cwd, flags, stop_at_entry,
-                       startup_files)
-
-
-@cli.command('bare')
-def cli_bare():
-    """ Just start a lldb shell """
-    commands = [f'command script import {Path(__file__).resolve().parent / "lldb_entrypoint.py"}']
-    commands = '\n'.join(commands)
-    launch_lldb.execute(f'lldb --one-line "{commands}"')
+    argv = list(argv)
+    envp = list(envp)
+    with create_hilda_client_using_launch(
+            exec_path, argv, envp, stdin, stdout, stderr, cwd, flags, stop_at_entry) as hilda_client:
+        hilda_client.interact(startup_files=startup_files)
 
 
 @cli.command('version')
-def cli_version():
+def cli_version() -> None:
     """Show the version information."""
     click.echo(version)

hilda/common.py

@@ -1,5 +1,14 @@
 from datetime import datetime
 from typing import Any, List, Mapping, Tuple, Union
 
+import inquirer3
+from inquirer3.themes import GreenPassion
+
 CfSerializable = Union[
     Mapping[str, Any], List, Tuple[Any, ...], str, bool, float, bytes, datetime, None]
+
+
+def selection_prompt(options_list: List):
+    question = [inquirer3.List('choice', message='choose device', choices=options_list, carousel=True)]
+    result = inquirer3.prompt(question, theme=GreenPassion(), raise_keyboard_interrupt=True)
+    return result['choice']

hilda/exceptions.py

@@ -1,7 +1,7 @@
 __all__ = ['HildaException', 'SymbolAbsentError', 'EvaluatingExpressionError', 'CreatingObjectiveCSymbolError',
            'ConvertingToNsObjectError', 'ConvertingFromNSObjectError', 'DisableJetsamMemoryChecksError',
            'GettingObjectiveCClassError', 'AccessingRegisterError', 'AccessingMemoryError',
-           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBException']
+           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBError', 'InvalidThreadIndexError']
 
 
 class HildaException(Exception):
@@ -9,12 +9,9 @@ class HildaException(Exception):
     pass
 
 
-class LLDBException(Exception):
-    """ A domain exception for lldb errors. """
-
-    def __init__(self, message: str):
-        super().__init__()
-        self.message = message
+class LLDBError(HildaException):
+    """ Wrapper for RAW LLDB errors """
+    pass
 
 
 class SymbolAbsentError(HildaException):
@@ -70,3 +67,8 @@ class BrokenLocalSymbolsJarError(HildaException):
 class AddingLldbSymbolError(HildaException):
     """ Raise when failing to convert a LLDB symbol to Hilda's symbol. """
     pass
+
+
+class InvalidThreadIndexError(HildaException):
+    """ Raise when thread idx invalid """
+    pass

hilda/hilda_client.py

@@ -30,10 +30,11 @@ from tqdm import tqdm
 from traitlets.config import Config
 
 from hilda import objective_c_class
-from hilda.common import CfSerializable
+from hilda.common import CfSerializable, selection_prompt
 from hilda.exceptions import AccessingMemoryError, AccessingRegisterError, AddingLldbSymbolError, \
     BrokenLocalSymbolsJarError, ConvertingFromNSObjectError, ConvertingToNsObjectError, CreatingObjectiveCSymbolError, \
-    DisableJetsamMemoryChecksError, EvaluatingExpressionError, HildaException, SymbolAbsentError
+    DisableJetsamMemoryChecksError, EvaluatingExpressionError, HildaException, InvalidThreadIndexError, \
+    SymbolAbsentError
 from hilda.lldb_importer import lldb
 from hilda.objective_c_symbol import ObjectiveCSymbol
 from hilda.registers import Registers
@@ -73,7 +74,7 @@ def disable_logs() -> None:
     logging.getLogger('parso.python.diff').disabled = True
     logging.getLogger('humanfriendly.prompts').disabled = True
     logging.getLogger('blib2to3.pgen2.driver').disabled = True
-    logging.getLogger('hilda.launch_lldb').disabled = True
+    logging.getLogger('hilda.launch_lldb').setLevel(logging.INFO)
 
 
 SerializableSymbol = namedtuple('SerializableSymbol', 'address type_ filename')
@@ -356,17 +357,19 @@ class HildaClient:
         if not self.process.Continue().Success():
             self.log_critical('failed to continue process')
 
-    def detach(self):
+    def detach(self) -> None:
         """
         Detach from process.
 
         Useful in order to exit gracefully so process doesn't get killed
         while you exit
         """
+        if not self.process.is_alive:
+            return
         if not self.process.Detach().Success():
             self.log_critical('failed to detach')
-        else:
-            self.log_info('Process Detached')
+            return
+        self.log_info('Process Detached')
 
     @stop_is_needed
     def disass(self, address: int, buf: bytes, flavor: str = 'intel',
@@ -397,30 +400,33 @@ class HildaClient:
 
         return self.symbol(module.ResolveFileAddress(address).GetLoadAddress(self.target))
 
-    def get_register(self, name) -> Symbol:
+    def get_register(self, name: str) -> Union[float, Symbol]:
         """
-        Get value for register by its name
-        :param name:
-        :return:
+        Get value for register by its name. Value can either be an Symbol (int) or a float.
+
+        :param name: Register name
+        :return: Register value
         """
-        register = self.frame.register[name.lower()]
-        if register is None:
+        register_value = self.frame.register[name.lower()]
+        if register_value is None:
             raise AccessingRegisterError()
-        return self.symbol(register.unsigned)
+        return self._get_symbol_or_float_from_sbvalue(register_value)
 
-    def set_register(self, name, value):
+    def set_register(self, name: str, value: Union[float, int]) -> None:
         """
         Set value for register by its name
-        :param name:
-        :param value:
-        :return:
+        :param name: Register name
+        :param value: Register value
         """
         register = self.frame.register[name.lower()]
         if register is None:
             raise AccessingRegisterError()
-        register.value = hex(value)
+        if isinstance(value, int):
+            register.value = hex(value)
+        else:
+            register.value = str(value)
 
-    def objc_call(self, obj, selector, *params):
+    def objc_call(self, obj: int, selector: str, *params):
         """
         Simulate a call to an objc selector
         :param obj: obj to pass into `objc_msgSend`
@@ -510,7 +516,7 @@ class HildaClient:
             if options.get('name', False):
                 name = options['name']
 
-            log_message = f'🚨 #{bp.id} 0x{symbol:x} {name}'
+            log_message = f'🚨 #{bp.id} 0x{symbol:x} {name} - Thread #{self.thread.idx}:{hex(self.thread.id)}'
 
             if 'regs' in options:
                 log_message += '\nregs:'
@@ -524,27 +530,32 @@ class HildaClient:
                     value = hilda.symbol(hilda.evaluate_expression(name))
                     log_message += f'\n\t{name} = {hilda._monitor_format_value(fmt, value)}'
 
-            if options.get('force_return', False):
-                hilda.force_return(options['force_return'])
-                log_message += f'\nforced return: {options["force_return"]}'
+            force_return = options.get('force_return')
+            if force_return is not None:
+                hilda.force_return(force_return)
+                log_message += f'\nforced return: {force_return}'
 
-            if options.get('bt', False):
+            if options.get('bt'):
                 # bugfix: for callstacks from xpc events
                 hilda.finish()
-                hilda.bt()
+                for frame in hilda.bt():
+                    log_message += f'\n\t{frame[0]} {frame[1]}'
 
-            if options.get('retval', False):
+            retval = options.get('retval')
+            if retval is not None:
                 # return from function
                 hilda.finish()
                 value = hilda.evaluate_expression('$arg1')
-                log_message += f'\nreturned: {hilda._monitor_format_value(options["retval"], value)}'
+                log_message += f'\nreturned: {hilda._monitor_format_value(retval, value)}'
 
             hilda.log_info(log_message)
 
             for cmd in options.get('cmd', []):
                 hilda.lldb_handle_command(cmd)
 
-            if not options.get('stop', False):
+            if options.get('stop', False):
+                hilda.log_info('Process remains stopped and focused on current thread')
+            else:
                 hilda.cont()
 
         return self.bp(address, callback, condition=condition, **options)
@@ -834,7 +845,7 @@ class HildaClient:
             raise ConvertingFromNSObjectError from e
         return json.loads(json_dump, object_hook=self._from_ns_json_object_hook)['root']
 
-    def evaluate_expression(self, expression) -> Symbol:
+    def evaluate_expression(self, expression: str) -> Union[float, Symbol]:
         """
         Wrapper for LLDB's EvaluateExpression.
         Used for quick code snippets.
@@ -844,8 +855,8 @@ class HildaClient:
             currentDevice = objc_get_class('UIDevice').currentDevice
             evaluate_expression(f'[[{currentDevice} systemName] hasPrefix:@"2"]')
 
-        :param expression:
-        :return: returned symbol
+        :param expression: Expression to evaluate
+        :return: Returned value (either float or a Symbol)
         """
         # prepending a prefix so LLDB knows to return an int type
         if isinstance(expression, int):
@@ -858,12 +869,12 @@ class HildaClient:
         options.SetTryAllThreads(True)
         options.SetUnwindOnError(self.configs.evaluation_unwind_on_error)
 
-        e = self.frame.EvaluateExpression(formatted_expression, options)
+        sbvalue = self.frame.EvaluateExpression(formatted_expression, options)
 
-        if not e.error.Success():
-            raise EvaluatingExpressionError(str(e.error))
+        if not sbvalue.error.Success():
+            raise EvaluatingExpressionError(str(sbvalue.error))
 
-        return self.symbol(e.unsigned)
+        return self._get_symbol_or_float_from_sbvalue(sbvalue)
 
     def import_module(self, filename: str, name: Optional[str] = None) -> Any:
         """
@@ -880,6 +891,16 @@ class HildaClient:
         spec.loader.exec_module(m)
         return m
 
+    def set_selected_thread(self, idx: Optional[int] = None) -> None:
+        if idx is None:
+            thread = selection_prompt(self.process.threads)
+        else:
+            try:
+                thread = [t for t in self.process.threads if t.idx == idx][0]
+            except IndexError:
+                raise InvalidThreadIndexError()
+        self.process.SetSelectedThread(thread)
+
     def unwind(self) -> bool:
         """ Unwind the stack (useful when get_evaluation_unwind() == False) """
         return self.thread.UnwindInnermostExpression().Success()
@@ -1033,7 +1054,7 @@ class HildaClient:
         ipython_config.InteractiveShellApp.extensions = ['hilda.ipython_extensions.magics',
                                                          'hilda.ipython_extensions.events',
                                                          'hilda.ipython_extensions.keybindings']
-        ipython_config.InteractiveShellApp.exec_lines = ["disable_logs()"]
+        ipython_config.InteractiveShellApp.exec_lines = ['disable_logs()']
         if startup_files is not None:
             ipython_config.InteractiveShellApp.exec_files = startup_files
             self.log_debug(f'Startup files - {startup_files}')
@@ -1041,10 +1062,17 @@ class HildaClient:
         namespace = globals()
         namespace.update(locals())
         namespace['p'] = self
+        namespace['ui'] = self.ui_manager
+        namespace['cfg'] = self.configs
         if additional_namespace is not None:
             namespace.update(additional_namespace)
         sys.argv = ['a']
         IPython.start_ipython(config=ipython_config, user_ns=namespace)
+
+    def __enter__(self) -> 'HildaClient':
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
         self.detach()
 
     @staticmethod
@@ -1158,3 +1186,11 @@ class HildaClient:
                 '__objc_class_list',
                 f'{objc_classlist_addr}')
             return json.loads(self.po(obj_c_code))
+
+    def _get_symbol_or_float_from_sbvalue(self, value: lldb.SBValue) -> Union[float, Symbol]:
+        # The `value` attribute of an SBValue stores a string representation of the actual value
+        # in a python-compatible format, so we can eval it to get the native python value
+        value = eval(value.value)
+        if isinstance(value, float):
+            return value
+        return self.symbol(value)

hilda/launch_lldb.py

@@ -4,7 +4,7 @@ from abc import ABC, abstractmethod
 from threading import Thread
 from typing import List, Optional
 
-from hilda.exceptions import LLDBException
+from hilda.exceptions import LLDBError
 from hilda.hilda_client import HildaClient
 from hilda.lldb_importer import lldb
 
@@ -14,14 +14,6 @@ lldb.hilda_client = None
 logger = logging.getLogger(__name__)
 
 
-def hilda(debugger, startup_files: Optional[List[str]] = None):
-    if lldb.hilda_client is None:
-        lldb.hilda_client = HildaClient(debugger)
-
-    additional_namespace = {'ui': lldb.hilda_client.ui_manager, 'cfg': lldb.hilda_client.configs}
-    lldb.hilda_client.interact(additional_namespace=additional_namespace, startup_files=startup_files)
-
-
 def execute(cmd: str) -> int:
     logging.debug(f'executing: {cmd}')
     return os.system(cmd)
@@ -49,10 +41,10 @@ class LLDBListenerThread(Thread, ABC):
     def _create_process(self) -> lldb.SBProcess:
         pass
 
-    def _check_success(self):
+    def _check_success(self) -> None:
         if self.error.Success():
             return
-        raise LLDBException(self.error.description)
+        raise LLDBError(self.error.description)
 
     def run(self):
         event = lldb.SBEvent()
@@ -67,12 +59,25 @@ class LLDBListenerThread(Thread, ABC):
                 logger.debug('Process Detached')
                 self.should_quit = True
             elif state == lldb.eStateExited:
-                logger.debug(f'Process Exited with status {self.process.GetExitStatus()}')
+                logger.info(f'Process Exited with status {self.process.GetExitStatus()}')
                 self.should_quit = True
             elif state == lldb.eStateRunning and last_state == lldb.eStateStopped:
-                logger.debug("Process Continued")
+                logger.debug('Process Continued')
             elif state == lldb.eStateStopped and last_state == lldb.eStateRunning:
                 logger.debug('Process Stopped')
+                for thread in self.process:
+                    frame = thread.GetFrameAtIndex(0)
+                    stop_reason = thread.GetStopReason()
+                    logger.debug(f'tid = {hex(thread.GetThreadID())} pc = {frame.GetPC()}')
+                    if stop_reason not in [lldb.eStopReasonSignal, lldb.eStopReasonException,
+                                           lldb.eStopReasonBreakpoint,
+                                           lldb.eStopReasonWatchpoint, lldb.eStopReasonPlanComplete,
+                                           lldb.eStopReasonTrace,
+                                           lldb.eStopReasonSignal]:
+                        continue
+                    self.process.SetSelectedThread(thread)
+                    break
+
             last_state = state
 
 
@@ -114,7 +119,7 @@ class LLDBAttachName(LLDBListenerThread):
         return self.debugger.CreateTargetWithFileAndArch(None, None)
 
     def _create_process(self) -> lldb.SBProcess:
-        logger.debug(f'Attaching to {self.name}')
+        logger.debug(f'Attaching to {self.proc_name}')
         return self.target.AttachToProcessWithName(self.listener, self.proc_name, self.wait_for, self.error)
 
 
@@ -148,42 +153,36 @@ class LLDBLaunch(LLDBListenerThread):
                                   self.error)
 
 
-def remote(hostname: str, port: int, startup_files: Optional[List[str]] = None) -> None:
-    """ Connect to remote process """
-    try:
-        lldb_t = LLDBRemote(hostname, port)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
-
-
-def attach(name: Optional[str] = None, pid: Optional[int] = None, wait_for: bool = False,
-           startup_files: Optional[List[str]] = None) -> None:
-    """ Attach to given process and start a lldb shell """
-    if (name is not None and pid is not None) or (name is None and pid is None):
-        raise ValueError('Provide either a process name or a PID, but not both.')
-
-    try:
-        if name is not None:
-            lldb_t = LLDBAttachName(name, wait_for)
-        else:
-            lldb_t = LLDBAttachPid(pid)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
-
-
-def launch(exec_path: str, argv: Optional[List] = None, envp: Optional[List] = None,
-           stdin: Optional[str] = None,
-           stdout: Optional[str] = None, stderr: Optional[str] = None, wd: Optional[str] = None,
-           flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False,
-           startup_files: Optional[List[str]] = None) -> None:
-    """ Launch to given process and start a lldb shell """
-    try:
-        lldb_t = LLDBLaunch(exec_path, argv, envp, stdin, stdout, stderr, wd, flags, stop_at_entry)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
+def _get_hilda_client_from_sbdebugger(debugger: lldb.SBDebugger) -> HildaClient:
+    hilda_client = HildaClient(debugger)
+    lldb.hilda_client = hilda_client
+    hilda_client.init_dynamic_environment()
+    return hilda_client
+
+
+def create_hilda_client_using_remote_attach(
+        hostname: str, port: int) -> HildaClient:
+    lldb_t = LLDBRemote(hostname, port)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_launch(
+        exec_path: str, argv: Optional[List] = None, envp: Optional[List] = None, stdin: Optional[str] = None,
+        stdout: Optional[str] = None, stderr: Optional[str] = None, wd: Optional[str] = None,
+        flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False) -> HildaClient:
+    lldb_t = LLDBLaunch(exec_path, argv, envp, stdin, stdout, stderr, wd, flags, stop_at_entry)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_attach_by_pid(pid: Optional[int] = None) -> HildaClient:
+    lldb_t = LLDBAttachPid(pid)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_attach_by_name(name: Optional[str] = None, wait_for: bool = False) -> HildaClient:
+    lldb_t = LLDBAttachName(name, wait_for)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)

{hilda-2.0.1.dist-info → hilda-2.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hilda
-Version: 2.0.1
+Version: 2.0.3
 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>
@@ -51,37 +51,32 @@ Requires-Dist: construct
 Requires-Dist: pymobiledevice3
 Requires-Dist: keystone-engine
 Requires-Dist: tabulate
+Requires-Dist: inquirer3
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 
-- [Description](#description)
-- [Installation](#installation)
-- [How to use](#how-to-use)
-    - [Starting a Hilda shell](#starting-a-hilda-shell)
-        - [Attach mode](#attach-mode)
-        - [Launch mode](#launch-mode)
-        - [Bare mode](#bare-mode)
-        - [Remote mode](#remote-mode)
-            - [The connected device is connected via network](#the-connected-device-is-connected-via-network)
-        - [Startup Files](#startup-files)
-    - [Usage](#usage)
-    - [Magic functions](#magic-functions)
-    - [Shortcuts](#shortcuts)
-    - [Configurables](#configurables)
-        - [Attributes](#attributes)
-        - [Example Usage](#example-usage)
-    - [UI Configuration](#ui-configuration)
-    - [Symbol objects](#symbol-objects)
-    - [Globalized symbols](#globalized-symbols)
-        - [Searching for the right symbol](#searching-for-the-right-symbol)
-        - [Objective-C Classes](#objective-c-classes)
-    - [Objective-C Objects](#objective-c-objects)
-    - [Using snippets](#using-snippets)
-- [Contributing](#contributing)
-
-Would you like any further adjustments?
-
-# Description
+# Hilda
+
+- [Hilda](#hilda)
+  - [Overview](#overview)
+  - [Installation](#installation)
+  - [How to use](#how-to-use)
+    - [Starting a Hilda interactive shell](#starting-a-hilda-interactive-shell)
+    - [Inside a Hilda shell](#inside-a-hilda-shell)
+      - [Magic functions](#magic-functions)
+      - [Key-bindings](#key-bindings)
+      - [Configurables](#configurables)
+      - [UI Configuration](#ui-configuration)
+    - [Python API](#python-api)
+      - [Symbol objects](#symbol-objects)
+      - [Globalized symbols](#globalized-symbols)
+      - [Searching for the right symbol](#searching-for-the-right-symbol)
+      - [Objective-C Classes](#objective-c-classes)
+      - [Objective-C Objects](#objective-c-objects)
+      - [Using snippets](#using-snippets)
+  - [Contributing](#contributing)
+
+## Overview
 
 Hilda is a debugger which combines both the power of LLDB and iPython for easier debugging.
 
@@ -93,8 +88,8 @@ 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:
 
-* Linux
-* Android
+- Linux
+- Android
 
 Since LLDB allows abstraction for both platform and architecture, it should be possible to make the necessary changes
 without too many modifications.
@@ -104,14 +99,14 @@ 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 💬](https://github.com/doronz88/hilda/discussions).
 
-# Installation
+## Installation
 
 Requirements for remote iOS device (not required for debugging a local OSX process):
 
-* Jailbroken iOS device
-* `debugserver` in device's PATH
-    * [You can use this tool in order to obtain the binary](https://github.com/doronz88/debugserver-deploy)
-    * After re-signing with new entitlements, you can put the binary in the following path: `/usr/bin/debugserver`
+- Jailbroken iOS device
+- `debugserver` in device's PATH
+  - [You can use this tool in order to obtain the binary](https://github.com/doronz88/debugserver-deploy)
+  - After re-signing with new entitlements, you can put the binary in the following path: `/usr/bin/debugserver`
 
 In order to install please run:
 
@@ -121,104 +116,40 @@ 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
+## How to use
 
-## Starting a Hilda shell
+### Starting a Hilda interactive shell
 
-### Attach mode
+You can may start a Hilda interactive shell by invoking any of the subcommand:
 
-Use the attach sub-command in order to start an LLDB shell attached to given process.
+- `hilda launch /path/to/executable`
+  - Launch given executable on current host
+- `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`)
+- `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:
 
-```shell
-hilda attach [-p pid] [-n process-name]
-```
-
-### Launch mode
-
-Use the attach sub-command in order to launch given process.
-
-```shell
-hilda launch /path/to/executable \
-    --argv arg1 --argv arg2 \
-    --envp NAME=Alice --envp AGE=30 \
-    --stdin /path/to/input.txt \
-    --stdout /path/to/output.txt \
-    --stderr /path/to/error.txt \
-    --wd /path/to/working/directory \
-    --flags 0x01 \
-    --stop-at-entry
-  ```
-
-### 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:
-
-```shell
-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](https://lldb.llvm.org/use/map.html).
-
-As a cheatsheet, connecting to a remote platform like so:
-
-```shell
-platform connect connect://ip:port
-```
-
-... and attaching to a local process:
-
-```shell
-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).
+    [lldb command map](https://lldb.llvm.org/use/map.html).
 
-From this point the flow diverges into 2 flows:
+    As a cheatsheet, connecting to a remote platform like so:
 
-### The connected device is connected via network
+    ```shell
+    platform connect connect://ip:port
+    ```
 
-Run the following command:
+    ... and attaching to a local process:
 
-```shell
-hilda remote HOSTNAME PORT
-``` 
-
-## Startup Files
-
-Each command can accept startup files to execute on start. As opposed to snippets, the startup files can accept Hilda
-syntax.
-
-#### Startup File Example
-
-```python
-cfg.objc_verbose_monitor = True
-p.bp(ADDRESS)
-p.cont()
-```
+    ```shell
+    process attach -n proccess_name
+    process attach -p proccess_pid
+    ```
 
-```shell
-hilda remote HOSTNAME PORT -f startupfile1 -f startupfile2
-```
+    When you are ready, just execute `hilda` to move to Hilda's iPython shell.
 
-## Usage
+### Inside a Hilda shell
 
 Upon starting Hilda shell, you are greeted with:
 
@@ -231,52 +162,53 @@ 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
+  - Print an hexdump of given buffer
 - `lsof`
-    - Get dictionary of all open FDs
+  - Get dictionary of all open FDs
 - `bt`
-    - Print an improved backtrace.
+  - Print an improved backtrace.
 - `disable_jetsam_memory_checks`
-    - Disable jetsam memory checks, prevent raising:
+  - 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
+  - Get symbol object for a given address
 - `objc_symbol`
-    - Get objc symbol wrapper for given address
+  - Get objc symbol wrapper for given address
 - `inject`
-    - Inject a single library into currently running process
+  - Inject a single library into currently running process
 - `rebind_symbols`
-    - Reparse all loaded images symbols
+  - Reparse all loaded images symbols
 - `poke`
-    - Write data at given address
+  - Write data at given address
 - `peek`
-    - Read data at given address
+  - Read data at given address
 - `peek_str`
-    - Peek a buffer till null termination
+  - Peek a buffer till null termination
 - `stop`
-    - Stop process.
+  - Stop process.
 - `cont`
-    - Continue process.
+  - Continue process.
 - `detach`
-    - Detach from process.
+  - 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
+  - Print disassembly from a given address
 - `file_symbol`
-    - Calculate symbol address without ASLR
+  - Calculate symbol address without ASLR
 - `get_register`
-    - Get value for register by its name
+  - Get value for register by its name
 - `set_register`
-    - Set value for register by its name
+  - Set value for register by its name
 - `objc_call`
-    - Simulate a call to an objc selector
+  - Simulate a call to an objc selector
 - `call`
-    - Call function at given address with given parameters
+  - Call function at given address with given parameters
 - `monitor`
-    - Monitor every time a given address is called
+  - Monitor every time a given address is called
       The following options are available:
+
       ```
       regs={reg1: format}
       will print register values
@@ -308,58 +240,57 @@ Here is a gist of methods you can access from `p`:
            override=True
                override previous break point at same location
       ```
+
 - `show_current_source`
-    - print current source code if possible
+  - print current source code if possible
 - `finish`
-    - Run current frame till its end.
+  - Run current frame till its end.
 - `step_into`
-    - Step into current instruction.
+  - Step into current instruction.
 - `step_over`
-    - Step over current instruction.
+  - Step over current instruction.
 - `remove_all_hilda_breakpoints`
-    - Remove all breakpoints created by Hilda
+  - Remove all breakpoints created by Hilda
 - `remove_hilda_breakpoint`
-    - Remove a single breakpoint placed by Hilda
+  - Remove a single breakpoint placed by Hilda
 - `force_return`
-    - Prematurely return from a stack frame, short-circuiting exection of newer frames and optionally
+  - 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 information about currently running mapped process.
 - `print_proc_entitlements`
-    - Get the plist embedded inside the process' __LINKEDIT section.
+  - Get the plist embedded inside the process' __LINKEDIT section.
 - `bp`
-    - Add a breakpoint
+  - Add a breakpoint
 - `show_hilda_breakpoints`
-    - Show existing breakpoints created by Hilda.
-- `show_commands`
-    - Show available commands.
+  - Show existing breakpoints created by Hilda.
 - `save`
-    - Save loaded symbols map (for loading later using the load() command)
+  - Save loaded symbols map (for loading later using the load() command)
 - `load`
-    - Load an existing symbols map (previously saved by the save() command)
+  - Load an existing symbols map (previously saved by the save() command)
 - `po`
-    - Print given object using LLDB's po command
+  - 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
+  - Make all symbols in python's global scope
 - `jump`
-    - jump to given symbol
+  - jump to given symbol
 - `lldb_handle_command`
-    - Execute an LLDB command
+  - Execute an LLDB command
       For example:
       lldb_handle_command('register read')
 - `objc_get_class`
-    - Get ObjC class object
+  - Get ObjC class object
 - `CFSTR`
-    - Create CFStringRef object from given string
+  - Create CFStringRef object from given string
 - `ns`
-    - Create NSObject from given data
+  - Create NSObject from given data
 - `from_ns`
-    - Create python object from NS object.
+  - Create python object from NS object.
 - `evaluate_expression`
-    - Wrapper for LLDB's EvaluateExpression.
+  - Wrapper for LLDB's EvaluateExpression.
       Used for quick code snippets.
 
       Feel free to use local variables inside the expression using format string.
@@ -367,31 +298,37 @@ Here is a gist of methods you can access from `p`:
       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)
+  - Import & reload given python module (intended mainly for external snippets)
 - `unwind`
-    - Unwind the stack (useful when get_evaluation_unwind() == False)
+  - 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.
 
-## Magic functions
+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)
 
-Sometimes accessing the python API can be tiring, so we added some magic functions to help you out!
+#### Magic functions
+
+Sometimes accessing the [Python API](#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)`
+  - Equivalent to: `className = p.objc_get_class(className)`
 - `%fbp <filename> <addressInHex>`
-    - Equivalent to: `p.file_symbol(addressInHex, filename).bp()`
+  - Equivalent to: `p.file_symbol(addressInHex, filename).bp()`
 
-## Shortcuts
+#### Key-bindings
 
 - **F7**: Step Into
 - **F8**: Step Over
 - **F9**: Continue
 - **F10**: Stop
 
-## Configurables
+#### Configurables
 
 The global `cfg` used to configure various settings for evaluation and monitoring.
 
-### Attributes
+These settings include:
 
 - `evaluation_unwind_on_error`: Whether to unwind on error during evaluation. (Default: `False`)
 - `evaluation_ignore_breakpoints`: Whether to ignore breakpoints during evaluation. (Default: `False`)
@@ -400,15 +337,9 @@ The global `cfg` used to configure various settings for evaluation and monitorin
 - `objc_verbose_monitor`: When set to `True`, using `monitor()` will automatically print Objective-C method arguments. (
   Default: `False`)
 
-### Example Usage
+#### UI Configuration
 
-```python
-cfg.objc_verbose_monitor = True
-```
-
-## UI Configuration
-
-Hilda contains minimal UI for examining the target state.
+Hilda contains a minimal UI for examining the target state.
 The UI is divided into views:
 
 - Registers
@@ -465,7 +396,31 @@ ui.colors.address = 'red'
 ui.color.title = 'green'
 ```
 
-## Symbol objects
+### Python API
+
+Hilda provides a comprehensive API wrappers to access LLDB capabilities.
+This API may be used to access process memory, trigger functions, place breakpoints and much more!
+
+Also, in addition to access this API using the [Hilda shell](#inside-a-hilda-shell), you may also use pure-python script using any of the `create_hilda_client_using_*` APIs.
+
+Consider the following snippet as an example of such usage:
+
+```python
+from hilda.launch_lldb import create_hilda_client_using_attach_by_name
+
+# attach to `sysmond`
+p = create_hilda_client_using_attach_by_name('sysmond')
+
+# allocate 10 bytes and print their address
+print(p.symbols.malloc(10))
+
+# detach
+p.detach()
+```
+
+Please note this script must be executed using `xcrun python3` in order for it to be able to access LLDB API.
+
+#### 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.
@@ -572,7 +527,7 @@ p.bp('symbol_name')
 p.bp('symbol_name', module_name='ModuleName')
 ```
 
-## Globalized symbols
+#### 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
@@ -617,7 +572,7 @@ jar = jar.code()
 jar.monitor(regs={'x0': 'x'}, bt=True)
 ```
 
-### Objective-C Classes
+#### Objective-C Classes
 
 The same as symbols applies to Objective-C classes name resolution. You can either:
 
@@ -670,7 +625,7 @@ dictionary = NSDictionary.capture_self(True)
 dictionary.show()
 ```
 
-## Objective-C Objects
+#### 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:
@@ -736,7 +691,7 @@ abc_string = p.evaluate_expression('[NSString stringWithFormat:@"abc"]')
 print(abc_string.po())
 ```
 
-## Using snippets
+#### Using snippets
 
 Snippets are extensions for normal functionality used as quick cookbooks for day-to-day tasks of a debugger.
 

{hilda-2.0.1.dist-info → hilda-2.0.3.dist-info}/RECORD

@@ -3,13 +3,13 @@ gifs/ui.png,sha256=iaRwNZ9qVWUkUe2TJb_6VPsTu--7HrElA2duWiyZ-Oc,131
 gifs/xpc_print_message.gif,sha256=i5S8Y9bJm9n-NtOipFTAC8_jUR4uZCM4sOap_ccJX0k,939935
 hilda/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hilda/__main__.py,sha256=KWRqvukK4wraxCMtvH5nO25mFXLO5aWXa7z_VfAtbO8,90
-hilda/_version.py,sha256=llBMh-GtSPemevJ46pFdqzJYvqrJ0mS-b_e99BsAPEQ,411
-hilda/cli.py,sha256=0keoM7FLQXiF-J65ftRUtLnYtyyRpGez6xNZ3tZIXZA,3329
-hilda/common.py,sha256=fxlVTyRP2AmKCnE6FdgnGJVoG-OBq7Tw6TrBQ_xgszI,194
-hilda/exceptions.py,sha256=spH9i27nLm71-SR5Nb028cBVD81qAS6qRfoC2XVoGls,2014
+hilda/_version.py,sha256=nHByjT85Mzor0VestVUVI70fkRS763utSt6toCJI-NY,411
+hilda/cli.py,sha256=jAM31J2aaXAyiEmMFRiRP3FjvQylt390SsFQJGhqfDo,3760
+hilda/common.py,sha256=VFtpOH9IRqbu6lONM6Hz-PxcdJfktgS3akJv5UCHO0s,523
+hilda/exceptions.py,sha256=8L1OvOqns4O4ieiH4YlrMbZkk_PvuyCq4UyqFAodkF8,2042
 hilda/hilda_ascii_art.html,sha256=-9YCjAKdGbjtdd6uoKrxkkcJq7j16r4dGka2bZ27b4o,120119
-hilda/hilda_client.py,sha256=TksJu9vdukY5cZQQh0qrY-siwXU3gVYkvEIaMBqQeAs,43486
-hilda/launch_lldb.py,sha256=SIBv-uGbp1mgJU96H9gBNU5ahiTwzRwpCiR5RGJ1xVE,7149
+hilda/hilda_client.py,sha256=4wY1syGiVV_LGyXRNch2QZi7Zi1VEi6OrMjbLHzZ3eQ,45274
+hilda/launch_lldb.py,sha256=tFSJK9dry1Z12lE5OSbDX53aJ23TO1XFElHo85qxeVo,7336
 hilda/lldb_entrypoint.py,sha256=vTiClzfiTtjorlxEfIsI-W657KEGobx74qDhaZ8nPhM,1007
 hilda/lldb_importer.py,sha256=LrIQnigDG3wgmIPXya67oBlWubkDgV-rEpzfWNEYCoc,553
 hilda/objective_c_class.py,sha256=Xyw7FucNVcu8NqhB0Gy-OjaN_2DmCywn6pjUEwyd1Hk,11760
@@ -46,9 +46,9 @@ hilda/snippets/macho/macho_load_commands.py,sha256=OsajG2xWuRwhYhj9f-lnUiNe43Yum
 hilda/ui/colors.json,sha256=f-ITquY3IInQreviTy23JfmxfJrGM1_MivACf1GKGqM,262
 hilda/ui/ui_manager.py,sha256=BmzI1sBx0PYCQDlB9Al7wsTEAMJxaJ7NW0DS4C7g5-0,2265
 hilda/ui/views.py,sha256=1u_eZzw7wAEP1bm_-9nkqgGhMSX__woiUuoBgnsAKVM,7843
-hilda-2.0.1.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
-hilda-2.0.1.dist-info/METADATA,sha256=BExnYkqJD8IDK4klLR0g5GXN209FCxll3B-G6oMBl60,23606
-hilda-2.0.1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-hilda-2.0.1.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
-hilda-2.0.1.dist-info/top_level.txt,sha256=TVD7l1WkE1noT866YqPFhiQnjYCYZM5Xz54v_3EYpnI,11
-hilda-2.0.1.dist-info/RECORD,,
+hilda-2.0.3.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
+hilda-2.0.3.dist-info/METADATA,sha256=7eMn09PoasA7uQIPpQWsAbJtNUzuJqanUYlioQvWdgs,23306
+hilda-2.0.3.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+hilda-2.0.3.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
+hilda-2.0.3.dist-info/top_level.txt,sha256=TVD7l1WkE1noT866YqPFhiQnjYCYZM5Xz54v_3EYpnI,11
+hilda-2.0.3.dist-info/RECORD,,