Imported Upstream version 1.2.2-1
[packages/binwalk.git] / docs / API
1 DESCRIPTION
2
3         The binwalk python module can be used by any python script to programatically perform binwalk scans and 
4         obtain the results of those scans. 
5
6         The classes, methods and objects in the binwalk modules are documented via pydoc, including examples, 
7         so those interested in using the binwalk module are encouraged to look there. However, several common usage 
8         examples are provided here to help jump-start development efforts.
9
10
11 BASIC SCAN
12
13         The following is an example of the simplest scan, and is equivalent to running binwalk on the command line 
14         with no additional arguments:
15
16                 import pprint
17                 from binwalk import Binwalk
18
19                 with Binwalk() as bw:
20                         pprint.PrettyPrinter().pprint(bw.scan('firmware.bin'))
21
22         The scan() method will return a dictionary of results, and may also be passed a list of files:
23
24                 from binwalk import Binwalk
25
26                 with Binwalk() as bw:
27                         for (filename, file_results) in bw.scan(['firmware1.bin', 'firmware2.bin']).iteritems():
28                         print "Results for %s:" % filename
29                         for (offset, results) in file_results:
30                                 for result in results:
31                                         print offset, result['description']
32
33         Alternatively, a callback function may be specified. The callback function is called as soon as a match is found. 
34         It is passed two arguments: the offset at which the match was found, and a list of results dictionaries (one dictionary 
35         per result found at that offset):
36
37                 from binwalk import Binwalk
38
39                 def my_callback(offset, results):
40                         print "Found %d results at offset %d:" % (len(results), offset)
41                         for result in results:
42                                 print " %s" % result['description']
43
44                 with Binwalk() as bw:
45                         bw.scan('firmware.bin', callback=my_callback)
46
47
48 ADDING FILTERS
49
50         Include and exclude filters may be specified which operate identically to the --include, and --exclude binwalk
51         command line options:
52
53                 from binwalk import Binwalk
54                 
55                 binwalk = Binwalk()
56                 
57                 # Exclusively filters out all signatures except those containing the string 'filesystem' (same as --include)
58                 binwalk.filter.include('filesystem')
59
60                 # Excludes all results that contain the string 'jffs2' (same as --exclude)
61                 binwalk.filter.exclude('jffs2')
62
63                 binwalk.scan('firmware')
64                 binwalk.cleanup()
65
66
67 EXTRACTING FILES
68
69         Extract rules may be specified which operate identically to the --dd and --extract binwalk command line options.
70         Extraction is automatically enabled when one or more extraction rules are specified.
71         
72         To add a custom extract rule, or a list of extract rules (such as with the --dd option):
73
74                 from binwalk import Binwalk
75
76                 binwalk = Binwalk()
77
78                 # Extract results containing the string 'gzip' with a file extension of 'gz' and run the gunzip command
79                 binwalk.extractor.add_rule('gzip:gz:gunzip %e')
80
81                 # Extract 'gzip' and 'filesystem' results
82                 binwalk.extractor.add_rule(['gzip:gz', 'filesystem:fs'])
83
84                 binwalk.scan('firmware')
85                 binwalk.cleanup()
86
87         To load the default extraction rules from the extract.conf file (such as with the --extract option):
88         
89                 from binwalk import Binwalk
90                 
91                 binwalk = Binwalk()
92                 binwalk.extractor.load_defaults()
93                 binwalk.scan('firmware.bin')
94                 binwalk.cleanup()
95
96         To enabled delayed file extraction (such as with the --delay option):
97
98                 from binwalk import Binwalk
99                 
100                 binwalk = Binwalk()
101                 binwalk.extractor.enable_delayed_extract(True)
102                 binwalk.scan('firmware.bin')
103                 binwalk.cleanup()
104
105         To enable file cleanup after extraction (such as with the --rm option):
106
107                 from binwalk import Binwalk
108                 
109                 binwalk = Binwalk()
110                 binwalk.extractor.cleanup_extracted_files(True)
111                 binwalk.scan('firmware.bin')
112                 binwalk.cleanup()
113