Symbolic execution with Java Pathfinder

JPF has an extension for symbolically executing Java bytecode (called SPF). I have been using SPF for analyzing some pieces of code. This post introduces installation and basic configurations of SPF to help JPF beginners. As the official documents are really more suitable for those experienced JPF users.

Install Java Pathfinder (jpf-core + jpf-symbc)

Step 1: download sources

I am using Eclipse as Java IDE, so here I assume you are using Eclipse. For downloading the sources of JPF, we can import projects from its Mercurial repositories (if you do not have Mercurial plugin installed, please install it before moving on).

• URL for jpf-core: http://babelfish.arc.nasa.gov/hg/jpf/jpf-core
• URL for jpf-symbc: http://babelfish.arc.nasa.gov/hg/jpf/jpf-symbc (jpf-symbc is the symbolic extension for JPF)

Step 2: build the jpf-core and jpf-symbc

JPF projects are ant-based, so you should use ant to build these two projects. Then you are done with installation.

JPF configuration (assume we are using Eclipse plugin to run JPF,here tells you how to install the plugin)

Step 1: copy the imported two projects (jpf-core and jpf-symbc) to a safe place in your machine (to avoid modification)

I put them under C:\Users\me\projects\jpf\

Step 2: configure the site.properties file

Create a folder call ".jpf" under your home directory (as Eclipse JPF plugin by default seaches ~/.jpf for the configuration file). Windows does not allow a folder name starting with a dot, so you can use command line tools to create this folder. Under the folder, create a site.properties file with the following content

# JPF site configuration

jpf.home = ${user.home}/projects/jpf

# can only expand system properties
jpf-core = ${user.home}/projects/jpf/jpf-core

# annotation properties extension
jpf-aprop = ${jpf.home}/jpf-aprop
extensions+=,${jpf-aprop}

# numeric extension
jpf-numeric = ${jpf.home}/jpf-numeric
extensions+=,${jpf-numeric}

# symbolic extension
jpf-symbc = ${jpf.home}/jpf-symbc
extensions+=,${jpf-symbc}

# concurrent extension
#jpf-concurrent = ${jpf.home}/jpf-concurrent
#extensions+=,${jpf-concurrent}

jpf-shell = ${jpf.home}/jpf-shell
extensions+=,${jpf-shell}

jpf-awt = ${jpf.home}/jpf-awt
extensions+=,${jpf-awt}

jpf-awt-shell = ${jpf.home}/jpf-awt-shels
extensions+=,${jpf-awt-shell}

Note that even in Windows, the path separator is slash (/) instead of back slash (\). Sometimes, back slash is ok, but occasionally it causes problems. So using slash is suggested according to my personal experience.

Run SPF (with and without plugin)

1. Using JPF plugin to verify java programs

JPF plugin knows where the JPF and SPF classes reside (jars under the build folder of jpf-core and jpf-symbc), so using plugin saves a lot of efforts. Please make sure that in Eclipse, Window->Preference->Java->JPF Preference->path to site.properties points to the directory where we create the configuration file (by default it is set up correctly).

Suppose we create a new Java project "TestJPF" and a class "MyClass".

public class MyClass {
	
	public int myMethod(int x, int y){
		int z = x + y;
		if (z > 0) {
			if(y>0){
				z = 1;
			} else{
				z = -1;
			}
//			System.out.println("path 1 explored");
		} else {
			if(x>0){
				z = z - x;
			} else{
				z = z + x;
			}
//			System.out.println("path 2 explored");
		}
		z = 2 * z;
		return z;
	}
	
	public static void main(String[] args){
		MyClass mc = new MyClass();
		mc.myMethod(1, 2);
	}

We can symbolically run the myMethod() method to explore every possible path, and SPF can help generate test cases to cover those paths (test generation is the typical magic of symbolic execution). In order to do so, you only need to create a .jpf file under the project folder. Lets call it MyClass.jpf. It content specifies the configuration of SPF. JPF is a great tool, but its configuration is intimidating. JPF's flexibility comes with a price.

target=MyClass
classpath=D:\\java_workspace\\TestJPF\\bin
symbolic.method=MyClass.myMethod(sym#sym)
#listener=gov.nasa.jpf.symbc.SymbolicListener
#vm.storage.class=nil
#search.multiple_errors=true
#symbolic.debug=true

The right click MyClass.jpf, and click "verify", you should the following content printed on Eclipse console.

Executing command: java -jar C:\Users\andrewust\projects\jpf\jpf-core\build\RunJPF.jar +shell.port=4242 D:\java_workspace\Temp\MyClass.jpf 
Running Symbolic PathFinder ...
symbolic.dp=choco
symbolic.string_dp_timeout_ms=0
symbolic.string_dp=none
symbolic.choco_time_bound=30000
symbolic.minint=-1000000
symbolic.maxint=1000000
symbolic.minreal=-10000.0
symbolic.maxreal=10000.0
symbolic.undefined=-1000000
JavaPathfinder v6.0 (rev ${version}) - (C) RIACS/NASA Ames Research Center


====================================================== system under test
application: MyClass.java

====================================================== search started: 5/17/12 8:20 PM

====================================================== results
no errors detected

====================================================== statistics
elapsed time:       00:00:00
states:             new=7, visited=0, backtracked=7, end=4
search:             maxDepth=3, constraints hit=0
choice generators:  thread=1 (signal=0, lock=1, shared ref=0), data=3
heap:               new=321, released=42, max live=321, gc-cycles=5
instructions:       2974
max memory:         59MB
loaded code:        classes=75, methods=960

====================================================== search finished: 5/17/12 8:20 PM

In the future post, I will explain those configuration parameters in a .jpf file. The minimal set includes target, classpath, and symbolic.method.

2. Configure a Eclipse run to symbolically execute a method

Here we don't need any .jpf file to specify JPF configurations. We specify them as Java properties (arguments when running a program using "java MyClass XXXX") by configuring a run.

Step 1 Add jpf-core and jpf-symbc to buildpath (without jpf-plugin, we need to explicitly add them as library so that JVM can find corresponding classes)

You can simply add the jars under jpf-core/build, jpf-core/lib, jpf-symbc/build, and jpf-symbc/lib as external jars. Or create user libraries to organize those jars. For example, I create jpf-core, jpf-symbc, and jpf-lib for holding those jars, and then add the three libraries to my build path.

Step 2 Run configuration

The we are done here. Click run, you will see the same results as in the run with plugin.