summaryrefslogtreecommitdiff
path: root/docs/guide/batch-processing.md
diff options
context:
space:
mode:
authorJordan Wiens <jordan@psifertex.com>2020-11-12 14:01:48 -0500
committerJordan Wiens <jordan@psifertex.com>2020-11-12 14:01:48 -0500
commitfb7f50532a8db63478bfe7bf9d21adf595c94c7a (patch)
treee23c8a7ecd6e26b832901c96c5ed78cd7c8bc26f /docs/guide/batch-processing.md
parent0e4485d2c6025cd08ed908be31d1e6c22436f2f3 (diff)
add environment variable overrides to batch documentation and fix typos
Diffstat (limited to 'docs/guide/batch-processing.md')
-rw-r--r--docs/guide/batch-processing.md25
1 files changed, 20 insertions, 5 deletions
diff --git a/docs/guide/batch-processing.md b/docs/guide/batch-processing.md
index 0ca55f3f..0277e56d 100644
--- a/docs/guide/batch-processing.md
+++ b/docs/guide/batch-processing.md
@@ -1,6 +1,6 @@
# Batch Processing and Other Automation Tips
-An often asked question of Binary Ninja is "How do I enable batch-processing mode?". The answer is that we don't have one--but the good news is because it doesn't need it! We have an even better solution. BN is simply a library that is trival to include in your own scripts for batch analysis. As long as you have a Commercial license (or a [headless](https://binary.ninja/purchase/#container:~:text=This%20works%20especially%20well%20with%20our,that%20are%20designed%20for%20headless%2Donly%20installs.) license), it's possible to invoke the core analysis library with all of its APIs without even launching the UI.
+An often asked question of Binary Ninja is "How do I enable batch-processing mode?". The answer is that we don't have one--but the good news is because it doesn't need it! We have an even better solution. BN is simply a library that is trivial to include in your own scripts for batch analysis. As long as you have a Commercial license (or a [headless](https://binary.ninja/purchase/#container:~:text=This%20works%20especially%20well%20with%20our,that%20are%20designed%20for%20headless%2Donly%20installs.) license), it's possible to invoke the core analysis library with all of its APIs without even launching the UI.
This document describes some general tips and tricks for effective batch processing. In particular, because Binary Ninja is multi-threaded, some methods for faster processing like [multiprocessing](https://docs.python.org/3/library/multiprocessing.html) can have dangerous consequences.
@@ -32,7 +32,7 @@ $ ./first.py
Opening /bin/ls which has 128 functions
```
-Note that we used the `open_view` method which lets you temporarily create a `bv` with the appropriate sope. The traditional way to do that was with `BinaryViewType.get_view_of_file` which returns a [BinaryView](https://api.binary.ninja/binaryninja.binaryview.BinaryView.html#binaryninja.binaryview.BinaryView) directly. Note however, that if you use that method you **MUST** close the BinaryView yourself when you are done with it. To do so, just:
+Note that we used the `open_view` method which lets you temporarily create a `bv` with the appropriate scope. The traditional way to do that was with `BinaryViewType.get_view_of_file` which returns a [BinaryView](https://api.binary.ninja/binaryninja.binaryview.BinaryView.html#binaryninja.binaryview.BinaryView) directly. Note however, that if you use that method you **MUST** close the BinaryView yourself when you are done with it. To do so, just:
```
bv.file.close()
@@ -40,7 +40,7 @@ bv.file.close()
### Multiple files
-Looks good! But what if we just want to parse basic headers or stop any major analysis from happening and scan multiple files quickly? We can use the `update_analysis` named parameter to prevent the usual linear sweep and recursive descent analysis from event occuring:
+Looks good! But what if we just want to parse basic headers or stop any major analysis from happening and scan multiple files quickly? We can use the `update_analysis` named parameter to prevent the usual linear sweep and recursive descent analysis from event occurring:
```python
#!/usr/bin/env python3
@@ -67,11 +67,11 @@ Notice that we have far fewer functions in `/bin/ls` this time. By shortcutting
### Further Customization
-We can customize our analysis a lot more granularly than that though. `open_view` is actually a wrapper around [`get_view_of_file_with_options`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryViewType.get_view_of_file_with_options). Notice the named `options` parameter, and the example code. Any setting you can set in the Binary Ninja "Open with Options" UI you can set through that paremter.
+We can customize our analysis a lot more granularly than that though. `open_view` is actually a wrapper around [`get_view_of_file_with_options`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryViewType.get_view_of_file_with_options). Notice the named `options` parameter, and the example code. Any setting you can set in the Binary Ninja "Open with Options" UI you can set through that parameter.
## Parallelization
-Of course, one of the main reasons you might want to build some automation so to spin up a number of threads to process multiple files. Be aware though, that Binary Ninja itself is multithreaded. In fact, if the bottle neck for your analysis script is BN itself, you're almost certainly better off not using any parallelization because the multithreading BN does on its own will provide more benefit than you'd gain by extra paralellization.
+Of course, one of the main reasons you might want to build some automation so to spin up a number of threads to process multiple files. Be aware though, that Binary Ninja itself is multithreaded. In fact, if the bottle neck for your analysis script is BN itself, you're almost certainly better off not using any parallelization because the multithreading BN does on its own will provide more benefit than you'd gain by extra parallelization.
That said, there are certainly several good use cases where splitting your analysis makes sense. When processing many files for example, you might want to use multiple processes so that a single big slow file doesn't slow down the rest of the analysis as much. Or if you're working with potentially malformed files that may trigger bugs or crashes and you're worried about a single script failing.
@@ -111,6 +111,21 @@ if __name__ == '__main__':
Of course, if you do any timing tests you'll quickly notice that this script is actually much slower than the previous, simpler example! Again, you probably only want to use some parallelization like this if the additional analysis you're doing on top of Binary Ninja is the bigger bottleneck in your analysis and thus you really want to split your analysis up across multiple processes.
+## Disabling Plugins and Settings
+
+Because the headless APIs will be using the same settings as the UI, you may wish to write batch-processing scripts that do NOT follow the same settings that you are using for interactive analysis. Likewise with wanting to not load additional plugins. You can disable loading of both of those by setting environment variables before importing binaryninja like:
+
+```python
+import os
+os.environ["BN_DISABLE_USER_SETTINGS"] = 1
+os.environ["BN_DISABLE_USER_PLUGINS"] = 1
+import binaryninja
+```
+
+Other alternative solutions include manually moving your settings file from your [user folder](../getting-started.md#user-folder) before running your headless automation
+
## Other Languages
TODO
+
+First, make sure to run the [install_api.py](https://github.com/Vector35/binaryninja-api/tree/dev/scripts) script. Note that the script is shipped with Binary Ninja already, just look in your [binary path](../getting-started.md#binary-path) inside of the `scripts` subfolder. Run it like: \ No newline at end of file