Binary graph

This program provides a simple way of visualizing the different regions of a binary file.

These are some references that inspired this project:

• Christopher Domas - The future of RE Dynamic Binary Visualization (YouTube).
• Sergey Bratus and Greg Conti - Voyage of the reverser (YouTube).
• Aldo Cortesi - Visualizing binaries with space-filling curves.
• Aldo Cortesi - Visualizing entropy in binary files.

If you are interested on more professional approaches, check out the following links:

• The binvis.io online tool by Aldo Cortesi.
• The mewbak/binary_viewer repository, which also includes some other links.
• The wapiflapi/veles repository, which is no longer maintained.

Building

The program depends on libpng for exporting the image. Install it from your package manager.

# Arch-based distros
pacman -S libpng

# Gentoo
emerge media-libs/libpng

Once all the dependencies are installed, compile the program.

git clone https://github.com/8dcc/bin-graph
cd bin-graph
make

If you want to install it on your system, run the following command.

sudo make install

Usage and modes

To see the full program usage, use the --help argument.

bin-graph --help
# Usage: bin-graph [OPTION...] INPUT OUTPUT
# Simple program for visualizing binary files.
#
# ...

The main behavior of the program is determined by the “generation mode”, which affects how the input binary is represented in the output graph. This is controlled by the --mode option, and the list of available values, along with their descriptions, can be printed with the --list-modes argument.

bin-graph --list-modes
# * grayscale: The brightness of each pixel represents the value of each sample
#   (00..FF).
# * ascii: The color of each pixel represents the "printability" of each sample
#   in a linear way. Black represents a null byte (00), white represents a set
#   byte (FF), blue represents printable characters and red represents any other
#   value.
# ...

Scripts

This project also includes some bash scripts that extend the functionality of the main program.

The bin-graph-section.sh script uses readelf and grep to find the offset and size of the specified ELF section, and uses that as the --offset-* arguments for bin-graph. Additional options after the section name will be passed to bin-graph.

./scripts/bin-graph-section.sh SECTION [OPTION...] INPUT OUTPUT.png
# ...

The bin-graph-hexdump.sh script prints the output of a hexdump command (xxd) side-by-side with the ANSI-escaped output of bin-graph.

./scripts/bin-graph-hexdump.sh [OPTION...] INPUT
# ...

The bin-graph-all-modes.sh script generates all possible binary graphs from an input file by calling bin-graph with different --mode arguments.

./scripts/bin-graph-all-modes.sh INPUT
# ...

The bin-graph-merged.sh script generates multiple binary graphs from an input file, and merges them together into a large PNG file.

./scripts/bin-graph-merged.sh [OPTION...] INPUT OUTPUT.png
# ...

Overview of the code

I tried to make each part of the program as modular and independent as possible, for more maintainability and for easier expansion.

This is the basic process for generating an image from a binary.

1. The arguments are parsed by the argp library from args.c into an Args structure. Some common checks are performed in this stage, but most modes also have their own mode-specific conditions.
2. The input file is opened and the data is read from the input file as a byte array, using the file_open and file_read function, defined in file.c.
3. An Image structure is generated from the byte array, using a different generation function depending on the main program mode. This Image structure is stored in memory as an array of RGB Color structures along with the image dimensions.
4. Optionally, the image is transformed using different methods, such as the Hilbert curve algorithm.
5. The Image structure is exported into the output file depending on the output format (e.g. as PNG file, ANSI escaped text, etc.).

Screenshots

./bin-graph --mode grayscale bin-graph examples/grayscale.png

./bin-graph --mode ascii bin-graph examples/ascii.png

./bin-graph --mode entropy --transform-squares 16 bin-graph examples/entropy-squared.png

./bin-graph --mode entropy-histogram --width 256 --block-size 512 bin-graph examples/entropy-histogram.png

# Only the .text section of the ELF file
./scripts/bin-graph-section.sh .text --width 256 --mode histogram bin-graph examples/histogram.png

# Only the .rodata section of the ELF file
./scripts/bin-graph-section.sh .rodata --mode bigrams bin-graph examples/rodata-bigrams.png

./bin-graph --mode dotplot --zoom 1 --offset-start 5000 --offset-end 5500 input.wav examples/dotplot.png

./bin-graph --width 256 --transform-hilbert 8 bin-graph examples/hilbert-ascii.png

./bin-graph --width 256 --transform-hilbert 8 --mode entropy --block-size 256 bin-graph examples/hilbert-entropy.png

./scripts/bin-graph-merged.sh --zoom 1 bin-graph examples/merged.png