mirror of
https://github.com/DarrylNixon/binhop
synced 2024-04-22 12:37:06 -07:00
76 lines
No EOL
3.4 KiB
Markdown
76 lines
No EOL
3.4 KiB
Markdown
<div align="center">
|
|
<img src="static/binhop.png" alt="binhop logo">
|
|
|
|
# binhop
|
|
|
|
`binhop` is a **file carving visualizer**, powered by `binwalk`.
|
|
|
|
It makes clear what parts of a blob can be extracted, so you can
|
|
take action on the parts that didn't.<br />
|
|
`binhop` relies entirely on a functioning installation of `binwalk`.
|
|
|
|
[Installation and Usage](#installation) •
|
|
[FAQ](#faq) •
|
|
[Contributing](#contributing) •
|
|
[License](#license)
|
|
</div>
|
|
|
|
## Installation and Usage
|
|
|
|
### Build with Docker (recommended)
|
|
|
|
Assuming you have Docker installed and running, you can serve binhop locally with something like:
|
|
|
|
```
|
|
git clone https://github.com/darrylnixon/binhop.git
|
|
cd binhop
|
|
docker build . -t csc842/binhop
|
|
docker run --name binhop -e PORT=3050 -p 3050:3050 --restart=always csc842/binhop
|
|
```
|
|
|
|
Then browse to [http://localhost:3050](http://localhost:3050) and upload a blob.
|
|
|
|
### Manually
|
|
|
|
To use this script, you need Python 3 and a functioning and "recent" version of `binwalk` installed on your system. In practice, this means you're *probably* going to need to be on an x86/x86_64 Linux, but maybe you have better karma than I do.
|
|
|
|
You'll probably also want to install optional `binwalk` dependencies such as `sasquatch`, `jefferson`, and others, depending on the binaries you want to submit. You can learn how to do that in [binwalk's INSTALL.md](https://github.com/ReFirmLabs/binwalk/blob/master/INSTALL.md). `binhop` only "requires" `binwalk`, but it'll fail on binaries for which `binwalk` is dependent on optional modules.
|
|
|
|
When that's done, get `binhop` running with something like:
|
|
|
|
```
|
|
git clone https://github.com/darrylnixon/binhop.git
|
|
cd binhop
|
|
pip install -r requirements.txt
|
|
./binhop.py [--port <port, default: 8080>]
|
|
```
|
|
|
|
Once running, browse to [http://localhost:8080](http://localhost:8080) and upload a blob.
|
|
|
|
## FAQ
|
|
|
|
**What problem does binhop solve?**
|
|
|
|
`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.
|
|
|
|
**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.
|
|
|
|
For aesthetics, the interface is browser-based. It'd be ideal to make it command-line accessible, but I ran out of time trying to summarize an arbitrarily large number of bytes and sections into a human-consumable CLI output. I'm open to ideas.
|
|
|
|
**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.
|
|
|
|
## License
|
|
|
|
This project is licensed under the GPLv3 License, because it's important to give back. See the `LICENSE` file for details. |