AppSensor Developer Guide

= AppSensor Developer Guide =

The AppSensor Project describes an application layer intrusion detection system. There is a Java implementation of this system whose basic usage can be found in the Getting Started guide. This document describes in more technical detail for developers how to use and extend AppSensor for a specific environment and application.

Developer Overview
AppSensor is an application layer intrusion detection system. The concept in implementation is roughly analogous to an intrusion detection (and prevention) system in the network security world. However, this concept can be applied inside of an application in a more specific way that (importantly) reduces false positives, which is an issue that often plagues network intrusion detection systems. This means that the core of the AppSensor system performs detection, monitoring, and (possibly) response depending on configuration settings.

AppSensor has been built to be quite extensible from the ground up. Most of the system can be appreciably modified to your needs by simply extending certain key interfaces, and modifying the appsensor configuration file appropriately. This extensible design makes it possible for various configurations to be applied depending upon the application. For instance, in a small application, you may choose to use a simple file-based model for storing intrusions that are detected, whereas for a larger application, you may have a relational database serving as your data store. See the Extending AppSensor section below for specifics on what can be extended.

Obtaining AppSensor
The appsensor.jar can be downloaded here - FIXME

The source is available here

Extending AppSensor
Below you will find the individual interfaces you are likely to extend in order to modify AppSensor for your environment.

IntrusionStore
The IntrusionStore interface represents, simply enough, the storage mechanism for any intrusions that occur in the system. The AppSensorIntrusionDetector takes care of adding the intrusions to the intrusion store. The current DefaultIntrusionStore class stores all of the intrusions in a simple HashMap. The class is fairly small and simple, though, so it is trivial to understand it's inner workings and to use similar concepts to build an implementation that suits your environment.

The setting you'll need to modify in appsensor.properties to enable your own implementation is:

AppSensor.intrusionStore=org.owasp.appsensor.intrusiondetection.reference.DefaultIntrusionStore
 * 1) This is the class that handles the intrusion store

ResponseAction
The ResponseAction interface is used to simply respond to an intrusion once a threshold has been crossed. The decision for when to respond is handled by the AppSensorIntrusionDetector, but the actual handling of the response is delegated to implementations of this interface. The only reason to not use the DefaultResponseAction would be if you have additional response actions you need to take, or if you need to modify the handling of one of the existing responses. Again, the DefaultResponseAction should give you a good starting point for creating your own implementation.

The setting you'll need to modify in appsensor.properties to enable your own implementation is:

AppSensor.responseAction=org.owasp.appsensor.intrusiondetection.reference.DefaultResponseAction
 * 1) This is the class that handles the response actions

DefaultResponseAction supports the following actions:  "log" - logs the activity "logout" - logs the currently logged in user out (if one exists) "disable" - disables the account of the currently logged in user (if one exists) "disableComponent" - disables access to the location of the intrusion using the AppSensorServiceController "disableComponentForUser" - disables access to the location of the intrusion using the AppSensorServiceController for the currently logged in user(if one exists) "emailAdmin" - Email administrator to notify of what action has occurred "smsAdmin" - SMS administrator (via email to sms account) to notify of what action has occurred 

Response actions can be configured for individual detection points using properties like: IntrusionDetector. .actions=

IntrusionDetector.IE99.actions=log,logout,disable,disableComponent
 * 1) list of actions you want executed in the specified order as the threshold for this intrusion is met -
 * 2) ie. log the first time, logout the user the second time, etc.

ASUtilities
The ASUtilities interface handles a collection of concerns. It handles retrieving the current user of the application (ie. the user that made the current request and/or caused the current intrusion). In addition, it handles the retrieval of the logger as well as the current HTTP request. The DefaultASUtilities implementation simply delegates to the equivalent ESAPI method calls to retrieve the appropriate data. If you are not using ESAPI's logging and/or authentication and/or request binding utilities, you'll need to create your own implementation of this class.  Note: This is the interface you'll need to implement if you are not using ESAPI. 

The setting you'll need to modify in appsensor.properties to enable your own implementation is:

AppSensor.asUtilities=org.owasp.appsensor.reference.DefaultASUtilities
 * 1) This is the class that handles the utility retriever

TrendLogger
The TrendLogger interface is in place to handle the logging of events in order to monitor trends. The techniques for doing this vary widely depending upon environment. You'll most likely not want to use the existing InMemoryTrendLogger as it will scale very poorly. It is simply in place as a starting point for other implementations.

The setting you'll need to modify in appsensor.properties to enable your own implementation is:

AppSensor.trendLogger=org.owasp.appsensor.trendmonitoring.reference.InMemoryTrendLogger
 * 1) This is the class that handles the trend logging