1Description
2===========
3
4The binwalk python module can be used by any python script to programmatically perform binwalk scans and obtain the results of those scans.
5
6The classes, methods and objects in the binwalk modules are documented via pydoc, including examples, so those interested in using the binwalk module are encouraged to look there. However, several common usage examples are provided here to help jump-start development efforts.
7
8
9Binwalk Scripting
10=================
11
12Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules. These modules can be invoked via `binwalk.scan`.
13
14In fact, the binwalk command line utility can be duplicated nearly entirely with just two lines of code:
15
16```python
17import binwalk
18binwalk.scan()
19```
20
21The `scan` 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).
22
23For example, to execute a signature scan, you at the very least have to specify the `--signature` option, as well as a list of files to scan. This can be done in a number of ways:
24
25```python
26binwalk.scan('--signature', 'firmware1.bin', 'firmware2.bin')
27
28binwalk.scan('firmware1.bin', 'firmware2.bin', signature=True)
29
30binwalk.scan('firmware1.bin', 'firmware2.bin', **{'signature' : True})
31
32binwalk.scan(*['firmware1.bin', 'firmware2.bin'], signature=True)
33
34binwalk.scan(*['--signature', 'firmware1.bin', 'firmware2.bin',])
35```
36
37All args and kwargs keys/values correspond to binwalk's command line options. Either args or kwargs, or a combination of the two may be used, with the following caveats:
38
39* All command line switches passed via args must be preceded by hyphens
40* All file names must be passed via args, not kwargs
41
42There is one available API argument which is not exposed via the command line: the `string` argument. When `string` is set to True, data to be scanned can be passed directly to the binwalk module, rather than a file name:
43
44```python
45data = "This is some data to scan for signatures"
46binwalk.scan(data, signature=True, string=True)
47```
48
49Accessing Scan Results
50======================
51
52`binwalk.scan` 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.
53
54The two attributes of greatest interest for each object are the `results` and `errors` objects. Each is a list of `binwalk.core.module.Result` and `binwalk.core.module.Error` instances, respectively. Each `Result` or `Error` instance may contain custom attributes set by each module, but are guaranteed to have at least the following attributes (though modules are not required to populate all attributes):
55
56|  Attribute  | Description |
57|-------------|-------------|
58| offset      | The file offset of the result/error (usually unused for errors) |
59| description | The result/error description, as displayed to the user |
60| module      | Name of the module that generated the result/error |
61| file        | The file object of the scanned file |
62| valid       | Set to True if the result is valid, False if invalid (usually unused for errors) |
63| display     | Set to True to display the result to the user, False to hide it (usually unused for errors) |
64| extract     | Set to True to flag this result for extraction (not used for errors) |
65| plot        | Set to False to exclude this result from entropy plots (not used for errors) |
66
67binwalk.core.module.Error has the additional guaranteed attribute:
68
69|  Attribute  | Description |
70|-------------|-------------|
71| exception   | Contains the Python exception object if the encountered error was an exception |
72
73Thus, scan results and errors can be programatically accessed rather easily:
74
75```python
76for module in binwalk.scan('firmware1.bin', 'firmware2.bin', signature=True, quiet=True):
77    print ("%s Results:" % module.name)
78    for result in module.results:
79        print ("\t%s    0x%.8X    %s" % (result.file.path, result.offset, result.description))
80```
81
82Note the above use of the `--quiet` option which prevents the binwalk module from printing its normal output to screen.
83
84Each module object will also have an additional `extractor` attribute, which is an instance of the `binwalk.modules.extractor.Extractor` class. Of particular use is `binwalk.modules.extractor.Extrctor.output`, a dictionary containing information about carved/extracted data:
85
86```python
87for module in binwalk.scan('firmware1.bin', 'firmware2.bin', signature=True, quiet=True, extract=True):
88    for result in module.results:
89        if module.extractor.output.has_key(result.file.path):
90            # These are files that binwalk carved out of the original firmware image, a la dd
91            if module.extractor.output[result.file.path].carved.has_key(result.offset):
92                print "Carved data from offset 0x%X to %s" % (module.extractor.output[result.file.path].carved[result.offset])
93            # These are files/directories created by extraction utilities (gunzip, tar, unsquashfs, etc)
94            if module.extractor.output[result.file.path].extracted.has_key(result.offset):
95                print "Extracted data from offset 0x%X to %s" % (module.extractor.output[result.file.path].extracted[result.offset][0])
96```
97
98Module Exceptions
99=================
100
101The only expected exception that should be raised is that of binwalk.ModuleException. This exception is thrown only if a required module encountered a fatal error (e.g., one of the specified target files could not be opened):
102
103```python
104try:
105    binwalk.scan()
106except binwalk.ModuleException as e:
107    print ("Critical failure:", e)
108```
109