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