Quick Start Guide

Installation

Install required run-time dependencies:

# Required for Python2.7 only
$ sudo apt-get install python-lzma

Download binwalk:

$ wget https://github.com/devttys0/binwalk/archive/master.zip
$ unzip master.zip

Install binwalk:

$ (cd binwalk-master && sudo python setup.py install)

Install optional graphing dependencies:

# Python2.7
# Graphing modules, for plotting entropy graphs
$ sudo apt-get install libqt4-opengl python-opengl python-qt4 python-qt4-gl python-numpy python-scipy python-pip
$ sudo pip install pyqtgraph

# Python3.x
# Graphing modules, for plotting entropy graphs
$ sudo apt-get install libqt4-opengl python3-opengl python3-pyqt4 python3-pyqt4.qtopengl python3-numpy python3-scipy python3-pip
$ sudo pip3 install pyqtgraph

Install optional disassembler dependencies:

# The capstone disassembler engine, for disassembly-based code signatures
$ wget http://www.capstone-engine.org/download/2.1.2/capstone-2.1.2.tgz
$ tar -zxvf capstone-2.1.2.tgz
$ (cd capstone-2.1.2 && ./make.sh && sudo make install)
$ (cd capstone-2.1.2/bindings/python && sudo python ./setup.py install)

Install optional extraction utilities:

# Extraction utilities, for automated file extraction and decompression
$ sudo apt-get install mtd-utils zlib1g-dev liblzma-dev ncompress gzip bzip2 tar arj lhasa p7zip p7zip-full cabextract cramfsprogs cramfsswap squashfs-tools

# Sasquatch SquashFS extraction tool, for extracting non-standard SquashFS file systems
$ sudo apt-get install zlib1g-dev liblzma-dev liblzo2-dev
$ git clone https://github.com/devttys0/sasquatch
$ (cd sasquatch && make && sudo make install)

# Install jefferson to extract JFFS2 file systems
$ sudo pip install cstruct
$ git clone https://github.com/sviehb/jefferson
$ (cd jefferson && sudo python setup.py install)

# Install unstuff (closed source) to extract StuffIt archive files
$ wget -O - http://my.smithmicro.com/downloads/files/stuffit520.611linux-i386.tar.gz | tar -zxv
$ sudo cp bin/unstuff /usr/local/bin/

See the INSTALL documentation for more details.

Scanning Firmware

The primary - and by far the most popular - feature of binwalk is its signature scanning.

Binwalk can scan a firmware image for many different embedded file types and file systems; just give it a list of files to scan:

$ binwalk firmware.bin

DECIMAL   	HEX       	DESCRIPTION
-------------------------------------------------------------------------------------------------------------------
0         	0x0       	DLOB firmware header, boot partition: "dev=/dev/mtdblock/2"
112       	0x70      	LZMA compressed data, properties: 0x5D, dictionary size: 33554432 bytes, uncompressed size: 3797616 bytes
1310832   	0x140070  	PackImg section delimiter tag, little endian size: 13644032 bytes; big endian size: 3264512 bytes
1310864   	0x140090  	Squashfs filesystem, little endian, version 4.0, compression:lzma, size: 3264162 bytes,  1866 inodes, blocksize: 65536 bytes, created: Tue Apr  3 04:12:22 2012

File Extraction

You can tell binwalk to extract any files that it finds in the firmware image with the -e option:

$ binwalk -e firmware.bin

Binwalk will even recursively scan files as it extracts them if you also specify the -M option:

$ binwalk -Me firmware.bin

And if the -r option is specified, any file signatures that couldn't be extracted - or that resulted in 0-size files - will be automatically deleted:

$ binwalk -Mre firmware.bin

Entropy Analysis

What happens if binwalk doesn't report any signatures? Or, how do you know binwalk didn't miss anything interesting?

Entropy analysis can help identify interesting sections of data inside a firmware image:

$ binwalk -E firmware.bin

HINT: You can combine other scans with the entropy scan. For example, you can combine a signature scan with an entropy scan:

$ binwalk -B -E fimware.bin

DECIMAL   	HEX       	DESCRIPTION
-------------------------------------------------------------------------------------------------------------------
36625     	0x8F11    	Zlib header, default compression