audit feature

Audit Feature

Version: 17.07

Supported Since: 17.01

Audit Feature

Audit Feature provides ability to print audit logs either to a file or to a database table. Audit Feature has API methods which falls onto two types with one being File Based Auditing and the other being DataBase Based Auditing. Each of these two API method types has a few prerequisites as follows. The Auditor Processing Element uses Audit Feature in it’s implementation hence most of the content here under prerequisites section will be quite similar to what it is there in the auditor processing element documentation.

Prerequisites

File Based Auditing API Methods

File based auditing API methods' underlying implementation uses log4j2 to print audit logs. When using the file based auditing methods there are some configurations to be done in the log4j2.xml file in UltraESB-X distribution.

First RollingRandomAccessFile Appender shown below, should be added under the Appenders.

<!-- RollingRandomAccessFile configuration for FileBasedAuditor -->
<RollingRandomAccessFile name="AUDIT_APPENDER" fileName="logs/audit-x.log"
                         filePattern="logs/$${date:yyyy-MM}/audit-x-%d{MM-dd-yyyy}-%i.log.gz">
    <PatternLayout>
        <Pattern>%d{ISO8601} [%X{ip}-%X{host}] [%t] [%X{xc}] %5p %c{1} %m%n</Pattern>
    </PatternLayout>
    <Policies>
        <SizeBasedTriggeringPolicy size="1 MB"/>
    </Policies>
    <DefaultRolloverStrategy max="10"/>
</RollingRandomAccessFile>

Then a Logger shown below, should be added under the Loggers.

<!-- Logger configuration for FileBasedAuditor -->
<Logger name="AUDIT_LOGGER" level="ALL" additivity="false">
    <AppenderRef ref="AUDIT_APPENDER"/>
</Logger>

For information on log4j2 configuration syntax please refer log4j2 configuration documentation.

DataBase Based Auditing API Methods

DB based auditing API methods will insert audit logs to a given database table. Underlying implementation uses Spring JdbcTemplate and hence should support any relational SQL database including Oracle, SQL Server and MySQL.

In order to use DB based auditor first a table in the database must be created. The auditor processing element allows user to use a custom schema (using the Custom Audit Fields parameter) or a fixed schema. If a custom schema is used a table according to that schema should be created. See APIs section for more info on that. The fixed schema will be as follows.

Schema for Oracle

-- Table structure for table 'AUDIT_LOG' --
CREATE TABLE USERNAME.AUDIT_LOG
(
  ID            NUMBER(10)      NOT NULL,
  SEVERITY      VARCHAR2(255)   DEFAULT NULL,
  SUBJECT       VARCHAR2(255)   DEFAULT NULL,
  MESSAGE       VARCHAR2(4000)  DEFAULT NULL,
  HEADERS       CLOB,
  PROPERTIES    CLOB,
  PAYLOAD       CLOB,
  OCCURRENCE    TIMESTAMP(3)    DEFAULT NULL,
  PRODUCT_NAME  VARCHAR2(255)   DEFAULT NULL,
  NODE_NAME     VARCHAR2(255)   DEFAULT NULL
);

-- 'AUDIT_LOG' primary key constraint
ALTER TABLE USERNAME.AUDIT_LOG
ADD CONSTRAINT AUDIT_LOG_PK PRIMARY KEY (ID);

-- 'AUDIT_LOG' sequence for the primary key generation
CREATE SEQUENCE USERNAME.AUDIT_LOG_SEQ START WITH 1 INCREMENT BY 1;

-- 'AUDIT_LOG' trigger for primary key generation
CREATE OR REPLACE TRIGGER USERNAME.AUDIT_LOG_SEQ_TR
BEFORE INSERT ON USERNAME.AUDIT_LOG FOR EACH ROW
WHEN (NEW.ID IS NULL)
  BEGIN
    SELECT USERNAME.AUDIT_LOG_SEQ.NEXTVAL
           INTO :NEW.ID
           FROM DUAL;
  END;
/

Schema for MySQL

CREATE TABLE DB_NAME.AUDIT_TABLE
(
    ID INT PRIMARY KEY NOT NULL AUTO_INCREMENT,
    SEVERITY VARCHAR(255) DEFAULT NULL ,
    SUBJECT VARCHAR(255) DEFAULT NULL ,
    MESSAGE VARCHAR(4000) DEFAULT NULL ,
    HEADERS LONGTEXT,
    PROPERTIES LONGTEXT,
    PAYLOAD LONGTEXT,
    OCCURRENCE TIMESTAMP,
    PRODUCT_NAME VARCHAR(255) DEFAULT NULL ,
    NODE_NAME VARCHAR(255) DEFAULT NULL
);

Schema for MS SQL Server

CREATE TABLE DB_NAME.SCHEMA_NAME.AUDIT_TABLE
(
    ID INT PRIMARY KEY NOT NULL IDENTITY,
    SEVERITY VARCHAR(255) DEFAULT NULL ,
    SUBJECT VARCHAR(255) DEFAULT NULL ,
    MESSAGE VARCHAR(4000) DEFAULT NULL ,
    HEADERS VARCHAR(MAX) DEFAULT NULL ,
    PROPERTIES VARCHAR(MAX) DEFAULT NULL ,
    PAYLOAD VARCHAR(MAX) DEFAULT NULL ,
    OCCURRENCE DATETIME,
    PRODUCT_NAME VARCHAR(255) DEFAULT NULL ,
    NODE_NAME VARCHAR(255) DEFAULT NULL
);

Then in order to create a connection with the database, a datasource must be defined in project.xpml. Sample datasource configuration for Oracle, MySQL and SQL Server are as follows.

<!-- For Oracle -->
<x:resource id="oracleUCP">
    <bean class="org.adroitlogic.ultracp.UltraDataSource" init-method="initialize" destroy-method="destroy">
        <property name="driverClass" value="oracle.jdbc.driver.OracleDriver"/>
        <property name="url" value="jdbc:oracle:thin:@//192.168.56.101:1521/ORA01"/>
        <property name="initialSize" value="1"/>
        <property name="minSize" value="1"/>
        <property name="maxTotal" value="5"/>
        <property name="validationQuery" value="SELECT 1 FROM DUAL"/>
        <property name="connectionProperties">
            <props>
                <prop key="user">user</prop>
                <prop key="password">password</prop>
            </props>
        </property>
    </bean>
</x:resource>
<!-- For MySQL -->
<x:resource id="mySqlUCP">
<bean class="org.adroitlogic.ultracp.UltraDataSource" init-method="initialize" destroy-method="destroy">
    <property name="driverClass" value="com.mysql.jdbc.Driver"/>
    <property name="url" value="jdbc:mysql://localhost:3306/DB_NAME"/>
    <property name="initialSize" value="1"/>
    <property name="minSize" value="1"/>
    <property name="maxTotal" value="5"/>
    <property name="validationQuery" value="SELECT 1"/>
    <property name="connectionProperties">
        <props>
            <prop key="user">user</prop>
            <prop key="password">password</prop>
        </props>
    </property>
</bean>
</x:resource>
<!-- For SQL Server -->
<x:resource id="sqlUCP">
    <bean class="org.adroitlogic.ultracp.UltraDataSource" init-method="initialize" destroy-method="destroy">
        <property name="driverClass" value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/>
        <property name="url" value="jdbc:sqlserver://192.168.56.102:1433;databaseName=DB_NAME"/>
        <property name="initialSize" value="1"/>
        <property name="minSize" value="1"/>
        <property name="maxTotal" value="5"/>
        <property name="validationQuery" value="SELECT 1"/>
        <property name="connectionProperties">
            <props>
                <prop key="user">user</prop>
                <prop key="password">password</prop>
            </props>
        </property>
    </bean>
</x:resource>

Finally relevant jdbc should be added the classpath.

MySQL driver is also available in maven central repository. Therefore instead of manually downloading, following dependency can also be used.

Please make sure you use a driver version which is compatible with your database version.

 
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>${mysql.version}</version>
</dependency>

APIs Java Docs

createFileAuditTemplate
Parameters
AuditSeverity auditSeverity

AuditSeverity enum value (SUCCESS, INFO, WARN, ERROR)

String requestedAuditFields

Comma separated list of fields for audit log. Accepted audit fields are as follows.

  • SEVERITY - Audit severity

  • SUBJECT - Custom subject for audit log

  • MESSAGE - Audit message

  • HEADERS - All the headers

  • PROPERTIES - All the properties

  • PAYLOAD - Message payload

  • OCCURRENCE - Timestamp for audit log

  • PRODUCT_NAME - Project Name

  • NODE_NAME - Node Name

  • MESSAGE_ID - Message ID

  • MESSAGE_CONTEXT_ID - Message context ID

  • @{message.headers.<header_name>} - Value of the header given by <header_name>

  • @{message.properties.<property_name>} - Value of the property given by <property_name>

  • @{variable.<variable_name>} - Value of the variable given by <variable_name>

  • @{messagecontext.properties.<message_context_property_name>} - Value of the message context property given by <message_context_property_name>

String auditSubject

Nullable parameter which can be used to given an audit subject to the audit log

String auditMessage

Nullable parameter which can be used to given an audit message

Returns
FileAuditTemplate

FileAuditTemplate representing the template

Creates a FileAuditTemplate using the given parameters.

createDatabaseAuditTemplate
Parameters
AuditSeverity auditSeverity

AuditSeverity enum value (SUCCESS, INFO, WARN, ERROR)

String requestedAuditFields

Comma separated list of fields for audit log. Accepted audit fields are as follows.

  • SEVERITY - Audit severity

  • SUBJECT - Custom subject for audit log

  • MESSAGE - Audit message

  • HEADERS - All the headers

  • PROPERTIES - All the properties

  • PAYLOAD - Message payload

  • OCCURRENCE - Timestamp for audit log

  • PRODUCT_NAME - Project Name

  • NODE_NAME - Node Name

  • MESSAGE_ID - Message ID

  • MESSAGE_CONTEXT_ID - Message context ID

  • @{message.headers.<header_name>} - Value of the header given by <header_name>

  • @{message.properties.<property_name>} - Value of the property given by <property_name>

  • @{variable.<variable_name>} - Value of the variable given by <variable_name>

  • @{messagecontext.properties.<message_context_property_name>} - Value of the message context property given by <message_context_property_name>

Data types for each audit field will be as follows.

Element Name

DB Data Type Oracle

DB Data Type MySQL

DB Data Type MSSQL

SEVERITY

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

SUBJECT

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

MESSAGE

VARCHAR2(4000)

VARCHAR(4000)

VARCHAR(4000)

HEADERS

CLOB

LONGTEXT

VARCHAR(MAX)

PROPERTIES

CLOB

LONGTEXT

VARCHAR(MAX)

PAYLOAD

CLOB

LONGTEXT

VARCHAR(MAX)

OCCURRENCE

TIMESTAMP(3)

TIMESTAMP

DATETIME

PRODUCT_NAME

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

NODE_NAME

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

MESSAGE_ID

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

MESSAGE_CONTEXT_ID

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

@{message.headers.header_name}

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

@{message.properties.property_name}

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)

@{messagecontext.properties.<message_context_property_name>}

VARCHAR2(255)

VARCHAR(255)

VARCHAR(255)
String auditSubject

Nullable parameter which can be used to given an audit subject to the audit log

String auditMessage

Nullable parameter which can be used to given an audit message

Returns
DatabaseAuditTemplate

DatabaseAuditTemplate representing the template

Creates a DatabaseAuditTemplate using the given parameters.

auditLogToFile
Parameters
AuditSeverity auditSeverity

AuditSeverity enum value (SUCCESS, INFO, WARN, ERROR)

Set<String> requestedAuditData

Set that represents which data to be included in the audit log. Accepted values in the Set are "PAYLOAD", "HEADERS" and "PROPERTIES".

XMessageContext xMessageContext

Message Context

String auditSubject

Nullable parameter which can be used to given an audit subject to the audit log

String auditMessage

Nullable parameter which can be used to given an audit message

Returns

void

Prints audit log to file. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.

auditLogToFile
Parameters
FileAuditTemplate fileAuditTemplate

FileAuditTemplate representing the audit log template

XMessageContext xMessageContext

Message Context

Returns

void

Prints audit log to file according to the custom structure represented by fileAuditTemplate. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.

auditLogToDatabase
Parameters
AuditSeverity auditSeverity

AuditSeverity enum value (SUCCESS, INFO, WARN, ERROR)

Set<String> requestedAuditData

Set that represents which data to be included in the audit log. Accepted values in the Set are "PAYLOAD", "HEADERS" and "PROPERTIES".

XMessageContext xMessageContext

Message Context

String auditSubject

Nullable parameter which can be used to give an audit subject to the audit log.

String auditMessage

Nullable parameter which can be used to give an audit message to the audit log.

DataSource dataSource

DataSource Resource Bean. (See prerequisites section above for more info)

String tableName

Name of the audit table in the database.

Returns
int

Number of rows affected. Since audit log insert is always only a single rwo this will either return 1 (in case of success) or 0 (in case of failure).

Inserts audit logs to the given database table. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.

auditLogToDatabaseAsync
Parameters
AuditSeverity auditSeverity

AuditSeverity enum value (SUCCESS, INFO, WARN, ERROR)

Set<String> requestedAuditData

Set that represents which data to be included in the audit log. Accepted values in the Set are "PAYLOAD", "HEADERS" and "PROPERTIES".

XMessageContext xMessageContext

Message Context

String auditSubject

Nullable parameter which can be used to give an audit subject to the audit log.

String auditMessage

Nullable parameter which can be used to give an audit message to the audit log.

DataSource dataSource

DataSource Resource Bean. (See prerequisites section above for more info)

String tableName

Name of the audit table in the database.

Returns
CompletableFuture<Integer>

CompletableFuture with integer result representing number of rows affected. Since audit log insert is always only a single rwo this will either return 1 (in case of success) or 0 (in case of failure).

Async operation for inserting audit logs to the given database table. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.

auditLogToDatabase
Parameters
DatabaseAuditTemplate databaseAuditTemplate

DatabaseAuditTemplate representing the audit table schema

XMessageContext xMessageContext

Message Context

String tableName

Name of the audit table in the database.

Returns
int

Number of rows affected. Since audit log insert is always only a single rwo this will either return 1 (in case of success) or 0 (in case of failure).

Inserts audit logs to the given database table with a schema represented by databaseAuditTemplate. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.

auditLogToDatabaseAsync
Parameters
DatabaseAuditTemplate databaseAuditTemplate

DatabaseAuditTemplate representing the audit table schema

XMessageContext xMessageContext

Message Context

String tableName

Name of the audit table in the database.

Returns
CompletableFuture<Integer>

CompletableFuture with integer result representing number of rows affected. Since audit log insert is always only a single rwo this will either return 1 (in case of success) or 0 (in case of failure).

Async operation for inserting audit logs to the given database table with a schema represented by databaseAuditTemplate. There are few configurations to be made prior to usage. Please refer prerequisites section above for more details.
In this topic
In this topic
(c) Copyright 2016-2017 AdroitLogic. All rights reserved.
Terms of Use
Contact Us