@@ -9,7 +9,7 @@ The classes, methods and objects in the binwalk modules are documented via pydoc
Binwalk Scripting
=================
Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules. These modules can be invoked via `binwalk.execute`, which makes scripting trivial through its execute method.
Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules. These modules can be invoked via `binwalk.execute`.
In fact, the binwalk command line utility can be duplicated nearly entirely with just two lines of code:
...
...
@@ -20,7 +20,7 @@ binwalk.execute()
The `execute` function accepts both args and kwargs, which correspond to the normal command line options accepted by the binwalk command line utility, providing a large amount of freedom in how you choose to specify binwalk options (if none are specified, sys.argv is used by default).
For example, to execute a signature scan, you at the very least have to specify the --signature command line option, as well as a list of files to scan. This can be done in a number of ways:
For example, to execute a signature scan, you at the very least have to specify the `--signature` command line option, as well as a list of files to scan. This can be done in a number of ways:
@@ -42,9 +42,9 @@ All args and kwargs keys/values correspond to binwalk's command line options. Ei
Accessing Scan Results
======================
`binwalk.execute` returns a list of objects. Each object corresponds to a module that was run. For example, if you specified --signature and --entropy, then both the Signature and Entropy modules would be executed and you would be returned a list of two objects.
`binwalk.execute` returns a list of objects. Each object corresponds to a module that was run. For example, if you specified `--signature` and `--entropy`, then both the Signature and Entropy modules would be executed and you would be returned a list of two objects.
The two attributes of interest for each object are the 'results' and 'errors' objects. Each is a list of binwalk.core.module.Result and binwalk.core.module.Error objects respectively. Each Result or Error object may contain custom attributes set by each module, but are guarunteed to have at least the following attributes (though modules are not required to populate all attributes):
The two attributes of interest for each object are the `results` and `errors` objects. Each is a list of binwalk.core.module.Result and binwalk.core.module.Error objects respectively. Each Result or Error object may contain custom attributes set by each module, but are guarunteed to have at least the following attributes (though modules are not required to populate all attributes):
Installation follows the typical configure/make process (standard development tools such as gcc, make, and Python must be installed in order to build):
$ ./configure
$ make
$ sudo make install
```bash
$ ./configure
$ make
$ sudo make install
```
Binwalk's core features will work out of the box without any additional dependencies. However, to take advantage of binwalk's graphing and extraction capabilities, multiple supporting utilities/packages need to be installed.
To ease "dependency hell", a shell script named `deps.sh` is included which attempts to install all required dependencies for Debian and RedHat based systems:
$ ./deps.sh
```bash
$ ./deps.sh
```
If you are running a different system, or prefer to install these dependencies manually, see the Dependencies section below.
...
...
@@ -64,11 +68,15 @@ For convenience, the following libraries are bundled with binwalk and will not c
Installation of any individual bundled library can be disabled at build time:
Alternatively, installation of all bundled libraries can be disabled at build time:
$ ./configure --disable-bundles
```bash
$ ./configure --disable-bundles
```
If a bundled library is disabled, the equivalent library must be installed to a standard system library location (e.g., `/usr/lib`, `/usr/local/lib`, etc) in order for binwalk to function properly.
...
...
@@ -89,7 +97,9 @@ Specifying a Python Interpreter
The default python interpreter used during install is the system-wide `python` interpreter. A different interpreter (e.g., `python2`, `python3`) can be specified at build time:
$ ./configure --with-python=python3
```bash
$ ./configure --with-python=python3
```
Installing the IDA Plugin
...
...
@@ -97,13 +107,17 @@ Installing the IDA Plugin
If IDA is installed on your system, you may optionally install the IDA plugin by specifying the location of your IDA install directory at build time:
$ ./configure --with-ida=/home/user/ida-6.6
$ make ida
```bash
$ ./configure --with-ida=/home/user/ida-6.6
$ make ida
```
Uninstallation
==============
The following command will remove binwalk from your system. Note that this will *not* remove manually installed packages, or utilities installed via deps.sh:
Binwalk follows the standard Unix configure/make installation procedure:
$ ./configure
$ make
$ sudo make install
```bash
$ ./configure
$ make
$ sudo make install
```
For convenience, optional dependencies for automatic extraction and graphical visualizations can be installed by running the included `deps.sh` script:
$ ./deps.sh
```bash
$ ./deps.sh
```
If your system is not supported by `deps.sh`, or if you wish to manually install dependencies, see `INSTALL.md`.
...
...
@@ -25,6 +29,8 @@ Usage
Basic usage is simple:
$ binwalk firmware.bin
```bash
$ binwalk firmware.bin
```
For additional examples and desriptions of advanced options, see the [wiki](https://github.com/devttys0/binwalk/wiki).
