Copyright 2011-2016 Google Inc.
Disclaimer: This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.
Introduction
BinNavi is a binary analysis IDE - an environment that allows users to inspect, navigate, edit, and annotate control-flow-graphs of disassembled code, do the same for the callgraph of the executable, collect and combine execution traces, and generally keep track of analysis results among a group of analysts.
Complications from a third-party dependency
BinNavi uses a commercial third-party graph visualisation library (yFiles) for displaying and laying out graphs. This library is immensely powerful, and not easily replaceable.
In order to perform direct development using yFiles, you need a developer license for it. At the same time, we want the community to be able to contribute to BinNavi without needing a commercial yFiles license. In order to do this and conform to the yFiles license, all interfaces to yFiles need to be properly obfuscated.
In order to achieve this, we did the following:
- BinNavi and all the libraries have been split into two: The parts of the project that directly depend on yFiles were split into subpackages called "yfileswrap":
com.google.security.zynamics.binnavi
com.google.security.zynamics.binnavi.yfileswrap
com.google.security.zynamics.zylib
com.google.security.zynamics.zylib.yfileswrap
com.google.security.zynamics.reil
com.google.security.zynamics.reil.yfileswrap
We are distributing a pre-built JAR file with all the code in the yfileswrap
subpackages - pre-linked and obfuscated against yFiles. If you wish to change
or add code in BinNavi and do not have a yFiles license, you can freely do
pretty much whatever you want in the non-yfileswrap packages - you can simply
put the lib/yfileswrap-obfuscated.jar
into your classpath to test and see
the results.
If you wish to make changes to the yfileswrap
subdirectories, please be aware
that you will need a valid yFiles license - and any contribution that you make
to the BinNavi project has to honor their license agreement. This means that
you can't simply expose their inner APIs under different names etc.
We will enforce this - we're very happy to have found a way to open-source BinNavi with the yFiles dependency, and we will make sure that any code we pull in respects the yFiles license.
Note for maintainers/yFiles license holders
To rebuild the yFiles wrapper library, first copy y.jar
and ysvg.jar
to
third_party/java/yfiles
. Then rebuild with:
mvn dependency:copy-dependencies
ant build-yfiles-wrapper-jar
mvn install:install-file \
-Dfile=target/yfileswrap-obfuscated.jar \
-DgroupId=com.google.security.zynamics.binnavi \
-DartifactId=yfileswrap-obfuscated \
-Dversion=6.1 \
-Dpackaging=jar \
-DlocalRepositoryPath=lib
Building BinNavi from scratch
BinNavi uses Maven for its dependency management, but not for the actual build yet. To build from scratch use these commands:
mvn dependency:copy-dependencies
ant build-binnavi-fat-jar
Running BinNavi for the first time
Please be aware that BinNavi makes use of a central PostgreSQL database for storing disassemblies/comments/traces - so you need to have such an instance running somewhere accessible to you. You can launch BinNavi as follows:
java -jar target/binnavi-all.jar
Importing the project into Eclipse
Loading the code into Eclipse for further development requires a little bit of configuration.
- Install the dependencies (as described above) and make sure you have a Java SDK with 1.8 language compliance installed.
- Create a new "Java Project From Existing Ant Buildfile" and use the file
build.xml
- Select the "javac" task found in target "build-binnavi-jar"
- Open the "Project Properties" dialog and choose "Java build Path" showing the "Source" tab.
- Remove all but one source folder and edit it to have the following properties:
- Linked Folder Location:
PROJECT_LOC/src/main/java
- Folder Name:
java
- Click on "Next"
- Linked Folder Location:
- Add
**/yfileswrap/**
to the list of directories to exclude. - Go to "Run->Run As", select "Java Application" and then search for
CMain
.
You should be ready to go from here.
Exporting disassemblies from IDA
As part of this project, we are distributing an IDA Pro plugin that exports disassemblies from IDA into the PostgreSQL database format that BinNavi requires. When running BinNavi, simply configure the right path for IDA, click on the "install plugin" button if necessary -- you should now be able to import disassemblies.
Using other disassemblers than IDA
Right now, we only have the IDA export plugin - but we are hoping very much that someone will help us build export functionality for other disassemblers in the near future.
Building BinNavi with Gradle
Please note that at current the Maven build is the authorative build system for BinNavi. Gradle is purely experimental and is likely to change.
You can build BinNavi with gradle by running the following:
On Linux / OS X:
$ ./gradlew clean jar
On Windows:
./gradlew.bat clean jar
This will produce the jar in the project route under build/libs/
.
Loading the project into Eclipse with Gradle
On Linux / OS X:
$ ./gradlew eclipse
On Windows:
./gradlew.bat eclipse
As part of the project creation process it will download the dependencies. Once complete do the following to load into Eclipse:
- Open Eclipse.
- File > Import... from menu bar.
- From the window that appears select General > Existing Projects into Workspace.
- Ensure the "Select root directory" radio button is selected.
- Click Browse... and navigate to the project directory.
- The projects area should now have "binnavi" and a tick next to it.
- Press Finish.
You Eclipse workspace is now setup and complete for BinNavi.
Loading the project into IntelliJ with Gradle
On Linux / OS X:
$ ./gradlew idea
On Windows:
./gradlew.bat idea
As part of the project creation process it will download the dependencies. Once complete do the following to load into IntelliJ:
- Open IntelliJ.
- Select "Open" from main window.
- Navigate to the project folder and should see the IntelliJ icon. This signifies its a project.
- Press Ok and wait for it to import and load.
- IntelliJ might not recognise it as a gradle project. Select enable from the popup window and use local gradle.
Your IntelliJ environment is now setup and complete for IntelliJ.