| 1 |
.. _remote-debugging: |
| 2 |
|
| 3 |
Remote debugging attachment protocol |
| 4 |
==================================== |
| 5 |
|
| 6 |
This protocol enables external tools to attach to a running CPython process and |
| 7 |
execute Python code remotely. |
| 8 |
|
| 9 |
Most platforms require elevated privileges to attach to another Python process. |
| 10 |
|
| 11 |
Disabling remote debugging |
| 12 |
-------------------------- |
| 13 |
|
| 14 |
To disable remote debugging support, use any of the following: |
| 15 |
|
| 16 |
* Set the :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` environment variable to ``1`` before |
| 17 |
starting the interpreter. |
| 18 |
* Use the :option:`-X disable_remote_debug` command-line option. |
| 19 |
* Compile Python with the :option:`--without-remote-debug` build flag. |
| 20 |
|
| 21 |
.. _permission-requirements: |
| 22 |
|
| 23 |
Permission requirements |
| 24 |
======================= |
| 25 |
|
| 26 |
Attaching to a running Python process for remote debugging requires elevated |
| 27 |
privileges on most platforms. The specific requirements and troubleshooting |
| 28 |
steps depend on your operating system: |
| 29 |
|
| 30 |
.. rubric:: Linux |
| 31 |
|
| 32 |
The tracer process must have the ``CAP_SYS_PTRACE`` capability or equivalent |
| 33 |
privileges. You can only trace processes you own and can signal. Tracing may |
| 34 |
fail if the process is already being traced, or if it is running with |
| 35 |
set-user-ID or set-group-ID. Security modules like Yama may further restrict |
| 36 |
tracing. |
| 37 |
|
| 38 |
To temporarily relax ptrace restrictions (until reboot), run: |
| 39 |
|
| 40 |
``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`` |
| 41 |
|
| 42 |
.. note:: |
| 43 |
|
| 44 |
Disabling ``ptrace_scope`` reduces system hardening and should only be done |
| 45 |
in trusted environments. |
| 46 |
|
| 47 |
If running inside a container, use ``--cap-add=SYS_PTRACE`` or |
| 48 |
``--privileged``, and run as root if needed. |
| 49 |
|
| 50 |
Try re-running the command with elevated privileges: |
| 51 |
|
| 52 |
``sudo -E !!`` |
| 53 |
|
| 54 |
|
| 55 |
.. rubric:: macOS |
| 56 |
|
| 57 |
To attach to another process, you typically need to run your debugging tool |
| 58 |
with elevated privileges. This can be done by using ``sudo`` or running as |
| 59 |
root. |
| 60 |
|
| 61 |
Even when attaching to processes you own, macOS may block debugging unless |
| 62 |
the debugger is run with root privileges due to system security restrictions. |
| 63 |
|
| 64 |
|
| 65 |
.. rubric:: Windows |
| 66 |
|
| 67 |
To attach to another process, you usually need to run your debugging tool |
| 68 |
with administrative privileges. Start the command prompt or terminal as |
| 69 |
Administrator. |
| 70 |
|
| 71 |
Some processes may still be inaccessible even with Administrator rights, |
| 72 |
unless you have the ``SeDebugPrivilege`` privilege enabled. |
| 73 |
|
| 74 |
To resolve file or folder access issues, adjust the security permissions: |
| 75 |
|
| 76 |
1. Right-click the file or folder and select **Properties**. |
| 77 |
2. Go to the **Security** tab to view users and groups with access. |
| 78 |
3. Click **Edit** to modify permissions. |
| 79 |
4. Select your user account. |
| 80 |
5. In **Permissions**, check **Read** or **Full control** as needed. |
| 81 |
6. Click **Apply**, then **OK** to confirm. |
| 82 |
|
| 83 |
|
| 84 |
.. note:: |
| 85 |
|
| 86 |
Ensure you've satisfied all :ref:`permission-requirements` before proceeding. |
| 87 |
|
| 88 |
This section describes the low-level protocol that enables external tools to |
| 89 |
inject and execute a Python script within a running CPython process. |
| 90 |
|
| 91 |
This mechanism forms the basis of the :func:`sys.remote_exec` function, which |
| 92 |
instructs a remote Python process to execute a ``.py`` file. However, this |
| 93 |
section does not document the usage of that function. Instead, it provides a |
| 94 |
detailed explanation of the underlying protocol, which takes as input the |
| 95 |
``pid`` of a target Python process and the path to a Python source file to be |
| 96 |
executed. This information supports independent reimplementation of the |
| 97 |
protocol, regardless of programming language. |
| 98 |
|
| 99 |
.. warning:: |
| 100 |
|
| 101 |
The execution of the injected script depends on the interpreter reaching a |
| 102 |
safe evaluation point. As a result, execution may be delayed depending on |
| 103 |
the runtime state of the target process. |
| 104 |
|
| 105 |
Once injected, the script is executed by the interpreter within the target |
| 106 |
process the next time a safe evaluation point is reached. This approach enables |
| 107 |
remote execution capabilities without modifying the behavior or structure of |
| 108 |
the running Python application. |
| 109 |
|
| 110 |
Subsequent sections provide a step-by-step description of the protocol, |
| 111 |
including techniques for locating interpreter structures in memory, safely |
| 112 |
accessing internal fields, and triggering code execution. Platform-specific |
| 113 |
variations are noted where applicable, and example implementations are included |
| 114 |
to clarify each operation. |
| 115 |
|
| 116 |
Locating the PyRuntime structure |
| 117 |
================================ |
| 118 |
|
| 119 |
CPython places the ``PyRuntime`` structure in a dedicated binary section to |
| 120 |
help external tools find it at runtime. The name and format of this section |
| 121 |
vary by platform. For example, ``.PyRuntime`` is used on ELF systems, and |
| 122 |
``__DATA,__PyRuntime`` is used on macOS. Tools can find the offset of this |
| 123 |
structure by examining the binary on disk. |
| 124 |
|
| 125 |
The ``PyRuntime`` structure contains CPython’s global interpreter state and |
| 126 |
provides access to other internal data, including the list of interpreters, |
| 127 |
thread states, and debugger support fields. |
| 128 |
|
| 129 |
To work with a remote Python process, a debugger must first find the memory |
| 130 |
address of the ``PyRuntime`` structure in the target process. This address |
| 131 |
can’t be hardcoded or calculated from a symbol name, because it depends on |
| 132 |
where the operating system loaded the binary. |
| 133 |
|
| 134 |
The method for finding ``PyRuntime`` depends on the platform, but the steps are |
| 135 |
the same in general: |
| 136 |
|
| 137 |
1. Find the base address where the Python binary or shared library was loaded |
| 138 |
in the target process. |
| 139 |
2. Use the on-disk binary to locate the offset of the ``.PyRuntime`` section. |
| 140 |
3. Add the section offset to the base address to compute the address in memory. |
| 141 |
|
| 142 |
The sections below explain how to do this on each supported platform and |
| 143 |
include example code. |
| 144 |
|
| 145 |
.. rubric:: Linux (ELF) |
| 146 |
|
| 147 |
To find the ``PyRuntime`` structure on Linux: |
| 148 |
|
| 149 |
1. Read the process’s memory map (for example, ``/proc/<pid>/maps``) to find |
| 150 |
the address where the Python executable or ``libpython`` was loaded. |
| 151 |
2. Parse the ELF section headers in the binary to get the offset of the |
| 152 |
``.PyRuntime`` section. |
| 153 |
3. Add that offset to the base address from step 1 to get the memory address of |
| 154 |
``PyRuntime``. |
| 155 |
|
| 156 |
The following is an example implementation:: |
| 157 |
|
| 158 |
def find_py_runtime_linux(pid: int) -> int: |
| 159 |
# Step 1: Try to find the Python executable in memory |
| 160 |
binary_path, base_address = find_mapped_binary( |
| 161 |
pid, name_contains="python" |
| 162 |
) |
| 163 |
|
| 164 |
# Step 2: Fallback to shared library if executable is not found |
| 165 |
if binary_path is None: |
| 166 |
binary_path, base_address = find_mapped_binary( |
| 167 |
pid, name_contains="libpython" |
| 168 |
) |
| 169 |
|
| 170 |
# Step 3: Parse ELF headers to get .PyRuntime section offset |
| 171 |
section_offset = parse_elf_section_offset( |
| 172 |
binary_path, ".PyRuntime" |
| 173 |
) |
| 174 |
|
| 175 |
# Step 4: Compute PyRuntime address in memory |
| 176 |
return base_address + section_offset |
| 177 |
|
| 178 |
|
| 179 |
On Linux systems, there are two main approaches to read memory from another |
| 180 |
process. The first is through the ``/proc`` filesystem, specifically by reading from |
| 181 |
``/proc/[pid]/mem`` which provides direct access to the process's memory. This |
| 182 |
requires appropriate permissions - either being the same user as the target |
| 183 |
process or having root access. The second approach is using the |
| 184 |
``process_vm_readv()`` system call which provides a more efficient way to copy |
| 185 |
memory between processes. While ptrace's ``PTRACE_PEEKTEXT`` operation can also be |
| 186 |
used to read memory, it is significantly slower as it only reads one word at a |
| 187 |
time and requires multiple context switches between the tracer and tracee |
| 188 |
processes. |
| 189 |
|
| 190 |
For parsing ELF sections, the process involves reading and interpreting the ELF |
| 191 |
file format structures from the binary file on disk. The ELF header contains a |
| 192 |
pointer to the section header table. Each section header contains metadata about |
| 193 |
a section including its name (stored in a separate string table), offset, and |
| 194 |
size. To find a specific section like .PyRuntime, you need to walk through these |
| 195 |
headers and match the section name. The section header then provides the offset |
| 196 |
where that section exists in the file, which can be used to calculate its |
| 197 |
runtime address when the binary is loaded into memory. |
| 198 |
|
| 199 |
You can read more about the ELF file format in the `ELF specification |
| 200 |
<https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_. |
| 201 |
|
| 202 |
|
| 203 |
.. rubric:: macOS (Mach-O) |
| 204 |
|
| 205 |
To find the ``PyRuntime`` structure on macOS: |
| 206 |
|
| 207 |
1. Call ``task_for_pid()`` to get the ``mach_port_t`` task port for the target |
| 208 |
process. This handle is needed to read memory using APIs like |
| 209 |
``mach_vm_read_overwrite`` and ``mach_vm_region``. |
| 210 |
2. Scan the memory regions to find the one containing the Python executable or |
| 211 |
``libpython``. |
| 212 |
3. Load the binary file from disk and parse the Mach-O headers to find the |
| 213 |
section named ``PyRuntime`` in the ``__DATA`` segment. On macOS, symbol |
| 214 |
names are automatically prefixed with an underscore, so the ``PyRuntime`` |
| 215 |
symbol appears as ``_PyRuntime`` in the symbol table, but the section name |
| 216 |
is not affected. |
| 217 |
|
| 218 |
The following is an example implementation:: |
| 219 |
|
| 220 |
def find_py_runtime_macos(pid: int) -> int: |
| 221 |
# Step 1: Get access to the process's memory |
| 222 |
handle = get_memory_access_handle(pid) |
| 223 |
|
| 224 |
# Step 2: Try to find the Python executable in memory |
| 225 |
binary_path, base_address = find_mapped_binary( |
| 226 |
handle, name_contains="python" |
| 227 |
) |
| 228 |
|
| 229 |
# Step 3: Fallback to libpython if the executable is not found |
| 230 |
if binary_path is None: |
| 231 |
binary_path, base_address = find_mapped_binary( |
| 232 |
handle, name_contains="libpython" |
| 233 |
) |
| 234 |
|
| 235 |
# Step 4: Parse Mach-O headers to get __DATA,__PyRuntime section offset |
| 236 |
section_offset = parse_macho_section_offset( |
| 237 |
binary_path, "__DATA", "__PyRuntime" |
| 238 |
) |
| 239 |
|
| 240 |
# Step 5: Compute the PyRuntime address in memory |
| 241 |
return base_address + section_offset |
| 242 |
|
| 243 |
On macOS, accessing another process's memory requires using Mach-O specific APIs |
| 244 |
and file formats. The first step is obtaining a ``task_port`` handle via |
| 245 |
``task_for_pid()``, which provides access to the target process's memory space. |
| 246 |
This handle enables memory operations through APIs like |
| 247 |
``mach_vm_read_overwrite()``. |
| 248 |
|
| 249 |
The process memory can be examined using ``mach_vm_region()`` to scan through the |
| 250 |
virtual memory space, while ``proc_regionfilename()`` helps identify which binary |
| 251 |
files are loaded at each memory region. When the Python binary or library is |
| 252 |
found, its Mach-O headers need to be parsed to locate the ``PyRuntime`` structure. |
| 253 |
|
| 254 |
The Mach-O format organizes code and data into segments and sections. The |
| 255 |
``PyRuntime`` structure lives in a section named ``__PyRuntime`` within the |
| 256 |
``__DATA`` segment. The actual runtime address calculation involves finding the |
| 257 |
``__TEXT`` segment which serves as the binary's base address, then locating the |
| 258 |
``__DATA`` segment containing our target section. The final address is computed by |
| 259 |
combining the base address with the appropriate section offsets from the Mach-O |
| 260 |
headers. |
| 261 |
|
| 262 |
Note that accessing another process's memory on macOS typically requires |
| 263 |
elevated privileges - either root access or special security entitlements |
| 264 |
granted to the debugging process. |
| 265 |
|
| 266 |
|
| 267 |
.. rubric:: Windows (PE) |
| 268 |
|
| 269 |
To find the ``PyRuntime`` structure on Windows: |
| 270 |
|
| 271 |
1. Use the ToolHelp API to enumerate all modules loaded in the target process. |
| 272 |
This is done using functions such as `CreateToolhelp32Snapshot |
| 273 |
<https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-createtoolhelp32snapshot>`_, |
| 274 |
`Module32First |
| 275 |
<https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-module32first>`_, |
| 276 |
and `Module32Next |
| 277 |
<https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-module32next>`_. |
| 278 |
2. Identify the module corresponding to :file:`python.exe` or |
| 279 |
:file:`python{XY}.dll`, where ``X`` and ``Y`` are the major and minor |
| 280 |
version numbers of the Python version, and record its base address. |
| 281 |
3. Locate the ``PyRuntim`` section. Due to the PE format's 8-character limit |
| 282 |
on section names (defined as ``IMAGE_SIZEOF_SHORT_NAME``), the original |
| 283 |
name ``PyRuntime`` is truncated. This section contains the ``PyRuntime`` |
| 284 |
structure. |
| 285 |
4. Retrieve the section’s relative virtual address (RVA) and add it to the base |
| 286 |
address of the module. |
| 287 |
|
| 288 |
The following is an example implementation:: |
| 289 |
|
| 290 |
def find_py_runtime_windows(pid: int) -> int: |
| 291 |
# Step 1: Try to find the Python executable in memory |
| 292 |
binary_path, base_address = find_loaded_module( |
| 293 |
pid, name_contains="python" |
| 294 |
) |
| 295 |
|
| 296 |
# Step 2: Fallback to shared pythonXY.dll if the executable is not |
| 297 |
# found |
| 298 |
if binary_path is None: |
| 299 |
binary_path, base_address = find_loaded_module( |
| 300 |
pid, name_contains="python3" |
| 301 |
) |
| 302 |
|
| 303 |
# Step 3: Parse PE section headers to get the RVA of the PyRuntime |
| 304 |
# section. The section name appears as "PyRuntim" due to the |
| 305 |
# 8-character limit defined by the PE format (IMAGE_SIZEOF_SHORT_NAME). |
| 306 |
section_rva = parse_pe_section_offset(binary_path, "PyRuntim") |
| 307 |
|
| 308 |
# Step 4: Compute PyRuntime address in memory |
| 309 |
return base_address + section_rva |
| 310 |
|
| 311 |
|
| 312 |
On Windows, accessing another process's memory requires using the Windows API |
| 313 |
functions like ``CreateToolhelp32Snapshot()`` and ``Module32First()/Module32Next()`` |
| 314 |
to enumerate loaded modules. The ``OpenProcess()`` function provides a handle to |
| 315 |
access the target process's memory space, enabling memory operations through |
| 316 |
``ReadProcessMemory()``. |
| 317 |
|
| 318 |
The process memory can be examined by enumerating loaded modules to find the |
| 319 |
Python binary or DLL. When found, its PE headers need to be parsed to locate the |
| 320 |
``PyRuntime`` structure. |
| 321 |
|
| 322 |
The PE format organizes code and data into sections. The ``PyRuntime`` structure |
| 323 |
lives in a section named "PyRuntim" (truncated from "PyRuntime" due to PE's |
| 324 |
8-character name limit). The actual runtime address calculation involves finding |
| 325 |
the module's base address from the module entry, then locating our target |
| 326 |
section in the PE headers. The final address is computed by combining the base |
| 327 |
address with the section's virtual address from the PE section headers. |
| 328 |
|
| 329 |
Note that accessing another process's memory on Windows typically requires |
| 330 |
appropriate privileges - either administrative access or the ``SeDebugPrivilege`` |
| 331 |
privilege granted to the debugging process. |
| 332 |
|
| 333 |
|
| 334 |
Reading _Py_DebugOffsets |
| 335 |
======================== |
| 336 |
|
| 337 |
Once the address of the ``PyRuntime`` structure has been determined, the next |
| 338 |
step is to read the ``_Py_DebugOffsets`` structure located at the beginning of |
| 339 |
the ``PyRuntime`` block. |
| 340 |
|
| 341 |
This structure provides version-specific field offsets that are needed to |
| 342 |
safely read interpreter and thread state memory. These offsets vary between |
| 343 |
CPython versions and must be checked before use to ensure they are compatible. |
| 344 |
|
| 345 |
To read and check the debug offsets, follow these steps: |
| 346 |
|
| 347 |
1. Read memory from the target process starting at the ``PyRuntime`` address, |
| 348 |
covering the same number of bytes as the ``_Py_DebugOffsets`` structure. |
| 349 |
This structure is located at the very start of the ``PyRuntime`` memory |
| 350 |
block. Its layout is defined in CPython’s internal headers and stays the |
| 351 |
same within a given minor version, but may change in major versions. |
| 352 |
|
| 353 |
2. Check that the structure contains valid data: |
| 354 |
|
| 355 |
- The ``cookie`` field must match the expected debug marker. |
| 356 |
- The ``version`` field must match the version of the Python interpreter |
| 357 |
used by the debugger. |
| 358 |
- If either the debugger or the target process is using a pre-release |
| 359 |
version (for example, an alpha, beta, or release candidate), the versions |
| 360 |
must match exactly. |
| 361 |
- The ``free_threaded`` field must have the same value in both the debugger |
| 362 |
and the target process. |
| 363 |
|
| 364 |
3. If the structure is valid, the offsets it contains can be used to locate |
| 365 |
fields in memory. If any check fails, the debugger should stop the operation |
| 366 |
to avoid reading memory in the wrong format. |
| 367 |
|
| 368 |
The following is an example implementation that reads and checks |
| 369 |
``_Py_DebugOffsets``:: |
| 370 |
|
| 371 |
def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets: |
| 372 |
# Step 1: Read memory from the target process at the PyRuntime address |
| 373 |
data = read_process_memory( |
| 374 |
pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE |
| 375 |
) |
| 376 |
|
| 377 |
# Step 2: Deserialize the raw bytes into a _Py_DebugOffsets structure |
| 378 |
debug_offsets = parse_debug_offsets(data) |
| 379 |
|
| 380 |
# Step 3: Validate the contents of the structure |
| 381 |
if debug_offsets.cookie != EXPECTED_COOKIE: |
| 382 |
raise RuntimeError("Invalid or missing debug cookie") |
| 383 |
if debug_offsets.version != LOCAL_PYTHON_VERSION: |
| 384 |
raise RuntimeError( |
| 385 |
"Mismatch between caller and target Python versions" |
| 386 |
) |
| 387 |
if debug_offsets.free_threaded != LOCAL_FREE_THREADED: |
| 388 |
raise RuntimeError("Mismatch in free-threaded configuration") |
| 389 |
|
| 390 |
return debug_offsets |
| 391 |
|
| 392 |
|
| 393 |
|
| 394 |
.. warning:: |
| 395 |
|
| 396 |
**Process suspension recommended** |
| 397 |
|
| 398 |
To avoid race conditions and ensure memory consistency, it is strongly |
| 399 |
recommended that the target process be suspended before performing any |
| 400 |
operations that read or write internal interpreter state. The Python runtime |
| 401 |
may concurrently mutate interpreter data structures—such as creating or |
| 402 |
destroying threads—during normal execution. This can result in invalid |
| 403 |
memory reads or writes. |
| 404 |
|
| 405 |
A debugger may suspend execution by attaching to the process with ``ptrace`` |
| 406 |
or by sending a ``SIGSTOP`` signal. Execution should only be resumed after |
| 407 |
debugger-side memory operations are complete. |
| 408 |
|
| 409 |
.. note:: |
| 410 |
|
| 411 |
Some tools, such as profilers or sampling-based debuggers, may operate on |
| 412 |
a running process without suspension. In such cases, tools must be |
| 413 |
explicitly designed to handle partially updated or inconsistent memory. |
| 414 |
For most debugger implementations, suspending the process remains the |
| 415 |
safest and most robust approach. |
| 416 |
|
| 417 |
|
| 418 |
Locating the interpreter and thread state |
| 419 |
========================================= |
| 420 |
|
| 421 |
Before code can be injected and executed in a remote Python process, the |
| 422 |
debugger must choose a thread in which to schedule execution. This is necessary |
| 423 |
because the control fields used to perform remote code injection are located in |
| 424 |
the ``_PyRemoteDebuggerSupport`` structure, which is embedded in a |
| 425 |
``PyThreadState`` object. These fields are modified by the debugger to request |
| 426 |
execution of injected scripts. |
| 427 |
|
| 428 |
The ``PyThreadState`` structure represents a thread running inside a Python |
| 429 |
interpreter. It maintains the thread’s evaluation context and contains the |
| 430 |
fields required for debugger coordination. Locating a valid ``PyThreadState`` |
| 431 |
is therefore a key prerequisite for triggering execution remotely. |
| 432 |
|
| 433 |
A thread is typically selected based on its role or ID. In most cases, the main |
| 434 |
thread is used, but some tools may target a specific thread by its native |
| 435 |
thread ID. Once the target thread is chosen, the debugger must locate both the |
| 436 |
interpreter and the associated thread state structures in memory. |
| 437 |
|
| 438 |
The relevant internal structures are defined as follows: |
| 439 |
|
| 440 |
- ``PyInterpreterState`` represents an isolated Python interpreter instance. |
| 441 |
Each interpreter maintains its own set of imported modules, built-in state, |
| 442 |
and thread state list. Although most Python applications use a single |
| 443 |
interpreter, CPython supports multiple interpreters in the same process. |
| 444 |
|
| 445 |
- ``PyThreadState`` represents a thread running within an interpreter. It |
| 446 |
contains execution state and the control fields used by the debugger. |
| 447 |
|
| 448 |
To locate a thread: |
| 449 |
|
| 450 |
1. Use the offset ``runtime_state.interpreters_head`` to obtain the address of |
| 451 |
the first interpreter in the ``PyRuntime`` structure. This is the entry point |
| 452 |
to the linked list of active interpreters. |
| 453 |
|
| 454 |
2. Use the offset ``interpreter_state.threads_main`` to access the main thread |
| 455 |
state associated with the selected interpreter. This is typically the most |
| 456 |
reliable thread to target. |
| 457 |
|
| 458 |
3. Optionally, use the offset ``interpreter_state.threads_head`` to iterate |
| 459 |
through the linked list of all thread states. Each ``PyThreadState`` |
| 460 |
structure contains a ``native_thread_id`` field, which may be compared to |
| 461 |
a target thread ID to find a specific thread. |
| 462 |
|
| 463 |
4. Once a valid ``PyThreadState`` has been found, its address can be used in |
| 464 |
later steps of the protocol, such as writing debugger control fields and |
| 465 |
scheduling execution. |
| 466 |
|
| 467 |
The following is an example implementation that locates the main thread state:: |
| 468 |
|
| 469 |
def find_main_thread_state( |
| 470 |
pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets, |
| 471 |
) -> int: |
| 472 |
# Step 1: Read interpreters_head from PyRuntime |
| 473 |
interp_head_ptr = ( |
| 474 |
py_runtime_addr + debug_offsets.runtime_state.interpreters_head |
| 475 |
) |
| 476 |
interp_addr = read_pointer(pid, interp_head_ptr) |
| 477 |
if interp_addr == 0: |
| 478 |
raise RuntimeError("No interpreter found in the target process") |
| 479 |
|
| 480 |
# Step 2: Read the threads_main pointer from the interpreter |
| 481 |
threads_main_ptr = ( |
| 482 |
interp_addr + debug_offsets.interpreter_state.threads_main |
| 483 |
) |
| 484 |
thread_state_addr = read_pointer(pid, threads_main_ptr) |
| 485 |
if thread_state_addr == 0: |
| 486 |
raise RuntimeError("Main thread state is not available") |
| 487 |
|
| 488 |
return thread_state_addr |
| 489 |
|
| 490 |
The following example demonstrates how to locate a thread by its native thread |
| 491 |
ID:: |
| 492 |
|
| 493 |
def find_thread_by_id( |
| 494 |
pid: int, |
| 495 |
interp_addr: int, |
| 496 |
debug_offsets: DebugOffsets, |
| 497 |
target_tid: int, |
| 498 |
) -> int: |
| 499 |
# Start at threads_head and walk the linked list |
| 500 |
thread_ptr = read_pointer( |
| 501 |
pid, |
| 502 |
interp_addr + debug_offsets.interpreter_state.threads_head |
| 503 |
) |
| 504 |
|
| 505 |
while thread_ptr: |
| 506 |
native_tid_ptr = ( |
| 507 |
thread_ptr + debug_offsets.thread_state.native_thread_id |
| 508 |
) |
| 509 |
native_tid = read_int(pid, native_tid_ptr) |
| 510 |
if native_tid == target_tid: |
| 511 |
return thread_ptr |
| 512 |
thread_ptr = read_pointer( |
| 513 |
pid, |
| 514 |
thread_ptr + debug_offsets.thread_state.next |
| 515 |
) |
| 516 |
|
| 517 |
raise RuntimeError("Thread with the given ID was not found") |
| 518 |
|
| 519 |
|
| 520 |
Once a valid thread state has been located, the debugger can proceed with |
| 521 |
modifying its control fields and scheduling execution, as described in the next |
| 522 |
section. |
| 523 |
|
| 524 |
Writing control information |
| 525 |
=========================== |
| 526 |
|
| 527 |
Once a valid ``PyThreadState`` structure has been identified, the debugger may |
| 528 |
modify control fields within it to schedule the execution of a specified Python |
| 529 |
script. These control fields are checked periodically by the interpreter, and |
| 530 |
when set correctly, they trigger the execution of remote code at a safe point |
| 531 |
in the evaluation loop. |
| 532 |
|
| 533 |
Each ``PyThreadState`` contains a ``_PyRemoteDebuggerSupport`` structure used |
| 534 |
for communication between the debugger and the interpreter. The locations of |
| 535 |
its fields are defined by the ``_Py_DebugOffsets`` structure and include the |
| 536 |
following: |
| 537 |
|
| 538 |
- ``debugger_script_path``: A fixed-size buffer that holds the full path to a |
| 539 |
Python source file (``.py``). This file must be accessible and readable by |
| 540 |
the target process when execution is triggered. |
| 541 |
|
| 542 |
- ``debugger_pending_call``: An integer flag. Setting this to ``1`` tells the |
| 543 |
interpreter that a script is ready to be executed. |
| 544 |
|
| 545 |
- ``eval_breaker``: A field checked by the interpreter during execution. |
| 546 |
Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this |
| 547 |
field causes the interpreter to pause and check for debugger activity. |
| 548 |
|
| 549 |
To complete the injection, the debugger must perform the following steps: |
| 550 |
|
| 551 |
1. Write the full script path into the ``debugger_script_path`` buffer. |
| 552 |
2. Set ``debugger_pending_call`` to ``1``. |
| 553 |
3. Read the current value of ``eval_breaker``, set bit 5 |
| 554 |
(``_PY_EVAL_PLEASE_STOP_BIT``), and write the updated value back. This |
| 555 |
signals the interpreter to check for debugger activity. |
| 556 |
|
| 557 |
The following is an example implementation:: |
| 558 |
|
| 559 |
def inject_script( |
| 560 |
pid: int, |
| 561 |
thread_state_addr: int, |
| 562 |
debug_offsets: DebugOffsets, |
| 563 |
script_path: str |
| 564 |
) -> None: |
| 565 |
# Compute the base offset of _PyRemoteDebuggerSupport |
| 566 |
support_base = ( |
| 567 |
thread_state_addr + |
| 568 |
debug_offsets.debugger_support.remote_debugger_support |
| 569 |
) |
| 570 |
|
| 571 |
# Step 1: Write the script path into debugger_script_path |
| 572 |
script_path_ptr = ( |
| 573 |
support_base + |
| 574 |
debug_offsets.debugger_support.debugger_script_path |
| 575 |
) |
| 576 |
write_string(pid, script_path_ptr, script_path) |
| 577 |
|
| 578 |
# Step 2: Set debugger_pending_call to 1 |
| 579 |
pending_ptr = ( |
| 580 |
support_base + |
| 581 |
debug_offsets.debugger_support.debugger_pending_call |
| 582 |
) |
| 583 |
write_int(pid, pending_ptr, 1) |
| 584 |
|
| 585 |
# Step 3: Set _PY_EVAL_PLEASE_STOP_BIT (bit 5, value 1 << 5) in |
| 586 |
# eval_breaker |
| 587 |
eval_breaker_ptr = ( |
| 588 |
thread_state_addr + |
| 589 |
debug_offsets.debugger_support.eval_breaker |
| 590 |
) |
| 591 |
breaker = read_int(pid, eval_breaker_ptr) |
| 592 |
breaker |= (1 << 5) |
| 593 |
write_int(pid, eval_breaker_ptr, breaker) |
| 594 |
|
| 595 |
|
| 596 |
Once these fields are set, the debugger may resume the process (if it was |
| 597 |
suspended). The interpreter will process the request at the next safe |
| 598 |
evaluation point, load the script from disk, and execute it. |
| 599 |
|
| 600 |
It is the responsibility of the debugger to ensure that the script file remains |
| 601 |
present and accessible to the target process during execution. |
| 602 |
|
| 603 |
.. note:: |
| 604 |
|
| 605 |
Script execution is asynchronous. The script file cannot be deleted |
| 606 |
immediately after injection. The debugger should wait until the injected |
| 607 |
script has produced an observable effect before removing the file. |
| 608 |
This effect depends on what the script is designed to do. For example, |
| 609 |
a debugger might wait until the remote process connects back to a socket |
| 610 |
before removing the script. Once such an effect is observed, it is safe to |
| 611 |
assume the file is no longer needed. |
| 612 |
|
| 613 |
Summary |
| 614 |
======= |
| 615 |
|
| 616 |
To inject and execute a Python script in a remote process: |
| 617 |
|
| 618 |
1. Locate the ``PyRuntime`` structure in the target process’s memory. |
| 619 |
2. Read and validate the ``_Py_DebugOffsets`` structure at the beginning of |
| 620 |
``PyRuntime``. |
| 621 |
3. Use the offsets to locate a valid ``PyThreadState``. |
| 622 |
4. Write the path to a Python script into ``debugger_script_path``. |
| 623 |
5. Set the ``debugger_pending_call`` flag to ``1``. |
| 624 |
6. Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field. |
| 625 |
7. Resume the process (if suspended). The script will execute at the next safe |
| 626 |
evaluation point. |
| 627 |
|
| 628 |
.. _remote-debugging-threat-model: |
| 629 |
|
| 630 |
Security and threat model |
| 631 |
========================= |
| 632 |
|
| 633 |
The remote debugging protocol relies on the same operating system primitives |
| 634 |
used by native debuggers such as GDB and LLDB. Attaching to a process |
| 635 |
requires the **same privileges** that those debuggers require, for example |
| 636 |
``ptrace`` / Yama LSM on Linux, ``task_for_pid`` on macOS, and |
| 637 |
``SeDebugPrivilege`` on Windows. Python does not introduce any new privilege |
| 638 |
escalation path; if an attacker already possesses the permissions needed to |
| 639 |
attach to a process, they could equally use GDB to read memory or inject |
| 640 |
code. |
| 641 |
|
| 642 |
The following principles define what is, and is not, considered a security |
| 643 |
vulnerability in this feature: |
| 644 |
|
| 645 |
Attaching requires OS-level privileges |
| 646 |
On every supported platform the operating system gates cross-process |
| 647 |
memory access behind privilege checks (``CAP_SYS_PTRACE``, root, or |
| 648 |
administrator rights). A report that demonstrates an issue only after |
| 649 |
these privileges have already been obtained is **not** a vulnerability in |
| 650 |
CPython, since the OS security boundary was already crossed. |
| 651 |
|
| 652 |
Crashes or memory errors when reading a compromised process are not vulnerabilities |
| 653 |
A tool that reads internal interpreter state from a target process must |
| 654 |
trust that memory to be well-formed. If the target process has been |
| 655 |
corrupted or is controlled by an attacker, the debugger or profiler may |
| 656 |
crash, produce garbage output, or behave unpredictably. This is the same |
| 657 |
risk accepted by every ``ptrace``-based debugger. Bugs in this category |
| 658 |
(buffer overflows, segmentation faults, or undefined behaviour triggered |
| 659 |
by reading corrupted state) are **not** treated as security issues, though |
| 660 |
fixes that improve robustness are welcome. |
| 661 |
|
| 662 |
Vulnerabilities in the target process are not in scope |
| 663 |
If the Python process being debugged has already been compromised, the |
| 664 |
attacker already controls execution in that process. Demonstrating further |
| 665 |
impact from that starting point does not constitute a vulnerability in the |
| 666 |
remote debugging protocol. |
| 667 |
|
| 668 |
When to use ``PYTHON_DISABLE_REMOTE_DEBUG`` |
| 669 |
------------------------------------------- |
| 670 |
|
| 671 |
The environment variable :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` (and the |
| 672 |
equivalent :option:`-X disable_remote_debug` flag) allows operators to disable |
| 673 |
the in-process side of the protocol as a **defence-in-depth** measure. This |
| 674 |
may be useful in hardened or sandboxed deployment environments where no |
| 675 |
debugging or profiling of the process is expected and reducing attack surface |
| 676 |
is a priority, even though the OS-level privilege checks already prevent |
| 677 |
unprivileged access. |
| 678 |
|
| 679 |
Setting this variable does **not** affect other OS-level debugging interfaces |
| 680 |
(``ptrace``, ``/proc``, ``task_for_pid``, etc.), which remain available |
| 681 |
according to their own permission models. |