Laufzeitstatus-Erweiterungen

Eine neue Struktur wird zu PyThreadState hinzugefügt, um Remote-Debugging zu unterstützen

typedef struct {
    int debugger_pending_call;
    char debugger_script_path[...];
} _PyRemoteDebuggerSupport;

Diese Struktur wird an PyThreadState angehängt und fügt nur wenige Felder hinzu, die **während der normalen Ausführung niemals abgerufen werden**. Das Feld debugger_pending_call zeigt an, wann ein Debugger eine Ausführung angefordert hat, während debugger_script_path einen Dateisystempfad zu einer Python-Quelldatei (.py) bereitstellt, die ausgeführt wird, wenn der Interpreter einen sicheren Punkt erreicht. Der Pfad muss auf eine Python-Quelldatei zeigen, nicht auf kompilierten Python-Code (.pyc) oder ein anderes Format.

Die Größe von debugger_script_path wird ein Kompromiss zwischen Binärgröße und der maximalen Länge von Pfaden für Debugging-Skripte sein. Um den Speicher-Overhead pro Thread zu begrenzen, werden wir dies auf 512 Bytes beschränken. Dieser Wert wird auch als Teil der Debugger-Unterstützungsstruktur bereitgestellt, damit Debugger wissen, wie viel sie schreiben können. Dieser Wert kann in Zukunft erweitert werden, falls wir ihn jemals benötigen.

Debug-Offsets-Tabelle

Python 3.12 führte eine Tabelle mit Debug-Offsets am Anfang der PyRuntime-Struktur ein. Dieser Abschnitt enthält die Struktur _Py_DebugOffsets, die es externen Werkzeugen ermöglicht, kritische Laufzeitstrukturen zuverlässig zu finden, unabhängig von ASLR oder der Art und Weise, wie Python kompiliert wurde.

Dieser Vorschlag erweitert die bestehende Tabelle mit Debug-Offsets um neue Felder für die Debugger-Unterstützung

struct _debugger_support {
    uint64_t eval_breaker;              // Location of the eval breaker flag
    uint64_t remote_debugger_support;   // Offset to our support structure
    uint64_t debugger_pending_call;     // Where to write the pending flag
    uint64_t debugger_script_path;      // Where to write the script path
    uint64_t debugger_script_path_size; // Size of the script path buffer
} debugger_support;

Diese Offsets ermöglichen es Debuggern, kritische Debugging-Kontrollstrukturen im Speicherbereich des Zielprozesses zu lokalisieren. Die Offsets eval_breaker und remote_debugger_support sind relativ zu jedem PyThreadState, während die Offsets debugger_pending_call und debugger_script_path relativ zu jeder _PyRemoteDebuggerSupport-Struktur sind. Dies ermöglicht es, die neue Struktur und ihre Felder unabhängig von ihrem Speicherort zu finden. debugger_script_path_size informiert das anhangende Tool über die Größe des Puffers.

Anhangsprotokoll

Wenn ein Debugger sich an einen Python-Prozess anhängen möchte, folgt er diesen Schritten

1. Lokalisieren der PyRuntime-Struktur im Prozess
   • Finden der Python-Binärdatei (Executable oder libpython) im Prozessspeicher (OS-abhängiger Prozess)
   • Extrahieren des Offsets des Abschnitts .PyRuntime aus dem Format der Binärdatei (ELF/Mach-O/PE)
   • Berechnen der tatsächlichen Adresse von PyRuntime im laufenden Prozess durch Relokation des Offsets zur Ladeadresse der Binärdatei
2. Zugriff auf Debug-Offset-Informationen durch Lesen von _Py_DebugOffsets am Anfang der PyRuntime-Struktur.
3. Verwenden der Offsets, um den gewünschten Thread-Zustand zu lokalisieren
4. Verwenden der Offsets, um die Debugger-Schnittstellenfelder innerhalb dieses Thread-Zustands zu lokalisieren
5. Schreiben von Steuerinformationen
   • Die meisten Debugger pausieren den Prozess, bevor sie in seinen Speicher schreiben. Dies ist eine gängige Praxis für Tools wie GDB, die SIGSTOP oder ptrace verwenden, um den Prozess anzuhalten. Dieser Ansatz verhindert Race Conditions beim Schreiben in den Prozessspeicher. Profiler und andere Tools, die den Prozess nicht anhalten möchten, können diese Schnittstelle trotzdem verwenden, müssen aber mögliche Race Conditions handhaben. Dies ist eine normale Überlegung für Profiler.
   • Schreiben eines Dateipfads zu einer Python-Quelldatei (.py) in das Feld debugger_script_path in _PyRemoteDebuggerSupport.
   • Setzen des Flags debugger_pending_call in _PyRemoteDebuggerSupport auf 1
   • Setzen des Bits _PY_EVAL_PLEASE_STOP_BIT im Feld eval_breaker

Sobald der Interpreter den nächsten sicheren Punkt erreicht, wird der Python-Code aus der vom Debugger angegebenen Datei ausgeführt.

Interpreter-Integration

Die reguläre Auswertungs-Schleife des Interpreters enthält bereits eine Prüfung des Flags eval_breaker zur Behandlung von Signalen, periodischen Aufgaben und anderen Unterbrechungen. Wir nutzen diesen bestehenden Mechanismus, indem wir nur dann nach ausstehenden Debugger-Aufrufen suchen, wenn eval_breaker gesetzt ist, was einen Zero-Overhead während der normalen Ausführung gewährleistet. Diese Prüfung hat keinen Overhead. Tatsächlich zeigt das Profiling mit dem Linux-Tool perf, dass dieser Zweig hochgradig vorhersagbar ist – die Prüfung von debugger_pending_call wird während der normalen Ausführung nie genommen, was modernen CPUs ermöglicht, sie effektiv zu überspringen.

Wenn ein Debugger sowohl das Flag eval_breaker als auch debugger_pending_call gesetzt hat, führt der Interpreter den bereitgestellten Debugging-Code am nächsten sicheren Punkt aus. Dies geschieht alles in einem vollständig sicheren Kontext, da garantiert ist, dass der Interpreter in einem konsistenten Zustand ist, wann immer der Eval-Breaker überprüft wird.

Die einzigen gültigen Werte für debugger_pending_call werden anfänglich 0 und 1 sein; andere Werte sind für zukünftige Verwendungen reserviert.

Vor der Ausführung des Codes wird ein Audit-Ereignis ausgelöst, das es ermöglicht, diesen Mechanismus zu überprüfen oder ihn bei Bedarf durch den Administrator eines Systems zu deaktivieren.

// In ceval.c
if (tstate->eval_breaker) {
    if (tstate->remote_debugger_support.debugger_pending_call) {
        tstate->remote_debugger_support.debugger_pending_call = 0;
        const char *path = tstate->remote_debugger_support.debugger_script_path;
        if (*path) {
            if (0 != PySys_Audit("debugger_script", "%s", path)) {
                PyErr_Clear();
            } else {
                FILE* f = fopen(path, "r");
                if (!f) {
                    PyErr_SetFromErrno(OSError);
                } else {
                    PyRun_AnyFile(f, path);
                    fclose(f);
                }
                if (PyErr_Occurred()) {
                    PyErr_WriteUnraisable(...);
                }
            }
        }
    }
}

Wenn der ausgeführte Code eine Python-Ausnahme auslöst, wird diese als nicht abfangbare Ausnahme im Thread behandelt, in dem der Code ausgeführt wurde.

Python API

Um die sichere Ausführung von Python-Code in einem Remote-Prozess zu unterstützen, ohne all diese Schritte in jedem Tool neu implementieren zu müssen, erweitert dieser Vorschlag das Modul sys um eine neue Funktion. Diese Funktion ermöglicht es Debuggern oder externen Tools, beliebigen Python-Code im Kontext eines bestimmten Python-Prozesses auszuführen.

def remote_exec(pid: int, script: str|bytes|PathLike) -> None:
    """
    Executes a file containing Python code in a given remote Python process.

    This function returns immediately, and the code will be executed by the
    target process's main thread at the next available opportunity, similarly
    to how signals are handled. There is no interface to determine when the
    code has been executed. The caller is responsible for making sure that
    the file still exists whenever the remote process tries to read it and that
    it hasn't been overwritten.

    Args:
         pid (int): The process ID of the target Python process.
         script (str|bytes|PathLike): The path to a file containing
             the Python code to be executed.
    """

Ein Beispiel für die Verwendung der API würde wie folgt aussehen:

import sys
import uuid
# Execute a print statement in a remote Python process with PID 12345
script = f"/tmp/{uuid.uuid4()}.py"
with open(script, "w") as f:
    f.write("print('Hello from remote execution!')")
try:
    sys.remote_exec(12345, script)
except Exception as e:
    print(f"Failed to execute code: {e}")

Konfigurations-API

Um Verteilern, Systemadministratoren oder Benutzern die Deaktivierung dieses Mechanismus zu ermöglichen, werden mehrere Methoden bereitgestellt, um das Verhalten des Interpreters zu steuern.

Eine neue Umgebungsvariable PYTHON_DISABLE_REMOTE_DEBUG wird bereitgestellt, um das Verhalten zur Laufzeit zu steuern. Wenn sie auf einen beliebigen Wert gesetzt ist (auch einen leeren String), ignoriert der Interpreter alle Versuche, sich über diesen Mechanismus an einen Debugger anzuhängen.

Diese Umgebungsvariable wird zusammen mit einem neuen Flag -X disable-remote-debug zum Python-Interpreter hinzugefügt, damit Benutzer diese Funktion zur Laufzeit deaktivieren können.

Zusätzlich wird ein neues Flag --without-remote-debug zum configure-Skript hinzugefügt, damit Verteilungspartner Python ohne Unterstützung für Remote-Debugging erstellen können, wenn sie dies wünschen.

Ein neues Flag, das den Status des Remote-Debuggings anzeigt, wird über die Debug-Offsets verfügbar gemacht, damit Tools abfragen können, ob ein Remote-Prozess die Funktion deaktiviert hat. Auf diese Weise können Tools eine nützliche Fehlermeldung anbieten, die erklärt, warum sie nicht funktionieren, anstatt zu glauben, dass sie sich angehängt haben und ihr Skript nie ausgeführt wird.

Multithreading-Überlegungen

Das gesamte Ausführungsmuster ähnelt der internen Signalbehandlung von Python. Der Interpreter garantiert, dass injizierter Code nur an sicheren Punkten ausgeführt wird und niemals atomare Operationen innerhalb des Interpreters selbst unterbricht. Dieser Ansatz stellt sicher, dass Debugging-Operationen den Interpreter-Zustand nicht beschädigen können, während sie in den meisten realen Szenarien dennoch rechtzeitig ausgeführt werden.

Allerdings kann der durch diese Schnittstelle injizierte Debugging-Code in jedem Thread ausgeführt werden. Dieses Verhalten unterscheidet sich von der Signalbehandlung in Python, da Signal-Handler nur im Haupt-Thread ausgeführt werden können. Wenn ein Debugger Code in jeden laufenden Thread injizieren möchte, muss er ihn in jeden PyThreadState injizieren. Wenn ein Debugger Code im ersten verfügbaren Thread ausführen möchte, muss er ihn in jeden PyThreadState injizieren, und dieser injizierte Code muss prüfen, ob er bereits von einem anderen Thread ausgeführt wurde (wahrscheinlich durch Setzen eines Flags in den Globals eines Moduls).

Beachten Sie, dass der Global Interpreter Lock (GIL) die Ausführung wie gewohnt regelt, wenn der injizierte Code ausgeführt wird. Das bedeutet, wenn ein Ziel-Thread gerade eine C-Erweiterung ausführt, die den GIL kontinuierlich hält, kann der injizierte Code erst ausgeführt werden, wenn diese Operation abgeschlossen ist und der GIL verfügbar wird. Die Schnittstelle führt jedoch keine zusätzliche GIL-Konfliktgefahr ein, über das hinaus, was der injizierte Code selbst erfordert. Wichtig ist, dass die Schnittstelle vollständig kompatibel mit Pythons Free-Threading-Modus bleibt.

Es kann für einen Debugger, der Code zur Ausführung injiziert hat, nützlich sein, dies durch Senden eines vorregistrierten Signals an den Prozess zu verfolgen, das blockierende E/A- oder Schlafzustände, die auf externe Ressourcen warten, unterbrechen und eine sichere Gelegenheit zur Ausführung des injizierten Codes ermöglichen kann.

Szenarien zur Sicherheit

• Für einen externen Angreifer ist die Möglichkeit, beliebigen Speicher in einem Prozess zu schreiben, bereits ein schwerwiegendes Sicherheitsproblem. Diese Schnittstelle führt keine neue Angriffsfläche ein, da der Angreifer bereits die Möglichkeit hätte, beliebigen Code im Prozess auszuführen. Diese Schnittstelle verhält sich genau wie bestehende Debugger und führt keine zusätzlichen neuen Sicherheitsrisiken ein.
• Für einen Angreifer, der Zugriff auf beliebige Speicherbeschreibungen in einem Prozess erlangt hat, aber nicht auf beliebige Codeausführung, erlaubt diese Schnittstelle keine Eskalation. Die Fähigkeit, spezifische Speicheradressen zu berechnen und dorthin zu schreiben, ist erforderlich, was ohne die Kompromittierung anderer externer Ressourcen des Python-Prozesses nicht verfügbar ist.

Darüber hinaus bedeutet die Tatsache, dass der auszuführende Code durch die Audit-Hooks des Interpreters gesteuert wird, dass die Ausführung des Codes von Systemadministratoren überwacht und kontrolliert werden kann. Das bedeutet, dass selbst wenn der Angreifer die Anwendung **und das Dateisystem** kompromittiert hat, die Nutzung dieser Schnittstelle für böswillige Zwecke ein sehr riskantes Unterfangen für einen Angreifer darstellt, da er riskiert, seine Aktionen an Systemadministratoren preiszugeben, die den Angriff nicht nur erkennen, sondern auch Maßnahmen zu seiner Verhinderung ergreifen könnten.

Schließlich ist wichtig zu beachten, dass wenn ein Angreifer beliebigen Speicher Schreibzugriff auf einen Prozess hat und das Dateisystem kompromittiert hat, er bereits durch andere bestehende Mechanismen zur beliebigen Codeausführung eskalieren kann, so dass diese Schnittstelle in diesem Szenario keine neuen Risiken einführt.

Schreiben von Python-Code in den Puffer

Wir haben uns entschieden, dass Debugger den Pfad zu einer Datei mit Python-Code in einen Puffer im Remote-Prozess schreiben. Dies wurde als sicherer erachtet als das Schreiben des auszuführenden Python-Codes selbst in einen Puffer im Remote-Prozess, da es bedeutet, dass ein Angreifer, der beliebige Schreibrechte in einem Prozess, aber keine beliebige Codeausführung oder Dateisystemmanipulation erlangt hat, über diese Schnittstelle nicht zu beliebiger Codeausführung eskalieren kann.

Dies erfordert jedoch, dass der anhangende Debugger bei der Erstellung der Datei mit dem auszuführenden Code auf Dateisystemberechtigungen achtet. Wenn ein Angreifer die Möglichkeit hat, die Datei zu überschreiben oder einen Symlink im Dateipfad zu ersetzen, damit er auf etwas Angreifer-kontrolliertes verweist, könnte dies ihm erlauben, seinen bösartigen Code anstelle des vom Debugger beabsichtigten Codes auszuführen.

Verwendung eines einzigen Laufzeitpuffers

Während der Überprüfung dieser PEP wurde vorgeschlagen, einen einzigen gemeinsamen Puffer auf Runtime-Ebene für die gesamte Debugger-Kommunikation zu verwenden. Obwohl dies einfacher erschien und weniger Speicher benötigte, stellten wir fest, dass es Szenarien verhindern würde, in denen mehrere Debugger Operationen über verschiedene Threads hinweg koordinieren müssen oder wo ein einzelner Debugger komplexe Debugging-Operationen orchestrieren muss. Ein einziger gemeinsamer Puffer würde die Serialisierung aller Debugging-Operationen erzwingen und es Debuggern unmöglich machen, unabhängig an verschiedenen Threads zu arbeiten.

Der Ansatz mit pro-Thread-Puffern ermöglicht trotz seines Speicher-Overheads in stark verschachtelten Anwendungen diese wichtigen Debugging-Szenarien, indem er es jedem Debugger ermöglicht, unabhängig mit seinem Ziel-Thread zu kommunizieren.