遠端偵錯附加協議¶

此協議使外部工具能夠附加到正在執行的 CPython 行程並遠端執行 Python 程式碼。

大多數平台上都會需要更高的權限才能附加到另一個 Python 行程。

權限需求¶

在大多數平台上，附加到正在執行的 Python 行程進行遠端偵錯需要更高的權限。具體要求和疑難排解步驟會取決於你的作業系統：

Linux

執行追蹤的行程 (tracer process) 必須具有CAP_SYS_PTRACE 功能或同等權限。你只能追蹤你擁有且可以發送訊號的行程。如果行程已經被追蹤，或者它以 set-user-ID 或 set-group-ID 執行，則追蹤可能會失敗。像 Yama 這樣的安全模組可能會進一步限制追蹤。

要暫時放寬 ptrace 限制（直到重新開機），請執行：

echo0|sudotee/proc/sys/kernel/yama/ptrace_scope

如果在容器內執行，請使用--cap-add=SYS_PTRACE 或--privileged，並在需要時以 root 身分執行。

嘗試使用提升後的權限重新執行命令：

sudo-E!!

macOS

要附加到另一個行程，你通常需要以提升過的權限來執行偵錯工具。這可以透過使用sudo 或以 root 身分執行來完成。

即使附加到你擁有的行程，macOS 也可能會阻止偵錯，除非偵錯器以 root 權限執行，這是由於系統安全限制。

Windows

要附加到另一個行程，你通常需要以系統管理員權限執行偵錯工具。以系統管理員身分啟動命令提示字元或終端機。

即使具有系統管理員權限，某些行程仍可能無法存取，除非你啟用了SeDebugPrivilege 權限。

要解決檔案或資料夾存取問題，請調整安全權限：

1. 右鍵點擊檔案或資料夾並選擇Properties。

2. 前往Security 分頁以檢視具有存取權限的使用者和群組。

3. 點擊Edit 以修改權限。

4. 選擇你的使用者帳戶。

5. 在Permissions 中，視需要勾選Read 或Full control。

6. 點擊Apply，然後點擊OK 來確認。

本節描述了低階協議，使外部工具能夠在正在執行的 CPython 行程中注入並執行 Python 腳本。

此機制構成了sys.remote_exec() 函式的基礎，該函式指示遠端 Python 行程執行.py 檔案。但本節不記錄該函式的用法，而是提供底層協議的詳細說明，該協議以目標 Python 行程的pid 和要執行的 Python 原始檔路徑作為輸入。此資訊支援該協議的獨立重新實作，無論使用何種程式語言。

一旦注入，腳本將在下次到達安全執行點時會由目標行程內的直譯器執行。這種方法使遠端執行功能成為可能，而不需修改正在執行的 Python 應用程式的行為或結構。

後續章節提供了協議的逐步描述，包括在記憶體中定位直譯器結構、安全存取內部欄位以及觸發程式碼執行的技術。在適用的情況下會註明平台特有的變化，並包含範例實作以闡明每個操作。

定位 PyRuntime 結構¶

CPython 將PyRuntime 結構放置在專用的二進位區段（section）中，以幫助外部工具在 runtime 找到它。此區段的名稱和格式因平台而異。例如，ELF 系統使用.PyRuntime、macOS 使用__DATA,__PyRuntime。工具可以透過檢查磁碟上的二進位檔案來找到此結構的偏移量。

PyRuntime 結構包含 CPython 的全域直譯器狀態，並可存取其他內部資料，包括直譯器清單、執行緒狀態和偵錯器支援欄位。

要與遠端 Python 行程協作，偵錯器必須首先找到目標行程中PyRuntime 結構的記憶體位址。此位址無法寫死或從符號名稱計算出，因為它取決於作業系統載入二進位檔案的位置。

尋找PyRuntime 的方法取決於平台，但步驟大致相同：

1. 找到目標行程中 Python 二進位檔案或共享函式庫被載入的基底位址。

2. 使用磁碟上的二進位檔案來定位.PyRuntime 區段的偏移量。

3. 將區段偏移量加到基底位址以計算記憶體中的位址。

以下各節說明如何在每個支援的平台上執行此操作，並包含範例程式碼。

Linux (ELF)

在 Linux 上尋找PyRuntime 結構：

1. 讀取行程的記憶體對映（例如/proc/<pid>/maps）以找到 Python 可執行檔位址或libpython 被載入的位址。

2. 剖析二進位檔案中的 ELF 區段標頭以取得.PyRuntime 區段的偏移量。

3. 將該偏移量加到步驟 1 的基底位址以取得PyRuntime 的記憶體位址。

以下是一個範例實作：

deffind_py_runtime_linux(pid:int)->int:# 步驟 1：嘗試在記憶體中找到 Python 可執行檔binary_path,base_address=find_mapped_binary(pid,name_contains="python")# 步驟 2：如果找不到可執行檔，則改用共享函式庫ifbinary_pathisNone:binary_path,base_address=find_mapped_binary(pid,name_contains="libpython")# 步驟 3：剖析 ELF 標頭以取得 .PyRuntime 區段偏移量section_offset=parse_elf_section_offset(binary_path,".PyRuntime")# 步驟 4：計算 PyRuntime 在記憶體中的位址returnbase_address+section_offset

在 Linux 系統上，有兩種主要方法可以從另一個行程讀取記憶體。第一種是透過/proc 檔案系統，特別是從/proc/[pid]/mem 讀取，這提供了對行程記憶體的直接存取。這需要適當的權限 - 要麼與目標行程是同一使用者，要麼就要擁有 root 存取權限。第二種方法是使用process_vm_readv() 系統呼叫，它提供了在行程之間複製記憶體的更有效方式。雖然 ptrace 的PTRACE_PEEKTEXT 操作也可以用來讀取記憶體，但它明顯較慢，因為它一次只讀取一個字，並且需要追蹤器和被追蹤行程之間的多次情境切換。

對於剖析 ELF 區段，該過程涉及從磁碟上的二進位檔案讀取並解釋 ELF 檔案格式結構。ELF標頭包含指向區段標頭表的指標。每個區段標頭包含關於區段的中介資料，包括其名稱（儲存在單獨的字串表中）、偏移量和大小。要找到像 .PyRuntime 這樣的特定區段，你需要遍歷這些標頭並匹配區段名稱。然後區段標頭會提供該區段在檔案中存在的偏移量，當二進位檔案載入到記憶體時，可以用它來計算 runtime 位址。

你可以在ELF 規範中閱讀更多關於 ELF 檔案格式的資訊。

macOS (Mach-O)

在 macOS 上找PyRuntime 結構：

1. 呼叫task_for_pid() 以取得目標行程的mach_port_t 任務埠 (task port)。此控制代碼 (handle) 用於使用像mach_vm_read_overwrite 和mach_vm_region 這樣的 API 來讀取記憶體。

2. 掃描記憶體區域以找到包含 Python 可執行檔或libpython 的區域。

3. 從磁碟載入二進位檔案並剖析 Mach-O 標頭以找到__DATA 程式段（segment）中名為PyRuntime 的區段。在 macOS 上，符號名稱會自動加上底線前綴，因此PyRuntime 符號在符號表中顯示為_PyRuntime，但區段名稱不受影響。

以下是一個範例實作：

deffind_py_runtime_macos(pid:int)->int:# 步驟 1：取得對行程記憶體的存取權限handle=get_memory_access_handle(pid)# 步驟 2：嘗試在記憶體中找到 Python 可執行檔binary_path,base_address=find_mapped_binary(handle,name_contains="python")# 步驟 3：如果找不到可執行檔，則改用 libpythonifbinary_pathisNone:binary_path,base_address=find_mapped_binary(handle,name_contains="libpython")# 步驟 4：剖析 Mach-O 標頭以取得 __DATA,__PyRuntime 區段偏移量section_offset=parse_macho_section_offset(binary_path,"__DATA","__PyRuntime")# 步驟 5：計算 PyRuntime 在記憶體中的位址returnbase_address+section_offset

在 macOS 上，存取另一個行程的記憶體需要使用 Mach-O 特定的 API 和檔案格式。第一步是透過task_for_pid() 取得task_port 控制代碼，它提供對目標行程記憶體空間的存取。此控制代碼透過像mach_vm_read_overwrite() 這樣的 API 啟用記憶體操作。

可以使用mach_vm_region() 掃描虛擬記憶體空間來檢查行程記憶體，而proc_regionfilename() 幫助識別在每個記憶體區域載入了哪些二進位檔案。當找到 Python 二進位檔案或函式庫時，需要剖析其 Mach-O 標頭以定位PyRuntime 結構。

Mach-O 格式將程式碼和資料組織成程式段和區段。PyRuntime 結構位於__DATA 程式段內名為__PyRuntime 的區段中。實際的 runtime 位址計算涉及找到作為二進位檔案基底位址的__TEXT 程式段，然後定位包含我們目標區段的__DATA 程式段。最終位址是透過將基底位址與來自 Mach-O 標頭的適當區段偏移量組合來計算的。

請注意，在 macOS 上存取另一個行程的記憶體通常需要提升過後的權限 - 要麼是 root 存取權限，要麼是授予偵錯行程的特殊安全授權。

Windows (PE)

在 Windows 上找PyRuntime 結構：

1. 使用 ToolHelp API 來列舉目標行程中載入的所有模組。這是使用諸如CreateToolhelp32Snapshot、Module32First 和Module32Next 等函式來完成的。

2. 識別對應於python.exe 或pythonXY.dll 的模組，其中X 和Y 是Python 版本的主要和次要版本號，並記錄其基底位址。

3. 定位PyRuntim 區段。由於 PE 格式對區段名稱有 8 個字元的限制（定義為IMAGE_SIZEOF_SHORT_NAME），所以原始名稱PyRuntime 會被截斷。此區段包含PyRuntime 結構。

4. 檢索區段的相對虛擬位址 (RVA, relative virtual address) 並將其加到模組的基底位址。

以下是一個範例實作：

deffind_py_runtime_windows(pid:int)->int:# 步驟 1：嘗試在記憶體中找到 Python 可執行檔binary_path,base_address=find_loaded_module(pid,name_contains="python")# 步驟 2：如果找不到可執行檔，則改用共享函式庫 pythonXY.dllifbinary_pathisNone:binary_path,base_address=find_loaded_module(pid,name_contains="python3")# 步驟 3：剖析 PE 區段標頭以取得 PyRuntime 區段的 RVA。# 由於 PE 格式 (IMAGE_SIZEOF_SHORT_NAME) 有8 字元的限制，# 區段名稱顯示為 "PyRuntim"。section_rva=parse_pe_section_offset(binary_path,"PyRuntim")# 步驟 4：計算 PyRuntime 在記憶體中的位址returnbase_address+section_rva

在 Windows 上，存取另一個行程的記憶體需要使用像CreateToolhelp32Snapshot() 和Module32First()/Module32Next() 這樣的 Windows API 函式來列舉載入的模組。OpenProcess() 函式提供一個控制代碼來存取目標行程的記憶體空間，並透過ReadProcessMemory() 啟用記憶體操作。

可以透過列舉載入的模組來檢查行程記憶體，以找到 Python 二進位檔案或 DLL。找到後，需要剖析其 PE 標頭以定位PyRuntime 結構。

PE 格式將程式碼和資料組織成區段。PyRuntime 結構位於名為 "PyRuntim" 的區段中（由於 PE 的 8 字元名稱限制，從 "PyRuntime" 截斷）。實際的 runtime 位址計算涉及從模組項目中找到模組的基底位址，然後在 PE 標頭中定位我們的目標區段。最終位址是透過將基底位址與 PE 區段標頭中的區段虛擬位址組合來計算的。

請注意，在 Windows 上存取另一個行程的記憶體通常需要適當的權限 - 要麼是系統管理員存取權限，要麼是授予偵錯行程的SeDebugPrivilege 權限。

讀取 _Py_DebugOffsets¶

一旦確定了PyRuntime 結構的位址，下一步就是讀取位於PyRuntime 區塊開頭的_Py_DebugOffsets 結構。

此結構提供了安全讀取直譯器和執行緒狀態記憶體所需的版本特定欄位偏移量。這些偏移量在不同的 CPython 版本之間有所不同，必須在使用前檢查以確保它們相容。

要讀取並檢查偵錯偏移量，請按照以下步驟操作：

1. 從目標行程中的PyRuntime 位址開始讀取記憶體，涵蓋與_Py_DebugOffsets 結構相同的位元組數。此結構位於PyRuntime 記憶體區塊的最開始處。其佈局 (layout) 在 CPython 的內部標頭中定義，並在給定的次要版本中維持不變，但在主要版本中可能會更改。

2. 檢查結構是否包含有效資料：

   • cookie 欄位必須匹配預期的偵錯標記。

   • version 欄位必須匹配偵錯器使用的 Python 直譯器版本。

   • 如果偵錯器或目標行程使用的是預發行版本（例如 alpha、beta 或候選版本），版本必須完全匹配。

   • free_threaded 欄位在偵錯器和目標行程中必須具有相同的值。

3. 如果結構有效，其中包含的偏移量可用於定位記憶體中的欄位。如果任何檢查失敗，偵錯器應停止操作以避免以錯誤的格式讀取記憶體。

以下是一個讀取並檢查_Py_DebugOffsets 的範例實作：

defread_debug_offsets(pid:int,py_runtime_addr:int)->DebugOffsets:# 步驟 1：在 PyRuntime 位址從目標行程讀取記憶體data=read_process_memory(pid,address=py_runtime_addr,size=DEBUG_OFFSETS_SIZE)# 步驟 2：將原始位元組反序列化為 _Py_DebugOffsets 結構debug_offsets=parse_debug_offsets(data)# 步驟 3：驗證結構的內容ifdebug_offsets.cookie!=EXPECTED_COOKIE:raiseRuntimeError("Invalid or missing debug cookie")ifdebug_offsets.version!=LOCAL_PYTHON_VERSION:raiseRuntimeError("Mismatch between caller and target Python versions")ifdebug_offsets.free_threaded!=LOCAL_FREE_THREADED:raiseRuntimeError("Mismatch in free-threaded configuration")returndebug_offsets

定位直譯器和執行緒狀態¶

在可以於遠端 Python 行程中注入並執行程式碼之前，偵錯器必須選擇一個用於排程執行的執行緒。這是必要的，因為用於執行遠端程式碼注入的控制欄位位於_PyRemoteDebuggerSupport 結構中，該結構嵌入在PyThreadState 物件中。偵錯器會修改這些欄位以請求執行注入的腳本。

PyThreadState 結構代表在 Python 直譯器內執行的執行緒。它維護執行緒的求值情境 (evaluation context)，並包含偵錯器協調所需的欄位。因此，定位有效的PyThreadState 是遠端觸發執行的關鍵前提。

通常根據執行緒的角色或 ID 來選擇執行緒。在大多數情況下會使用主執行緒，但某些工具可能會透過其原生執行緒 ID 來定位特定執行緒。一旦選擇了目標執行緒，偵錯器必須在記憶體中定位直譯器和相關的執行緒狀態結構。

相關的內部結構定義如下：

• PyInterpreterState 代表一個隔離的 Python 直譯器實例。每個直譯器維護自己的一組已引入模組、內建狀態和執行緒狀態串列。雖然大多數 Python 應用程式使用單一直譯器，但 CPython 支援在同一行程中使用多個直譯器。

• PyThreadState 代表在直譯器內運行的執行緒。它包含執行狀態和偵錯器使用的控制欄位。

要定位執行緒：

1. 使用偏移量runtime_state.interpreters_head 來取得PyRuntime 結構中第一個直譯器的位址。這是活動直譯器鏈結串列的進入點。

2. 使用偏移量interpreter_state.threads_main 來存取與所選直譯器相關的主執行緒狀態。這通常是最可靠的目標執行緒。

3. 可選地使用偏移量interpreter_state.threads_head 來遍歷所有執行緒狀態的鏈結串列。每個PyThreadState 結構包含一個native_thread_id 欄位，可以將其與目標執行緒 ID 進行比較以找到特定執行緒。

4. 一旦找到有效的PyThreadState，其位址可以在協議的後續步驟中使用，例如寫入偵錯器控制欄位和排程執行。

以下是一個定位主執行緒狀態的範例實作：

deffind_main_thread_state(pid:int,py_runtime_addr:int,debug_offsets:DebugOffsets,)->int:# 步驟 1：從 PyRuntime 讀取 interpreters_headinterp_head_ptr=(py_runtime_addr+debug_offsets.runtime_state.interpreters_head)interp_addr=read_pointer(pid,interp_head_ptr)ifinterp_addr==0:raiseRuntimeError("No interpreter found in the target process")# 步驟 2：從直譯器讀取 threads_main 指標threads_main_ptr=(interp_addr+debug_offsets.interpreter_state.threads_main)thread_state_addr=read_pointer(pid,threads_main_ptr)ifthread_state_addr==0:raiseRuntimeError("Main thread state is not available")returnthread_state_addr

以下範例示範如何透過原生執行緒 ID 來定位執行緒：

deffind_thread_by_id(pid:int,interp_addr:int,debug_offsets:DebugOffsets,target_tid:int,)->int:# 從 threads_head 開始並遍歷鏈結串列thread_ptr=read_pointer(pid,interp_addr+debug_offsets.interpreter_state.threads_head)whilethread_ptr:native_tid_ptr=(thread_ptr+debug_offsets.thread_state.native_thread_id)native_tid=read_int(pid,native_tid_ptr)ifnative_tid==target_tid:returnthread_ptrthread_ptr=read_pointer(pid,thread_ptr+debug_offsets.thread_state.next)raiseRuntimeError("Thread with the given ID was not found")

一旦定位到有效的執行緒狀態，偵錯器就可以繼續修改其控制欄位並排程執行，如下一節所述。

寫入控制資訊¶

一旦識別出有效的PyThreadState 結構，偵錯器就可以修改其中的控制欄位以排程執行指定的 Python 腳本。直譯器會定期檢查這些控制欄位，當正確設定時，它們會在求值迴圈中的安全點觸發遠端程式碼的執行。

每個PyThreadState 都包含一個_PyRemoteDebuggerSupport 結構，能用於偵錯器和直譯器之間的通訊。其欄位的位置由_Py_DebugOffsets 結構定義，包括以下內容：

• debugger_script_path：一個固定大小的緩衝區，用於保存 Python 原始檔（.py）的完整路徑。觸發執行時，目標行程必須能夠存取和讀取此檔案。

• debugger_pending_call：一個整數旗標。將其設定為1 會告訴直譯器腳本已準備好執行。

• eval_breaker：直譯器在執行期間檢查的欄位。在此欄位中設定位元 5（_PY_EVAL_PLEASE_STOP_BIT，值1U<<5）會導致直譯器暫停並檢查偵錯器活動。

要完成注入，偵錯器必須執行以下步驟：

1. 將完整的腳本路徑寫入debugger_script_path 緩衝區。

2. 將debugger_pending_call 設定為1。

3. 讀取eval_breaker 目前的值，設定位元 5（_PY_EVAL_PLEASE_STOP_BIT）並將更新後的值寫回。這會向直譯器發出檢查偵錯器活動的訊號。

以下是一個範例實作：

definject_script(pid:int,thread_state_addr:int,debug_offsets:DebugOffsets,script_path:str)->None:# 計算 _PyRemoteDebuggerSupport 的基底偏移量support_base=(thread_state_addr+debug_offsets.debugger_support.remote_debugger_support)# 步驟 1：將腳本路徑寫入 debugger_script_pathscript_path_ptr=(support_base+debug_offsets.debugger_support.debugger_script_path)write_string(pid,script_path_ptr,script_path)# 步驟 2：將 debugger_pending_call 設定為 1pending_ptr=(support_base+debug_offsets.debugger_support.debugger_pending_call)write_int(pid,pending_ptr,1)# 步驟 3：在 eval_breaker 中設定 _PY_EVAL_PLEASE_STOP_BIT（位元 5，值為 1 << 5）eval_breaker_ptr=(thread_state_addr+debug_offsets.debugger_support.eval_breaker)breaker=read_int(pid,eval_breaker_ptr)breaker|=(1<<5)write_int(pid,eval_breaker_ptr,breaker)

一旦設定了這些欄位，偵錯器就可以恢復行程（如果它先被暫停了）。直譯器將在下一個安全執行點處理請求、從磁碟載入腳本並執行它。

偵錯器有責任確保腳本檔案在執行期間仍然存在且可供目標行程存取。

摘要¶

要在遠端行程中注入並執行 Python 腳本：

1. 在目標行程的記憶體中定位PyRuntime 結構。

2. 讀取並驗證PyRuntime 開頭的_Py_DebugOffsets 結構。

3. 使用偏移量來定位有效的PyThreadState。

4. 將 Python 腳本的路徑寫入debugger_script_path。

5. 將debugger_pending_call 旗標設定為1。

6. 在eval_breaker 欄位中設定_PY_EVAL_PLEASE_STOP_BIT。

7. 恢復行程（如果已暫停）。腳本將在下一個安全執行點執行。