Version: 17.07
Supported Since: 17.01
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’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.
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.
Oracle driver downloads page - http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html
MySQL driver downloads page - https://dev.mysql.com/downloads/connector/j/
MS SQL Server driver downloads page - https://www.microsoft.com/en-us/download/details.aspx?id=11774
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.
|
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 |
Audit Severity * |
Basic |
Parameter which sets audit severity. Assignable values are as follows.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Auditor Implementation * |
Basic |
This parameter allows to select auditor implementation.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
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.
|
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.
Configuration of the auditor processing element is shown below.
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