https://github.com/lostjared/mxdbg
ELF x86_64 Debugger for Linux with AI (via ollama)
https://github.com/lostjared/mxdbg
ai debugger linux x64
Last synced: about 1 month ago
JSON representation
ELF x86_64 Debugger for Linux with AI (via ollama)
- Host: GitHub
- URL: https://github.com/lostjared/mxdbg
- Owner: lostjared
- License: gpl-3.0
- Created: 2025-06-15T06:26:07.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-18T13:45:39.000Z (11 months ago)
- Last Synced: 2025-09-05T06:09:28.702Z (9 months ago)
- Topics: ai, debugger, linux, x64
- Language: C++
- Homepage: https://lostsidedead.biz/mxdbg/
- Size: 1.36 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mxdbg - ELF x86_64 Debugger with AI Integration
coded by Jared Bruni (jaredbruni@protonmail.com)
A modern C++ debugger built with ptrace that integrates with Ollama for AI-powered code analysis and explanation.
## Color Key
- Cyan for AI
- Red for machine code/disassembly
- White for debugger text
# Not complete, some features still need to be implemented. This is a new project.
## 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
- **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
## Dependencies
### Required 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
### Installing ollama_gen
The project requires the `ollama_gen` library for AI integration. Install it by building from source. https://github.com/lostjared/ollama_gen
## Environment Setup
### Required Environment Variables
To use the AI integration features, you must export these environment variables to use with ollama
```bash
export MXDBG_HOST="localhost" # Your Ollama server URL can included port
# example 192.168.1.50:1088 op just the ip 192.168.1.50
export MXDBG_MODEL="llama2" # Your preferred Ollama model ex: codellama:7b
```
### Setting up Ollama
1. Install Ollama on your system
2. Start the Ollama service: `ollama serve`
3. Pull a model: `ollama pull llama2` (or your preferred model)
4. Set the environment variables as shown above
## Building
```bash
mkdir build
cd build
cmake ..
make
```
### Installation
```bash
sudo make install
```
### Uninstall
```bash
sudo make uninstall
```
## Usage
### Basic Usage
```bash
# Launch a program for debugging
./mxdbg /path/to/program
# Attach to an existing process
./mxdbg -p
# Dump assembly of a binary
./mxdbg -d /path/to/binary
```
### Command Line Options
- `-p `: Attach to process with given PID
- `-P `: Same as `-p` (long form)
- `-R `: Launch executable at path
- `-r `: Same as `-R` (short form)
- `-A `: Additional arguments for the launched process
- `-a `: Same as `-A` (short form)
- `-d`: Dump assembly of executable
- `-D`: Same as `-d` (long form)
### Interactive Commands
Once in the debugger shell (`mx $>`), you can use:
## Available Commands
| Command | Aliases | Description |
|---------|---------|-------------|
| **Expression & Variables** | | |
| `expr ` | | Evaluate expression |
| `setval ` | | 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 ` | `run_until ` | Run until specific address |
| `status` | `st` | Show process status |
| `start` | `restart` | Restart the program |
| **Threading** | | |
| `thread` | | Show current thread |
| `thread ` | | Switch to thread context |
| `threads` | | List all running threads |
| `debug_thread ` | | Debug specific thread |
| **Code Analysis** | | |
| `cur` | `current` | Print current instruction |
| `list` | | Display full disassembly |
| `list_less` | | Display disassembly with pager |
| `list_function ` | | 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 ` | `reg ` | Show specific register value |
| `register32 ` | | Show 32-bit register |
| `register16 ` | | Show 16-bit register |
| `register8 ` | | Show 8-bit register |
| `set ` | | Set register to value |
| **FPU/Float Registers** | | |
| `get_fpu ` | | Get FPU register value |
| `set_fpu ` | | Set FPU register to value |
| `list_fpu` | | List all FPU registers |
| **Breakpoints & Watchpoints** | | |
| `break ` | `b ` | Set breakpoint at address |
| `break_if ` | | Set conditional breakpoint that only triggers when condition is true |
| `function ` | | Set breakpoint at function |
| `list_break` | `lb` | List all breakpoints |
| `remove ` | `rmv` | Remove breakpoint |
| `watch [type]` | | Set watchpoint (type: read/write/access) |
| `watchpoints` | `wp` | List watchpoints |
| **Memory Operations** | | |
| `read ` | | Read 8 bytes from memory address |
| `read_bytes ` | | Read specific number of bytes |
| `write ` | | Write value to memory address |
| `write_bytes ` | | Write byte sequence to memory |
| `hexdump ` | | Display memory as hexadecimal dump |
| `as_bytes ` | | Convert value to byte representation |
| `maps` | `memory_maps` | Show memory map |
| `local ` | | Read local variable on stack |
| **Memory Search** | | |
| `search int ` | | Search for 32-bit integer in memory |
| `search int64 ` | | Search for 64-bit integer in memory |
| `search string ` | | Search for string in memory |
| `search bytes ` | | Search for byte pattern |
| `search pattern ` | | Search with wildcards (e.g., 41??43) |
| **Stack Analysis** | | |
| `stack_frame` | | Analyze current stack frame |
| **AI Features** | | |
| `explain ` | | Explain function disassembly with AI |
| `ask ` | | Ask the AI a question about the program |
| `mode ` | `user ` | Set AI difficulty (beginner/programmer/expert) |
| **File Information** | | |
| `info files` | | Show open file descriptors |
| **Utility** | | |
| `find ` | | Find text in disassembly using grep |
| `shell ` | `sh ` | Execute shell command |
| `clear` | | Clear the screen |
| `debug_state` | | Show detailed debug state |
| `help` | `h` | Show this help message |
| `quit` | `q`, `exit` | Exit debugger |
## AI Integration
When `MXDBG_HOST` and `MXDBG_MODEL` are set, the debugger will:
- Provide AI explanations when stepping through code
- Analyze disassembly output with the `explain` command
- Offer context-aware debugging assistance with the ask command
Example AI integration:
```bash
mx $> explain function
# AI will analyze the program's disassembly and explain its behavior
```
## Project Structure
```
mxdbg/
├── libmxdbg/ # Core debugger library
│ ├── include/mxdbg/ # Public headers
│ ├── process.cpp # Process control and ptrace operations
│ ├── debugger.cpp # Main debugger logic
│ └── pipe.cpp # IPC utilities
├── mxdbg/ # Main executable
│ └── main.cpp # Entry point and argument parsing
└── tests/ # Test suite
├── process_*.cpp # Process control tests
├── pipe_*.cpp # IPC tests
└── register_*.cpp # Register manipulation tests
```
## Supported Architectures
- x86_64 Linux systems
- Requires ptrace support in kernel
## Register Support
### 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`
## Testing
Run the test suite:
```bash
cd build/tests
ctest
```
Individual tests can be run:
```bash
./tests/process_continue_test
./tests/pipe_test
./tests/register_test
```
**Build errors**: Ensure all dependencies are installed, especially ollama_gen and readline development packages.