From 53f960b3b204293deab72973ce9bfab2f0087572 Mon Sep 17 00:00:00 2001 From: dnix Date: Thu, 18 May 2023 18:49:27 +0000 Subject: [PATCH] add FAQ --- README.md | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1cbeb10..941da18 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,26 @@ It makes clear what parts of a blob can be extracted, so you can take action on the parts that didn't.
binhop relies entirely on a functioning installation of binwalk. -[Usage](#usage) • [Installation](#installation) • +[Usage](#usage) • +[FAQ](#faq) • [Contributing](#contributing) • [License](#license) +## Installation + +To use this script, you need Python 3 and a functioning and "recent" version of `binwalk` installed on your system. You'll probably also want to install optional `binwalk` dependencies such as `sasquatch`, `jefferson`, and others. You can learn how to do that in the [binwalk documentation](https://github.com/ReFirmLabs/binwalk/blob/master/INSTALL.md). + +When that's done, install the Python dependencies for `binhop`, running something like: + +``` +git clone https://github.com/darrylnixon/binhop.git +cd binhop +pip install -r requirements.txt +pip install . +``` + ## Usage To use the script, run the following command: @@ -29,25 +43,28 @@ Alternatively, you can run binhop on data from STDIN like so: binhop < ``` -## Installation +## FAQ -To use this script, you need Python 3 and a functioning and "recent" version of `binwalk` installed on your system. You'll probably also want to install optional `binwalk` dependencies such as `sasquatch`, `jefferson`, and others. You can learn how to do that in the [binwalk documentation](https://github.com/ReFirmLabs/binwalk/blob/master/INSTALL.md). +**What problem does binhop solve?** -When that's done, install the Python dependencies for `binhop`, running something like: +binhop was written under the assumption that reverse engineers are blindly running `binwalk -qeM` on firmware images without validating what percentage of the image successfully extracted. I'm guilty of this in the past. binhop makes it easier to determine "coverage" of a walk/carve so that pieces that did not match any magic bytes can be analyzed further. -``` -git clone https://github.com/darrylnixon/binhop.git -cd binhop -pip install -r requirements.txt -pip install . -``` +**What are the future plans for binhop?** + +This repository is part of my coursework for CSC 842 - Security Tool Development at Dakota State University. Consequently, I may choose not to maintain this tool beyond the length of the course, but have selected a license that enables open contributions in any case. + +**Why did you select GPLv3? MIT is so much better.** + +GPLv3 still gives you the right to use, modify, and share binhop. It also has the benefit of requiring you to open-source software that uses it and share back any significant modifications or improvements to the code, and I like that. + +**How can I report a bug or request new features?** + +See [Contributing](#contributing) below. ## Contributing If you would like to contribute to this project, feel free to submit a pull request or open an issue on GitHub. -This tool was written as part of my coursework for CSC 842 - Security Tool Development at Dakota State University. Consequently, I may choose not to maintain this tool beyond the length of the course, but have selected a license that enables open contributions in any case. - ## License This project is licensed under the GPLv3 License, because it's important to give back. See the `LICENSE` file for details. \ No newline at end of file