auditor

Auditor

Version: 17.07

Supported Since: 17.01

What is an Auditor?

An Auditor is a processing element which can be used for audit logging. Currently it supports two implementations. One is file based auditing which will print audit logs to a file called audit-x.log and the other is database auditing which will insert audit logs to a database table.

File Based Auditor

File based auditor’s underlying implementations uses log4j2 to print audit logs. When using the file based auditor for the first time there are some configurations to be done in the log4j2.xml file.

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.

DB Based Auditor

Database auditor 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 Parameters 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 we need to add the relevant jdbc driver according to the database used.

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>

In order to use this processing element, you must first select the Message Auditor dependency from the processor list when you are creating an empty Ultra project. If you have already created a project, you can add this dependency via Component Registry. From Tools menu, select Ultra Studio → Component Registry and from the Processors list, select the Message Auditor dependency.

Alternatively, you can add the following dependency to the maven pom.xml manually.

<dependency>
    <groupId>org.adroitlogic.x.processors</groupId>
    <artifactId>x-processor-audit</artifactId>
    <version>17.07</version>
</dependency>
auditor outports

Out Ports

Next

The message will be sent to this outport if audit logging is successful

On Exception

The message will be sent to this outport if the processing element failed in audit logging

Parameters

Audit Severity *

Basic

Parameter which sets audit severity. Assignable values are as follows.

  • SUCCESS

  • INFO

  • WARN

  • ERROR

Audit Data *

Basic

Audit Data represents which data to be included in the audit log. Note that this is a multi select field. You can select one or more fields here.

  • PAYLOAD - will log payload if selected

  • HEADERS - will log headers if selected

  • PROPERTIES - will log properties if selected

Auditor Implementation *

Basic

This parameter allows to select auditor implementation.

  • FILE_BASED_AUDITOR - file based auditor

  • DB_BASED_AUDITOR - db based auditor

Audit Subject

Basic

This allows user to add custom subject for audit log.

Audit Message

Basic

This audit message parameter allows user to add more information to the audit log.

Datasource

Basic

When DB_BASED_AUDITOR is used, a datasource should be selected.

Table Name

Basic

When DB_BASED_AUDITOR is used, a table name should be provided.

Use Custom Audit Fields

Advanced

Boolean parameter which can be used to toggle between custom audit log structure and fixed audit log structure. Default value is false. Set this parameter to true if custom audit log structure needs to be used.

Custom Audit Fields

Advanced

This parameter accepts an ordered comma separated list of fields representing data required to be in Audit Log. This parameter can be used to provide a custom audit log structure for the audit log. In order to use this parameter Use Custom Audit Fields boolean must be set to true and when it is set to true, this Custom Audit Fields parameter will take priority over Audit Data parameter.

Possible values for this parameter are 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>

Output field name (column name in the case of DB_BASED_AUDITOR and Log Line field name in the case of FILE_BASED_AUDITOR) is usually the given field name itself except in custom property, variable and header syntax. In that case that respective custom value name will be used as the field name. If there is a requirement to use custom output field names, custom output field name should be given after the field name separated by a colon ':'

An example value for this parameter will be as follows.

"SEVERITY, SUBJECT, MESSAGE, PAYLOAD, @{message.headers.MY_HEADER}:custom_header, @{message.properties.MY_PROPERTY}:custom_property, @{variable.MY_VARIABLE}:custom_variable, OCCURRENCE:timestamp"

In case of DB_BASED_AUDITOR the 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)

Sample Use Case

In the following use case, auditor processing element is used to print audit logs to a file using file based auditor implementation. Here to demonstrate the auditor operation, NIO HTTP Ingress Connector and NIO HTTP Egress Connector is used. Complete flow for the use case is shown below.

auditor flow

Configuration of the auditor processing element is shown below.

auditor conf

When a message is sent to the endpoint which http listener is configured, following audit log line will be print to audit log file named audit-x.log.

2016-12-28T17:12:28,494 [-] [pool-2-thread-3] []  INFO AUDIT_LOGGER SEVERITY : SUCCESS, HEADERS : {SOAPAction=urn:getQuote, User-Agent=AdroitLogic (http://adroitlogic.org) - SOA Toolbox/1.5.0, Connection=close, Host=localhost:8280, Content-Length=12, Content-Type=text/xml; charset=UTF-8}, PROPERTIES : {x.http.method=POST, x.http.ssl_client_dn=null, x.http.entity_size=12, x.http.query_param_map_wdups={}, x.http.ssl_client_certs=null, x.http.header_size=233, x.http.forward_url_postfix=/, x.http.server_connection_debug=UUID=5f727eb6-168e-b1d4-0000-000000000003, C2E-Connection=127.0.0.1:8320->127.0.0.1:8280, C2E-Req-StartTime=17:12:28.492, C2E-Req-EndTime=17:12:28.492, C2E-Req-ConnCreateTime=17:12:28.491, C2E-Req-URL=/service/echo-proxy, C2E-Req-Protocol=HTTP/1.0, C2E-Req-Method=POST, C2E-Req-IP=127.0.0.1, x.http.message_size=245}, PAYLOAD : Test_Payload, PRODUCT_NAME : UltraESB 17.01, NODE_NAME : node1
In this topic
In this topic
Contact Us