-
Notifications
You must be signed in to change notification settings - Fork 32
/
README
263 lines (196 loc) · 7.93 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
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)
0. Requirements
- a recent Linux (e.g. Ubuntu) or a recent MacOS (Windows is only tested occasionally)
- Java == 1.8
- ant >= 1.9.6
- Maven >= 3.x
- g++ compiler for WALA (build-essential package on ubuntu and debian)
1. Fetch submodule sources
git submodule init
git submodule update
2. Setup WALA and other dependencies
./setup_deps
3. Run ant
ant
4. 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.
2. 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.
3. 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 :)