This is the README of the Joana IFC analysis framework.

Joana is developed at the Programming Paradigms Group of the Karlsruhe Institute of Technology. This software is a RESEARCH PROTOTYPE that comes with absolute NO WARRANTY.

For further details and publications related to Joana please visit our homepage at http://joana.ipd.kit.edu.

In case you find BUGS, feel free to report them through the GitHub bug tracker.

In case you want to contact us, we are:

Martin Mohr martin.mohr@kit.edu Martin Hecker martin.hecker@kit.edu Simon Bischof simon.bischof@kit.edu Johannes Bechberger johannes.bechberger@kit.edu

Joana is based on previous work and research done by Jens Krinke, Christian Hammer, Dennis Giffhorn and many students at the University of Passau and the Karsruhe Institute of Technology.

================== === What is Joana?

Joana is a static analysis tool that can be used for information flow control (IFC) of Java bytecode. IFC allows to verify the INTEGRITY (no attacker can temper with sensitive information) or CONFIDENTIALITY (no attacker can infer secret information from public outputs) of a Java program.

System dependence graphs (SDG) form the basic technology for our analyses. These graphs precisely represent all information flow within a program. To classify the sensitivity of data, input and output channels of a program are annotated with security levels. Joana determines using a data flow analysis on the SDG whether data of a certain security level may illicitly reach an unauthorized user of the system

==================================================== === Very quick first time setup (just compile .jars)

1. Requirements

2. a recent Linux (e.g. Ubuntu) or a recent MacOS (Windows is only tested occasionally)

3. Java == 1.8
4. ant >= 1.9.6
5. Maven >= 3.x

6. g++ compiler for WALA (build-essential package on ubuntu and debian)

7. Fetch submodule sources

git submodule init git submodule update

1. Setup WALA and other dependencies

./setup_deps

1. Run ant

ant

1. Jar-files should have been generated in dist/

==================== === First time setup

1. General remarks

Joana needs Java 1.8 or above.

We suggest to use and compile Joana using eclipse, but you may also just build and use its core parts with ant. Please see the "Building Joana with ant" section for details.

For Eclipse you will need the following setup in order to compile and run Joana:

Eclipse >= 3.7 Download classic package, as it contains already plug-in-development stuff. Do not forget to set an API Baseline!

We use the ANTLR parser generator to generate various parsers for Joana from grammars. We provide an ANTLRv3 jar and the generated parser source code is also present in the git repo, so you don't need to install ANTLR or generate any parsers. However, if you want to edit or extend the parsers from within eclipse, you may want to install the ANTLRv3 IDE plug-in (http://antlrv3ide.sourceforge.net/). Please note that the "v3" denotes the version of ANTLR itself, not the version of the actual plug-in.

The ANTLRv3 plugin needs also the following plug-ins:

* Dynamic Languages Toolkit - Core Framework 3.0.1
    (http://www.eclipse.org/dltk)
    Important: Use version 3.0.1 as ANTLR v3 IDE does not work with a
    newer version. You may have to install this manually on newer
    eclipse versions.
* Graphical Editing Framework GEF SDK
* Graphical Editing Framework Zest SDK

Eclipse should have >= 1024M heap space when running.

Setting up the workspace:

When you add projects from the GIT repository to your workspace we
strongly suggest to use the "Import existing project" feature and to
not copy files. This way changes you make to Joana will also be made
to the files in your repository and not only on the local copy in your
workspace. Also many Joana projects rely on the directory layout in
the repository to e.g. load example source files from ../../example/.
This will not work properly if project files are copied into the
workspace.

1. Download and setup WALA 2.1. Init submodule and download WALA framework sources

git submodule init git submodule update

2.2. Open eclipse and add projects

Joana needs the following WALA projects in the workspace:

com.ibm.wala.core com.ibm.wala.shrike com.ibm.wala.util

If you also plan to use some of the deprecated Joana projects, you will also need.

com.ibm.wala.cast com.ibm.wala.cast.java com.ibm.wala.ide

See further information on setting up WALA at wala.sf.net.

1. Add Joana projects to workspace

You may want to add at least the following projects to your workspace, in order to get the core parts of Joana:

in wala/: joana.wala.core joana.wala.flowless joana.wala.summary joana.wala.util

in ifc/sdg:

• all -

in contrib/lib: joana.contrib.lib

in util: joana.util

For use of the Joana API, also import (from api/) joana.api joana.api.annotations.passon

If you also want to add the eclipse project of the IFC Console, you need additionally (from ui/ifc/wala): joana.ui.ifc.wala.console

======================== === Build Joana with ant

All jar-files are copied into the global dest/ directory. The following jar files can be built. Normally you will want to choose joana.api.jar or joana.ui.ifc.wala.console.jar, depending on if you want a nice GUI or not. They contain all the classes you need for a standard IFC analysis. Other jar-files are mostly only relevant for development purposes. Please note that in order to build these jars, you first need to setup Joana and WALA as described in "Very quick first time setup".

joana.api.jar Contains wala, joana.wala and joana.ifc.sdg stuff. This is the only jar you are going to need.

joana.ui.ifc.wala.console.jar Contains all of joana.api and a nice GUI. This is the only jar you are going to need if you also want a GUI.

joana.ui.ifc.sdg.graphviewer.jar Builds the GraphViewer GUI that can be used to load and view .pdg files. You need this if you want to view SDG files.

joana.ifc.sdg.core.jar Contains the all components relevant for graph based IFC. Does not contain SDG computation.

joana.wala.core.jar Pure SDG computation from bytecode. Contains also wala stuff.

joana.wala.dictionary.jar Contains wala, joana.wala.core and flowless modular computation. This stuff is experimental.

========================== === Project file structure

joana | +-- api _ API interface to the framework. | +-- contrib | | | +-- lib _ External libraries. | | | +-- wala __ GIT submodule of the WALA framework. | | | +-- www _ Resources for Joana homepage and Web Start applications. | +-- deprecated Old deprecated projects. Will be removed. | +-- example _ Example programs that can be analyzed. | +-- ifc | | | +-- sdg _ IFC algorithms working purely on the SDG. | | | | | +-- qifc Quantitative information flow analyses | | | +-- wala __ IFC algorithms using WALA and SDG. | +-- ui | | | +-- wala __ User interface programs for SDG construction. | | | +-- ifc | | | +-- sdg _ User interface programs for IFC on SDGs. | | | +-- wala User interface programs for SDG construction and IFC. | +-- util __ General utility classes. E.g. logging. | +-- wala __ SDG construction algorithms using WALA.

=============== === Style guide

The whole Joana project uses UTF-8 and Unix line delimiter for all text files. You can find code template, formatter and style definitions for Eclipse in the joana-*.xml files in the root directory.

All joana projects should use the Java-1.8 execution environment. Use classpath options in Eclipse to change this.

Use the Java code conventions and common sense. Common sense is allowed to override JCC, iff it makes sense ;)

All java files should start with the default header (joana-default-java-header.txt).

The maximal line length for java files is 120 chars. Tabs are 4 spaces.

-- PS: Joana means Java Object-sensitive ANAlysis in case you wondered :)