Skip to content

README.md

Latest commit

 

History

History
198 lines (144 loc) · 4.67 KB

README.md

File metadata and controls

198 lines (144 loc) · 4.67 KB

go-binspect

A low-level tool to inspect and visualize binary file structures with a beautiful Terminal User Interface (TUI).

Features

  • 🔍 Multi-Format Support: ELF, PE, PNG, and PDF file formats
  • 📊 Hex Viewer: Display binary data in hex and ASCII format
  • 🎨 TUI Interface: Beautiful terminal interface powered by Bubble Tea
  • 🔧 Modular Design: Extensible parser architecture for adding new formats
  • 🖥️ Cross-Platform: Works on Linux, macOS, and Windows
  • 📝 Detailed Inspection: View headers, sections, offsets, and data types

Installation

From Source

git clone https://github.com/BaseMax/go-binspect.git
cd go-binspect
go build -o binspect ./cmd/binspect

Using Go Install

go install github.com/BaseMax/go-binspect/cmd/binspect@latest

Usage

binspect <file>

Examples

Inspect an ELF binary:

binspect /bin/ls

Inspect a PNG image:

binspect image.png

Inspect a PDF document:

binspect document.pdf

Inspect a Windows executable:

binspect program.exe

Interface Controls

Once the TUI is running, use these keys to navigate:

  • 1: Overview - Shows file format, size, and summary
  • 2: Headers - Displays file headers with fields and offsets
  • 3: Sections - Shows all sections with their properties
  • 4: Hex Dump - View raw binary data in hex format
  • ↑/↓ or j/k: Scroll up/down
  • Page Up/Down: Scroll by page
  • Home: Jump to top
  • q or Ctrl+C: Quit

Supported Formats

ELF (Executable and Linkable Format)

  • Linux executables and shared libraries
  • Displays architecture, class, data encoding
  • Shows section information

PE (Portable Executable)

  • Windows executables (.exe, .dll)
  • Displays machine type and section details
  • Shows DOS and PE headers

PNG (Portable Network Graphics)

  • Image files with detailed chunk information
  • IHDR header with width, height, bit depth
  • Chunk-by-chunk breakdown

PDF (Portable Document Format)

  • Document structure analysis
  • Version information
  • Object and cross-reference table inspection

Architecture

The tool is organized into several packages:

  • cmd/binspect: Main application entry point
  • internal/parser: File format parsers (ELF, PE, PNG, PDF)
  • internal/reader: Hex view and binary reading utilities
  • internal/ui: TUI components using Bubble Tea

Adding New Parsers

To add support for a new file format:

  1. Create a new parser file in internal/parser/
  2. Implement the Parser interface: 
    type Parser interface {
    Detect(data []byte) bool
    Parse(reader interface{}) (*FileInfo, error)
    GetName() string
}
  3. Register the parser in cmd/binspect/main.go

Testing

Run the test suite:

go test ./...

Run tests with coverage:

go test -cover ./...

Development

Project Structure

go-binspect/
├── cmd/
│   └── binspect/          # Main application
│       └── main.go
├── internal/
│   ├── parser/            # File format parsers
│   │   ├── parser.go      # Parser interface
│   │   ├── elf.go         # ELF parser
│   │   ├── pe.go          # PE parser
│   │   ├── png.go         # PNG parser
│   │   └── pdf.go         # PDF parser
│   ├── reader/            # Binary reading utilities
│   │   └── hexview.go     # Hex dump formatter
│   └── ui/                # TUI components
│       └── tui.go         # Bubble Tea UI
├── go.mod
├── go.sum
└── README.md

Building

go build -o binspect ./cmd/binspect

Running

./binspect <file>

Dependencies

Contributing

Contributions are welcome! Here are some ways you can contribute:

  • Add support for new file formats (Mach-O, COFF, WASM, etc.)
  • Improve existing parsers with more detailed information
  • Add more TUI features (search, filtering, export)
  • Improve documentation and examples
  • Report bugs and suggest features

License

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

Author

Max Base

Acknowledgments

  • Built with Bubble Tea TUI framework
  • Styled with Lip Gloss
  • Inspired by tools like hexdump, objdump, and readelf