From 2584b31e5e06ffa2c240cc833ac8facbee36ea97 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Fri, 3 Apr 2026 00:25:12 +0100 Subject: [PATCH 1/2] Add threat model to remote debugging docs The remote debugging protocol has been generating spurious vulnerability reports from automated scanners that pattern-match on "remote access" and "memory operations" without understanding the privilege model. This section documents the security boundaries so reporters can self-triage before submitting. The threat model clarifies three points: attaching requires the same OS-level privileges as GDB (ptrace, task_for_pid, or SeDebugPrivilege), crashes caused by reading corrupted target process memory are not security issues, and a compromised target process is out of scope. A subsection explains when operators should use PYTHON_DISABLE_REMOTE_DEBUG for defence-in-depth. --- Doc/howto/remote_debugging.rst | 56 ++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/Doc/howto/remote_debugging.rst b/Doc/howto/remote_debugging.rst index dfe0176b75a020..1a23ee98e5e494 100644 --- a/Doc/howto/remote_debugging.rst +++ b/Doc/howto/remote_debugging.rst @@ -624,3 +624,59 @@ To inject and execute a Python script in a remote process: 6. Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field. 7. Resume the process (if suspended). The script will execute at the next safe evaluation point. + +.. _remote-debugging-threat-model: + +Security and threat model +========================= + +The remote debugging protocol relies on the same operating system primitives +used by native debuggers such as GDB and LLDB. Attaching to a process +requires the **same privileges** that those debuggers require, for example +``ptrace`` / Yama LSM on Linux, ``task_for_pid`` on macOS, and +``SeDebugPrivilege`` on Windows. Python does not introduce any new privilege +escalation path; if an attacker already possesses the permissions needed to +attach to a process, they could equally use GDB to read memory or inject +code. + +The following principles define what is, and is not, considered a security +vulnerability in this feature: + +**Attaching requires OS-level privileges.** + On every supported platform the operating system gates cross-process + memory access behind privilege checks (``CAP_SYS_PTRACE``, root, or + administrator rights). A report that demonstrates an issue only after + these privileges have already been obtained is **not** a vulnerability in + CPython, since the OS security boundary was already crossed. + +**Crashes or memory errors when reading a compromised process are not +vulnerabilities.** + A tool that reads internal interpreter state from a target process must + trust that memory to be well-formed. If the target process has been + corrupted or is controlled by an attacker, the debugger or profiler may + crash, produce garbage output, or behave unpredictably. This is the same + risk accepted by every ``ptrace``-based debugger. Bugs in this category + (buffer overflows, segmentation faults, or undefined behaviour triggered + by reading corrupted state) are **not** treated as security issues, though + fixes that improve robustness are welcome. + +**Vulnerabilities in the target process are not in scope.** + If the Python process being debugged has already been compromised, the + attacker already controls execution in that process. Demonstrating further + impact from that starting point does not constitute a vulnerability in the + remote debugging protocol. + +When to use ``PYTHON_DISABLE_REMOTE_DEBUG`` +------------------------------------------- + +The environment variable :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` (and the +equivalent :option:`-X disable_remote_debug` flag) allows operators to disable +the in-process side of the protocol as a **defence-in-depth** measure. This +may be useful in hardened or sandboxed deployment environments where no +debugging or profiling of the process is expected and reducing attack surface +is a priority, even though the OS-level privilege checks already prevent +unprivileged access. + +Setting this variable does **not** affect other OS-level debugging interfaces +(``ptrace``, ``/proc``, ``task_for_pid``, etc.), which remain available +according to their own permission models. From dce0e756fd391fcd474fe790a730666b11b33f83 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Fri, 3 Apr 2026 00:40:48 +0100 Subject: [PATCH 2/2] Fix RST indentation in threat model section The bold-text definition list pattern caused a docutils "Unexpected indentation" error because the bold markup spanned multiple lines. Switch to plain definition list terms instead. --- Doc/howto/remote_debugging.rst | 45 +++++++++++++++++----------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/Doc/howto/remote_debugging.rst b/Doc/howto/remote_debugging.rst index 1a23ee98e5e494..1d5cf24d062843 100644 --- a/Doc/howto/remote_debugging.rst +++ b/Doc/howto/remote_debugging.rst @@ -642,29 +642,28 @@ code. The following principles define what is, and is not, considered a security vulnerability in this feature: -**Attaching requires OS-level privileges.** - On every supported platform the operating system gates cross-process - memory access behind privilege checks (``CAP_SYS_PTRACE``, root, or - administrator rights). A report that demonstrates an issue only after - these privileges have already been obtained is **not** a vulnerability in - CPython, since the OS security boundary was already crossed. - -**Crashes or memory errors when reading a compromised process are not -vulnerabilities.** - A tool that reads internal interpreter state from a target process must - trust that memory to be well-formed. If the target process has been - corrupted or is controlled by an attacker, the debugger or profiler may - crash, produce garbage output, or behave unpredictably. This is the same - risk accepted by every ``ptrace``-based debugger. Bugs in this category - (buffer overflows, segmentation faults, or undefined behaviour triggered - by reading corrupted state) are **not** treated as security issues, though - fixes that improve robustness are welcome. - -**Vulnerabilities in the target process are not in scope.** - If the Python process being debugged has already been compromised, the - attacker already controls execution in that process. Demonstrating further - impact from that starting point does not constitute a vulnerability in the - remote debugging protocol. +Attaching requires OS-level privileges + On every supported platform the operating system gates cross-process + memory access behind privilege checks (``CAP_SYS_PTRACE``, root, or + administrator rights). A report that demonstrates an issue only after + these privileges have already been obtained is **not** a vulnerability in + CPython, since the OS security boundary was already crossed. + +Crashes or memory errors when reading a compromised process are not vulnerabilities + A tool that reads internal interpreter state from a target process must + trust that memory to be well-formed. If the target process has been + corrupted or is controlled by an attacker, the debugger or profiler may + crash, produce garbage output, or behave unpredictably. This is the same + risk accepted by every ``ptrace``-based debugger. Bugs in this category + (buffer overflows, segmentation faults, or undefined behaviour triggered + by reading corrupted state) are **not** treated as security issues, though + fixes that improve robustness are welcome. + +Vulnerabilities in the target process are not in scope + If the Python process being debugged has already been compromised, the + attacker already controls execution in that process. Demonstrating further + impact from that starting point does not constitute a vulnerability in the + remote debugging protocol. When to use ``PYTHON_DISABLE_REMOTE_DEBUG`` -------------------------------------------