Event Logging

Event Logging is a Java JAXB implementation of the Event Logging XML Schema and an API for logging events conforming to the Event Logging XML Schema. Event Logging can be incorporated into your Java application to provide a means of recording and outputting audit events.

Using the API

The Event Logging API is available as a Maven/Gradle depenndency on Bintray. To include it in your Gradle build add the following:

repositories {
  //...
  maven { url "https://dl.bintray.com/stroom/event-logging" }
}

//...

dependencies {
  compile 'event-logging:event-logging:v4.0.7_schema-v3.2.4'
}

Generation of the JAXB artefacts

The JAXB artefacts are generated using the xjc binary that ships with the Java JDK. This parses the XML Schema and builds a set of classes based on the schema. Prior to running xjc the schema undergoes an automated tidy up process to rename many of the elements to improve the class names in the JAXB model.

The generation process is reliant on having the required version of the Event Logging XML schema in the directory event-logging-generator/schema/. The Gradle build will download the schema from GitHub as long as the following line in the root build.gradle file has been set to the correct schema version.

def eventLoggingSchemaVer = "v3.1.2"

The Gradle build will generate the JAXB artefacts and go onto build the API jar.

The Event Logging XML schema is authored in github.com/gchq/event-logging-schema. The Event Logging XML Schema in event-logging-generator/schema/ should never be edited directly. It should always be a copy of the desired version from event-loggin-schema.

Building the Event Logging API jar

The API jar is built using Gradle. This will generate the JAXB artefacts, as well as copying the API classes, test classes and XML schema from the base module into the event-logging-api module.

All files under event-logging-api/src are transient and will be generated or copied in as part of the Gradle build.

The build is run as follows:

./gradlew clean build

To run the build with specific version number do something like:

./gradlew clean build -Pversion=v1.2.3_schema-v4.5.6

Towards the end of the build process, it will download the sources jar for the latest release of event-logging from GitHub and compare the Java source files in it to those just built. This provides a quick way of seeing the impact on the API from any changes in the schema. For example some schema changes that would not be a breaking change as far as an XML document is concerned (e.g. a rename of a complex type), would become a breaking change in the JAXB classes.

Releasing the Event Logging API jar

To perform a release simply tag the master branch as follows:

git tag -a vX.Y.Z_schema-vA.B.C

Where X.Y.Z is the version of the event-logging API library and A.B.C is the version of the event-logging XMLSchema. The two version numbers are totally independent of each other and have different life-cycles, e.g. a minor release of the schema could trigger a breaking change and major release of the API. Equally there may be a new release of the API with an identical schema version to the previous one. The build process will validate the tag when it is used as the version property in Travis.

When prompted to enter the commit message set the first line to event-logging-vX.Y.Z_schema-vA.B.C and lines 3+ to be the changes made, as extracted from the CHANGELOG.md file. Once the tag is picked up by Travis, the build will be run and the build artefacts published to GitHub releases.

Using the Event Logging API

The interface for logging audit events is LoggingEventsService.java. A default implementation is included in the form of DefaultEventLoggingService.java. This simple implementation writes the serialized events out to a Log4J appender.

Examples of how to construct various types of events and log them can be found in the test class base/src/test/java/event/logging/EventLoggingServiceIT.java.

The following is a very simple example of logging an Authentication type event.

//Create the logging service
final EventLoggingService eventLoggingService = new DefaultEventLoggingService();

//Create the system that is logging the authenticat event
final System system = new System();
system.setName("Test System");
system.setEnvironment("Test");

//Describe the device the event occurred on 
final Device device = DeviceUtil.createDevice(null, "123.123.123.123");

//Create the user involved in the authenticate action (possibly different from
//the eventSource user)
final User user = EventLoggingUtil.createUser("someuser");

//Provide details of where the event came from
final Event.EventSource eventSource = new Event.EventSource();
eventSource.setSystem(system);
eventSource.setGenerator("JUnit");
eventSource.setDevice(device);
eventSource.setUser(user);

//Create the authenticate object to describe the authentication specific details
final Event.EventDetail.Authenticate authenticate = new Event.EventDetail.Authenticate();
authenticate.setAction(AuthenticateAction.LOGON);
authenticate.setUser(user);

//Create the detail of what happened
//TypeId is typically a system specific code that is unique to a use case in that system
final Event.EventDetail eventDetail = new Event.EventDetail();
eventDetail.setTypeId("LOGON");
eventDetail.setDescription("A user logon");
eventDetail.setAuthenticate(authenticate);

//Define the time the event happened
final Event.EventTime eventTime = EventLoggingUtil.createEventTime(new Date());

//Combine the sub-objects together
final Event event = eventLoggingService.createEvent();
event.setEventTime(eventTime);
event.setEventSource(eventSource);
event.setEventDetail(eventDetail);

//Send the event
eventLoggingService.log(event);

LzrBear / event-logging