libdebug · Frank01001 · Nov 1, 2024 · Nov 2, 2024 · Feb 15, 2025 · Feb 15, 2025
diff --git a/docs/assets/ace_dark.png b/docs/assets/ace_dark.png
diff --git a/docs/assets/ace_light.png b/docs/assets/ace_light.png
diff --git a/docs/logging/liblog.md b/docs/logging/liblog.md
@@ -28,7 +28,7 @@ The `debugger` option displays all logs related to the debugging operations perf
 ### :material-pipe: Pipe Logging
 The `pipe` option, on the other hand, displays all logs related to interactions with the process pipe: bytes received and bytes sent.
 
-<img src="/assets/pipe_logging.jpeg" alt="pipe argv option" />
+<img src="../../assets/pipe_logging.jpeg" alt="pipe argv option" />
 
 ### :material-vector-union: The best of both worlds
 The `dbg` option is the combination of the `pipe` and `debugger` options. It displays all logs related to the debugging operations performed on the process by libdebug, as well as interactions with the process pipe: bytes received and bytes sent.

diff --git a/docs/multithreading/multithreading.md b/docs/multithreading/multithreading.md
@@ -59,7 +59,7 @@ stateDiagram-v2
 </div>
 <div style="text-align: center; font-size: 0.85rem;">All live threads are synchronized in their execution state.</div>
 
-## **libdebug** API for Multithreading
+## :octicons-code-24: API for Multithreading
 To access the threads of a process, you can use the `threads` attribute of the [Debugger](../../from_pydoc/generated/debugger/debugger/) object. This attribute will return a list of [ThreadContext](../../from_pydoc/generated/state/thread_context/) objects, each representing a thread of the process.
 
 If you're already familiar with the [Debugger](../../from_pydoc/generated/debugger/debugger/) object, you'll find the [ThreadContext](../../from_pydoc/generated/state/thread_context/) straightforward to use. The [Debugger](../../from_pydoc/generated/debugger/debugger/) has always acted as a facade for the main thread, enabling you to access registers, memory, and other thread state fields exactly as you would for the main thread. The difference you will notice is that the [ThreadContext](../../from_pydoc/generated/state/thread_context/) object is missing a couple of fields that just don't make sense in the context of a single thread (e.g. symbols, which belong to the binary, and memory maps, since they are shared for the whole process).

diff --git a/docs/quality_of_life/arbitrary_code_execution.md b/docs/quality_of_life/arbitrary_code_execution.md
@@ -0,0 +1,76 @@
+---
+icon: fontawesome/solid/wand-magic-sparkles
+search:
+    boost: 4
+---
+# :fontawesome-solid-wand-magic-sparkles: Arbitrary Code Execution
+Debugging is primarily a way to follow the execution of a program and understand its behavior. Stepping, stopping, continuing, reading registers...these are all tools that only serve to help humans understand the running code at their own pace. However, a debugger's intervention in a program execution can be much more than that. The debugger can virtually do anything to the program it is debugging, including changing its behavior, modifying its memory, and even executing arbitrary code.
+
+<div style="text-align: center;">
+    <img src="../../assets/ace_light.png#only-light" loading="lazy" width="720rem" />
+    <img src="../../assets/ace_dark.png#only-dark" loading="lazy" width="720rem" />
+</div>
+
+
+Since **libdebug** 0.9.0 NAME_TO_BE_DETERMINED, **libdebug** offers some primitives to perform arbitrary code execution inside a process. Specifically, it allows for the arbitrary invocation of *syscalls*. This can be useful for a variety of purposes, such as:
+
+- Playing with file descriptors
+- Allocating new memory maps
+- Forking the process to create checkpoints (feature coming soon)
+- Opening sockets to turn offline interactions into a service
+
+All of this is essentially live-patching the running code to perform arbitrary actions. This is a powerful feature that can be used to perform a variety of tasks, but it should be used with caution.
+
+!!! WARNING "Altering The Control Flow"
+    The control flow of a binary is a delicate thing. When executing arbitrary code, **libdebug** cannot guarantee that the process won't crash or behave unexpectedly. Remember, you are changing things under the hood without the program's knowledge.
+
+## :fontawesome-solid-terminal: Syscall Invocation
+Invoking a syscall is as simple as calling the [`invoke_syscall()`](../../from_pydoc/generated/state/thread_context/#libdebug.state.thread_context.ThreadContext.invoke_syscall) method of the [`ThreadContext`](../../from_pydoc/generated/state/thread_context/) class or the [`Debugger`](../../from_pydoc/generated/debugger/debugger/) object. In the latter case, the syscall will be invoked in the context of the main thread of the process.
+
+The invoked syscall will be treated just like any other syscall. This means that **libdebug** will show it when [pretty printing](../pretty_printing/#syscall-trace-pretty-printing) the syscall trace and callbacks will be triggered as expected.
+
+What exactly happens when you call this primitive?
+
+<div align="center">
+```mermaid
+graph TD
+    InvokeNode("invoke_syscall()") --> A[Backup Registers];
+    A --> B(Patch Code);
+    B --> CD("Syscall (Enter + Exit)");
+    CD --> E[Restore Code];
+    E --> F[Restore Registers];
+    F --> J(Return);
+
+    %% Styling the InvokeNode
+    style InvokeNode stroke:# blue,stroke-width:2px;
+    style J stroke:# blue,stroke-width:2px;
+```
+</div>
+Additionally, when the syscall is a [`fork`](https://man7.org/linux/man-pages/man2/fork.2.html), [`vfork`](https://man7.org/linux/man-pages/man2/vfork.2.html) or [`clone`](https://man7.org/linux/man-pages/man2/clone.2.html), the function will also restore the state in the child process / thread. This is done by copying the registers from the parent process / thread to the child process / thread.
+
+As you can see, registers values are restored after the syscall is executed to reduce the chances of the process crashing. However, be mindful that the syscall is indeed executed. Thus, the state of the process will have changed. Specifically, changes in the memory contents as a result of the syscall execution will not be reverted.
+
+### :octicons-code-24: Syscall Invocation API
+
+The following is the API of the arbitrary syscall invocation:
+invoke
+!!! ABSTRACT "Function Signature"
+    ```python
+    d.invoke_syscall(syscall_identifier: str | int, ...) -> int:
+    ```
+
+**Parameters**:
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `syscall_identifier` | `str` \| `int` | The syscall name or number. |
+| `...` | `int` | The arguments to be passed to the syscall. Not fixed, since the number of arguments depends on the syscall. |
+
+**Returns**:
+
+| Return | Type | Description |
+| --- | --- | --- |
+| `int` | `int` | The return value from the syscall invocation. |
+
+!!! QUESTION "Where can I call this?"
+    You can invoke syscalls whenever the process is stopped. The invocation can happen both synchronously and asynchronously (in a callback). The only exception to that is when the process is stopped on another syscall's enter or inside a syscall handling callback.
diff --git a/docs/quality_of_life/quality_of_life.md b/docs/quality_of_life/quality_of_life.md
@@ -18,5 +18,8 @@ Visualizing the state of the process you are debugging can be a daunting task. *
 ### [:octicons-stack-24: Stack Frame Utils](../stack_frame_utils/)
 **libdebug** offers utilities to resolve the return addresses of a process.
 
+### [:fontawesome-solid-wand-magic-sparkles: Arbitrary Code Execution](../arbitrary_code_execution/)
+**libdebug** offers a few functions that will help you execute arbitrary code in the context of the process you are debugging. Beware though, this features can significantly change the intended behavior of the process and may cause unexpected behaviors.
+
 ### [:material-run-fast: Evasion of Anti-Debugging](../anti_debugging/)
 **libdebug** offers a few functions that will help you evade simple anti-debugging techniques. These functions can be used to bypass checks for the presence of a debugger.
diff --git a/docs/stopping_events/breakpoints.md b/docs/stopping_events/breakpoints.md
@@ -29,7 +29,7 @@ Hardware breakpoints are a more reliable way to set breakpoints. They are made p
     Hardware breakpoints have to be aligned to 4 bytes (which is the size of an ARM instruction).
 
 
-## **libdebug** API for Breakpoints
+## :octicons-code-24: API for Breakpoints
 
 The `breakpoint()` function in the [Debugger](../../from_pydoc/generated/debugger/debugger/) object sets a breakpoint at a specific address.
 

diff --git a/docs/stopping_events/debugging_flow.md b/docs/stopping_events/debugging_flow.md
@@ -39,7 +39,7 @@ When a **synchronous** event is hit, the process will stop, awaiting further com
 
   Internally, hijacks are considered callbacks, so you cannot have a callback and hijack registered for the same event.
 
-## Common APIs of Stopping Events
+## :octicons-code-24: Common APIs of Stopping Events
 All **libdebug** stopping events share some common attributes that can be employed in debugging scripts.
 
 ### :material-power: Enable/Disable

diff --git a/docs/stopping_events/signals.md b/docs/stopping_events/signals.md
@@ -19,7 +19,7 @@ Signal catchers can be created to register [stopping events](../stopping_events/
 !!! INFO "Multiple catchers for the same signal"
     Please note that there can be at most **one** user-defined catcher or hijack for each signal. If a new catcher is defined for a signal that is already caught or hijacked, the new catcher will replace the old one, and a warning will be printed.
 
-## **libdebug** API for Signal Catching
+## :octicons-code-24: API for Signal Catching
 The `catch_signal()` function in the [Debugger](../../from_pydoc/generated/debugger/debugger/) object registers a catcher for the specified signal.
 
 !!! ABSTRACT "Function Signature"

diff --git a/docs/stopping_events/syscalls.md b/docs/stopping_events/syscalls.md
@@ -42,7 +42,7 @@ Syscall handlers can be created to register [stopping events](../stopping_events
 !!! QUESTION "Do I have to handle both on enter and on exit?"
     When using [asynchronous](../debugging_flow) syscall handlers, you can choose to handle both or only one of the two events. However, when using synchronous handlers, both events will stop the process.
 
-## **libdebug** API for Syscall Handlers
+## :octicons-code-24: API for Syscall Handlers
 The `handle_syscall()` function in the [Debugger](../../from_pydoc/generated/debugger/debugger/) object registers a handler for the specified syscall.
 
 !!! ABSTRACT "Function Signature"
@@ -230,3 +230,5 @@ For your convenience, you can also easily provide the syscall parameters to be u
 
     Again, the secret will be leaked to the standard output.
 
+## :fontawesome-solid-wand-magic-sparkles: Arbitrary Syscall Invocation
+Did you know? Since **libdebug** 0.9.0 NAME_TO_BE_DETERMINED you can also invoke an arbitrary syscall on a thread of your choice. Read more on this feature in the page dedicated to [Arbitrary Code Execution](../../quality_of_life/arbitrary_code_execution#arbitrary-syscall-invocation). 
diff --git a/docs/stopping_events/watchpoints.md b/docs/stopping_events/watchpoints.md
@@ -8,7 +8,7 @@ Watchpoints are a special type of [hardware breakpoint](../breakpoints#hardware-
 
 Features of watchpoints are shared with breakpoints, so you can set [asynchronous](../debugging_flow) watchpoints and use properties in the same way.
 
-## **libdebug** API for Watchpoints
+## :octicons-code-24: API for Watchpoints
 The `watchpoint()` function in the [Debugger](../../from_pydoc/generated/debugger/debugger/) object sets a watchpoint at a specific address. While you can also use the [breakpoint API](../breakpoints/#libdebug-api-for-breakpoints) to set up a watchpoint, a specific API is provided for your convenience:
 
 !!! ABSTRACT "Function Signature"

diff --git a/libdebug/architectures/aarch64/aarch64_call_utilities.py b/libdebug/architectures/aarch64/aarch64_call_utilities.py
@@ -33,3 +33,7 @@ def get_call_and_skip_amount(self: Aarch64CallUtilities, opcode_window: bytes) -
         """Check if the current instruction is a call instruction and compute the instruction size."""
         skip = self.compute_call_skip(opcode_window)
         return skip != 0, skip
+
+    def get_syscall_instruction(self: CallUtilitiesManager) -> bytes:
+        """Return the bytes of the syscall instruction."""
+        return b"\x1f\x20\x03\xd5\x01\x00\x00\xD4\x1f\x20\x03\xd5" # SVC #0 + NOPs
diff --git a/libdebug/architectures/amd64/amd64_call_utilities.py b/libdebug/architectures/amd64/amd64_call_utilities.py
@@ -63,3 +63,7 @@ def get_call_and_skip_amount(self, opcode_window: bytes) -> tuple[bool, int]:
         """Check if the current instruction is a call instruction and compute the instruction size."""
         skip = self.compute_call_skip(opcode_window)
         return skip != 0, skip
+
+    def get_syscall_instruction(self: CallUtilitiesManager) -> bytes:
+        """Return the bytes of the syscall instruction."""
+        return b"\x90\x0F\x05\x90\x90"  # syscall + NOPs
diff --git a/libdebug/architectures/call_utilities_manager.py b/libdebug/architectures/call_utilities_manager.py
@@ -21,5 +21,9 @@ def compute_call_skip(self: CallUtilitiesManager, opcode_window: bytes) -> int:
         """Compute the address where to skip after the current call instruction."""
 
     @abstractmethod
-    def get_call_and_skip_amount(self, opcode_window: bytes) -> tuple[bool, int]:
+    def get_call_and_skip_amount(self: CallUtilitiesManager, opcode_window: bytes) -> tuple[bool, int]:
         """Check if the current instruction is a call instruction and compute the instruction size."""
+
+    @abstractmethod
+    def get_syscall_instruction(self: CallUtilitiesManager) -> bytes:
+        """Return the bytes of the syscall instruction."""
diff --git a/libdebug/architectures/i386/i386_call_utilities.py b/libdebug/architectures/i386/i386_call_utilities.py
@@ -61,3 +61,7 @@ def compute_call_skip(self: I386CallUtilities, opcode_window: bytes) -> int:
     def get_call_and_skip_amount(self: I386CallUtilities, opcode_window: bytes) -> tuple[bool, int]:
         skip = self.compute_call_skip(opcode_window)
         return skip != 0, skip
+
+    def get_syscall_instruction(self: CallUtilitiesManager) -> bytes:
+        """Return the bytes of the syscall instruction."""
+        return b"\x90\xCD\x80\x90" # int 0x80 + NOPs
diff --git a/libdebug/builtin/pretty_print_syscall_handler.py b/libdebug/builtin/pretty_print_syscall_handler.py
@@ -18,6 +18,18 @@
     from libdebug.state.thread_context import ThreadContext
 
 
+def negate_value(value: int, word_size: int) -> int:
+    """Negate a value.
+
+    Args:
+        value (int): the value.
+        word_size (int): the word size.
+
+    Returns:
+        int: the negated value.
+    """
+    return (1 << word_size * 8) - value
+
 def pprint_on_enter(t: ThreadContext, syscall_number: int, **kwargs: int) -> None:
     """Function that will be called when a syscall is entered in pretty print mode.
 
@@ -92,4 +104,4 @@ def pprint_on_exit(syscall_return: int | tuple[int, int]) -> None:
             f"{ANSIColors.YELLOW}{ANSIColors.STRIKE}0x{syscall_return[0]:x}{ANSIColors.RESET} {ANSIColors.YELLOW}0x{syscall_return[1]:x}{ANSIColors.RESET}",
         )
     else:
-        print(f"{ANSIColors.YELLOW}0x{syscall_return:x}{ANSIColors.RESET}")
+        print(f"{ANSIColors.YELLOW}0x{syscall_return:x}{ANSIColors.RESET}")
diff --git a/libdebug/data/ace_fixup_kit.py b/libdebug/data/ace_fixup_kit.py
@@ -0,0 +1,64 @@
+#
+# This file is part of libdebug Python library (https://github.com/libdebug/libdebug).
+# Copyright (c) 2025 Francesco Panebianco. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from libdebug.debugger import Debugger
+    from libdebug.state.thread_context import ThreadContext
+
+
+@dataclass(frozen=True)
+class ACEFixupKit:
+    """A class that provides a fixup kit for new processes and threads after arbitrary code execution."""
+
+    register_dump: dict[str, int] = None
+    """The register dump."""
+
+    patch_address: int = 0
+    """The address of the applied patch."""
+
+    code_backup: bytes = b""
+    """The code backup."""
+
+    @staticmethod
+    def create_fixup_kit(
+        thread: ThreadContext,
+        patch_address: int,
+        code_backup: bytes,
+    ) -> ACEFixupKit:
+        """Create a fixup kit from the template of the given thread."""
+        kit = ACEFixupKit(
+            register_dump={},
+            patch_address=patch_address,
+            code_backup=code_backup,
+        )
+        # Fill the register dump with the current register values
+        for reg_name in dir(thread.regs):
+            if isinstance(getattr(thread.regs, reg_name), int | float) and reg_name != "_thread_id":
+                kit.register_dump[reg_name] = getattr(thread.regs, reg_name)
+
+    def fixup_thread(
+        self: ACEFixupKit,
+        thread: ThreadContext,
+    ) -> None:
+        """Fixup the new thread from the template."""
+        # Restore the registers
+        for reg_name, reg_value in self.register_dump.items():
+            setattr(thread.regs, reg_name, reg_value)
+
+    def fixup_process(
+        self: ACEFixupKit,
+        debugger: Debugger,
+    ) -> None:
+        """Fixup the new process from the template."""
+        self.fixup_thread(debugger.threads[0])
+
+        # Restore the code
+        debugger.memory[self.patch_address : self.patch_address + len(self.code_backup)] = self.code_backup
diff --git a/libdebug/data/syscall_handler.py b/libdebug/data/syscall_handler.py
@@ -27,6 +27,7 @@ class SyscallHandler:
         on_exit_user (Callable[[ThreadContext, SyscallHandler], None]): The callback defined by the user to execute when the syscall is exited.
         on_enter_pprint (Callable[[ThreadContext, int, Any], None]): The callback defined by the pretty print to execute when the syscall is entered.
         on_exit_pprint (Callable[[int | tuple[int, int]], None]): The callback defined by the pretty print to execute when the syscall is exited.
+        on_enter_invoked (Callable[[ThreadContext, SyscallHandler], None]): The internal callback to execute when the syscall is arbitrarily invoked.
         recursive (bool): Whether, when the syscall is hijacked with another one, the syscall handler associated with the new syscall should be considered as well. Defaults to False.
         enabled (bool): Whether the syscall will be handled or not.
         hit_count (int): The number of times the syscall has been handled.
@@ -35,8 +36,9 @@ class SyscallHandler:
     syscall_number: int
     on_enter_user: Callable[[ThreadContext, SyscallHandler], None]
     on_exit_user: Callable[[ThreadContext, SyscallHandler], None]
-    on_enter_pprint: Callable[[ThreadContext, int, Any], None]
+    on_enter_pprint: Callable[[int, Any], None]
     on_exit_pprint: Callable[[int | tuple[int, int]], None]
+    on_enter_invoked: Callable[[ThreadContext, SyscallHandler], None]
     recursive: bool = False
     hit_count: int = 0
 

diff --git a/libdebug/debugger/debugger.py b/libdebug/debugger/debugger.py
@@ -983,3 +983,12 @@ def load_snapshot(self: Debugger, file_path: str) -> Snapshot:
             file_path (str): The path to the snapshot file.
         """
         return self._internal_debugger.load_snapshot(file_path)
+
+    def invoke_syscall(self: Debugger, syscall_identifier: str | int, *args: int) -> int:
+        """Invokes a syscall with the specified arguments on the main thread.
+
+        Args:
+            syscall_identifier (str | int): The syscall identifier.
+            *args (int): The syscall arguments.
+        """
+        return self.threads[0].invoke_syscall(syscall_identifier, *args)