Imported Upstream version 1.0
[packages/binwalk.git] / docs / README
1 DESCRIPTION
2
3         Binwalk is a tool for searching a given binary image for embedded file types. Specifically,
4         it was designed for identifying files embedded inside of firmware images. Binwalk file signatures
5         are compatible with the magic signatures used by the Unix file utility.
6
7         Binwalk includes customized/improved signatures for files that are commonly found in firmware images
8         such as compressed/archived files, firmware headers, Linux kernels, bootloaders, filesystems, etc. 
9
10         Binwalk can scan for executable code by searching for opcodes associated with the function prologues/epiloges 
11         of various architectures.
12
13         Binwalk can display the value of each file offset in various data types (long, short, date, etc). This is 
14         useful for identifying unknown firmware header fields such as date and length values.
15
16         Binwalk can extract embedded files from firmware images and invoke external applications for further analysis,
17         decompression or extraction.
18
19 INSTALLATION
20
21         To install binwalk, run the following command from the src directory:
22
23                 # python setup.py install
24
25 DEPENDENCIES
26
27         Binwalk is currently supported on the Linux and Mac OSX platforms.
28
29         Binwalk depends on the libmagic library (version 5.05 or newer) and its corresponding magic Python module. Debian 
30         users can install these dependencies via apt-get:
31
32                 $ sudo apt-get install libmagic1 python-magic
33
34         Note that some distributions/platforms may not have libmagic readily available, or may use an older version of 
35         libmagic that is incompatible with binwalk. In this case, you may download the source code for the file utility at:
36
37                 ftp://ftp.astron.com/pub/file/
38
39         Follow the file utility's documentation to build and install both libmagic and the Python magic module.
40
41
42 BASIC USAGE
43
44         The only required options to binwalk are the file(s) that you want to search:
45
46                 $ binwalk firmware1.bin firmware2.bin firmware3.bin
47
48         Binwalk signatures and system-wide configuration files can be updated to the latest from the SVN
49         trunk with the --update option (this likely will need to be run as root):
50
51                 # binwalk --update
52
53         To see more verbose information about the file being scanned, specify the --verbose option. This option
54         is automatically enabled if more than one target file is specified on the command line:
55
56                 $ binwalk --verbose firmware.bin
57
58         Output can be logged to a file with the --file option:
59
60                 $ binwalk --file=binwalk.log firmware.bin
61
62         Output to stdout can be suppressed with the --quiet option:
63
64                 $ binwalk --file=binwalk.log --quiet firmware.bin
65
66         By default, scans start at the first byte of the specified file (offset 0) and end at the end of the
67         specified file. These settings can be controlled with the --offset and --length options, respectively.
68         For example, the following command will scan 128 bytes starting at offset 64:
69
70                 $ binwalk --offset=64 --length=128 firmware.bin
71
72         By default, binwalk will scan every byte for possible signatures. To scan every 2 bytes, 4 bytes, 8 bytes,
73         etc, use the --align option:
74
75                 $ binwalk --align=4 firmware.bin
76
77         By default binwalk will use the signatures from the magic.binwalk file, but you may specify an alternate
78         signature file with the --magic option:
79
80                 $ binwalk --magic=/usr/share/misc/magic firmware.bin
81
82         To search for a sequence of bytes without creating a signature file, use the --raw-bytes option:
83
84                 $ binwalk --raw-bytes="\x00\x01\x02\x03" firmware.bin
85
86
87 TYPES OF SCANS
88
89         By default binwalk will scan for file signatures inside the specified target file(s), however, other
90         types of scans are also supported.
91
92         To scan for known x86/MIPS/ARM/PPC opcodes, use the --opcodes option:
93
94                 $ binwalk --opcodes firmware.bin
95
96         To cast each offset in the file as various data types (big/little endian shorts/longs, date fields, etc),
97         use the --cast option (best used with the --length / --offset options):
98
99                 $ binwalk --cast --length=64 firmware.bin
100
101
102 CONTROLLING SCAN BEHAVIOR
103
104         Some signatures - notably those whose magic signatures are less than 3 bytes - are excluded by default
105         from binwalk scans. These can be individually included with the --include option, or globally with --all
106         (multiple --include options may be specified):
107
108                 $ binwalk --include=minix firmware.bin
109                 $ binwalk --all firmware.bin
110
111         By default results marked as invalid are not displayed. They can be displayed by specifying the --show-invalid
112         option:
113
114                 $ binwalk --show-invalid firmware.bin
115
116         By default binwalk will stop scanning for signatures at any given offset once a valid signature has been
117         found at that offset. To display all signatures that match at all offsets, use the --keep-going option:
118
119                 $ binwalk --keep-going firmware.bin
120
121
122 FILTERING SCAN RESULTS
123
124         It may at times be desirable to exclude certian signatures from the scan results. This can be done with the
125         --exclude option (multiple --exclude options may be specified):
126
127                 $ binwalk --exclude='lzma compressed data' firmware.bin
128
129         It may at times be desirable to only search for a certian signature or group of signatures. This can be 
130         done with the --search option (multiple --search options may be specified):
131         
132                 $ binwalk --search=filesystem firmware.bin
133
134         The --grep option is useful for filtering output that contains multiple results per line, such as occurs 
135         with the --cast option:
136
137                 $ binwalk --cast --grep=2012 firmware.bin
138
139 EXTRACTING FILES
140
141         Binwalk can extract matches found inside the target file(s), and optionally execute an external command
142         each time a file is extracted using the --dd option. At a minimum, a string to search for in the output
143         description and a file extension must be specified. A command to execute may also be specified. These 
144         three fields are colon delimited.
145
146         To extract all matches that contain the text 'gzip compressed data' and save them with a file extension
147         of 'gz':
148
149                 $ binwalk --dd='gzip compressed data:gz' firmware.bin
150         
151         To extract all matches that contain the text 'gzip compressed data', save them with a file extension of
152         'gz' and execute the 'gunzip' command against the extracted file (note the use of the %e place holder for
153         the path to the extracted file):
154
155                 $ binwalk --dd='gzip compressed data:gz:gunzip %e' firmware.bin
156         
157         There are some file types that are commonly extracted, and specifying a --dd option for each one is tiresome.
158         The -e option will load extract rules from the system/user extract.conf file (see the CONFIGURATION FILES section
159         below):
160
161                 $ binwalk -e firmware.bin
162         
163         To specify a different extraction rule file, use --extract:
164
165                 $ binwalk --extract=./my_extract.conf firmware.bin
166         
167         Extracting files with --dd or --extract can leave a lot of uneccessary files laying around. These can be 
168         automatically cleaned up with the --rm option. If specified, any extracted file that had a command run against
169         it will be deleted after the command has finished execution. Additionally, if files created by the executed
170         command are 0 bytes in size, they will also be removed:
171
172                 $ binwalk --rm firmware.bin
173
174         Some file types do not specify their file size in their header, but rather rely on a footer or delimiter to
175         signify the end of the file. When extracted these files will by default be copied from the start of the header
176         to the end of the target file. If there are many of these files, this can take up unecessary disk space. For
177         those files which are supported, specifying the --delay option will delay the extraction of these files until
178         the end of the file can be found:
179
180                 $ binwalk --delay firmware.bin
181
182         
183 DISPLAYING SCAN PROGRESS
184
185         Some scans can take some time to complete and may not display many results during this time. You can press the 
186         enter key at any time to force binwalk to display its current scan progress:
187
188                 $ binwalk -v firmware.bin
189
190                 DECIMAL         HEX             DESCRIPTION
191                 ------------------------------------------------------------------------------------------
192                 <Enter>
193                 Progress:  1595 / 12074736  (0.01%)
194                 <Enter>
195                 Progress:  8015 / 12074736  (0.07%)
196                 <Enter>
197                 Progress:  12424 / 12074736  (0.10%)
198
199
200 SIGNATURE FILES
201
202         There are three signature files used by binwalk:
203
204                 o magic/binwalk - The default signature file.
205                 o magic/binarch - The signature file used with --opcodes.
206                 o magic/bincast - The signature file used with --cast.
207
208         Users may create their own signatures that will be added to the respective system-wide files when performing a scan.
209         This is as easy as editing the following files in the user home directory:
210
211                 o .binwalk/magic/binwalk
212                 o .binwalk/magic/binarch
213                 o .binwalk/magic/bincast
214
215         Although the system-wide signature files can also be altered, the system-wide signature files will be overwritten when
216         upgrading binwalk, or using the --update option. The user files will not be touched however, and will survive these updates.
217
218
219 CONFIGURATION FILES
220
221         There is one configuration file used by binwalk only when the --extract option is specified:
222
223                 o config/extract.conf
224
225         This file contains a list of extract rules, identical to the arguments that would be passed to the --dd option.
226
227         Users can override and add to this list of extract rules by adding their own rules to the following file in the user home
228         directory:
229
230                 o .binwalk/config/extract.conf
231
232         Note that when overriding a system-wide extract rule, the 'type' field in the user extract rule must exactly match the 'type'
233         field in the system-wide extract rule.
234
235         Although the system-wide extract.conf file can also be altered, this file will be overwritten when upgrading binwalk or using
236         the --update option. The user extract.conf file will not be touched however, and will survive these updates.
237
238 MORE INFORMATION
239
240         For more detailed and up to date information, visit the binwalk wiki page at:
241
242                 http://code.google.com/p/binwalk/wiki/TableOfContents
243