# bisect-binary: Determine relevant parts of binary data

[ development, mit, program ] [ Propose Tags ]

This little program helps with the following task:

You need to analyse some binary file (e.g., the firmware for some microcontroller). You want to understand how it does certain things, but the file is big. One approach to help you in the process is to erase parts of the file (by overwriting it with binary zeros) and see if the file still does what it should be doing. If it does, then you know that the interesting parts are in another part of the file.

binary-binary assists in this process by doing the book-keeping and zeroing out parts of the file.

Versions [faq] 0.1, 0.1.0.1 ChangeLog.md base (>=4.9 && <4.12), bytestring, directory, filepath, hashable, haskeline (==0.7.*), integer-logarithms, optparse-applicative (==0.13.*), process, terminal-size, time, yaml (==0.8.*) [details] MIT 2017 Joachim Breitner Joachim Breitner mail@joachim-breitner.de Development http://github.com/nomeata/bisect-binary head: git clone https://github.com/nomeata/bisect-binary by JoachimBreitner at 2017-12-05T14:14:21Z NixOS:0.1.0.1 bisect-binary 1228 total (22 in the last 30 days) (no votes yet) [estimated by Bayesian average] λ λ λ Docs not available Last success reported on 2017-12-05

#### Maintainer's Corner

For package maintainers and hackage trustees

## Readme for bisect-binary-0.1.0.1

[back to package description]

# bisect-binary

This little program helps with the following task:

You need to analyse some binary file (e.g., the firmware for some microcontroller). You want to understand how it does certain things, but the file is big. One approach to help you in the process is to erase parts of the file (by overwriting it with binary zeros) and see if the file still does what it should be doing. If it does, then you know that the interesting parts are in another part of the file.

bisect-binary assists in this process by doing the book-keeping and zeroing out parts of the file.

## Screenshot

The following screenshot shows bisect-binary in action, as it determins which part of a “Hello World” program written in Haskell are actually needed: It is taken from a Asciinema demo, and edited to fit your screen.

## Usage

Run bisect-binary with the input file, the output file, and optionally a command to run on every try (which could, for example, flash the microcontroller with the binary):

\$ bisect-binary --help
Binary file bisector

Usage: bisect-binary (-i|--input FILE) (-o|--output FILE) [-c|--command COMMAND]
Fills a file with as much zeroes as possible

Available options:
-h,--help                Show this help text
-i,--input FILE          input file
-o,--output FILE         output file
-c,--command COMMAND     command to run


Now bisect-binary will zero out parts of the file and ask you if the result is now good or bad, as seen in the screenshot above. Your options are:

• Y: Mark this example as good. It will remember which portions it zeroed out and from now on only add to it
• N: Mark this example as bad. It will revert to the previous good version and try out other parts of the file.
• R: Re-run the command.
• U: Undo the last marking.
• Q: Quit the program.

Upon quitting, bisect-binary will leave output in the last known state.

A persisent file name output-file.bisect.log is kept, so you can quit and restart at any time without losing your work.

The status line tells you:

• how much of the file could be zeroed out sucessfully.

• how many bytes it is now adding to that.

• how many bytes of the file may be relevant for your task

• a status bar describing the progress:

• The top row visualizes the part of the file that we know we can zero out for sure.
• The bottom row visualizes the part that we are zeroing out next.

Two dots indicate all bytes in this part, one dot indicates some bytes.

## Contact

Please reports bugs and missing features at the GitHub bugtracker. This is also where you can find the source code.

bisect-binary was written by Joachim Breitner and is licensed under a permissive MIT license.