Binary Ninja Backend
Install
Binary Ninja is not distributed with OFRAK. You need to have a valid Binary Ninja license to use OFRAK Binary Ninja. You can run OFRAK Binary Ninja natively with a valid commercial licence, and in a Docker container with a valid headless license.
The recommended Binary Ninja version to use with OFRAK is 3.2.3814. If you are running OFRAK outside of the Docker image, you can switch to this version of Binary Ninja using the Binary Ninja version switcher.
You need to have Binary Ninja installed along with a valid commercial Binary Ninja license to run OFRAK Binary Ninja natively.
- Create a virtual environment to which you will install code:
% python3 -m venv venv % source venv/bin/activate
- Install
ofrak
and its dependencies. - Run
make {install, develop}
inside of the 'ofrak_binary_ninja/' directory to install OFRAK Binary Ninja. - Next, install the Binary Ninja Python APIs in your virtual environment
% python3 "/Applications/Binary Ninja.app/Contents/Resources/scripts/install_api.py" -v
You need to have a valid headless Binary Ninja license to build and run the Docker image. Read about the environment setup for more details.
To build the image, the license should be placed in the project's root directory and named license.dat
. The serial number needs to be extracted from that file into a file named serial.txt
. This can be done with the following command:
python3 \
-c 'import json, sys; print(json.load(sys.stdin)[0]["serial"])' \
< license.dat \
> serial.txt
The command DOCKER_BUILDKIT=1 python3 build_image.py --config ofrak-binary-ninja.yml --base --finish
will build an image using Docker BuildKit secrets so that neither the license nor serial number are exposed in the built Docker image. BuildKit is required for the build to succeed!
The Docker container should be run with the same license file from the installation step. The license can then be mounted into the Docker container at location /root/.binaryninja/license.dat
by adding the following arguments to the docker run
command:
--mount type=bind,source="$(pwd)"/license.dat,target=/root/.binaryninja/license.dat
For example:
# This simple command...
docker run -it redballoonsecurity/ofrak/binary-ninja bash
# ...becomes the following. Notice the --mount
docker run \
-it \
--mount type=bind,source="$(pwd)"/license.dat,target=/root/.binaryninja/license.dat \
redballoonsecurity/ofrak/binary-ninja \
bash
Usage
To use Binary Ninja, you need to discover the components at setup-time with:
ofrak = OFRAK(logging.INFO)
ofrak.injector.discover(ofrak_binary_ninja)
Warning
You can only use one of these analysis backends at a time (angr OR Binary Ninja OR Ghidra)
Binary Ninja auto-analysis
Using Binary Ninja auto-analysis is transparent after the components are discovered, you don't have to do anything!
Manually-analyzed program import
If Binary Ninja auto-analysis doesn't match the expected analysis of a file, you can manually process the file in the Binary Ninja desktop application and apply any manual patch of the analysis. Then export a Binary Ninja DataBase file (.bndb
).
You will need both your original file (<file_path>
) and the Binary Ninja DataBase (<bndb_file_path>
) in the ofrak script.
Define a BinaryNinjaAnalyzerConfig
and manually run the BinaryNinjaAnalyzer
:
async def main(ofrak_context: OFRAKContext,):
resource = await ofrak_context.create_root_resource_from_file(<file_path>)
binary_ninja_config = BinaryNinjaAnalyzerConfig(<bndb_file_path>)
await resource.run(BinaryNinjaAnalyzer, binary_ninja_config)
if __name__ == "__main__":
ofrak = OFRAK(logging.INFO)
ofrak.injector.discover(ofrak_binary_ninja)
ofrak.run(main)
Documentation
Binary Ninja User Documentation
Troubleshooting
You can test python code in the interactive python console available in the Binary Ninja desktop application. Enable it with View -> Native Docks -> Show Python Console
(on Mac).