hilda 1.4.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

hilda/__main__.py

@@ -1,5 +1,9 @@
-from hilda.launch_lldb import cli
+from hilda.cli import cli
 
 
 def main():
     cli()
+
+
+if __name__ == '__main__':
+    main()

hilda/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.4.2'
-__version_tuple__ = version_tuple = (1, 4, 2)
+__version__ = version = '2.0.0'
+__version_tuple__ = version_tuple = (2, 0, 0)

hilda/cli.py

@@ -0,0 +1,89 @@
+import logging
+from pathlib import Path
+from typing import List, Mapping, Optional
+
+import click
+import coloredlogs
+
+from hilda import launch_lldb
+from hilda._version import version
+
+DEFAULT_HILDA_PORT = 1234
+
+coloredlogs.install(level=logging.DEBUG)
+
+
+@click.group()
+def cli():
+    pass
+
+
+startup_files_option = click.option('-f', '--startup_files', multiple=True, default=None, help='Files to run on start')
+
+
+def parse_envp(ctx: click.Context, param: click.Parameter, value: List[str]) -> List[str]:
+    env_list = []
+    for item in value:
+        try:
+            key, val = item.split('=', 1)
+            env_list.append(f'{key}={val}')
+        except ValueError:
+            raise click.BadParameter(f'Invalid format for --envp: {item}. Expected KEY=VALUE.')
+    return env_list
+
+
+@cli.command('remote')
+@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:
+    """ Connect to remote debugserver at given address """
+    launch_lldb.remote(hostname, port, 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:
+    """ Attach to given process and start a lldb shell """
+    launch_lldb.attach(name=name, pid=pid, startup_files=startup_files)
+
+
+@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('--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:
+    """ 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}"')
+
+
+@cli.command('version')
+def cli_version():
+    """Show the version information."""
+    click.echo(version)

hilda/exceptions.py

@@ -1,7 +1,7 @@
 __all__ = ['HildaException', 'SymbolAbsentError', 'EvaluatingExpressionError', 'CreatingObjectiveCSymbolError',
            'ConvertingToNsObjectError', 'ConvertingFromNSObjectError', 'DisableJetsamMemoryChecksError',
            'GettingObjectiveCClassError', 'AccessingRegisterError', 'AccessingMemoryError',
-           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError']
+           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBException']
 
 
 class HildaException(Exception):
@@ -9,6 +9,14 @@ class HildaException(Exception):
     pass
 
 
+class LLDBException(Exception):
+    """ A domain exception for lldb errors. """
+
+    def __init__(self, message: str):
+        super().__init__()
+        self.message = message
+
+
 class SymbolAbsentError(HildaException):
     """ Raise when trying to get a symbol that doesn't exist. """
     pass

hilda/hilda_client.py

@@ -1,4 +1,3 @@
-import ast
 import base64
 import builtins
 import importlib
@@ -8,18 +7,19 @@ import logging
 import os
 import pickle
 import struct
+import sys
 import time
 import typing
 from collections import namedtuple
 from contextlib import contextmanager, suppress
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from functools import cached_property
+from functools import cached_property, wraps
 from pathlib import Path
 from typing import Any, Callable, List, Optional, Union
 
 import hexdump
 import IPython
-import lldb
 from humanfriendly import prompts
 from humanfriendly.terminal.html import html_to_ansi
 from IPython.core.magic import register_line_magic  # noqa: F401
@@ -34,7 +34,7 @@ from hilda.common import CfSerializable
 from hilda.exceptions import AccessingMemoryError, AccessingRegisterError, AddingLldbSymbolError, \
     BrokenLocalSymbolsJarError, ConvertingFromNSObjectError, ConvertingToNsObjectError, CreatingObjectiveCSymbolError, \
     DisableJetsamMemoryChecksError, EvaluatingExpressionError, HildaException, SymbolAbsentError
-from hilda.launch_lldb import disable_logs  # noqa: F401
+from hilda.lldb_importer import lldb
 from hilda.objective_c_symbol import ObjectiveCSymbol
 from hilda.registers import Registers
 from hilda.snippets.mach import CFRunLoopServiceMachPort_hooks
@@ -49,48 +49,77 @@ except ImportError:
     lldb.KEYSTONE_SUPPORT = False
     print('failed to import keystone. disabling some features')
 
-with open(os.path.join(Path(__file__).resolve().parent, 'hilda_ascii_art.html'), 'r') as f:
-    hilda_art = f.read()
+hilda_art = Path(__file__).resolve().parent.joinpath('hilda_ascii_art.html').read_text()
 
 GREETING = f"""
 {hilda_art}
 
 <b>Hilda has been successfully loaded! 😎
-Use the <span style="color: magenta">p</span> global to access all features.
+Usage:
+ <span style="color: magenta">p</span>   Global to access all features.
+ <span style="color: magenta">F7</span>  Step Into.
+ <span style="color: magenta">F8</span>  Step Over.
+ <span style="color: magenta">F9</span>  Continue.
+ <span style="color: magenta">F10</span> Stop.
+
 Have a nice flight ✈️! Starting an IPython shell...
 """
 
-MAGIC_FUNCTIONS = """
-import shlex
-from IPython.core.magic import register_line_magic, needs_local_scope
-
-@register_line_magic
-@needs_local_scope
-def objc(line, local_ns=None):
-    p = local_ns['p']
-    className = line.strip()
-    if not className:
-        p.log_error("Error: className is required.")
-        return
-    try:
-        local_ns[className] = p.objc_get_class(className)
-        p.log_info(f'{className} class loaded successfully')
-    except Exception:
-        p.log_error(f'Error loading class {className}')
-
-
-@register_line_magic
-@needs_local_scope
-def fbp(line, local_ns=None):
-    p = local_ns['p']
-    module_name, address = shlex.split(line.strip())
-    address = int(address, 16)
-    p.file_symbol(address, module_name).bp()
-"""
+
+def disable_logs() -> None:
+    logging.getLogger('asyncio').disabled = True
+    logging.getLogger('parso.cache').disabled = True
+    logging.getLogger('parso.cache.pickle').disabled = True
+    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
+
 
 SerializableSymbol = namedtuple('SerializableSymbol', 'address type_ filename')
 
 
+@dataclass
+class Configs:
+    """ Configuration settings for evaluation and monitoring. """
+    evaluation_unwind_on_error: bool = field(default=False,
+                                             metadata={'doc': 'Whether to unwind on error during evaluation.'})
+    evaluation_ignore_breakpoints: bool = field(default=False,
+                                                metadata={'doc': 'Whether to ignore breakpoints during evaluation.'})
+    nsobject_exclusion: bool = field(default=False, metadata={
+        'doc': 'Whether to exclude NSObject during evaluation - reduce ipython autocomplete results.'})
+    objc_verbose_monitor: bool = field(default=False, metadata={
+        'doc': 'When set to True, using monitor() will automatically print objc methods arguments.'})
+
+    def __repr__(self):
+        return self.__str__()
+
+    def __str__(self):
+        config_str = 'Configuration settings:\n'
+        max_len = max(len(field_name) for field_name in self.__dataclass_fields__) + 2
+
+        for field_name, field_info in self.__dataclass_fields__.items():
+            value = getattr(self, field_name)
+            doc = field_info.metadata.get('doc', 'No docstring available')
+            config_str += f'\t{field_name.ljust(max_len)}: {str(value).ljust(5)} | {doc}\n'
+
+        return config_str
+
+
+def stop_is_needed(func: Callable):
+    """Decorator to check if the process must be stopped before proceeding."""
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        is_running = self.process.GetState() == lldb.eStateRunning
+        if is_running:
+            self.logger.error(f'Cannot {func.__name__.replace("_", "-")}: Process must be stopped first.')
+            return
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
 class HildaClient:
     Breakpoint = namedtuple('Breakpoint', 'address options forced callback')
 
@@ -108,13 +137,7 @@ class HildaClient:
         self.registers = Registers(self)
         self.arch = self.target.GetTriple().split('-')[0]
         self.ui_manager = UiManager(self)
-        # should unwind the stack on errors. change this to False in order to debug self-made calls
-        # within hilda
-        self._evaluation_unwind_on_error = True
-
-        # should ignore breakpoints while evaluation
-        self._evaluation_ignore_breakpoints = True
-
+        self.configs = Configs()
         self._dynamic_env_loaded = False
         self._symbols_loaded = False
 
@@ -144,7 +167,7 @@ class HildaClient:
         # convert FDs into int
         return {int(k): v for k, v in result.items()}
 
-    def bt(self, should_print=True, depth: Optional[int] = None) -> List:
+    def bt(self, should_print: bool = False, depth: Optional[int] = None) -> List[Union[str, lldb.SBFrame]]:
         """ Print an improved backtrace. """
         backtrace = []
         for i, frame in enumerate(self.thread.frames):
@@ -251,6 +274,7 @@ class HildaClient:
         globals()['symbols'] = self.symbols
         self._symbols_loaded = True
 
+    @stop_is_needed
     def poke(self, address, buf: bytes):
         """
         Write data at given address
@@ -265,6 +289,7 @@ class HildaClient:
 
         return retval
 
+    @stop_is_needed
     def poke_text(self, address: int, code: str) -> int:
         """
         Write instructions to address.
@@ -276,6 +301,7 @@ class HildaClient:
         bytecode, count = self._ks.asm(code, as_bytes=True)
         return self.poke(address, bytecode)
 
+    @stop_is_needed
     def peek(self, address, size: int) -> bytes:
         """
         Read data at given address
@@ -294,6 +320,7 @@ class HildaClient:
 
         return retval
 
+    @stop_is_needed
     def peek_str(self, address: Symbol) -> str:
         """
         Peek a buffer till null termination
@@ -302,7 +329,7 @@ class HildaClient:
         """
         return address.po('char *')[1:-1]  # strip the ""
 
-    def stop(self):
+    def stop(self, *args) -> None:
         """ Stop process. """
         self.debugger.SetAsync(False)
 
@@ -313,8 +340,10 @@ class HildaClient:
 
         if not self.process.Stop().Success():
             self.log_critical('failed to stop process')
+        else:
+            self.log_info('Process Stopped')
 
-    def cont(self):
+    def cont(self, *args) -> None:
         """ Continue process. """
         is_running = self.process.GetState() == lldb.eStateRunning
 
@@ -328,6 +357,8 @@ class HildaClient:
 
         if not self.process.Continue().Success():
             self.log_critical('failed to continue process')
+        else:
+            self.log_info('Process Continued')
 
     def detach(self):
         """
@@ -338,8 +369,12 @@ class HildaClient:
         """
         if not self.process.Detach().Success():
             self.log_critical('failed to detach')
+        else:
+            self.log_info('Process Detached')
 
-    def disass(self, address, buf, flavor='intel', should_print=True) -> lldb.SBInstructionList:
+    @stop_is_needed
+    def disass(self, address: int, buf: bytes, flavor: str = 'intel',
+               should_print: bool = False) -> lldb.SBInstructionList:
         """
         Print disassembly from a given address
         :param flavor:
@@ -528,14 +563,16 @@ class HildaClient:
             self.thread.StepOutOfFrame(self.frame)
             self._bp_frame = None
 
-    def step_into(self):
+    @stop_is_needed
+    def step_into(self, *args):
         """ Step into current instruction. """
         with self.sync_mode():
             self.thread.StepInto()
         if self.ui_manager.active:
             self.ui_manager.show()
 
-    def step_over(self):
+    @stop_is_needed
+    def step_over(self, *args):
         """ Step over current instruction. """
         with self.sync_mode():
             self.thread.StepOver()
@@ -821,9 +858,9 @@ class HildaClient:
             formatted_expression = str(expression)
 
         options = lldb.SBExpressionOptions()
-        options.SetIgnoreBreakpoints(self._evaluation_ignore_breakpoints)
+        options.SetIgnoreBreakpoints(self.configs.evaluation_ignore_breakpoints)
         options.SetTryAllThreads(True)
-        options.SetUnwindOnError(self._evaluation_unwind_on_error)
+        options.SetUnwindOnError(self.configs.evaluation_unwind_on_error)
 
         e = self.frame.EvaluateExpression(formatted_expression, options)
 
@@ -847,35 +884,6 @@ class HildaClient:
         spec.loader.exec_module(m)
         return m
 
-    def set_evaluation_unwind(self, value: bool):
-        """
-        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.
-        """
-        self._evaluation_unwind_on_error = value
-
-    def get_evaluation_unwind(self) -> bool:
-        """
-        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.
-        """
-        return self._evaluation_unwind_on_error
-
-    def set_evaluation_ignore_breakpoints(self, value: bool):
-        """
-        Set whether to ignore breakpoints while evaluating expressions
-        """
-        self._evaluation_ignore_breakpoints = value
-
-    def get_evaluation_ignore_breakpoints(self) -> bool:
-        """
-        Get evaluation "ignore-breakpoints" state.
-        """
-        return self._evaluation_ignore_breakpoints
-
     def unwind(self) -> bool:
         """ Unwind the stack (useful when get_evaluation_unwind() == False) """
         return self.thread.UnwindInnermostExpression().Success()
@@ -1016,28 +1024,32 @@ class HildaClient:
 
         return value
 
-    def interact(self, additional_namespace: typing.Mapping = None) -> None:
+    def interact(self, additional_namespace: Optional[typing.Mapping] = None,
+                 startup_files: Optional[List[str]] = None) -> None:
         """ Start an interactive Hilda shell """
         if not self._dynamic_env_loaded:
             self.init_dynamic_environment()
         print('\n')
         self.log_info(html_to_ansi(GREETING))
+        ipython_config = Config()
+        ipython_config.IPCompleter.use_jedi = True
+        ipython_config.BaseIPythonApplication.profile = 'hilda'
+        ipython_config.InteractiveShellApp.extensions = ['hilda.ipython_extensions.magics',
+                                                         'hilda.ipython_extensions.events',
+                                                         'hilda.ipython_extensions.keybindings']
+        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}')
 
-        config = Config()
-        config.IPCompleter.use_jedi = True
-        config.InteractiveShellApp.exec_lines = [
-            """disable_logs()""",
-            """IPython.get_ipython().events.register('pre_run_cell', self._ipython_run_cell_hook)""",
-            MAGIC_FUNCTIONS,
-        ]
-        config.BaseIPythonApplication.profile = 'hilda'
         namespace = globals()
         namespace.update(locals())
         namespace['p'] = self
         if additional_namespace is not None:
             namespace.update(additional_namespace)
-
-        IPython.start_ipython(config=config, user_ns=namespace)
+        sys.argv = ['a']
+        IPython.start_ipython(config=ipython_config, user_ns=namespace)
+        self.detach()
 
     @staticmethod
     def _add_global(name: str, value: Any, reserved_names=None):
@@ -1108,35 +1120,6 @@ class HildaClient:
 
         return f'((intptr_t(*)({args_type}))({address}))({args_conv})'
 
-    def _ipython_run_cell_hook(self, info):
-        """
-        Enable lazy loading for symbols
-        :param info: IPython's CellInfo object
-        """
-        if info.raw_cell[0] in ['!', '%'] or info.raw_cell.endswith('?'):
-            return
-
-        for node in ast.walk(ast.parse(info.raw_cell)):
-            if not isinstance(node, ast.Name):
-                # we are only interested in names
-                continue
-
-            if node.id in locals() or node.id in globals() or node.id in dir(builtins):
-                # That are undefined
-                continue
-
-            if not hasattr(SymbolsJar, node.id):
-                # ignore SymbolsJar properties
-                try:
-                    symbol = getattr(self.symbols, node.id)
-                except SymbolAbsentError:
-                    pass
-                else:
-                    self._add_global(
-                        node.id,
-                        symbol if symbol.type_ != lldb.eSymbolTypeObjCMetaClass else self.objc_get_class(node.id)
-                    )
-
     @staticmethod
     def _std_string(value):
         if struct.unpack("b", (value + 23).peek(1))[0] >= 0:

hilda/ipython_extensions/events.py

@@ -0,0 +1,53 @@
+import ast
+import builtins
+
+from IPython.terminal.interactiveshell import TerminalInteractiveShell
+
+from hilda.exceptions import EvaluatingExpressionError, SymbolAbsentError
+from hilda.hilda_client import HildaClient
+from hilda.lldb_importer import lldb
+from hilda.symbols_jar import SymbolsJar
+
+
+class HIEvents:
+    def __init__(self, ip: TerminalInteractiveShell):
+        self.shell = ip
+        self.hilda_client: HildaClient = self.shell.user_ns['p']
+
+    def pre_run_cell(self, info):
+        """
+        Enable lazy loading for symbols
+        :param info: IPython's CellInfo object
+        """
+        if info.raw_cell[0] in ['!', '%'] or info.raw_cell.endswith('?'):
+            return
+        for node in ast.walk(ast.parse(info.raw_cell)):
+            if not isinstance(node, ast.Name):
+                # we are only interested in names
+                continue
+
+            if node.id in locals() or node.id in globals() or node.id in dir(builtins):
+                # That are undefined
+                continue
+
+            if not hasattr(SymbolsJar, node.id):
+                # ignore SymbolsJar properties
+                try:
+                    symbol = getattr(self.hilda_client.symbols, node.id)
+                except SymbolAbsentError:
+                    pass
+                else:
+                    try:
+                        self.hilda_client._add_global(
+                            node.id,
+                            symbol if symbol.type_ != lldb.eSymbolTypeObjCMetaClass else self.hilda_client.objc_get_class(
+                                node.id)
+                        )
+                    except EvaluatingExpressionError:
+                        self.hilda_client.log_warning(
+                            f'Process is running. Pause execution in order to resolve "{node.id}"')
+
+
+def load_ipython_extension(ip: TerminalInteractiveShell):
+    hie = HIEvents(ip)
+    ip.events.register('pre_run_cell', hie.pre_run_cell)

hilda/ipython_extensions/keybindings.py

@@ -0,0 +1,22 @@
+from prompt_toolkit.enums import DEFAULT_BUFFER
+from prompt_toolkit.filters import EmacsInsertMode, HasFocus, HasSelection, ViInsertMode
+from prompt_toolkit.keys import Keys
+
+
+def load_ipython_extension(ipython):
+    def register_keybindings():
+        hilda = ipython.user_ns['p']
+        keys_mapping = {Keys.F7: hilda.step_into,
+                        Keys.F8: hilda.step_over,
+                        Keys.F9: hilda.cont,
+                        Keys.F10: hilda.stop}
+
+        insert_mode = ViInsertMode() | EmacsInsertMode()
+        registry = ipython.pt_app.key_bindings
+
+        for key, callback in keys_mapping.items():
+            registry.add_binding(key, filter=(HasFocus(DEFAULT_BUFFER) & ~HasSelection() & insert_mode))(
+                callback)
+
+    register_keybindings()
+    ipython.events.register('shell_initialized', register_keybindings)

hilda/ipython_extensions/magics.py

@@ -0,0 +1,40 @@
+import shlex
+
+from IPython.core.magic import Magics, line_magic, magics_class, needs_local_scope
+
+
+@magics_class
+class HIMagics(Magics):
+
+    @line_magic
+    @needs_local_scope
+    def objc(self, line, local_ns=None):
+        """Load an Objective-C class by name into the IPython session."""
+        p = local_ns.get('p')
+        class_name = line.strip()
+        if not class_name:
+            p.log_error("Error: className is required.")
+            return
+        try:
+            local_ns[class_name] = p.objc_get_class(class_name)
+            p.log_info(f'{class_name} class loaded successfully')
+        except Exception as e:
+            p.log_error(f'Error loading class {class_name}: {str(e)}')
+
+    @line_magic
+    @needs_local_scope
+    def fbp(self, line, local_ns=None):
+        """Set a file breakpoint in the debugger."""
+        p = local_ns.get('p')
+        try:
+            module_name, address = shlex.split(line.strip())
+            address = int(address, 16)
+            p.file_symbol(address, module_name).bp()
+        except ValueError as ve:
+            p.log_error(f"Error parsing arguments: {str(ve)}")
+        except Exception as e:
+            p.log_error(f"Error setting breakpoint: {str(e)}")
+
+
+def load_ipython_extension(ipython):
+    ipython.register_magics(HIMagics)