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.
- the application is instrumented at loadtime time using aspect-j
- the injected code tracks invocations by logging them using an
InvocationTracker-- this is basically a simple in-memory database
- the default implementation tracks methods by thread, using
ThreadLocalin 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.
- the invocation tracker gets activated by a (servlet) filter, see
- when request handling finishs, the filter copies the captured invocations into an outbox, and adds a header
provenanceto 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
- add the option
-javaagent:aspectjweaver.jarto 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.
- 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.
- 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.xmlin the web app can be found here
- 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.xmlin the web app can be found here. For instance, if the URL was
foo, and the provenance header value returned was
__provenance/42can be used to pick up the JSON-encoded provenance information.
Build the project with
mvn package, this will create
- by changing aspects in
nz.ac.wgtn.veracity.provenance.injector.jee.instrumentation) and rebuilding
- by editing
src/main/resources/META-INF/aop.xmland 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
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
Aspect-J Memory Issues
Aspect-J seems to sometimes run out of memory. Increasing heap space by passing
ajc does not solve this. Check for details in the
ajcore.<timestamp>.txt files generated by
Instrumenting Native Mathods
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 start with
test. to avoid exclusion by patterns defined in
src/main/resources/META-INF/aop.xml and the actual point cuts.