Imported Upstream version 1.0
[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         This is the simplest scan, and is equivalent to running binwalk on the command line with no additional arguments.
14         Note the use of the cleanup() method, which will ensure all temporary files generated by binwalk are cleaned up:
15
16                 from binwalk import Binwalk
17
18                 binwalk = Binwalk()
19                 results = binwalk.scan('firmware.bin')
20                 binwalk.cleanup()
21
22         The scan() method will return a list of tuples, one tuple for each offset in the target file where a matching
23         signature was found. The first element of each tuple is the offset into the file at which the match was found. 
24         The second tuple is a list of dictionaries (depending on the binwalk options, there may be more than one match 
25         for a given offset); each dictionary describes a matching signature:
26
27                 results = [
28                                 (0, [{description : "LZMA compressed data..."}]),
29                                 (112, [{description : "gzip compressed data..."}]),
30                 ]
31
32         A callback function may also be specified. The callback function is called as soon as a match is identified. It
33         is passed two arguments: the offset at which the match was found, and a list of dictionaries as described above:
34
35                 from binwalk import Binwalk
36
37                 def my_callback(offset, results):
38                         print "Found %d results at offset %d:" % (len(results), offset)
39                         for result in results:
40                                 print " %s" % result['description']
41
42                 binwalk = Binwalk(callback=my_callback)
43                 binwalk.scan('firmware.bin')
44                 binwalk.cleanup()
45
46
47 ADDING FILTERS
48
49         Include and exclude filters may be specified which operate identically to the --include, --exclude and --search
50         binwalk command line options:
51
52                 from binwalk import Binwalk
53                 
54                 binwalk = Binwalk()
55                 
56                 # Adds a normally excluded signature to the existing list of signatures (same as --include)
57                 binwalk.filter.include('minix', exclusive=False)
58
59                 # Exclusively filters out all signatures except those containing the string 'filesystem' (same as --search)
60                 binwalk.filter.include('filesystem')
61
62                 # Excludes all results that contain the string 'jffs2' (same as --exclude)
63                 binwalk.filter.exclude('jffs2')
64
65                 binwalk.scan('firmware')
66
67
68 EXTRACTING FILES
69
70         Extract rules may be specified which operate identically to the --dd and --extract binwalk command line options.
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
86         To load the default extraction rules from the extract.conf file (such as with the --extract option):
87         
88                 from binwalk import Binwalk
89                 
90                 binwalk = Binwalk()
91                 binwalk.extractor.load_defaults()
92                 binwalk.Scan('firmware.bin')
93
94
95         To enabled delayed file extraction (such as with the --delay option):
96
97                 from binwalk import Binwalk
98                 
99                 binwalk = Binwalk()
100                 binwalk.extractor.enable_delayed_extract(True)
101                 binwalk.Scan('firmware.bin')
102
103         To enable file cleanup after extraction (such as with the --rm option):
104
105                 from binwalk import Binwalk
106                 
107                 binwalk = Binwalk()
108                 binwalk.extractor.cleanup_extracted_files(True)
109                 binwalk.Scan('firmware.bin')
110