Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/google/binnavi

BinNavi is a binary analysis IDE that allows to inspect, navigate, edit and annotate control flow graphs and call graphs of disassembled code.
https://github.com/google/binnavi

analysis binnavi java reverse-engineering yfiles

Last synced: 3 months ago
JSON representation

BinNavi is a binary analysis IDE that allows to inspect, navigate, edit and annotate control flow graphs and call graphs of disassembled code.

Awesome Lists containing this project

README 

        
# BinNavi [![Build Status](https://api.travis-ci.org/google/binnavi.svg?branch=master)](https://travis-ci.org/google/binnavi)



Copyright 2011-2020 Google LLC



## 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.



**Note: The BinNavi project is no longer under active development.**



## Commercial 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:



1) 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.

Java 11 is the minimum supported version.



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.



1. Install the dependencies (as described above) and make sure you have a

   Java SDK with 1.8 language compliance installed.

2. Create a new "Java Project From Existing Ant Buildfile" and use the file ``build.xml``

3. Select the "javac" task found in target "build-binnavi-jar"

4. Open the "Project Properties" dialog and choose "Java build Path" showing the "Source" tab.

5. 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"

6. Add ``**/yfileswrap/**`` to the list of directories to exclude.

7. 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 authoritative 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:



1. Open Eclipse.

2. File > Import... from menu bar.

3. From the window that appears select General > Existing Projects into Workspace.

4. Ensure the "Select root directory" radio button is selected.

5. Click Browse... and navigate to the project directory. 

6. The projects area should now have "binnavi" and a tick next to it.

7. 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:



1. Open IntelliJ.

2. Select "Open" from main window.

3. Navigate to the project folder and should see the IntelliJ icon. This signifies its a project.

4. Press Ok and wait for it to import and load. 

5. 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.