Fork me on GitHub

User Guide

The user guide helps guide you through using AppSensor once it's been setup. If you're not setup yet, have a look at the getting started guide first.


This guide will help you get AppSensor into your application and get you on your way to detecting and responding to events.

The getting started guide helped you get your back-end analysis system setup. This guide leads you through the front-end detection setup as well as discusses some long term issues such as monitoring and maintenance.


After getting your environment setup properly (see getting started), the next step is to have your application start sending events to AppSensor. There are a few standard ways of doing this.

  • A detection point is added to your application in a single location
  • A detection point is added to your application in multiple locations (usually via AOP)
  • External System (WAF, SSO system, SIEM, etc.) detects events (or even attacks) and sends them to AppSensor on behalf of your application

Let's cover each of these in turn:


    Single Location

This is the simplest concept and the most logical case. This will likely be how most of your detection points are added to your application. In this case, you simply modify existing code to additionally report an event to AppSensor.

An example here would be a user entering too many characters in the username field (reference). If the username is intended to have a limit, say, of 30 characters, and the user enters a username with 200 characters, that could be a sign that the user is attempting to attack the application. In this case, a simple modification of existing code would suffice to insert the detection point.

Some pseudocode for this example would look like:

if ( username.length > 30 )
    screen_errors.add ( "The username entered is too long." )

    # -----------------------------
    #  start new code for AppSensor

    # "AE4" is the identifier for this specific detection point
    appSensor.addEvent ( logged_in_user, "AE4" )

    #  end new code for AppSensor
    # -----------------------------

As you can see, supporting the detection point is really a matter of adding a single line of code. However, the real work is in identifying which detection points to use and where to put them.


    Multiple Locations (AOP)

Another option would be to have a single detection point instrumented into the code in multiple locations. This would typically be handled through Aspect-Oriented Programming (AOP) or a similar mechanism. AOP gives you the constructs necessary to apply a given set of code in multiple locations via convention or configuration as opposed to having to do it manually. This is a desirable strategy for many detection points.

Consider the ACE1 detection point for example, which is "Modifying a URL argument within a GET request for a direct object access attempt". This would be when an attacker tries to change /accounts/1234 to /accounts/1235 in order to access another account. This is a very typical attack, and a very common issue to have to prevent in applications. Many applications will solve this problem in a single method that is applied to multiple locations using AOP.

Using AOP or similar techniques provides a powerful capability as you can apply detection and response more easily to a larger portion of your application.


    External System

Many organizations already have powerful security tools setup that they use to protect their applications. AppSensor provides the flexibility to use the intelligence produced by these tools to feed into your detection and response system.

External tools can notify AppSensor of new events just as your normal application code would, assuming you are using a remote deployment option (REST/SOAP/etc.). If your tool provides attack-detection itself, it can even signal AppSensor and notify it of attacks, circumventing the attack detection process, and going straight to attack storage and response.

A significant note here is that the ModSecurity Core Rule Set project has spent a significant amount of time integrating with AppSensor. There are cross-references from the rules in the rule set to our detection points and there are some attack detection capabilities built into the core rule set. Also, the project is open-source as an OWASP project as well. This is definitely a project you should consider when evaluating external tools for AppSensor integration.

This is just another way to leverage your security investment and create a holistic approach to detection and response.


This is a standard part of application development, but it should be mentioned here that AppSensor does have the possibility of changing the functionality and/or performance of your application depending upon the way you implement it. For that reason, you should thoroughly test your application both before and after implementing AppSensor to ensure any impacts are acceptable.



By design, AppSensor detection points are meant to capture exceptional conditions, conditions that you believe may represent abnormal or malicious behaviour. By that definition, you should not be detecting events on every request for a normal user. (An exception to this general rule would be automated attacks of high-volume ... someone scans you with OWASP ZAP for instance)

Though AppSensor is not meant to cause a large performance impact, you should verify that through performance testing the application thoroughly, particularly with tests that exercise AppSensor alert generation, and ensure performance is acceptable.

Another specific issue to validate is the performance impact of polling for responses in a remote configuration. Every poll is a network request. The polling frequency is configurable and should be configured specifically for your environment.

One side note: by deploying AppSensor, you should be able to detect malicious users. One common side effect of attacking an application is denial-of-service for legitimate users. By detecting and containing/responding to the malicious activity, you might find the peformance increase in normal usage since attackers are no longer impacting the application. This caveat applies to a subset of attackers and a subset of attacks. However, large internet-facing applications often have to deal with this type of issues, so AppSensor can be beneficial in that specific regard.

AppSensor is a system that can be managed in various ways. You can perform real-time detection AND response (it's even recommended), which is great since you can set the policy and then not necessarily require a human in the loop to perform an action. However, you may have some actions that you want a human to perform, or you may have an out of band process you would like to do. Also, you may choose to simply report events as opposed to responding to them with some specific action.

No matter your particular setup, it is highly desirable to be able to view the state of your system. AppSensor produces data that is of interest to security, and should be monitored. Here are a few ideas for how to do that:

  • Use the provided AppSensor admin application and dashboard (available in 2.2 and higher)
  • Use the API to retrieve stored data and send it to a
    • log file
    • custom viewer application
    • log analysis tool
    • SIEM tool

As you can see you have options when it comes to monitoring your data, the important thing is that you actually do monitor your system. The AppSensor concept involves gaining visibility into the security posture of your application at runtime, but that comes with it the responsibility to actually manage the application over time. Don't put in the effort to get AppSensor working and then ignore the data it produces.

As mentioned in the "Monitor" section above, part of the AppSensor concept is managing your application, and specifically AppSensor, over the long term. As time goes by, your application will change and attackers will change. As such your AppSensor configuration and detection points should change as well. Here are a few ideas for things you should be considering over time:

  • AppSensor Configuration
    • Detection Points
      • Add new detection points as the application gets new functionality
      • Add new detection points as new attacks or attack patterns are discovered or realized
      • Evaluate existing detection points for effectiveness
    • Thresholds
      • I never see certain detection points trigger attacks. Are the thresholds too high or is the detection point invalid?
      • Certain detection points are too noisy
  • Monitoring system (new ways to visualize/use information)
  • New application protections based on AppSensor feedback - what are people attacking?

These are just some of the things you can do to optimize your AppSensor system. The list is by no means exhaustive. The key takeaway is that you should be monitoring your system over time and adjusting your configuration as your application changes and as you learn more about your attackers and what AppSensor can do to help you improve the security posture of your applications.

Congratulations ... If you've finished this guide, you've got AppSensor setup and your application configured to use it! At this point, you'll want to go have a look at the rest of our documentation to cover specific topics you might be interested in.

See more Documentation »