Initial commit

.gitignore

@@ -0,0 +1,3 @@
+.idea
+*.iml
+event-logging/src/main/resources/event/logging/impl/schema.xsd

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/) 
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+### Added
+
+### Changed
+
+## [initialOpenSourceRelease] - 2016-10-31
+Intial open source release
+
+[Unreleased]: https://github.com/gchq/event-logging/compare/initialOpenSourceRelease...HEAD

LICENCE.txt

@@ -0,0 +1,15 @@
+
+Copyright 2016 Crown Copyright
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

NOTICE.md

@@ -0,0 +1,15 @@
+# Event Logging
+
+Copyright 2016 Crown Copyright
+
+This software project uses libraries which fall under several licences. The purpose of this `NOTICE.md` file is to contain notices that are required by copyright owners and their licences. The full texts of all the licences used by third party libraries are included in the `licences` folder.
+
+See the file [LICENCE.txt](./LICENCE.txt) for licencing information for this project.
+
+The table below includes licences for all Maven dependencies.
+
+| Group                                     | Artifact                                     | Version          | Licence       | Licence | Licence       |
+|-------------------------------------------|----------------------------------------------|------------------|---------------|---------|---------------|
+| log4j                                     | log4j                                        | 1.2.17           | APL 2.0       |         |               |
+| junit                                     | junit                                        | 4.12             | EPL 1.0       |         |               |
+

README.md

@@ -0,0 +1,68 @@
+# 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 application to provide a means of recording and outputting audit events.
+
+## 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. Also it will apply all XSLT stylesheets found in _generator/src/main/resources/translations/_ to the _Event Logging XML Schema_. Currently the only stylesheet in use adds Event as a root element to the schema.
+
+The generation process is reliant on having the required version of the _Event Logging_ XML schema in the directory _generator_.  Once this is in place it is simply a matter of running a Maven build.  The Maven build will generate the JAXB artefacts and go onto build the API jars.
+
+The _Event Logging_ XML schema is authored in [github.com/gchq/event-logging-schema](https://github.com/gchq/event-logging-schema). The _Event Logging XML Schema_ in _generator_ 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 the Maven root pom. 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 module.
+
+All files under event-logging/src are transient and will be generated as part of the Maven build.
+
+The build is run as follows:
+
+`mvn clean install -U`
+
+## 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.
+
+``` java 
+//Create the logging service, choosing how to handle
+final EventLoggingService eventLoggingService = new DefaultEventLoggingService();
+
+final User user = new User();
+user.setId("someuser");
+
+final Event.EventDetail.Authenticate authenticate = new Event.EventDetail.Authenticate();
+authenticate.setAction(AuthenticateAction.LOGON);
+authenticate.setUser(user);
+
+final Event.EventTime eventTime = EventLoggingUtil.createEventTime(new Date());
+final Device device = DeviceUtil.createDevice(null, "123.123.123.123");
+final User user = EventLoggingUtil.createUser("someuser");
+
+final System system = new System();
+system.setName("Test System");
+system.setEnvironment("Test");
+
+final Event.EventSource eventSource = new Event.EventSource();
+eventSource.setSystem(system);
+eventSource.setGenerator("JUnit");
+eventSource.setDevice(device);
+eventSource.setUser(user);
+
+final Event.EventDetail eventDetail = new Event.EventDetail();
+eventDetail.setTypeId("LOGON");
+eventDetail.setDescription("A user logon");
+eventDetail.setAuthenticate(authenticate);
+
+final Event event = eventLoggingService.createEvent();
+event.setEventTime(eventTime);
+event.setEventSource(eventSource);
+event.setEventDetail(eventDetail);
+
+eventLoggingService.log(event);
+```
+

base/.gitignore

@@ -0,0 +1,4 @@
+/target/
+*.swp
+/.classpath
+/bin/

base/pom.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>event-logging</groupId>
+        <artifactId>parent</artifactId>
+        <version>3.0.0</version>
+    </parent>
+
+    <artifactId>base</artifactId>
+    <description>Classes to include in the logging API in addition to the JAXB generated ones from the schema</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>event-logging</groupId>
+            <artifactId>event-logging</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+    </dependencies>
+</project>

base/src/main/java/event/logging/EventLoggingService.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2016 Crown Copyright
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package event.logging;
+
+/**
+ * A service for creating events.
+ */
+public interface EventLoggingService {
+    /**
+     * Creates an event that may have some common values set by default depending on the particular EventLoggingService
+     * implementation being used.
+     * 
+     * @return An event that is ready to have additional properties set.
+     */
+    Event createEvent();
+
+    /**
+     * Logs an event.
+     * 
+     * @param event
+     *            The event to log.
+     */
+    void log(Event event);
+
+    /**
+     * Set to true if the event logging service should validate the output XML against the schema. This option helps
+     * identify areas of code that are producing invalid data. For performance reasons it is recommended that
+     * validation is not performed in production.
+     * 
+     * If validate is set to null then the system property shall be used to determine if validation is performed.
+     * 
+     * @param validate
+     *            The validation flag.
+     */
+    void setValidate(Boolean validate);
+
+    /**
+     * Use to determine if the event logging service is set to validate output data against the XML schema.
+     * 
+     * @return True if the validate flag is set.
+     */
+    boolean isValidate();
+}

base/src/main/java/event/logging/XMLValidator.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2016 Crown Copyright
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package event.logging;
+
+/**
+ * Should be implemented by classes providing a way to validate some XML.
+ */
+public interface XMLValidator {
+
+    /**
+     * Validates the <b>XML</b> and optionally writes the result to a file or
+     * log.
+     * 
+     * @param xml
+     *            The XML to validate.
+     */
+    void validate(String xml);
+}

base/src/main/java/event/logging/impl/DefaultEventLoggingService.java

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2016 Crown Copyright
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package event.logging.impl;
+
+import event.logging.Event;
+import event.logging.EventLoggingService;
+import event.logging.XMLValidator;
+import event.logging.Event;
+import org.apache.log4j.Logger;
+import org.xml.sax.ErrorHandler;
+
+import event.logging.EventLoggingService;
+import event.logging.XMLValidator;
+
+/**
+ * This is the default implementation for creating an event that writes to Log4J when logged.
+ */
+public class DefaultEventLoggingService implements EventLoggingService {
+    private static final Logger LOGGER = Logger.getLogger(DefaultEventLoggingService.class);
+
+    private static final String SCHEMA_LOCATION = SchemaLocator.getSchemaLocation();
+
+    private static final String VALIDATE = "event.logging.validate";
+
+    private final EventSerializer eventSerializer = new DefaultEventSerializer();
+    private final LogReceiverFactory logReceiverFactory = LogReceiverFactory.getInstance();
+    private final XMLValidator xmlValidator;
+
+    /**
+     * Used to set validation on or off overriding the system property. This is mainly for testing purposes.
+     */
+    private Boolean validate;
+
+    public DefaultEventLoggingService() {
+        xmlValidator = new DefaultXMLValidator(SCHEMA_LOCATION);
+    }
+
+    public DefaultEventLoggingService(ErrorHandler schemaValidationErrorHandler) {
+        xmlValidator = new DefaultXMLValidator(SCHEMA_LOCATION, schemaValidationErrorHandler);
+    }
+
+    /**
+     * @param schemaValidationErrorHandler
+     * @param validationExceptionBehaviourMode
+     *            Controls how the validator handles exceptions thrown by the schemaValidationExceptionHandler
+     */
+    public DefaultEventLoggingService(ErrorHandler schemaValidationErrorHandler,
+                                      ValidationExceptionBehaviourMode validationExceptionBehaviourMode) {
+
+        LOGGER.info("Using schema location " + SCHEMA_LOCATION);
+        xmlValidator = new DefaultXMLValidator(SCHEMA_LOCATION, schemaValidationErrorHandler,
+                validationExceptionBehaviourMode);
+    }
+
+    /**
+     * Creates an empty event.
+     * 
+     * @return An event that is ready to have additional elements added.
+     */
+    @Override
+    public Event createEvent() {
+        return new Event();
+    }
+
+    /**
+     * Logs an event to the log.
+     * 
+     * @param event
+     *            The event to log.
+     */
+    @Override
+    public void log(final Event event) {
+        final String data = eventSerializer.serialize(event);
+        final String trimmed = data.trim();
+        if (trimmed.length() > 0) {
+            // Validate data here if the configuration option is set.
+            if (checkValidating()) {
+                xmlValidator.validate(trimmed);
+            }
+
+            final LogReceiver logReceiver = logReceiverFactory.getLogReceiver();
+            logReceiver.log(trimmed);
+        }
+    }
+
+    private boolean checkValidating() {
+        // Check the programmatic flag first.
+        if (validate != null) {
+            return validate;
+        }
+
+        // If we aren't setting validate on .
+        final String val = System.getProperty(VALIDATE);
+        return Boolean.valueOf(val);
+    }
+
+    /**
+     * Set to true if the event logging service should validate the output XML against the schema. This option helps
+     * identify areas of code that are producing invalid data. For performance reasons it is recommended that
+     * validation is not performed in production.
+     * 
+     * If validate is set to null then the system property shall be used to determine if validation is performed.
+     * 
+     * @param validate
+     *            The validation flag.
+     */
+    @Override
+    public void setValidate(final Boolean validate) {
+        this.validate = validate;
+    }
+
+    /**
+     * Use to determine if the event logging service is set to validate data against the XML schema.
+     * 
+     * @return True if the validate flag is set.
+     */
+    @Override
+    public boolean isValidate() {
+        return validate != null && validate;
+    }
+
+}