DICOM audit support

The ipf-commons-audit module contains a reimplementation and improvement of the ATNA functionality contained in the ipf-oht-atna-* modules that originate from the Eclipse OpenHealthTools project. This includes building DICOM/ATNA-compliant Audit Records as well as queueing and sending them to an Audit Repository.

The most important improvements are:

  • type-safe Audit Event builders, that enforce setting mandatory members and avoid setting coded values into the wrong places (e.g. accidentally setting a ParticipantObjectTypeCodeRole code as ParticipantObjectTypeCode code).
  • possibility to select an Audit Message XML schema that belongs to a specific DICOM version
  • possibility to plug-in your own exception handler in case the Audit Repository is not reachable
  • configuration is done via an AuditContext bean instead of a static global class. You can create and use as many AuditContext configuration beans as you wish.

Constructing an Audit Message

All of the IHE components implemented by IPF automatically use the audit support of this module for ATNA auditing. You only need to configure an AuditContext bean. When you use one of the Spring Boot starter modules, this bean is already provided for you.

In order to create and submit your own Audit Message, perform the following steps

  1. Construct your Audit Message by using one of the builder classes contained in the org.openehealth.ipf.commons.audit.event package. Note that the IHE modules (such as ipf-commons-ihe-core or ipf-commons-ihe-xds) inherit from some of these builders to create IHE-style ATNA-compliant Audit messages more easily.
  2. Call the getMessage or getMessages method to obtain the AuditMessage from the builder.
  3. Submit the Audit Message to the configured destination by calling AuditContext#audit(AuditMessage...) method.

Every Audit Message and Audit Message builder also has a validate method that check basic restrictions defined by DICOM or IHE.

The AuditMessageBuilder implementations are modelled corresponding to the definitions of the DICOM Specific Audit Messages. The delegate builder class IHEAuditMessageBuilder has builder sub classes that correspond with the IHE ITI specification, Volume 2a, section 3.20.4.1.

The DICOM serialization strategies produce XML files that validate against the schema of the respective revision of the DICOM Audit Message Schema.

For more details on the API, please study the javadocs.

Example

Auditing an application start event

auditContext.audit(
    new ApplicationActivityBuilder.ApplicationStart(EventOutcomeIndicator.Success)
        .setAuditSource(auditContext)
        .setApplicationParticipant(
                appName,
                null,
                appName,
                AuditUtils.getLocalHostName())
        .addApplicationStarterParticipant(System.getProperty("user.name"))
        .getMessage()
);

Auditing a change to a user account:

auditContext.audit(
new SecurityAlertBuilder(EventOutcomeIndicator.Success, null, EventTypeCode.UserSecurityAttributesChanged)
                .addActiveParticipant(adminUserId, null, adminUserName, true, null, networkId)
                .addParticipantObjectIdentification(
                        ParticipantObjectIdTypeCode.UserIdentifier,
                        targetUserName,
                        null,
                        null,
                        targetUserId,
                        ParticipantObjectTypeCode.Person,
                        ParticipantObjectTypeCodeRole.User,
                        null, null)
                .getMessage()
);

Hints

The org.openehealth.ipf.commons.audit.utils.AuditUtils class contains static methods to obtain runtime information like process ID, current user, local host and IP address.

Configuration of the AuditContext

The AuditContext interface (and its DefaultAuditContext implementation) is the only place to configure static details for auditing, e.g. whether auditing is activated, the location of the Audit Repository, or the transmission protocol. It also allows to setup strategies for serialization, whether to send synchronously or asynchronously, and how errors are handled.

Generic properties

Property Default Description
auditEnabled false Whether audit is sent to the repository or not
auditRepositoryHost localhost Host name of the audit repository where audit records are sent to
auditRepositoryPort 514 Port of the the audit repository where audit records are sent to
auditRepositoryTransport UDP Transport protocol. See info about Audit Transmission Protocols below.

Content properties

Property Default Description
sendingApplication IPF Sending application for the Syslog header info
auditSourceId IPF Audit source ID for the source identification of the audit message
auditEnterpriseSiteId IPF Audit enterprise site ID for the source identification of the audit message
auditSource 9 (Other) Audit source type for the source identification of the audit message
includeParticipantsFromResponse false Whether to include participant objects from a response into the audit message

Advanced properties

Property Default Description
auditTransmissionProtocol Instance of UDPSyslogSenderImpl Transport implementation. Overrules auditRepositoryTransport
auditMessageQueue Instance of SynchronousAuditMessageQueue Audit message dispatcher implementation
serializationStrategy Instance of Current (i.e. DICOM2017c) Serialization implementation
tlsParameters (3.7) using system defaults Parameters used for TLS-based transmission
auditMetadataProvider (3.7) Instance of DefaultAuditMetadataProvider Provider for header data used for SYSLOG-based transmission
auditMessagePostProcessor no-op Audit Message Postprocessing, called before audit message is dispatched
auditExceptionHandler Instance of LoggingAuditExceptionHandler Handler to be called if the delivery of audit message to the audit repository has failed
auditValueIfMissing MISSING Value used if a mandatory audit attribute is not present

The default setup is to send Audit Messages via UDP to localhost:514, and handle delivery errors by just logging them. For production usage, it is usually required to configure:

  • a TLS connection to a remote Audit Record Repository
  • some decent strategy for handling failed connections

Audit Transmission Protocols

The transmission protocol determines the network protocol used for sending an audit record to the Audit Record Repository.

auditRepositoryTransport auditTransmissionProtocol class Description
UDP UDPSyslogSenderImpl UDP transport as SYSLOG record without delivery guarantee. Failed delivery is ignored.
TLS TLSSyslogSenderImpl Blocking TLS transport as SYSLOG record
NIO-TLS or NETTY-TLS NettyTLSSyslogSenderImpl Non-blocking TLS transport as SYSLOG record. Requires Netty library on the classpath
REACTOR-NETTY-TLS ReactorNettyTLSSyslogSenderImpl Reactive TLS transport as SYSLOG record. Requires Reactor-Netty library on the classpath
VERTX-TLS (deprecated) VertxTLSSyslogSenderImpl Non-blocking TLS transport as SYSLOG record. Requires Vertx library on the classpath

Audit Message Queues

There are a couple of implementations for “how” IPF handles audit records. Some implementations circumvent the Audit Transmission Protocol.

auditMessageQueue class Description
SynchronousAuditMessageQueue Synchronously pass the audit record to the auditTransmissionProtocol instance
AsynchronousAuditMessageQueue Asynchronously pass the audit record to the auditTransmissionProtocol instance. Must be initialized with an ExecutorService
JMSAuditMessageQueue Send the audit record to a JMS queue. SYSLOG header data is sent as JMS properties. Requires JMS API library.
BasicHttpAuditMessageQueue (3.7) Send the audit record to a HTTP service. SYSLOG header data is sent as HTTP properties.
LoggingAuditMessageQueue Just log the audit record to an SLF4J logger
CamelAuditMessageQueue Send the audit record via a Camel producer. SYSLOG header data is sent as Camel headers.
CompositeAuditMessageQueue Send the audit record sequentially using one of the implementations listed above

TLS Parameters (3.7)

With TLS-based audit transmission, the default TLS parameters (as passed using the javax.net.ssl.* system properties) are used. However, sometimes the TLS Audit connection requires a different TLS configuration. In this case, an instance of CustomTlsParameters can be used to specifically assign a different TLS setup to the AuditContext.

TLS/UDP Syslog Server (4.0)

As of IPF 4.0, the ipf-commons-audit module comes with a server-side component that implements a Syslog server for both the RFC 5425 (TLS transport) and RFC 5426 (UDP transport) specifications.

These servers are primarily meant for integration testing of functionality that emits ATNA audit records, but can also be used as basis for standalone applications. Note that only the Syslog endpoints and some parsers are provided, however, the library doesn’t include a persistence layer or any other production-level features.

TLS (TlsSyslogServer) and UDP (UdpSyslogServer) servers are used very similarly, so the following examples primarily cover the TLS server.

Required dependencies

Two optional Maven dependencies need to be included (versions can be imported from the dependencies module):

        <dependency>
            <groupId>io.projectreactor.netty</groupId>
            <artifactId>reactor-netty-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.palindromicity</groupId>
            <artifactId>simple-syslog-5424</artifactId>
        </dependency>

Instantiation and Start

The Syslog servers parses an incoming syslog record into a Map<String, Object> of its attributes. A SyslogServer instance is initialized with

  • a regular consumer the processes this map
  • an error consumer that processes any Exception that may have occurred during parsing
  • an instance of TlsParameters

and is started with

  • a host (localhost for local access, 0.0.0.0 for external access)
  • a port (the RFCs define 6514 for TLS and 514 for UDP)

The number of connections per remote host is not restricted.

The regular consumer defines what happens with the syslog record. We provide one consumer (org.openehealth.ipf.commons.audit.server.support.SyslogEventCollector) that simply collects the records in memory and can be configured with some expectations for unit tests. See the following snippet for a potential unit test:

        var defaultTls = TlsParameters.getDefault();
        auditContext.setTlsParameters(defaultTls);
        auditContext.setAuditRepositoryTransport("TLS");
        var count = 100;
        var consumer = SyslogEventCollector.newInstance()
            .withExpectation(count)  // expecting count records to arrive
            .withDelay(100);         // artificial delay of 100ms for handling a record  

        try (var ignored = new TlsSyslogServer(consumer, Throwable::printStackTrace, defaultTls)
                .start("localhost", port))  // For a real server you would have to block here.
        { 
            IntStream.range(0, count).forEach(i -> sendAudit());  // send out "count" records via AuditContext#audit
            assertTrue(consumer.await(5, TimeUnit.SECONDS));      // wait max. 5 seconds for all records to arrive
        }  // SyslogServers are AutoCloseable!

The consumer executes asynchronously using a variable number of threads (depending on producer/consumer load) rather than in the receiver thread, so that the test finishes within 5 seconds even though consuming sleeps for 100ms for each of the 100 messages.

ATNA unmarshaller

IPF also provides an unmarshaller (org.openehealth.ipf.commons.audit.unmarshal.dicom.DICOMAuditParser) that allows to parse syslog XML payload following the current DICOM specification (used by the IHE ATNA profile) back into an instance of org.openehealth.ipf.commons.audit.model.AuditMessage while optionally validating the XML content against corresponding the XML schema.

This would allow to write an ATNA Consumer for the Syslog Server that extracts structured data from the ATNA payload, e.g. for offering detailed queries to retrieve specific records.

Beta disclaimer

The Syslog server is a new feature and, while being stable enough for “happy case” usage, it may still require improvement and configuration possibilities, particularly to handle edge cases. You are invited to give it a test drive and report and findings or suggestions. Thank you!