Skip to content

Native Linux Adapter - #1237

Open
UvuvDev wants to merge 6 commits into
devfrom
native-linux-adapter
Open

UvuvDev wants to merge 6 commits into
devfrom
native-linux-adapter

Conversation

@UvuvDev

@UvuvDev UvuvDev commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Adds a native ptrace debug adapter for local Linux x86 and x86-64 targets. Supports launch/attach, registers and memory, software/hardware breakpoints, module and symbol inspection, stepping, fork/exec handling, descriptor redirects and syscall stops.

@UvuvDev UvuvDev self-assigned this Nov 4, 2026
@UvuvDev

UvuvDev commented Nov 4, 2026

Copy link
Copy Markdown
Member Author

Looking over the tests, the agent wrote .sh scripts in order to test the ptrace engine alone without needing to relink Binary Ninja. Not a good strategy so I will be keeping the C++ test cases, move compilation into CMake, and replace the .sh runners with pytest, stress and sanitizer runs should be separate configurations, with the regression suite wired into CI.

I also do not like the amount of files. It's not necessarily a dealbreaker but there is quite a lot of files. Maybe some can be consolidated, or the architecture might be more suited to this and we just reorganize the directories.

@UvuvDev

UvuvDev commented Nov 4, 2026

Copy link
Copy Markdown
Member Author

Changed the test suite. I also do not like the ELF custom parser that is put in: I would prefer to use Binary Ninja primitives if possible. However, I don't know if all of the data we need can be obtained from Binary Ninja.


namespace BinaryNinjaDebugger {

BNDebugStopReason StopReasonFromLinuxSignal(int signal)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure whether a giant switch statement here is better than something like:

static constexpr auto signalReasons = [] {
    std::array<BNDebugStopReason, NSIG> reasons{};
    reasons.fill(UnknownReason);

    reasons[SIGHUP]  = SignalHup;
    reasons[SIGINT]  = SignalInt;
    reasons[SIGILL]  = IllegalInstruction;
    reasons[SIGSEGV] = SignalSegv;
    // Remaining mappings follow the same pattern.
    return reasons;
}();

BNDebugStopReason StopReasonFromLinuxSignal(int signal)
{
    auto index = static_cast<size_t>(signal);
    return index < signalReasons.size()
        ? signalReasons[index] : UnknownReason;
}

My gut tells me that the switch is better. K.I.S.S.

@xusheng6

xusheng6 commented Nov 4, 2026

Copy link
Copy Markdown
Member

I am not sure if this is meant for review, or just for me to see the code, but I am not a big fan of how the code is currently structured. There are way too many files. Ideally we should have one .cpp/.h file for ptrace debugging, and one .cpp/.h for the debug adapter. There isn't a need to further separate them into smaller files

@UvuvDev
UvuvDev marked this pull request as draft November 4, 2026 19:15
@UvuvDev

UvuvDev commented Nov 5, 2026

Copy link
Copy Markdown
Member Author

I put ptrace and the tests in subdirectories. so that looks a lot better now.


// Generated from asm/unistd_64.h and asm/unistd_32.h of Linux 6.8, sorted by number
const SyscallEntry g_x86_64[] = {
{0, "read"}, {1, "write"}, {2, "open"}, {3, "close"},

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should definitely be a better way to do this than hardcoding all of these into the CPP file. Is there a Linux header that might define these? Maybe we do a JSON file instead?

@UvuvDev
UvuvDev force-pushed the native-linux-adapter branch 2 times, most recently from ea37cc7 to 513e8ad Compare November 5, 2026 18:16
@UvuvDev
UvuvDev marked this pull request as ready for review November 5, 2026 18:34
@xusheng6
xusheng6 self-requested a review November 5, 2026 19:59
@UvuvDev
UvuvDev force-pushed the native-linux-adapter branch 5 times, most recently from 274488e to 17c1912 Compare November 10, 2026 17:06
@UvuvDev

UvuvDev commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

I believe this is ready for an actual review.

@UvuvDev
UvuvDev force-pushed the native-linux-adapter branch from 17c1912 to 226cfa5 Compare November 10, 2026 21:50
@xusheng6

Copy link
Copy Markdown
Member

I believe this is ready for an actual review.

Could you create a test_xxx branch and make sure it passes through our current CI? I see the branch is now named native-linux-adapter

@UvuvDev
UvuvDev force-pushed the native-linux-adapter branch from 226cfa5 to 17c1912 Compare November 16, 2026 13:56
Register the native PTRACE adapter on Linux. Introduce tracer, event and
terminal I/O threads, marshal ptrace requests to the tracer, and support
launch, continue, interrupt and termination.

Describe x86/x86-64 register layouts, access register sets through ptrace,
and read/write target memory through /proc/<pid>/mem.
Install software traps while preserving original bytes, and program x86
hardware breakpoints/watchpoints. Keep module-relative breakpoints pending
until their modules load.

Read process maps, ELF metadata and symbols, expose frame-pointer backtraces,
and track the dynamic loader. Implement step-over and step-return with
temporary breakpoints matched to the initiating thread and frame.
Attach to running processes, apply ordered descriptor redirects, initialize
the terminal and reap detached launch targets. Release fork/vfork children
safely and reconcile target state, symbols and breakpoints across exec.

Handle Linux signal stops and target-generated traps, optionally stop at
signal handlers, and preserve stopped state on failed operations. Expose
syscall tracing/emulation, console commands and adapter properties; derive
register aliases from the Binary Ninja architecture.
Put deadlines on waits and report unresponsive threads. Bound and batch
terminal output, drain shutdown output, and handle teardown from an event
handler or while a handler is blocked.

Check ptrace operations that maintain thread/breakpoint invariants. Centralize
breakpoint suspension/restoration, retain failed restores for retry, and
abort detach when cleanup fails. Release non-thread clones and only claim
hardware traps from active slots.
Replace manual ELF decoding with pinned, header-only ELFIO, preserving symbol
semantics and validating malformed metadata. Wire production and test builds
to its submodule and package its MIT notice.

Build standalone engine/fault drivers and fixtures with CMake. Run isolated
pytest scenarios with deadlines and descendant cleanup, including readelf
comparisons, malformed ELF, register layouts and adapter integration. Add
sanitizer/stress options, Linux CI integration and Python adapter settings.
Drain adapter callbacks before session replacement/controller destruction.
Allow PTRACE to queue public callbacks without waiting while preserving
synchronous controller state and stop-channel updates.

Keep breakpoint bytes consistent after partial writes, close pause races,
tag debugger interrupts, reset inherited launch signals, check automatic
resumes and retain failed temporary-breakpoint cleanup. Resolve module
instances by unique short name. Add regressions to the required suite.

Document architecture, guarantees, limitations and the build/test workflow.

Drop resume operations queued before Quit, Restart or Detach. Report process exit when a thread's death or an external kill takes the group down, and do not deliver a SIGTRAP that the target never raised. Do not count a refused resume as one, leave a forked child frozen or carrying the debugger's breakpoints, or let a dead target look alive. Fix the data races found by ThreadSanitizer, split command lines like a shell, and add the fault-injection and differential fuzzing tooling.
@UvuvDev
UvuvDev force-pushed the native-linux-adapter branch from 17c1912 to 4309cc9 Compare November 16, 2026 19: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.

2 participants