Debugger with AI Integration for Linux ELF x86_64 executables

A debugger built with ptrace that integrates with Ollama for AI-powered code analysis and explanation.

Color Key:

Cyan for AI responses Red for machine code/disassembly White for debugger text

Project Overview

mxdbg is a debugger that provides comprehensive debugging capabilities for x86_64 Linux systems. Built using ptrace system calls, it offers traditional debugging features enhanced with AI-powered code analysis through Ollama integration.

Note: This project is currently in development. Some features are still being implemented.

Features

Process Control

Launch or attach to processes with full debugging capabilities

Register Manipulation

Read and write 64-bit, 32-bit, 16-bit, and 8-bit registers

Memory Operations

Read and write process memory with byte-level precision

Breakpoint Management

Set, remove, and handle breakpoints efficiently

Single Stepping

Execute instructions one at a time with full control

Disassembly

View disassembled code using objdump integration

AI Integration

Get AI-powered explanations of disassembly and code behavior

Interactive Shell

Readline-based command interface with history

Installation

Dependencies

CMake 3.20+: Build system
C++20 compatible compiler: GCC 10+ or Clang 10+
readline: For interactive command line interface
ollama_gen: AI integration library for Ollama communication
Standard Linux tools: objdump, ptrace support

Environment Setup

To use AI integration features, export these environment variables:

export MXDBG_HOST="localhost"    # Your Ollama server URL
export MXDBG_MODEL="llama2"      # Your preferred Ollama model

Building

git clone https://github.com/lostjared/ollama_gen.git
git clone https://github.com/lostjared/mxdbg.git 
cd ollama_gen
mkdir build
cd build
cmake ..
cmake --build .
sudo cmake --install .
cd ../../
cd mxdbg
mkdir build
cd build
cmake ..
cmake --build .
sudo cmake --install .
cd ../../

Installation

sudo cmake --install  .

Uninstall

sudo make uninstall

Usage

Basic Usage

# Launch a program for debugging
mxdbg /path/to/program

# Attach to an existing process
mxdbg -p <PID>

# Dump assembly of a binary
mxdbg -d /path/to/binary

Command Line Options

-p <PID>: Attach to process with given PID
--pid <PID>: Same as -p (long form)
--path <path>: Launch executable at path
-r <path>: Same as -R (short form)
--args <args>: Additional arguments for the launched process
-a <args>: Same as -A (short form)
-e: Dump assembly of executable
-d: Disable AI
--disable-ai: Disable AI

Interactive Commands

Once in the debugger shell (mx $>), you can use the following commands:

Expression & Variables

expr <e> Evaluate expression

setval <name> <value> Set variable to value

listval List variables

Process Control

run, r Run program (sets main breakpoint)

continue, c Continue process execution

step, s Execute single instruction

step N, s N Execute N instructions

next Step over function calls

finish, step_out Step out of current function

until <addr>, run_until <addr> Run until specific address

status, st Show process status

start, restart Restart the program

Threading

thread Show current thread

thread <id> Switch to thread context

threads List all running threads

debug_thread <id> Debug specific thread

Code Analysis

cur, current Print current instruction

list Display full disassembly

list_less Display disassembly with pager

list_function <name> Show specific function disassembly

base Show base address and current PC

backtrace, bt, where Show call stack backtrace

Registers

registers, regs Show all registers

register <name>, reg <name> Show specific register value

register32 <name> Show 32-bit register

register16 <name> Show 16-bit register

register8 <name> Show 8-bit register

set <reg> <value> Set register to value

Breakpoints & Watchpoints

break <addr>, b <addr> Set breakpoint at address

function <name> Set breakpoint at function

list_break, lb List all breakpoints

remove <addr/index>, rmv Remove breakpoint

watch <addr> <size> [type] Set watchpoint (type: read/write/access)

watchpoints, wp List watchpoints

Conditional Breakpoints

break_if <addr> <condition> Set conditional breakpoint that only triggers when condition is true

FPU/Float Registers

get_fpu <name> Get FPU register value

set_fpu <name> <value> Set FPU register to value

list_fpu List all FPU registers

Memory Operations

read <addr> Read 8 bytes from memory address

read_bytes <addr> <size> Read specific number of bytes

write <addr> <value> Write value to memory address

write_bytes <addr> <bytes> Write byte sequence to memory

maps, memory_maps Show memory map

local <reg> <offset> <size> Read local variable on stack

hexdump <addr> <size> Display memory as hexadecimal dump

as_bytes <value> Convert value to byte representation

Memory Search

search int <value> Search for 32-bit integer in memory

search int64 <value> Search for 64-bit integer in memory

search string <text> Search for string in memory

search bytes <hex bytes> Search for byte pattern

search pattern <pattern> Search with wildcards (e.g., 41??43)

Stack Analysis

stack_frame Analyze current stack frame

AI Features

explain <function> Explain function disassembly with AI

ask <question> Ask the AI a question about the program

mode <level>, user <level> Set AI difficulty (beginner/programmer/expert)

Utility

find <text> Find text in disassembly using grep

debug_state Show detailed debug state

help, h Show this help message

quit, q, exit Exit debugger

info files Show open file descriptors

shell <command>, sh <command> Execute shell command

clear Clear the screen

AI Integration

When MXDBG_HOST and MXDBG_MODEL are set, the debugger provides:

AI Explanations

Get detailed explanations of code behavior when stepping through programs

Disassembly Analysis

Analyze disassembly output with the explain command

Context-Aware Assistance

Ask questions about the code using the ask command

Adaptive Learning

Set your experience level to get explanations tailored to your knowledge

Supported Registers

64-bit Registers

rax, rbx, rcx, rdx, rsi, rdi, rbp, rsp, rip, r8-r15

32-bit Registers

eax, ebx, ecx, edx, esi, edi, ebp, esp, r8d-r15d

16-bit Registers

ax, bx, cx, dx, si, di, bp, sp, r8w-r15w

8-bit Registers

al, ah, bl, bh, cl, ch, dl, dh, sil, dil, bpl, spl, r8b-r15b

Examples

Debug a Simple Program

# Compile a test program
gcc -g -o test test.c

# Launch in debugger
mxdbg ./test

# In debugger shell:
mx $> run
mx $> step
mx $> step
mx $> registers
mx $> read 0x400000

Attach to Running Process

# Find process ID
ps aux | grep myprogram

# Attach debugger
mxdbg -p 1234

# Debug the running process
mx $> registers
mx $> step
mx $> list
mx $> explain main