GDBC - A Terminal GDB Client

GDBC is a comprehensive terminal-based GDB client written in Rust for connecting to GDB servers and performing remote debugging operations.

Features

• Dual Operation Modes: Interactive shell and single instruction execution
• Memory Operations: Read/write memory with various display formats
• Debugging Controls: Set/remove breakpoints, step execution, continue execution
• Register Access: View CPU registers
• Colorized Output: Syntax highlighting for better readability (configurable)
• Connection Management: Connect, disconnect, and reconnect to GDB servers
• Command History: Persistent command history across sessions

Installation

From Source

Ensure you have Rust and Cargo installed, then:

# Clone the repository
git clone https://github.com/sammwyy/gdbc.git
cd gdbc

# Build the project
cargo build --release

# Run the client
./target/release/gdbc

Using Cargo

cargo install gdbc

Usage

Command Line Arguments

USAGE:
    gdbc [OPTIONS]

OPTIONS:
    -h, --host <HOST>               Host to connect to [default: localhost]
    -p, --port <PORT>               Port to connect to [default: 1234]
    -i, --instruction <INSTRUCTION> Single instruction to execute
    --no-color                      Disable colored output
    -d, --debug                     Enable debug output
    --help                          Show this help message
    --version                       Show version information

Interactive Mode

Launch GDBC without the -i flag to enter interactive mode:

gdbc -h target-host -p 1234

This starts an interactive shell where you can input commands.

Single Instruction Mode

Execute a single command and exit:

gdbc -h target-host -p 1234 -i "readmem 0x1000 64"

This executes the specified instruction and returns the result.

Commands

Command	Aliases	Description
connect HOST[:PORT]		Connect to GDB server (default port 1234)
disconnect		Disconnect from server
reconnect		Reconnect to the last server
readmem ADDR SIZE [MODE] [ENDIAN]	rm	Read memory
writemem ADDR DATA	wm	Write memory (DATA as hex, string, or bytes)
break ADDR	b	Set breakpoint
delete ADDR	d	Remove breakpoint
continue	c	Continue execution
step	s	Single step
registers	regs	Read registers
help	h, ?	Show help
quit	exit, q	Exit the program

Memory Reading Modes

When reading memory, you can specify the format:

• hex (default): Display as hexadecimal bytes with ASCII representation
• ascii/str: Display as ASCII string
• int16: Display as 16-bit integers
• int32: Display as 32-bit integers
• int64: Display as 64-bit integers

You can also specify endianness:

• little (default): Little-endian format
• big: Big-endian format

Examples

gdb> connect localhost:1234
gdb> readmem 0x1000 64
gdb> rm 0x1000 16 str
gdb> rm 0x1000 8 int32 big
gdb> writemem 0x1000 "Hello, world!"
gdb> wm 0x2000 0x01020304
gdb> break 0x1500
gdb> continue
gdb> step
gdb> registers

Project Structure

The client is divided into two main components:

1. Core Library (src/lib.rs)

   • client.rs: GDB protocol implementation
   • commands.rs: Command parsing and execution
   • display.rs: Output formatting and colors
   • error.rs: Error handling

2. CLI Interface (src/main.rs)

   • Interactive shell
   • Command-line argument parsing
   • Single instruction execution

GDB Remote Protocol

GDBC implements the GDB Remote Serial Protocol (RSP) for communicating with a GDB server. The protocol uses a packet-based mechanism with checksums for reliability. Key packet types supported:

• Memory access: m (read), M (write)
• Breakpoints: Z0 (set), z0 (clear)
• Execution control: c (continue), s (step)
• Register access: g (read all)

Development

Prerequisites

• Rust 1.54.0 or later
• Cargo

Dependencies

• clap: Command-line argument parsing
• rustyline: Interactive line editing and history
• colored: Terminal color support
• thiserror: Error handling
• byteorder: Endianness conversion
• regex: Command parsing
• env_logger: Logging backend
• dirs: User configuration directory detection

Building

cargo build

Testing

cargo test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• The GDB project for the remote protocol specification
• Rust community for the excellent libraries