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:

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
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.

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

Acknowledgments

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

License

sammwyy/gdbc

ErrorLooks like something went wrong!

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Languages

Error
Looks like something went wrong!