Getting Started

The reference implementation currently supports 5 execution modes and we'll discuss each in turn.

 

REST Web Service

The REST model is the most common model for APIs today, and it is easy to understand why. The model is simple, lightweight and effective, while still allowing for flexibility. It's also supported by almost every networking framework available, making integration effort much easier.

 

Use when:

Choose this model if any/all of the following are true:

• You are using a non-Java language for your application
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)

 

Avoid when:

Avoid this model if any/all of the following are true:

• You only have 1 application and it is Java
• You do not want the network overhead, and would rather make local JVM calls

 

Thrift

The Thrift model uses Thrift, which is a binary protocol that allows fast communication and supports many languages.

 

Use when:

Choose this model if any/all of the following are true:

• You are looking for high-speed communication
• You are using a non-Java language for your application
• All of your client applications are in a thrift-supported language
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)

 

Avoid when:

Avoid this model if any/all of the following are true:

• You are using a non-thrift language for a client application
• You only have 1 application and it is Java
• You are not comfortable with a binary protocol and want something more "debuggable", like REST

 

SOAP Web Service

The SOAP model is still in heavy use, but more often within the enterprise. There is significant tooling available. It's a well-known and well understood protocol. Integration points are often available, and there are a fair number of supporting frameworks.

 

Use when:

Choose this model if any/all of the following are true:

• You are using a non-Java language for your application
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)
• Your enterprise requires SOAP or SOAP provides better integration points in your organization

 

Avoid when:

Avoid this model if any/all of the following are true:

• You only have 1 application and it is Java
• You do not want the network overhead, and would rather make local JVM calls
• You would rather use a simpler network model, like REST

 

RabbitMQ

The RabbitMQ model uses RabbitMQ, which is an AMQP implementation for doing messaging that supports a variety of deployment patterns and languages.

 

Use when:

Choose this model if any/all of the following are true:

• You are looking for decoupled communication systems
• You are using a non-Java language for your application
• All of your client applications are in a RabbitMQ-supported language
• Your organization is already using RabbitMq
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)

 

Avoid when:

Avoid this model if any/all of the following are true:

• You are using a non-RabbitMQ language for a client application
• You only have 1 application and it is Java
• You are not comfortable with a decoupled architecture.

 

Kafka

The Kafka model uses Kafka, which is a ""publish-subscribe messaging system rethought as a distributed commit log"". It supports a variety of deployment patterns and languages.

 

Use when:

Choose this model if any/all of the following are true:

• You have very high performance requirements
• You are looking for decoupled communication systems
• You are using a non-Java language for your application
• All of your client applications are in a Kafka-supported language
• Your organization is already using Kafka
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)

 

Avoid when:

Avoid this model if any/all of the following are true:

• You are using a non-Kafka language for a client application
• You only have 1 application and it is Java
• You are not comfortable with a decoupled architecture.

 

Local (Embedded Java)

The local model simply means that the client and server portions of appsensor are "embedded" within a single application. When an event is triggered, all of the communication occurs within the JVM as native calls, as opposed to network requests. This model was the only one available in AppSensor version 1. There are drawbacks to this approach, but it is still a good model for some.

 

Use when:

Choose this model if any/all of the following are true:

• You only have 1 application and it is Java
• You do not want the network overhead, and would rather make local JVM calls

 

Avoid when:

Avoid this model if any/all of the following are true:

• You are using a non-Java language for your application
• You need to support multiple applications
• You are in a clustered environment (1 application over multiple servers)

AppSensor v2 has been built with pluggability in mind. Ever major component of the system can be swapped out, including the analysis engines themselves. While this allows for great flexibility, it comes with the cost that you have to perform some up-front configuration in order to get going. For most situations, this will be a trivial one-time step.

The following section describes each of the components you'll interact with in order to get your system setup:

 

AppSensor Core (Required)

Core represents the central domain and interface specifications for the system. You'll need this, but you often don't have to specify it as an explicit dependency, since pretty much every other part of the system depends on this component as well.

 

Analysis Engine (Required)

The analysis engines are the core implementation components. These components decide when an event becomes an attack and how to respond accordingly.

There is currently only the reference implementation (policy driven), but there could be more in the future.

 

Storage (Required)

The storage component does what you'd expect: stores the data for the system.

There are several implementations, including in-memory, file-based, and sql/no-sql databases. You'll need to select a storage implementation based on your needs.

 

Configuration (Required)

The configuration component of the system represents your client (connect to server) and server (client info, detection points) configurations. While there are other possible implementations, the only current implementation is XML (Stax). You'll need to include this component in order to allow your configuration information to be processed properly.

 

Access Controller (Required if using REST or SOAP)

The access controller component simply ensures that the client that is making requests has permission to do so.

There is currently only a single access controller implementation (reference), which implements a simple role-based access control check.

This component is necessary if you are using either the REST or SOAP configurations.

 

Reporting (Optional)

Reporting is an important part of the AppSensor capability. The analysis engine on the server interacts with the client to allow responses to be sent and processed by the client, but that's the extent of data provided. In order to get any other information about the system, you'll want to use the reporting subsystem.

There are multiple implementations of the reporting component (logging, websocket, REST/SOAP), and you can select one appropriate to your environment.

While many of the implementations available in AppSensor do not require further configuration, some will.

Some require configuration and for others, configuration is optional. An example is in the storage component:

• If you use the in-memory data store, no further configuration is necessary.
• If you use the file-based data store, you can optionally configure where the file is stored (default is in a temporary directory, so configuration is recommended).
• If you are using the JPA (SQL) data store, then you must provide a configuration to access the appropriate database as well as your credentials. In this case, the configuration is done via Spring configuration.

There are various components that have configuration options. The necessary specific information regarding these components can be found in the documentation on GitHub or in the JavaDoc for that component.

While reporting is technically just another component of AppSensor, it's a common need, so I'll call it out separately here.

There are various implementations of the reporting subsystem, such as:

• Simple Logging (logs to whatever logger you have configured) [executes as events occur, does not support queries]
• WebSockets (sends data to all connected WebSocket clients) [executes as events occur, does not support queries]
• REST API (/reports/*) [does nothing as events occur, does support queries]

Setting up reporting is an important part of a complete AppSensor system. The reporting components as well as sample dashboards are included in the source at GitHub.

Congratulations ... If you've finished this guide, you've got AppSensor setup! Now, you'll want to get your application configured to use AppSensor. Have a look at the user guide to start that process.

See the User Guide »