Collecting Audit Messages from Third-party Applications

The following figure illustrates the audit message data flow and its important components:

As shown in the figure, the application sends the audit messages to a queue (dxt Queue in the figure). The generic JMS collector picks up the messages from the queue and then passes them to the Persistence Service Unit. The Persistence Service Unit first transforms the message from XML structure into the corresponding in-memory object. Next, it forwards the object to the digest producer and to the tag producer. Finally, it stores the whole data structure containing the object representing the audit message, digests and tags into the corresponding database tables.

If an error occurs, the message is passed to the Error Handling Unit, which stores it along with error information in the configured /errors folder.

The application must produce audit messages according to the XML namespace "urn:com:siemens:dxt:persistence:schemadb:2.0". You can find it in the schema file AuditMessages.xsd in the folder install_path/conf/xsd.

The application can put multiple messages into one XML document; the root element to use is always <auditMessages>. Individual messages are then contained sequentially in the sub-elements named <auditMessage>. The application can send this XML document to the configured JMS queue or write it to files in the configured input folder for the file collector. For sample messages, see the files in the folder Additions/Data/SampleData/Access on the installation media.

For examples on how to write a JMS producer for Apache ActiveMQ, see the JMS specification (for example, https://jcp.org/aboutJava/communityprocess/final/jsr914/index.html) and the Apache ActiveMQ documentation; for example, http://activemq.apache.org/hello-world.html.

In order to easily distinguish its messages from those of DirX Identity and DirX Access, the application should fill the attribute source of the <identification> element with an appropriate name.

DirX Audit provides two generic collectors: one for reading messages from a JMS message queue and one for reading messages from files. The message queue should be selected for a production environment; the file collector is mainly intended for testing purposes or initial load.

Both collectors expect the messages in the DirX Audit XML format (see "Setting up the Third-party Application" for details).

For information on how to configure these collectors, see the section "Configuring Generic Collectors" in the chapter "Configuring DirX Audit Collectors" of the DirX Audit Administration Guide.

A digest producer - also called a digest generator - is responsible for generating one or more digests for an audit message. A digest producer is specific to the audit message provider.

A digest producer is a Java class and must implement the interface com.siemens.dxt.persistence.digest.api.DigestProducer with its only method getDigests(AuditMessage auditMessage). The method accepts one audit message in its Java (not XML) representation and returns a set of audit events, the digests.

A digest consists of the properties operation, type and detail. It is intended to give a summary of the audit message that can be understood by auditors that are not experts in the audited product. In addition to Add Object, Update Object or Delete Object, the operation can also be more high-level; for example, Login, Set Password or Accept and Reject. The type usually denotes the type of the affected object; this can be something like User, Account and Role, but can also denote relationships like User to Role or Account to Group. The detail of a digest depends on the operation and type; it typically contains the human-readable names of the affected objects; for example, the user’s pseudonym, the login name of an account along with the target system display name (if available) or the name of a workflow and an approval activity.

Thread safety is not an issue for the digest producer because it is a Spring bean (see https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#spring-core) and is instantiated by the Spring dependency injection framework for each message. This design permits configuring the Java class name along with any custom class properties in external XML configuration files.

To configure the digest producer, see the section "Configuring a Digest Producer" in the chapter "Customizing Digest and Tag Producers" in this guide.

To deploy the digest producer, see the section "Deploying Digest and Tag Producers" in this guide.

For a sample of a digest producer Java class, see the digester for Apache Tomcat in the folder Additions/Data/SampleJava on the installation media.

A tag producer - also called a tag generator or dimension generator - generates tags for an audit message and audit event. A tag consists of a key (type) - value pair.

The tags are evaluated for filling fact tables and are used as dimension values in charts. They can also be used to filter events in DirX Audit Manager’s Audit analysis. Tag keys and values can be any string that seems appropriate for the event. For example, typical tag keys for DirX Identity are:

A tag key APPLICATION can be used, for example, in charts on password changes to slice the number of password changes per target system and drill through to the password change events for a selected target system. For the configuration of fact and dimension tables, see the chapter "Customizing Fact and Dimension Tables" in this guide.

A tag producer is a Java class that implements the interfaces com.siemens.dxt.persistence.dim.DigestDimensionProducer for audit event dimensions and com.siemens.dxt.persistence.dim.MessageDimensionProducer for audit message dimensions. For each of these interfaces, it must implement one method that accepts either the audit message or the audit event with the digest and returns a set of key - value pairs, the tags. Like the digest producer, a tag producer is a Spring bean instantiated for each message and event.

To configure a dimension generator, see the section "Adding a Tag Producer" in the chapter "Customizing Digest and Tag Producers" in this guide.

For a sample of a tag producer Java class, see the one for Apache Tomcat in the folder Additions/Data/SampleJava on the installation media.

To deploy a tag producer, see the section "Deploying Digest and Tag Producers" in this guide.

All of the digest and tag producers - along with a lot of other libraries - are deployed as separate jar files in DirX Audit Server deployment folders. Custom producers, especially those for a third-party collector, must be added to the correct server deploy folder.

Place the valid Java jar file with Java producer classes into one of the following folders depending on whether it is tenant-specific or shared for all tenants:

Next: