Skip to content

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Sep 11, 2025

This PR documents the newly discovered capability to debug Windows PE executables on Linux using wine + winedbg + Binary Ninja's LLDB adapter.

Based on testing by @xusheng6, Windows PE files can be successfully debugged on Linux by using wine's built-in winedbg debugger as a bridge to Binary Ninja's LLDB adapter. This provides a practical solution for debugging Windows executables without requiring a Windows VM or dual-boot setup.

Changes Made

Updated Compatibility Matrix

  • Added new row "Windows PE (via wine)" showing "Yes (Local)" support for Linux hosts
  • Updated both README.md and docs/guide/index.md consistently
  • Added footnote linking to comprehensive setup documentation

New Wine Debugging Guide

Created docs/guide/wine-debugging.md with complete documentation including:

  • Setup instructions: How to launch winedbg in GDB server mode
    winedbg --gdb --port 31337 --no-start ./program.exe
  • Binary Ninja configuration: How to connect LLDB adapter using gdb-remote process plugin
  • Known limitations: Documented the stepping-over issue at main function start
  • Workarounds: Use step into (F7) or breakpoints instead of step over (F8) at main start
  • Troubleshooting: Common issues and solutions
  • Advanced usage: Multiple sessions, wine prefixes, etc.

Technical Details

The solution works by:

  1. Running the Windows PE under wine
  2. Using winedbg --gdb to expose a GDB remote protocol server
  3. Connecting Binary Ninja's LLDB adapter to this server via gdb-remote plugin
  4. Debugging proceeds normally with full Binary Ninja UI support

Performance: Comparable to GDB, slightly slower than native debugging but fully functional.

Compatibility: Works with both 32-bit and 64-bit Windows PE files that can run under wine.

This addresses a significant capability gap and enables cross-platform debugging scenarios that were previously difficult or impossible.

Fixes #525.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

1 similar comment
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@Copilot Copilot AI changed the title [WIP] Update docs and compatablity matrix for debugging Windows PE running under wine with LLDB adapter Add support for debugging Windows PE files on Linux via wine Sep 11, 2025
@Copilot Copilot AI requested a review from xusheng6 September 11, 2025 08:06
Copilot finished work on behalf of xusheng6 September 11, 2025 08:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Update docs and compatablity matrix for debugging Windows PE running under wine with LLDB adapter
3 participants