All the libs listed below should be in your Java classpath:
Libraries required:
These libraries are required to compile Diver source package and, more other libraries may be needed to add to either the JVM class path or Soot class path, depending on which part of diver is to be used. Those more libraries are clarified in the sections where they are involved as follows.
Simply put, the input to Diver should be the Java bytecodes, plus a set of methods that are supposed to be changed, which we call queries. The bytecodes, in the form of classfiles, are to be presented to the Diver's static analysis module as the source input of the whole Diver dynamic analysis pipeline as well, which includes three phases:
(1) static analysis, which builds the static MDG and instruments probes for method event monitoring;
(2) running the instrumented code, by which Diver traces the method entry and returned-into events;
(3) post-processing, using the traces generated from phase (2) and the static MDG constructed from phase (1), Diver computes the impact set of the input queries.
As these phases being listed, the input for phase (2) is the instrumented subject classfiles, and that for the phase (3) is the outputs from running the subject instrumented and the static MDG. The static MDG will be dumped to a binary file named "staticVtg.dat" in the same directory of the instrumented class files, and the running outputs are method execution trace per test case. Another input for phase (2) is, of course, what the original subject should be fed with---the test inputs.
In order for Diver to instrument the bytecode of the target subject, adding certain statements in the subject source code is needed. More specifically, Diver requires the insertion of statements into the main/entry class of the whole subject software.
Precisely, the following statements should be added to the entry class, which is essentially an extra static method and thus would not mess up the original source code:
public class TheEntryClass {
......
// added for Diver Instrumentation
static void __link() {
Diver.EAMonitor.__link();
}
......
As long as the libraries required as described above are included in the class paths, the compiler will be able to find the packages and names in there. For the package "Diver.EAMonitor" to be resolved, however, the path where the Diver classfiles are located should also be added to the class path setting for the Java compiler.
Now the source code of target subject with the foregoing additions can be compiled, an exemplary class path setting is given below as it is in a complete compilation script (in Linux B-shell):
ROOT=/home/hcai/
MAINCP=".:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/tools/Diver/bin/:$ROOT/subject/src/"
javac -g:source -source 1.4 -cp ${MAINCP} -d $ROOT/subject/bin subjectFile1.java
Other paths needed for the subject's class dependences and libraries ought also to be in "MAINCP". Note that the "-g:source -source:1.4" option for javac is strongly recommended for compiling subject in order to ensure correct functionalities of Diver in addition to lower overheads of the underlying DUA-forensics/Soot analysis procedures. Once the compilation succeeds, it is ready to start the static analysis of Diver as demonstrated as follows.
Once the inputs for Diver are prepared, 'DiverInst' is ready to run. Despite the name implying 'instrumentation' only, this phase builds the static MDG, which is actually the predominant task for this step. As shown in the following example, the class path for JVM and Soot are given by "MAINCP" and "SOOTCP", respectively. To run 'DiverInst' on command line on Windows, the shell script below can be converted into batch script accordingly. When running it in IDEs such as Eclipse, a Run/Debug configuration can be created by picking class paths as exemplified in the script too and indicating corresponding parameters.
The primary parameters for 'DiverInst' are explained as follows.
ver=$1
seed=$2
ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/polyglot-1.3.5/lib/polyglot.jar:$ROOT/tools/soot-2.3.0/lib/sootclasses-2.3.0.jar:$ROOT/tools/jasmin-2.3.0/lib/jasminclasses-2.3.0.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/tools/Diver/bin:$ROOT/tools/java_cup.jar"
mkdir -p out-DiverInstr
SOOTCP=".:$ROOT/software/j2re1.4.2_18/lib/rt.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/tools/Diver/bin:$subjectloc/bin/${ver}${seed}:$subjectloc/libs"
OUTDIR=$subjectloc/DiverInstrumented-$ver$seed
mkdir -p $OUTDIR
starttime=`date +%s%N | cut -b1-13`
#-sclinit \
#-debug \
#-dumpJimple \
#-reachability \
#-ignoreRTECD \
java -Xmx1600m -ea -cp ${MAINCP} Diver.DiverInst \
-w -cp $SOOTCP -p cg verbose:true,implicit-entry:false \
-p cg.spark verbose:true,on-fly-cg:true,rta:true -f c \
-d $OUTDIR \
-brinstr:off -duainstr:off \
-duaverbose \
-wrapTryCatch \
-intraCD \
-interCD \
-exInterCD \
-slicectxinsens \
-allowphantom \
-serializeVTG \
-main-class org.apache.xml.security.test.AllTestsSelect \
-entry:org.apache.xml.security.test.AllTestsSelect \
-process-dir $subjectloc/bin/${ver}${seed} \
-process-dir $subjectloc/bin/td${ver} \
1>out-DiverInstr/instr-${ver}${seed}.out 2>out-DiverInstr/instr-${ver}${seed}.err
Note that another useful option is "-dumpFunctionList", which asks Diver to dump the full list of methods in the target program, in the format of function signature. Since the post-process phase needs input queries in such format, you may want to always set this flag if you are not familiar with the method signatures in the software you are analyzing.
After successful instrumentation, you should find the instrumented subject and the static MDG in the "staticVtg.dat" file, both in the "$OUTDIR" directory. The next step is to run the instrumented code using Diver runner as follows.
An actual example of the runtime phase usage of Diver is shown below.
ver=$1
seed=$2
ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
INDIR=$subjectloc/DiverInstrumented-$ver$seed
MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/polyglot-1.3.5/lib/polyglot.jar:$ROOT/tools/soot-2.3.0/lib/sootclasses-2.3.0.jar:$ROOT/tools/jasmin-2.3.0/lib/jasminclasses-2.3.0.jar:$ROOT/tools/Diver/bin:$ROOT/tools/java_cup.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$subjectloc/libs:$INDIR"
OUTDIR=$subjectloc/Diveroutdyn-${ver}${seed}
mkdir -p $OUTDIR
java -Xmx2800m -ea -cp ${MAINCP} Diver.DiverRun \
org.apache.xml.security.test.AllTestsSelect \
"$subjectloc" \
"$INDIR" \
${ver}${seed} \
$OUTDIR
With both the static MDG and execution traces ready, now it is the time to get the impact set of any queries of your interest. Of course, an addition input is the queries. As noted before, the input queries need be given in the full signature form to be exact. If you give only a part of method signatures, Diver will automatically match all containing signatures and compute impact sets of all the matched methods.
An actual example of the post-process phase usage of Diver is shown below.
ver=$1
seed=$2
NT=${3:-"92"}
query=${4:-"<org.apache.xml.security.signature.XMLSignatureInput: java.util.Set getNodeSet()>"}
ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
INDIR=$subjectloc/Diveroutdyn-${ver}${seed}
BINDIR=$subjectloc/DiverInstrumented-$ver$seed
MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/polyglot-1.3.5/lib/polyglot.jar:$ROOT/tools/soot-2.3.0/lib/sootclasses-2.3.0.jar:$ROOT/tools/jasmin-2.3.0/lib/jasminclasses-2.3.0.jar:$ROOT/tools/java_cup.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/tools/Diver/bin:$subjectloc/libs:$INDIR"
starttime=`date +%s%N | cut -b1-13`
#-matchingForAll
#-pruningForAll
#-debug
java -Xmx8000m -ea -cp ${MAINCP} Diver.DiverAnalysis \
"$query" \
"$INDIR" \
"$BINDIR" \
$NT
The last argument gives the number of per-test traces. Diver will ouput the list of impacted methods by the query. For multiple queries, use semicolumn to separate but without whitespaces between them.
1.6.1