DESCRIPTION

	Binwalk is a tool for searching a given binary image for embedded file types. Specifically,
	it was designed for identifying files embedded inside of firmware images. Binwalk file signatures
	are compatible with the magic signatures used by the Unix file utility.

	Binwalk includes a customized/improved signatures for files that are commonly found in firmware 
	images such as compressed/archived files, firmware headers, Linux kernels, bootloaders, filesystems, etc. 

	Binwalk can scan for executable code by searching for opcodes associated with the function prologues/epiloges 
	of various architectures.

	Binwalk can display the value of each file offset in various data types (long, short, date, etc). This is 
	useful for identifying header fields such as date and length values.

	Binwalk can extract embedded files from firmware images, and invoke external applications for further analysis,
	decompression or extraction.

INSTALLATION

	To build and install binwalk, run:

		$ ./configure
		$ make
		# make install

DEPENDENCIES

	Binwalk is currently supported on the Linux and Mac OSX platforms.

	To build from source, you must have the libmagic and libcurl development 
	libraries. Debian users can install these libraries via apt-get:

		$ sudo apt-get install libmagic-dev libcurl4-openssl-dev

	Note that some distributions/platforms may not have libmagic readily available,
	or may use a version of libmagic that is incompatible with binwalk. In this
	case, you may download the source code for the Unix file utility at:

		ftp://ftp.astron.com/pub/file/

	Building and installing the file utility will also install libmagic.


BASIC USAGE

	The only required options to binwalk are the file(s) that you want to search:

		$ binwalk firmware1.bin firmware2.bin firmware3.bin

	By default binwalk will use the signatures from the magic.binwalk file, but you may specify any other
	libmagic-compatible signature file with the -m option. Note that for full maigc file compatibility,
	you must specify the -s option to disable 'smart' matching:

		$ binwalk -m /usr/share/misc/magic -s firmware.bin

SEARCH OFFSETS

	By default binwalk will check for valid file signatures anywhere in the target file. This means that
	scanning a 4MB file is (roughly) equivalent to running the Unix file utility 4 million times. To
	decrease scan time, you may specify the byte alignment via the -b option. If, for example,
	you specify a byte alignment of 16, then binwalk will assume that everything in the file is
	16-byte aligned and will only look for signatures every 16 bytes:

		$ binwalk -b 16 firmware.bin

	You may also specify at what offset into the firmware image to start searching, and how many
	bytes should be searched. The following command searches 1000 bytes of data starting at an offset
	of 100:
		
		$ binwalk -o 100 -l 1000 firmware.bin

	All integer arguments, such as -o, and -l, can be entered as decimal (ex: 16) or hexadecimal
	(ex: 0x10, \x10, 10H, 10h) values.

FILTERING RESULTS

	By default, most magic signatures that are only two bytes long are ignored as they have a high
	rate of false positive matches. To include these magic signatures, specify the -a option:

		$ binwalk -a firmware.bin

	By default, binwalk will apply several default filters in order to improve scan reliability.
	These filters can be explicitly disabled with the -d option:

		$ binwalk -d firmware.bin

	You can also include individual signatures from the default exclude list with the -i option:

		$ binwalk -i foo firmware.bin
	
	Include and exclude filters may also be specified in order to limit the search results. Multiple
	include / exclude filters may be specified, and are case insensitive. If an include filter is specified,
	only descriptions that match that filter will be displayed. If an exclude filter is specified, all
	results will be displayed except those that match the exclude filter. If both exclude and include
	filters are specified, exclude filters trump include filters.

	Only search for gzip results:

		$ binwalk -y gzip firmware.bin

	Search for everything except results that contain the string 'system':

		$ binwalk -x system firmware.bin

	Search only for results that are file systems, but that are not JFFS2 file systems:

		$ binwalk -y filesystem -x jffs2 firmware.bin

UPDATING SIGNATURES	

	To update to the latest binwalk signatures, use the -u option (requires an Internet connection):

		# binwalk -u

DISPLAYING PROGRESS

	Some scans can take some time to complete and may not display many results during this time. 
	You can press the enter key at any time to force binwalk to display its current scan progress:

		$ binwalk -v firmware.bin

		Scan Time:    Dec 09, 2011 @ 18:00:42
		Magic File:   /usr/local/etc/binwalk/magic.binwalk
		Signatures:   76
		Target File:  firmware.bin
		MD5 Checksum: 1c802dbacdcfc0b96b900f8680d9d196

		DECIMAL   	HEX       	DESCRIPTION
		------------------------------------------------------------------------------------------
		<Enter>
		Progress:  1595 / 12074736  (0.01%)
		<Enter>
		Progress:  8015 / 12074736  (0.07%)
		<Enter>
		Progress:  12424 / 12074736  (0.10%)

FILE EXTRACTION

	Binwalk can extract embedded files from the target file and alternately invoke external applications.
	To extract all matches that contain the string 'gzip' and save them with the file extension 'gz':

		$ binwalk --dd=gzip:gz firmware.bin

	The file name used for each extracted file will be the hexadecimal offset at which it was found in
	the target file. Multiple --dd options may be specified. 

	You may also specify an external application to be run against the extracted files:

		$ binwalk --dd='gzip:gz:gunzip %e' firmware.bin

	The above command will run the gunzip command against each of the extracted files whose descriptions
	contain the string 'gzip'. The %e is a placeholder which is replaced with the name of the extracted
	file.

AUTOMATIC FILE EXTRACTION

	There will invariably be file types that are encountered on a frequent basis that you would like
	to extract automatically whenever they are found. This can be done with the --extract argument:

		$ binwalk --extract firmware.bin

	When --extract is specified, binwalk will load the contents of /usr/local/etc/binwalk/extract.conf
	and $HOME/.binwalk/extract.conf. The $HOME/.binwalk/extract.conf file takes precidence and can override 
	any settings in /usr/local/etc/binwalk/extract.conf.

	These files may contain as many extract rules as necessary, one rule per line (comments start with '#').
	The extract rules are the same as those passed to the --dd option:

		gzip:gz:gunzip %e
		lzma:7z:p7zip -d %e 
	
	See the src/extract.conf file for more examples.

SOURCE FILES

	docs/README		Project README file
	docs/COPYING		Project license file
        src/binwalk.c		Main binwalk source code file
        src/binwalk.h		Main binwalk source header file
	src/common.c		Common functions used by binwalk
	src/common.h		Common function declarations and definitions
	src/dd.c		Code for dumping sections of the target file to disk
	src/dd.h		DD code functions header file
	src/extract.conf	Default extract rules, installed as the system-wide defaults
	src/filter.c		Result filtering functions
	src/filter.h		Filter functions header file
	src/magic.binarch	Custom magic signature file for opcode scans
        src/magic.bincast	Custom magic signature file for casting data types
        src/magic.binwalk	Custom magic signature file for binwalk
	src/md5.c		MD5 algorithm code by Peter Deutsch
	src/md5.h		MD5 algorithm header by Peter Deutsch
	src/mparse.c		Minimal magic file parsing library
	src/mparse.h		Parsing library header file
	src/nargv.c		Command line parser by Triston Taylor
	src/nargv.h		Command line parser header file by Triston Taylor
	src/smartsig.c		Parses signature results for smart signature keywords
	src/smartsig.h		Smart signature header file
	src/update.c		Magic file update routines
	src/update.h		Updates header file

