# How to Install SootUp

## Installing SootUp

Open the command prompt in your computer and in the directory of your choice (Desktop, Downloads.. etc) run`git clone https://github.com/secure-software-engineering/Shttps://hackmd.io/ootUp.git` (paste this command in your terminal). You should see the below output.


###### Figure 1: Screenshot of the successful clone of SootUP

We then change directories using the command `cd SootUp` in your terminal. After this run `mvn install` in the terminal (`mvn` stands for Maven). You should see the below output.


##### Figure 2: Screenshot of the successful build of SootUP

## IDE
After building SootUp in your directory of choice, you should install IntelliJ IDEA (Ultimate Edition) (https://www.jetbrains.com/idea/). As a student, you can avail the free version from the JetBrains website. We will be using this IDE for the duration of this course.

Open IntelliJ and click on New Project, choose the required options for the project as shown below.


##### Figure 3: Screenshot of the New Project specifications for the Hello World project

## Maven
When you open your Project, you should be able to see something similar as shown below. In the below screenshot, you can see the pom.xml file.


Open your project's pom.xml file.
Below `</properties>` and before `</project>` in your pom.xml file, paste the below code. Once IntelliJ renders your pom.xml file, you will see a small blue M icon show up next to your code. Click this to import the Maven projects, and your Output window should not show any errors.

<repositories>
        <repository>
            <id>SootUp-repo</id>
            <url>https://github.com/soot-oss/SootUp</url>
        </repository>
    </repositories>

    <dependencies>

        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.core</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.java.core</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.java.sourcecode</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.java.bytecode</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.jimple.parser</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.callgraph</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>org.soot-oss</groupId>
            <artifactId>sootup.analysis</artifactId>
            <version>1.1.2</version>
        </dependency>

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>2.0.0-alpha0</version>
        </dependency>

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.0-alpha0</version>
            <scope>runtime</scope>
        </dependency>

    </dependencies>

Save the pom.xml file.

## Adding Jar files

Next, click on `Files>>Project Structure>> Modules>>Dependencies>>click on the plus button then click on Jars and Directories`. For every folder that starts with `sootup` in your directory, go to the target folder, click the `.jar` file in that directory, and add it. Ensure that you do this for every subfolder. If you have an error asking what kind of file this is, click `Jar Directory.`

##### Figure 4: Screenshot of adding the jar files for the Hello World project

# Running HelloWorld.java

Paste the below code into a new file in your SootUp directory called HelloWorld.java in src>main>java>org>example.

public class HelloWorld {

    public static void main(String[] args) {

        System.out.println("Hello, World");
    }
}

In your Terminal, cd into the directory where you just created your HelloWorld.java file.

Run `javac HelloWorld.java`, this will create a class file called HelloWorld.class in your project directory.

Run `java HelloWorld.java`

After this go to your project in IntelliJ and create another file called HelloWorldAnalysis.java, in the same directory as your HelloWorld.java and HelloWorld.class files.

Copy and paste the following code into the HelloWorldAnalysis.java file:

import sootup.core.Project;
import sootup.core.inputlocation.AnalysisInputLocation;
import sootup.core.jimple.common.stmt.Stmt;
import sootup.core.model.SootClass;
import sootup.core.model.SootMethod;
import sootup.core.signatures.MethodSignature;
import sootup.core.types.ClassType;
import sootup.core.views.View;
import sootup.java.bytecode.inputlocation.JavaClassPathAnalysisInputLocation;
import sootup.java.core.JavaProject;
import sootup.java.core.JavaSootClass;
import sootup.java.core.JavaSootClassSource;
import sootup.java.core.language.JavaLanguage;
import sootup.java.core.views.JavaView;
import java.util.Collections;

public class HelloWorldAnalysis {
    public static void main(String[] args) {
        AnalysisInputLocation<JavaSootClass> inputLocation =
                new JavaClassPathAnalysisInputLocation("src/main/java/org/example");
        JavaLanguage language = new JavaLanguage(8);

        Project<JavaSootClass, JavaView> project =
                JavaProject.builder(language)
                        .addInputLocation(inputLocation).build();

        ClassType classType =
                project.getIdentifierFactory().getClassType("HelloWorld");

        MethodSignature methodSignature = project.getIdentifierFactory().getMethodSignature(
                "main", String.valueOf(classType), "void",
                Collections.singletonList("java.lang.String[]"));

        View<JavaSootClass> view = project.createView();

        SootClass<JavaSootClassSource> sootClass = view.getClass(classType).get();

        SootMethod sootMethod =
                sootClass.getMethod(methodSignature.getSubSignature()).get();

        System.out.println(sootMethod.getBody().getStmts());
        }
    }
}

Once you run the HelloWorldAnalysis.java file, you will be able to see the Jimple representation of your HelloWorld.java code as shown below.


# Testing for sources and sinks

To be able to test if the given programs let in or let out sensitive information, run the test cases in the `sources/main/java/org/example/SourcesSinksTests.java` file in the `sources-and-sinks-implementation` branch by clicking on the green Play button in IntelliJ. Feel free to create your own by inputting methods into the code as follows:

Example folder name containing .class Java file to compile: `"helloworld"` (the exact path is `sources/main/java/org/example/helloworld/HelloWorld.class`)

Example method signature to verify source/ sink analysis on: `<java.io.PrintStream: void println(java.lang.String)>`

@Test
@DisplayName("Println is indeed a sink")
public void testHelloWorld() {
    String printOutput = SourcesAndSinksAnalysis.SourcesSinks("helloworld").get("<java.io.PrintStream: void println(java.lang.String)>");
    assert Objects.equals(printOutput, "SINK");
}

# Running these tests automatically
To automatically run all tests, input the following into your command to compile the automated testing file:
`javac TestRunner.java`

Then, run the green Play button in IntelliJ to run the tests.

# The WorkList Algorithm

To run a version of the WorkList algorithm on SootUp, go to ```url://url```. This is an implementation of the algorithm in SootUp specifically using SootUp's ```Stmt``` class.

This algorithm runs on a pre-defined ```Node``` class. It has the attrbutes ```stmt```, which is of the ```Stmt``` type, as well as successors and predecessors, which are a ```Hashset``` constaining ```Node``` types.

This algorithm uses the [test for sources and sinks](https://hackmd.io/2mMA1-8USkCbXSVYEngi1Q#Testing-for-sources-and-sinks) to determine whether a node is a source or sink. If it is neither, the algorithm uses the various methods in the ```Stmt``` to determine whether the ```Node``` holds an ```AssignStmt```, ```InvokeStmt``` or any other type of ```Stmt``` supported by SootUp.

After this, the algorithm performs a union operation with the predeccesors of this node and the ```Stmt``` contained within the node in question. This provides a detailed ```Hashset``` of all the data from this ```Node``` and its predeccesors that could potentially be leaked.

# FAQ

1. How to install Maven?

If you get the `command not found` error you need to install maven, you can do that by going to https://maven.apache.org/download.cgi and then downloading the 3.9.5 bin.tar.gz if you are using Mac and bin.zip file if you are using Windows. Additional help can be found here for installing maven for Mac https://www.digitalocean.com/community/tutorials/install-maven-mac-os, installing maven for Windows https://phoenixnap.com/kb/install-maven-windows.

2. Java version

Make sure when you run `javac -version` and `java -version`, the outputs in the terminal should match. This usually means you have two Java versions installed on your computer. For this project, we will be using either Java 8 or Java 18.