pyx64dbg 0.1.0__tar.gz

pyx64dbg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoav Shamay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyx64dbg-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+
+recursive-include pyx64dbg *.cpp
+recursive-include pyx64dbg *.hpp

pyx64dbg-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pyx64dbg
+Version: 0.1.0
+Summary: A debugger implemented in Python
+Author-email: Yoav Shamay <yoavsh97@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yoav Shamay
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/yoav-shamay/pyx64dbg
+Project-URL: Repository, https://github.com/yoav-shamay/pyx64dbg
+Keywords: debugger,ptrace,x86-64,linux
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: capstone
+Requires-Dist: pyelftools
+Requires-Dist: ipython
+Requires-Dist: prompt_toolkit
+Requires-Dist: pyside6
+Requires-Dist: nest_asyncio
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: jinja2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# PyX64Dbg
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Linux_x86__64-lightgrey.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+**PyX64Dbg** is a Python-based debugger for x86-64 Linux binaries.
+
+PyX64Dbg utilizes the Linux `ptrace` system call and the `/proc` filesystem (`procfs`) to trace and introspect ELF processes. These low-level operating system primitives are abstracted into an intuitive Python object model, enabling direct manipulation of process memory, CPU registers, and execution flow.
+
+The tool features through three primary interfaces: a **Python API** designed for automated reverse engineering and binary analysis, a **Graphical User Interface (GUI)** for visual debugging, and a robust **IPython-based CLI** for debugging from the terminal.
+
+## Key Features
+
+- **Python API:** Automate reverse engineering, exploit development, or testing using a clean, object-oriented interface. Unlike GDB, PyX64Dbg acts as a standard Python library you can import and use anywhere.
+- **Graphical Interface (GUI):** Built with PySide6, featuring disassembly views, memory watches, register panels, and an embedded interactive terminal.
+- **Command Line Interface (CLI):** An interactive IPython REPL that supports live Python syntax, auto-completion, and inline evaluation.
+- **Advanced Target Support:** Native handling of PIE (Position Independent Executables), ASLR, shared libraries (`ld.so`), and dynamic symbols.
+- **C-Like Type System:** A custom extension providing native types (`Int32`, `UInt64`, `Float80`, etc.) that strictly follow C promotion, overflow, and truncation rules.
+- **Extended Registers (AVX/SSE):** Supports CPU `xstate`, including `XMM`, `YMM`, and FPU (`st`) vector registers. The API allows you to seamlessly treat vector data as a C-style union across all possible integer and floating-point array representations.
+
+## Prerequisites
+
+- **Operating System**: Linux (x86-64 architecture only)
+- **Python**: 3.10 or later
+- **C++ Compiler**: A C++20 compatible compiler (e.g., `g++` or `clang`) and Python development headers are required to compile the `ptrace` and numeric type extensions during installation.
+
+## Installation
+
+### From PyPI (Recommended)
+```bash
+pip install pyx64dbg
+```
+
+### From Source (Development)
+Clone the repository and install it in editable mode:
+```bash
+git clone https://github.com/yoav-shamay/pyx64dbg.git
+cd pyx64dbg
+pip install -e .
+```
+
+## Usage
+
+### Graphical Interface (GUI)
+Start the visual debugger (requires a desktop session like X11 or Wayland):
+```bash
+pyx64dbg-gui
+```
+*Tip: The full IPython CLI is embedded directly into the GUI and is available via the "Interactive Console" tab at the bottom.*
+
+### Command Line Interface (CLI)
+Launch the interactive IPython console:
+```bash
+pyx64dbg [/path/to/binary]
+```
+Once inside, simply type `help` to see a list of available commands and aliases (e.g., `run`, `step`, `bps`, `dis`).
+
+## Python API Showcase
+
+PyX64Dbg is built to be scripted. You can easily interact with binaries directly from Python.
+
+```python
+from pyx64dbg import Debugger
+from pyx64dbg.number_types import UInt64
+
+# 1. Spawn process and attach debugger
+dbg = Debugger.start_and_debug("./target_binary")
+
+# 2. Set a breakpoint at the 'main' function
+main_addr = dbg.symbols["main"]
+dbg.breakpoints.add_breakpoint(main_addr)
+
+# 3. Run until the breakpoint is hit
+dbg.control.continue_execution()
+
+# 4. Read memory and native vector registers
+rip = dbg.registers.rip
+rsp_val = dbg.memory.read_number(dbg.registers.rsp, UInt64)
+ymm0_floats = dbg.registers.ymm0.f32  # Access YMM0 as an array of 32-bit floats
+
+print(f"[+] Halted at RIP: 0x{rip:x}")
+print(f"[+] Stack pointer value: 0x{rsp_val:x}")
+print(f"[+] YMM0 state: {ymm0_floats}")
+
+# 5. Clean up - kill the process
+dbg.control.kill_process()
+```
+
+## Limitations
+
+- Supported exclusively on Linux ELF binaries running on `x86-64`.
+- Relies on the `ptrace` system call and the `/proc` filesystem. It will not function in hardened environments where these features are disabled.
+
+## Testing
+
+The repository includes a suite of integration tests that run against provided pre-compiled C binaries to verify register states, memory reading, and edge cases.
+
+To run the tests:
+```bash
+pytest test/
+```
+
+*Note: If you wish to rebuild the test executables from source, a `Makefile` is provided in `test/executables/`. Rebuilding may cause certain tests to fail if the compiler generates different instruction offsets.*
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyx64dbg-0.1.0/README.md

@@ -0,0 +1,108 @@
+# PyX64Dbg
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Linux_x86__64-lightgrey.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+**PyX64Dbg** is a Python-based debugger for x86-64 Linux binaries.
+
+PyX64Dbg utilizes the Linux `ptrace` system call and the `/proc` filesystem (`procfs`) to trace and introspect ELF processes. These low-level operating system primitives are abstracted into an intuitive Python object model, enabling direct manipulation of process memory, CPU registers, and execution flow.
+
+The tool features through three primary interfaces: a **Python API** designed for automated reverse engineering and binary analysis, a **Graphical User Interface (GUI)** for visual debugging, and a robust **IPython-based CLI** for debugging from the terminal.
+
+## Key Features
+
+- **Python API:** Automate reverse engineering, exploit development, or testing using a clean, object-oriented interface. Unlike GDB, PyX64Dbg acts as a standard Python library you can import and use anywhere.
+- **Graphical Interface (GUI):** Built with PySide6, featuring disassembly views, memory watches, register panels, and an embedded interactive terminal.
+- **Command Line Interface (CLI):** An interactive IPython REPL that supports live Python syntax, auto-completion, and inline evaluation.
+- **Advanced Target Support:** Native handling of PIE (Position Independent Executables), ASLR, shared libraries (`ld.so`), and dynamic symbols.
+- **C-Like Type System:** A custom extension providing native types (`Int32`, `UInt64`, `Float80`, etc.) that strictly follow C promotion, overflow, and truncation rules.
+- **Extended Registers (AVX/SSE):** Supports CPU `xstate`, including `XMM`, `YMM`, and FPU (`st`) vector registers. The API allows you to seamlessly treat vector data as a C-style union across all possible integer and floating-point array representations.
+
+## Prerequisites
+
+- **Operating System**: Linux (x86-64 architecture only)
+- **Python**: 3.10 or later
+- **C++ Compiler**: A C++20 compatible compiler (e.g., `g++` or `clang`) and Python development headers are required to compile the `ptrace` and numeric type extensions during installation.
+
+## Installation
+
+### From PyPI (Recommended)
+```bash
+pip install pyx64dbg
+```
+
+### From Source (Development)
+Clone the repository and install it in editable mode:
+```bash
+git clone https://github.com/yoav-shamay/pyx64dbg.git
+cd pyx64dbg
+pip install -e .
+```
+
+## Usage
+
+### Graphical Interface (GUI)
+Start the visual debugger (requires a desktop session like X11 or Wayland):
+```bash
+pyx64dbg-gui
+```
+*Tip: The full IPython CLI is embedded directly into the GUI and is available via the "Interactive Console" tab at the bottom.*
+
+### Command Line Interface (CLI)
+Launch the interactive IPython console:
+```bash
+pyx64dbg [/path/to/binary]
+```
+Once inside, simply type `help` to see a list of available commands and aliases (e.g., `run`, `step`, `bps`, `dis`).
+
+## Python API Showcase
+
+PyX64Dbg is built to be scripted. You can easily interact with binaries directly from Python.
+
+```python
+from pyx64dbg import Debugger
+from pyx64dbg.number_types import UInt64
+
+# 1. Spawn process and attach debugger
+dbg = Debugger.start_and_debug("./target_binary")
+
+# 2. Set a breakpoint at the 'main' function
+main_addr = dbg.symbols["main"]
+dbg.breakpoints.add_breakpoint(main_addr)
+
+# 3. Run until the breakpoint is hit
+dbg.control.continue_execution()
+
+# 4. Read memory and native vector registers
+rip = dbg.registers.rip
+rsp_val = dbg.memory.read_number(dbg.registers.rsp, UInt64)
+ymm0_floats = dbg.registers.ymm0.f32  # Access YMM0 as an array of 32-bit floats
+
+print(f"[+] Halted at RIP: 0x{rip:x}")
+print(f"[+] Stack pointer value: 0x{rsp_val:x}")
+print(f"[+] YMM0 state: {ymm0_floats}")
+
+# 5. Clean up - kill the process
+dbg.control.kill_process()
+```
+
+## Limitations
+
+- Supported exclusively on Linux ELF binaries running on `x86-64`.
+- Relies on the `ptrace` system call and the `/proc` filesystem. It will not function in hardened environments where these features are disabled.
+
+## Testing
+
+The repository includes a suite of integration tests that run against provided pre-compiled C binaries to verify register states, memory reading, and edge cases.
+
+To run the tests:
+```bash
+pytest test/
+```
+
+*Note: If you wish to rebuild the test executables from source, a `Makefile` is provided in `test/executables/`. Rebuilding may cause certain tests to fail if the compiler generates different instruction offsets.*
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyx64dbg-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools", "wheel", "pybind11"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyx64dbg"
+version = "0.1.0"
+description = "A debugger implemented in Python"
+authors = [
+    { name = "Yoav Shamay", email = "yoavsh97@gmail.com" }
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = ["capstone", "pyelftools", "ipython", "prompt_toolkit", "pyside6", "nest_asyncio"]
+keywords = ["debugger", "ptrace", "x86-64", "linux"]
+classifiers = [
+    "Operating System :: POSIX :: Linux",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Debuggers"
+]
+
+[project.urls]
+Homepage = "https://github.com/yoav-shamay/pyx64dbg"
+Repository = "https://github.com/yoav-shamay/pyx64dbg"
+
+[project.optional-dependencies]
+dev = ["black", "jinja2", "pytest"]
+
+[project.scripts]
+pyx64dbg = "pyx64dbg.CLI.main:main"
+pyx64dbg-gui = "pyx64dbg.GUI.main:main"
+
+[tool.setuptools.package-data]
+# Include type stubs, the py.typed marker, and all GUI web/styling assets
+"pyx64dbg" = ["py.typed", "**/*.pyi"]
+"pyx64dbg.GUI" = ["pty_view/*", "styles/*.qss", "assets/*"]

pyx64dbg-0.1.0/pyx64dbg/CLI/ipython_cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+from typing import Optional
+from IPython.terminal.embed import InteractiveShellEmbed
+from IPython.terminal.prompts import Prompts, Token
+from pyx64dbg.interactive_console.interactive_console import InteractiveConsole, banner
+import atexit
+import sys
+
+class ConsolePrompt(Prompts):
+    """
+    An implementation of the IPython Prompts class to define a custom prompt for our interactive console.
+    We want to show "PyX64Dbg> " as the prompt for our console.
+    """
+    def in_prompt_tokens(self, cli=None):
+        """
+        Override of the in_prompt_tokens method to return our custom prompt.
+        """
+        return [(Token.Prompt, "PyX64Dbg> ")]
+
+
+class IPythonCLI:
+    """
+    A class that manages the IPython CLI for the debugger.
+    Uses the InteractiveConsole class to manage the console state, and uses IPython for the shell itself.
+    """
+    def __init__(self, file_name: Optional[str] = None, verbose: bool = False, use_external_pty: bool = False) -> None:
+        self._verbose: bool = verbose
+        # create the interactive console object. We want stdio to appear in the terminal, so we don't redirect it to a PTY.
+        self.interactive_console = InteractiveConsole(
+            file_name,
+            redirect_stdio_to_pty=use_external_pty,
+            disable_pty_echo=False, # if we are using an external PTY, we don't disable the echo as we want to see what we are typing
+        )
+        # register our callbacks for updating aliases
+        self.interactive_console.update_aliases_callbacks.add(self._refresh_aliases)
+
+    def _refresh_aliases(self, aliases: dict[str, object]) -> None:
+        """
+        The callback for refreshing the aliases in the interactive console.
+        Moves the aliases to the IPython shell's user namespace so that they are accessible to the user.
+        """
+        self.shell.push(aliases)
+    
+    def _show_simple_error(
+        self,
+        exc_tuple=None,
+        filename=None,
+        tb=None,
+        tb_offset=None,
+        exception_only=False,
+        running_compiled_code=False,
+    ):
+        """
+        Custom error handler to show only the exception type and message without the full traceback.
+        This is in order to simplify the error output for the user.
+        """
+        # if we are not provided exc_tuple, take it from sys.exc_info() to get the current exception
+        if exc_tuple is not None:
+            exc_type, exc_value, _ = exc_tuple
+        else:
+            exc_type, exc_value, _ = sys.exc_info()
+        # use the console printing error message with the name of the exception class and its msg
+        self.interactive_console.print_error(exc_type.__name__, exc_value)
+
+    def start_console(self) -> None:
+        """
+        Starts the IPython interactive console.
+        """
+        atexit.register(self.interactive_console.handle_exit)  # register the console exit handler using atexit
+        # create the InteractiveShellEmbed object for the console, with linux colors and no banner (we have our own banner that we print separately)
+        self.shell = InteractiveShellEmbed(colors="linux", display_banner=False)
+        # define custom prompt (PyX64Dbg>) for the console
+        self.shell.prompts = ConsolePrompt(self.shell)
+        # if verbose mode is disabled, use the custom simple error handler that shows reduced error information to simplify console output
+        if not self._verbose:
+            self.shell.showtraceback = self._show_simple_error
+        # allow to call functions without parentheses, e. g. "s" instead of "s()"
+        self.shell.autocall = 2
+        # Disable the kernel from printing the autocall expansion to keep the CLI cleaner
+        self.shell.show_rewritten_input = False
+        print(banner, end='') # banner already has a newline at the end
+        # start the shell with the initial aliases from the interactive console
+        self.shell(local_ns=self.interactive_console.get_aliases())

pyx64dbg-0.1.0/pyx64dbg/CLI/main.py

@@ -0,0 +1,34 @@
+"""
+The entry point for the CLI tool.
+Parses command line arguments and starts the IPython CLI for the debugger.
+"""
+from __future__ import annotations
+import argparse
+from pyx64dbg.CLI.ipython_cli import IPythonCLI
+
+
+def parse_arguments() -> argparse.Namespace:
+    """
+    Parses the command line arguments for the CLI tool.
+    Returns an argparse.Namespace object containing the parsed arguments.
+    """
+    parser = argparse.ArgumentParser(prog='pyx64dbg',
+                                     description='A debugger for x64 Linux binaries, written in Python')
+    # optional filename argument
+    parser.add_argument("filename", nargs="?", default=None, help="The file to debug")
+    # verbose option (full tracebacks)
+    parser.add_argument("-v", "--verbose", action="store_true", help="Print verbose output in case of errors, including full traceback")
+    args = parser.parse_args()
+    return args
+
+def main():
+    """
+    The entry point for the CLI tool.
+    """
+    args = parse_arguments()
+    file_name = args.filename
+    console = IPythonCLI(file_name, verbose=args.verbose)
+    console.start_console()
+
+if __name__ == "__main__":
+    main()

pyx64dbg-0.1.0/pyx64dbg/GUI/assets/icon.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <!-- Refined Handle - Slightly larger, still anchored to boundary -->
+  <rect x="78.3" y="78.3" width="18" height="7" transform="rotate(45 78.3 78.3)" fill="black" rx="3.5" />
+
+  <!-- Centered Magnifying Glass Frame -->
+  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="2.5" fill="none" />
+
+  <!-- Organic Bug Design - Centered and contained -->
+  <g transform="translate(50, 46) scale(1.1)" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <!-- Hollow Head -->
+    <path d="M -5.5,-8.5 C -7,-17 7,-17 5.5,-8.5" />
+    
+    <!-- Antennae -->
+    <path d="M -2.5,-14 C -4,-18 -7,-19 -9,-18" />
+    <path d="M 2.5,-14 C 4,-18 7,-19 9,-18" />
+
+    <!-- Natural Curved Body -->
+    <path d="M -5.5,-8.5 
+             C -10,-8.5 -13,0 -11,8 
+             C -9,18 -5,26 0,26 
+             C 5,26 9,18 11,8 
+             C 13,0 10,-8.5 5.5,-8.5 
+             Z" />
+    
+    <!-- Curved Wing Split -->
+    <path d="M 0,-8.5 Q 0,10 0,26" stroke-width="1.2" />
+
+    <!-- Organic Curved Legs -->
+    <path d="M -9,0 C -13,-2 -15,0 -16,4" />
+    <path d="M 9,0 C 13,-2 15,0 16,4" />
+    
+    <path d="M -11,9 C -15,9 -17,13 -17,17" />
+    <path d="M 11,9 C 15,9 17,13 17,17" />
+
+    <path d="M -9,18 C -11,21 -12,27 -11,31" />
+    <path d="M 9,18 C 11,21 12,27 11,31" />
+  </g>
+</svg>

pyx64dbg-0.1.0/pyx64dbg/GUI/async_slot.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+import asyncio
+from functools import wraps
+from typing import Any, Callable, ParamSpec, Awaitable
+
+P = ParamSpec("P") # parameter specifications of the callables
+
+# save a reference to all background tasks created so they aren't discarded by the garbage collecotr.
+background_tasks: set[asyncio.Task[Any]] = set()
+
+def async_slot(func: Callable[P, Awaitable[Any]]) -> Callable[P, None]:
+    """
+    Decorator to connect async methods to standard Qt signals.
+    Automatically schedules the coroutine on the active asyncio event loop.
+    """
+    # define the wrapper function
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs):
+        # Catch any arguments the signal emits and pass them to the async function
+        task = asyncio.create_task(func(*args, **kwargs))
+        # save a reference to the task to prevent it from getting garbage collected, and remove it once the task is done
+        background_tasks.add(task)
+        task.add_done_callback(background_tasks.discard)
+    
+    return wrapper