Commit cf480ef3 by devttys0

Minor update to API.md

parent a0048db7
...@@ -9,40 +9,40 @@ The classes, methods and objects in the binwalk modules are documented via pydoc ...@@ -9,40 +9,40 @@ The classes, methods and objects in the binwalk modules are documented via pydoc
Binwalk Scripting Binwalk Scripting
================= =================
Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules. These modules can be invoked via `binwalk.execute`. Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules. These modules can be invoked via `binwalk.scan`.
In fact, the binwalk command line utility can be duplicated nearly entirely with just two lines of code: In fact, the binwalk command line utility can be duplicated nearly entirely with just two lines of code:
```python ```python
import binwalk import binwalk
binwalk.execute() binwalk.scan()
``` ```
The `execute` 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). The `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).
For example, to execute a signature scan, you at the very least have to specify the `--signature` command line option, as well as a list of files to scan. This can be done in a number of ways: For example, to execute a signature scan, you at the very least have to specify the `--signature` command line option, as well as a list of files to scan. This can be done in a number of ways:
```python ```python
binwalk.execute('firmware1.bin', 'firmware2.bin', signature=True) binwalk.scan('firmware1.bin', 'firmware2.bin', signature=True)
binwalk.execute('firmware1.bin', 'firmware2.bin', **{'signature' : True}) binwalk.scan('firmware1.bin', 'firmware2.bin', **{'signature' : True})
binwalk.execute(*['firmware1.bin', 'firmware2.bin'], signature=True) binwalk.scan(*['firmware1.bin', 'firmware2.bin'], signature=True)
binwalk.execute(*['--signature', 'firmware1.bin', 'firmware2.bin',]) binwalk.scan(*['--signature', 'firmware1.bin', 'firmware2.bin',])
binwalk.execute('--signature', 'firmware1.bin', 'firmware2.bin') binwalk.scan('--signature', 'firmware1.bin', 'firmware2.bin')
``` ```
All 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: All 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:
* All command line switches passed via args must be preceeded by hyphens (not required for kwargs) * All command line switches passed via args must be preceeded by hyphens
* All file names must be passed via args, not kwargs * All file names must be passed via args, not kwargs
Accessing Scan Results Accessing Scan Results
====================== ======================
`binwalk.execute` 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. `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.
The two attributes of interest for each object are the `results` and `errors` objects. Each is a list of binwalk.core.module.Result and binwalk.core.module.Error objects respectively. Each Result or Error object may contain custom attributes set by each module, but are guarunteed to have at least the following attributes (though modules are not required to populate all attributes): The two attributes of interest for each object are the `results` and `errors` objects. Each is a list of binwalk.core.module.Result and binwalk.core.module.Error objects respectively. Each Result or Error object may contain custom attributes set by each module, but are guarunteed to have at least the following attributes (though modules are not required to populate all attributes):
...@@ -66,7 +66,7 @@ binwalk.core.module.Error has the additional guarunteed attribute: ...@@ -66,7 +66,7 @@ binwalk.core.module.Error has the additional guarunteed attribute:
Thus, scan results and errors can be programatically accessed rather easily: Thus, scan results and errors can be programatically accessed rather easily:
```python ```python
for module in binwalk.execute('firmware1.bin', 'firmware2.bin', signature=True): for module in binwalk.scan('firmware1.bin', 'firmware2.bin', signature=True):
print ("%s Results:" % module.name) print ("%s Results:" % module.name)
for result in module.results: for result in module.results:
print ("\t%s 0x%.8X %s" % (result.file.name, result.offset, result.description)) print ("\t%s 0x%.8X %s" % (result.file.name, result.offset, result.description))
...@@ -79,7 +79,7 @@ The only expected exception that should be raised is that of binwalk.ModuleExcep ...@@ -79,7 +79,7 @@ The only expected exception that should be raised is that of binwalk.ModuleExcep
```python ```python
try: try:
binwalk.execute() binwalk.scan()
except binwalk.ModuleException as e: except binwalk.ModuleException as e:
print ("Critical failure:", e) print ("Critical failure:", e)
``` ```
...@@ -84,6 +84,7 @@ Currently, the following libmagic versions are known to work properly with binwa ...@@ -84,6 +84,7 @@ Currently, the following libmagic versions are known to work properly with binwa
5.19 5.19
5.20 5.20
Specifying a Python Interpreter Specifying a Python Interpreter
=============================== ===============================
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment