This readme is not completed

This project contains the logic to track method invocations that can be mapped to the use of features of interest. It creates (upon running mvn package) an agent that intercepts method invocations.

Design

1. the application is instrumented at loadtime time using aspect-j
2. the injected code tracks invocations by logging them using an InvocationTracker -- this is basically a simple in-memory database
3. the default implementation tracks methods by thread, using ThreadLocal in order to support concurrency and therefore better throughout. Filters and servlets are guaranteed to execute in the same thread (servlet spec 3.0, sect. 6.2.3). The catch is that this will miss invocations if request handling uses additional threads ! Alternative implementations are possible, as usual, tradeoffs between recall (tracked methods), precision (of assigning tracked records to requests) and performance must be made here.
4. the invocation tracker gets activated by a (servlet) filter, see InvocationTrackerManagerFilter
5. when request handling finishs, the filter copies the captured invocations into an outbox, and adds a header provenance to the response that can be used to construct a URL (by the fuzzing client) in order to pick up the recorded methods with a separate GET request. The pickup servlet is ProvenancePickupServlet, this must be injected and mapped to an URL in the target application.

Deployment for a Given Web Application

1. add the option -javaagent:aspectjweaver.jar to the container -- Tomcat, Jetty, .. JVM starts -- a few options how to do this for Tomcat are discussed here. The precompiled weaver jar can be found here, this has been tested with version 1.9.6.
2. add the library build from this project to the web application (within the war, jars are located in WEB-INF/lib). A war is just a zip file, so this can be done by unzip -> add content -> zip.
3. register the filter to intercept http request processing, the filter is nz.ac.wgtn.veracity.provenance.injector.jee.rt.InvocationTrackerManagerFilter, this should apply to all requests to be tracked (e.g., using the /* URL pattern). Details how to do this by editing WEB-INF/web.xml in the web app can be found here
4. map the servlet to be used to pick up provenance information to a URL, the class name is nz.ac.wgtn.veracity.provenance.injector.jee.rt.ProvenancePickupServlet. Details how to do this by editing WEB-INF/web.xml in the web app can be found here. For instance, if the URL was foo, and the provenance header value returned was 42, then __provenance/42 can be used to pick up the JSON-encoded provenance information.

Building

Build the project with mvn package, this will create target/provenance-injector-<version>.jar .

Customising Instrumentation

1. by changing aspects in src/ (package nz.ac.wgtn.veracity.provenance.injector.jee.instrumentation) and rebuilding
2. by editing src/main/resources/META-INF/aop.xml and rebuilding , this is useful for including / excluding classes, or to register additional aspects

Limitations and Issues

Aspect-J Maven Plugin Issues with Java Version

Java 8 must be set as the default JRE, otherwise aspect-j cannot find tools.jar / com.sun:tools:jar:<version>. For instance, on OSX, if Java 8 is installed, this can be achieved with:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`

This can then be verified with java -version.

Aspect-J Memory Issues

Aspect-J seems to sometimes run out of memory. Increasing heap space by passing -Xmx.. to ajc does not solve this. Check for details in the ajcore.<timestamp>.txt files generated by ajc.

Instrumenting Native Mathods

Since execution is used to instrument, native methods are instrumented. This is a limitation of the current approach, instrumenting call sites could overcome this.

Test Packages

Test packages start with test. to avoid exclusion by patterns defined in src/main/resources/META-INF/aop.xml and the actual point cuts.