HexRS

HexRS is a feature-rich command-line hex viewer and file analyzer written in Rust.
It combines the power of traditional hex dumps with modern features like custom binary format parsing, colored field highlighting, pattern search, and detailed file statistics — all presented in a clean, terminal‑friendly interface with ANSI color support.

---

✨ Features

• Hex Dump – Classic hex view with offsets, hex bytes, and ASCII/Unicode representation.
• Colored Highlights – Visually distinguish format fields, search matches, and special bytes (null, 0xFF).
• Custom Format Definitions – Describe any binary structure in YAML; HexRS automatically parses and displays fields.
• Pattern Search – Find any byte sequence (e.g., 90 90 ff or DEADBEEF) and highlight all occurrences.
• File Information – Show file metadata, content statistics (null bytes, printable chars, entropy), and detect common file types.
• Flexible Viewport – Control start offset, number of bytes, and line width.
• Multiple Format Directories – Automatically load formats from standard locations (./formats, ~/.hexrs/formats, etc.).
• Professional Output – Clear tables, color-coded legends, and field value display.

---

📦 Installation

Using Cargo (recommended)

cargo install hexrs

From Source

git clone https://github.com/yourusername/hexrs.git
cd hexrs
cargo build --release

The binary will be at target/release/hexrs. You can copy it to a directory in your PATH.

---

🚀 Basic Usage

hexrs [OPTIONS] <FILE>

Simple hex dump

hexrs firmware.bin

Shows the first 1024 bytes.

Start at a specific offset

hexrs firmware.bin -o 0x200 -l 256

Displays 256 bytes starting from offset 0x200. Offsets can be hex (with 0x) or decimal.

Show file information only

hexrs firmware.bin -I

Prints metadata, statistics, and type detection without hex dump.

Search for a pattern

hexrs firmware.bin -s "DEADBEEF"

Searches for the byte sequence DE AD BE EF and highlights matches in red.

Use a format definition

hexrs firmware.bin -F ELF

Uses the built‑in ELF format (if loaded) to highlight fields and display parsed values.

Load a custom format file

hexrs custom.dat --format-file myformat.yaml -F MyFormat

Loads a format definition from myformat.yaml and applies it to the file.

---

🔍 Detailed Examples

Example 1: Analyzing an ELF binary

hexrs /bin/ls -F ELF -o 0 -l 256

Output (excerpt):

HEX DUMP
Range: 0x00000000-0x000000FF (256 bytes)

Offset   Hex                                          ASCII
00000000 7F 45 4C 46 02 01 01 00 00 00 00 00 00 00 00 00  .ELF............
00000010 02 00 3E 00 01 00 00 00 50 10 40 00 00 00 00 00  ..>.....P.@.....
...

PARSED FIELDS
Format: ELF (5 fields)

  magic:4      ✓ @0x00000000 @+0     ELF magic number
  class:1      2 (0x02) @0x00000004 @+4     File class (32/64-bit)
  data:1       1 (0x01) @0x00000005 @+5     Data encoding (endianness)
  version:1    1 (0x01) @0x00000006 @+6     ELF version
  os_abi:1     0 (0x00) @0x00000007 @+7     OS/ABI identification
  type:2       2 (0x0002) @0x00000010 @+16  Object file type
  machine:2    62 (0x003E) @0x00000012 @+18 Machine type
  entry_point:4 0x401050 @0x00000018 @+24   Entry point address

Example 2: Searching for a string in a binary

hexrs firmware.bin -s "55 AA" -l 512

Finds every occurrence of the bytes 0x55 0xAA and highlights them in red.

Example 3: File information with statistics

hexrs secret.pdf -I

Output:

╔══════════════════════════════════════════════════════════════════════════════════╗
║                            FILE INFORMATION                                      ║
╠══════════════════════════════════════════════════════════════════════════════════╣
║ Path:          secret.pdf                                                        ║
║ Size:          248,523 bytes (0.24 MB)                                           ║
║ Type:          File (.pdf)                                                       ║
║ Permissions:   Permissions(0o644)                                                ║
║ Created:       2025-02-15 10:30:12.000                                           ║
║ Modified:      2025-02-15 10:30:12.000                                           ║
║ Accessed:      2025-02-15 10:30:12.000                                           ║
╠══════════════════════════════════════════════════════════════════════════════════╣
║                         CONTENT ANALYSIS                                         ║
╠══════════════════════════════════════════════════════════════════════════════════╣
║ Null bytes:          12,304 ( 4.9%)                                              ║
║ Printable chars:    211,445 (85.1%)                                              ║
║ Control chars:       4,452 ( 1.8%)                                               ║
║ Entropy:             6.23 bits/byte                                              ║
║ Detected type:       PDF Document                                                ║
║ Byte range:          0x00-0xFF (avg: 0x4A)                                       ║
╚══════════════════════════════════════════════════════════════════════════════════╝

---

🧩 Custom Format Definitions

HexRS lets you describe binary formats in YAML. Place your .yaml files in one of these directories to have them auto‑loaded:

• ./formats/
• ~/.hexrs/formats/
• The directory containing the hexrs executable (<exe>/formats/)

You can also load a specific file with --format-file.

Format Structure

A format definition looks like this:

name: "MyFormat"
description: "A custom binary format"
endianness: "big" # optional, defaults to "little"
structure:
  - name: "header"
    type: Struct
    config:
      fields:
        - name: "magic"
          type: Magic
          config:
            value: [0xCA, 0xFE]
          offset: 0
          size: 2
        - name: "version"
          type: U8
          offset: 2
        - name: "flags"
          type: U16
          offset: 3
  - name: "data"
    type: Bytes
    config:
      length: 256
    offset: 5
    description: "Payload data"

Supported Field Types

Type	Description	Configuration
U8/U16/U32/U64	Unsigned integers (size determined by type)	–
I8/I16/I32/I64	Signed integers	–
F32/F64	Floating‑point numbers	–
Bytes	Fixed‑length byte array	length: <number>
String	Text string	encoding: "utf8"/"ascii", length: <number>, null_terminated: true/false
Array	Repeated element type	element_type: <type>, count: <number>
Struct	Nested structure	fields: [...]
Enum	Mapped numeric values	variants: { "name": value }, size: 1/2/4/8
Magic	Fixed byte pattern for validation	value: [0x..]
Padding	Skipped bytes	length: <number>

Field Attributes

Each field in structure can have:

• name – Field identifier (displayed in output).
• type – One of the types above.
• config – Type‑specific configuration.
• offset – Byte offset from the start of the file (or from the containing structure if nested). If omitted, fields are assumed to be sequential, but for clarity it's recommended to specify offsets.
• size – Override computed size (useful for variable‑length fields).
• description – Optional description shown in the parsed fields table.

Endianness

The top‑level endianness field controls integer and float parsing. Values: "little" (default) or "big".

Nested Structures

Use Struct and Array to build complex hierarchies. For example:

- name: "files"
  type: Array
  config:
    count: 3
    element_type:
      type: Struct
      config:
        fields:
          - name: "name"
            type: String
            config:
              length: 32
              encoding: "ascii"
          - name: "size"
            type: U32

---

🎨 Output Explanation

Hex Dump Section

HEX DUMP
Range: 0x00000000-0x000000FF (256 bytes)

Offset   Hex                                          ASCII
00000000 7F 45 4C 46 02 01 01 00 00 00 00 00 00 00 00 00  .ELF............
00000010 02 00 3E 00 01 00 00 00 50 10 40 00 00 00 00 00  ..>.....P.@.....

• Offset – Absolute byte position (including --base-offset if used).
• Hex – 16 bytes per line by default (change with -W).
• ASCII – Printable characters; ∅ = null, ■ = 0xFF, · = other non‑printable.

Field Highlighting

When a format is active, fields are displayed above the rows where they start:

▶ entry_point
00000018 50 10 40 00 00 00 00 00 00 00 00 00 00 00 00 00  P.@.............

Field bytes are color‑coded (cyclic palette). The legend at the bottom explains which color corresponds to which field.

Parsed Fields Table

After the hex dump, a table shows the parsed values:

PARSED FIELDS
Format: ELF (5 fields)

  magic:4      ✓ @0x00000000 @+0     ELF magic number
  class:1      2 (0x02) @0x00000004 @+4     File class (32/64-bit)
  data:1       1 (0x01) @0x00000005 @+5     Data encoding (endianness)
  version:1    1 (0x01) @0x00000006 @+6     ELF version
  os_abi:1     0 (0x00) @0x00000007 @+7     OS/ABI identification

• Field name and size – e.g., magic:4.
• Value – Formatted according to type (hex for integers, quoted for strings).
• Offset – Absolute address.
• Offset from base – Relative to --base-offset (useful when analyzing file sections).
• Description – If provided in the format definition.

Search Matches

If a pattern is found, occurrences are highlighted in red in the hex dump, and a summary appears in the legend:

LEGEND
  SEARCH - Pattern match (2 occurrences)

---

🛠️ Advanced Usage

Adjusting the Base Offset

The -O / --base-offset option shifts all displayed offsets and field positions. This is useful when you want to view a file from a certain logical address (e.g., a memory‑mapped region). The field offsets in the parsed table will also reflect this shift.

hexrs firmware.bin -o 0x100 -O 0x8000

Start at file offset 0x100, but display offsets as if they started at 0x8000.

Logging

Set the log level with --log-level (debug, info, warn, error). This helps when debugging format loading issues.

hexrs firmware.bin --log-level debug

Creating Your Own Formats

1. Create a .yaml file in one of the format directories.
2. Define your structure as described above.
3. Run HexRS with -F <name> where <name> matches the name field in your YAML.

If you want to test a format without copying it to a standard directory, use --format-file.

---

📊 File Information Details

When -I is used, HexRS displays:

• Basic metadata – Path, size, permissions, timestamps.
• Content analysis – Counts of null bytes, printable characters, control characters, and entropy.
• Type detection – Based on magic bytes and heuristics (PNG, JPEG, PDF, ELF, ZIP, etc.).
• Byte statistics – Minimum, maximum, and average byte values.

Entropy is calculated as Shannon entropy in bits per byte. Higher values indicate more randomness (typical of encrypted or compressed data).

---

🔧 Configuration

HexRS looks for format files in three directories. You can override this by using --format-file or by placing your formats in one of the standard locations. There is no global configuration file; everything is done via command‑line arguments.

---

📝 Tips

• Use -W to adjust line width for easier reading or to match your terminal.
• Combine -s with a format to see search matches within fields.
• Explore built‑in formats – If you have examples like elf.yaml, pe.yaml, etc., place them in the format directories.
• For large files, limit the displayed range with -l to keep performance high.

---

🤝 Contributing

Contributions are welcome! Feel free to open issues, submit pull requests, or suggest new format definitions. Please follow the existing code style and include tests where appropriate.

---

📄 License

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

---

Happy hexing!