The Oracle Audit Vault documentation provides examples of a Java-based collection plug-in implementation, including a hypothetical source that writes events to a table named AUD.

Implementing Oracle Audit Vault and Database Firewall involves writing Java classes that implement the AuditEventCollectorFactory interface, and that extend the AuditEventCollector class, which are part of the Audit Vault Collection Framework. The same Java class can both extend the AuditEventCollector class. and implement the AuditEventCollectorFactory interface. Alternately, you can choose to write two separate classes.The sample consists of two classes, SampleEventCollectorFactory which implements the AuditEventCollectorFactory interface and SampleEventCollector which extends from the AuditEventCollector class.

During runtime the collection plug-in can require multiple implementations of AuditEventCollector. The AuditEventCollectorFactory object enables this capability for Oracle Audit Vault and Database Firewall.

The Collection Framework does not create an instance of the AuditEventCollector object directly. Instead, it creates an instance of the AuditEventCollectorFactory class and using the factory object, gets the AuditEventCollector object. This is because the collection plug-in may require multiple implementations of AuditEventCollector. The collection plug-in decides at run time which implementation to use. Therefore, every collection plug-in should have an implementation of AuditEventCollectorFactory.

In the following example, the createAuditEventCollector() always creates and returns an instance of the SampleAuditEventCollector class.

public class SampleEventCollectorFactory implements AuditEventCollectorFactory {
 
   public AuditEventCollector createAuditCollection(
         CollectorContext collectorContext) throws AuditEventCollectorException {
      return new SampleEventCollector();
   }
}

Learn how to use source attributes, which provide the Oracle AVDF collection plug-in with information about the source that is needed to collect the audit trail effectively.

The Collection Framework passes an instance of the CollectorContext class to the collection plug-in through the initializeCollector method. This instance can be queried by the collection plug-in to obtain information needed to collect the audit trails generated by the source.

Use these examples to understand how to initialize a Java-based collection plug-in, and how to start audit events collection with Oracle Audit Vault and Database Firewall.

private AVLogger m_logger;
   private CollectorContext m_collectorContext;
   private long m_timeZoneOffset;
   private AuditService m_auditService;
   private Timestamp m_previousCheckpoint;
 
   public void initializeCollector(CollectorContext collectorContext)
         throws AuditEventCollectorException {
      m_collectorContext = collectorContext;
      m_auditService = m_collectorContext.getAuditService();
      m_previousCheckpoint = m_collectorContext.getCheckpoint();
      m_logger = m_collectorContext.getLogger();
      // Get other attributes of the Source.
      String offset = m_collectorContext.getAttribute("TimeZoneOffset");
      if (offset != null) {          m_timeZoneOffset = getTimeZoneOffsetInMs(offset);
      }
      connectToSource();
 }

private ConnectionManager m_connectionManager;
   
   private void connectToSource() throws AuditEventCollectorException {
      m_logger.logDebugMethodEntered();
      // Get connection information from collector context.
      String user = m_collectorContext.getSecuredTargetUser();
      String password = new String(m_collectorContext.getSecuredTargetPassword());
      String connectionString = m_collectorContext.getSecuredTargetLocation();
      // Create a ConnectionManager object.
      try {
         m_connectionManager = new ConnectionManagerImpl(connectionString,
               user, password.toCharArray());
         m_connection = m_connectionManager.getConnection();
      } catch (AuditException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.FAILED_CONNECT_TO_SOURCE,
               new Object[] { connectionString }, ex);
      }
      m_logger.logDebugMethodExited();
   }

Use these examples to understand how to connect a Java-based collection plug-in, how to fetch events, and how to set checkpoints with Oracle Audit Vault and Database Firewall.

   private ResultSet m_resultSet;
   private Timestamp m_nextCheckpoint;
 
   private void fetchEvents() throws AuditEventCollectorException {
      m_logger.logDebugMethodEntered();
      if (m_nextCheckpoint != null) {
         m_auditService.setCheckpoint(m_nextCheckpoint);
         m_previousCheckpoint = m_nextCheckpoint;
      }
     // It is not good to hold on to the Connection for long. As this is the
      // only place we can release the connection, we release and reacquire the
      // connection.
      try {
         if (m_connection != null) {
            m_connectionManager.releaseConnection(m_connection);
         }
      } catch (AuditException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.FAILED_TO_RELEASE_CONNECTION_TO_DB, null, ex);
      }
 
      try {
         m_connection = m_connectionManager.getConnection();
      } catch (AuditException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.FAILED_TO_GET_CONNECTION_TO_DB, null, ex);
      }
 
     // This is the upper bound which is current time minus 5 seconds.
      m_nextCheckpoint = new Timestamp(System.currentTimeMillis() - 5000);
     String query = null;
      try {
         if (m_previousCheckpoint == null) {
            query = "select * from AUD where EVENT_TIME <= ?";
            m_preparedStatement = m_connection.prepareStatement(query);
            m_preparedStatement.setTimestamp(1, m_nextCheckpoint);
         } else {
            query = "select * from AUD where EVENT_TIME > ? and EVENT_TIME <= ?";
            m_preparedStatement = m_connection.prepareStatement(query);
            m_preparedStatement.setTimestamp(1, m_previousCheckpoint);
            m_preparedStatement.setTimestamp(2, m_nextCheckpoint);
         }
         m_resultSet = m_preparedStatement.executeQuery();
      } catch (SQLException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE,
               new Object[] { query }, ex);
      }
      m_logger.logDebugMethodExited();
   }

     public boolean hasNext() throws AuditEventCollectorException {
      boolean hasMore;
      try {
         if(m_resultSet == null) {
            fetchEvents();
            return m_resultSet.next();
         }
         hasMore = m_resultSet.next();
         if (!hasMore) {
            fetchEvents();
            hasMore = m_resultSet.next();
         }
      } catch (SQLException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE, null, ex);
      }
      return hasMore;
   }

Learn about when and how the Oracle AVDF collection plug-in transforms source event values to Oracle AVDF values.

The collector retrieves values of specific fields from source. For some fields, in addition to retrieving the values, the collection plug-in must transform the values in certain ways. This section discusses transformations that are required for all source types.

When field values do not require transformations, the Oracle Audit Vault Java-based collection plug-in returns the value it obtains from the source.

In the following example, the Oracle Audit Vault collection plug-in obtains a user name, and returns it.

   public String getUserName() throws AuditEventCollectorException {
      try {
         return m_resultSet.getString("USER_ID");
      } catch (SQLException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE, null, ex);
      }
   }

If you are an administrator, then you can change the attributes that a Java-based collector plug-in uses during Oracle AVDF audit trail collection.

If you are an Oracle AVDF administrator, then you can update attributes, including source attributes, at any time. To update attributes, you can use either the Audit Vault Server console, or you can use the AVCLI command-line tool.

public void setAttribute(String name, String value)
         throws SetAttributeException {
           if (name.equalsIgnoreCase("TimeZoneOffset")) {
              m_timeZoneOffset = getTimeZoneOffsetInMs(value);
      } else {
         throw new SetAttributeException(ErrorCodes.INVALID_ATTRIBUTE_NAME,
               new Object[] { name, value }, null);
      }
   }

See how administrators can change custom collector plug-in attributes at runtime while Oracle Audit Vault and Database Firewall collects the audit trail.

As with Oracle Audit Vault and Database Firewall (Oracle AVDF) attributes, you can also change custom attributes at runtime.

If you want to change custom attributes, then you must implement the following methods to validate the custom attributes before you can use custom attributes in the setAttribute method.

private static final String[] s_attributes = new String[] { "av.collector.configureParameter1", "av.collector.configureParameter2" };
public String[] getAttributeNames() throws AuditEventCollectorException {
         return s_attributes.clone();
 }
 
public void setAttribute(String name, String value)
         throws SetAttributeException {
           if (name.equalsIgnoreCase("configureParameter1")) {
           // use value
           }else if (name.equalsIgnoreCase("configureParameter2"))
           {
           // use value
           }else {
         throw new SetAttributeException(ErrorCodes.INVALID_ATTRIBUTE_NAME,
               new Object[] { name, value }, null);
      }
   }

See an example of how to create an extension field for Java-based collection plug-ins in Oracle Audit Vault and Database Firewall.

The extension field contains all the fields of the source event which are of interest to the user, but do not correspond to any of the core or large fields. The collector must form one string which contains the names and values of these extra fields. The format of this string is up to the collection plug-in. The Collection Framework never tries to parse this string. In this example of creating an extension field, it uses the following format, repeating as needed:

 <field_name>=<field_value>;

Note that this example extension file sends three fields:

  public String getExtension() throws AuditEventCollectorException {
      try {
         StringBuilder sb = new StringBuilder();
         sb.append("DB_ID=" + m_resultSet.getString("DB_ID") + ";");
         sb.append("INSTANCE=" + m_resultSet.getString("INSTANCE") + ";");
         sb.append("PROCESS=" + m_resultSet.getString("PROCESS"));
         return sb.toString();
      } catch (SQLException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE, null, ex);
      }
   }

See an example of how Oracle Audit Vault and Database Firewall handles very large audit record fields.

Some audit record fields can be very large, so that returning them as a string is not feasible. Therefore, methods corresponding to those fields return an object of type Reader. If the source field is a character large object (aCLOB), then the Reader can be obtained by using clob.getCharacterStream().

You must design the collection plug-in to keep the connection to the source alive until all events using readers have been sent to the Audit Vault Server.

If the collector wants to reset the Connection to the source, it must do so immediately after setting the checkpoint. This is because the Collection Framework sends batches of records, and then sets the checkpoint. The time the ckeckpoint is sent is the only time that the collector knows that all records are flushed to Oracle Audit Vault Server. Note that there are other occasions that records are sent to the Oracle Audit Vault Server, but this is the only one with a checkpoint.

If the Reader instance cannot be obtained directly, then the collector must create and return a Reader.

   public Reader getCommandText() throws AuditEventCollectorException {
      try {
         Clob clob = m_resultSet.getClob("SQL_TEXT");
         return clob.getCharacterStream();
      } catch (SQLException ex) {
         throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE, null, ex);
      }
   }

See an example of how to create a marker, and review guidelines for how to create markers for Oracle Audit Vault and Database Firewall.

The collector must generate markers which the collection framework uses to uniquely identify a record.

The collector must generate a unique marker for each record in a particular trail. It can use more than one event field to create a marker. It can even use information not present in the audit event, such as, table name, file name, file creation time, and so on if it is not a template-based collection plug-in. Smaller sized markers are preferred because they take less time to create, less space in recovery phase, and less time to match. Markers are useful in certain scenarios, particularly in the recovery phase, where any records which were sent after the last checkpoint must be filtered. When the collection plug-in starts collecting events, it starts from the last checkpoint of the last run. However, some records might have been collected after that checkpoint and sent to the Audit Vault Server. To prevent duplication, the Collection Framework compares incoming records against existing records in the Audit Vault Server using the record markers.

In the following example, The strings Session_ID and Entry_ID are used to form a marker.

public String getMarker() throws AuditEventCollectorException {
      // ENTRY_ID will identify an audit event uniquely with in a session. Hence
      // ENTRY_ID along with SESSION_ID will uniquely identify an audit event
      // across sessions.
      try {
         return m_resultSet.getString("SESSION_ID") + ":"
               + m_resultSet.getString("ENTRY_ID");
      } catch (SQLException ex) {
           throw new AuditEventCollectorException(
               ErrorCodes.ERROR_GETTING_DATA_FROM_SOURCE, null, ex);
      }
   }

See how you can close a Java-based collection plug-in for Oracle Audit Vault and Database Firewall.

The process of closing a Java-based collection plug-in begins when the Collection Framework receives a command to stop collecting a particular audit trail, causing the Collection Framework to notify the collector using the close() method. In this method, the collector performs clean-up tasks, such as closing database connections or file handles. Once the close() method returns control to the Collection Framework, the collection thread ends.

This method should not result in any exceptions errors. In case of an exception, it should log an error message, as shown in the following example.

public void close() {
      try {
         if (m_resultSet != null) {
            m_resultSet.close();
            m_resultSet = null;
         }
         if (m_connectionManager != null) {
            m_connectionManager.destroy();
            m_connectionManager = null;
         }
         m_previousCheckpoint = null;
         m_nextCheckpoint = null;
         m_logger = null;
      } catch (SQLException ex) {
         m_logger.logError("SampleEventCollector", "close",
               "SQLException occurred. ", ex);
      } catch (AuditException ex) {
         m_logger.logError("SampleEventCollector", "close",
               "AuditException occurred. ", ex);
      }
   }  

An Oracle Audit Vault and Database Firewall collector can generate several different types of exceptions.

The collector can throw the following two checked exceptions: AuditEventCollectorException and SetAttributeException.

The setAttribute method can throw the SetAttributeException exception when the method cannot set a new attribute. Upon receiving this exception, it is possible that the Collection Framework does not stop the collector (see an example in "Changing Audit Vault and Database Firewall Attributes at Run Time").

The rest of the methods except the close method throw AuditEventCollectorException. This exception must be thrown only if an unrecoverable condition has occurred. Upon receiving this exception, the Collection Framework stops the collector. Before stopping the collector, the Collection Framework calls close method. See the previous sections for sample code to create and throw these exceptions.

All of the Oracle Audit Vault and Database Firewall components (collectors, agents, and server) that are written in Java must use the ConnectionManager API to manage their connections to databases.

You use the ConnectionManager API to manage connections to source databases, such as Oracle Database, Microsoft SQL Server, Sybase Adaptive Server, and IBM DB2.

See how to use the ConnectionManager API to manage Oracle Audit Vault and Database Firewall Java compnent connections to databases.

//Connection Manager
ConnectionManager cManager = null;
 
try {
  /*
   * Connection Pool Properties.
   * Set the pool properties such as URL
   * Initial pool size, Min pool size, etc.
   * The set of supported connection pool properties are
   * documented in the Oracle UCP documentation
   */
  Properties pProps = new Properties(); 
  pProps.put(URL, "jdbc:oracle:thin:@hostname:port:sid");
 
  /*
   *  Connection Properties
   *
   *  Set the connection properties here.
   *  The set of connection properties that can be set
   *  depends on the driver.  To enable SSL using the
   *  the oracle jdbc driver, you need to set the following
   *     Properties cProps = new Properties();
   *     String walletLoc =    "/path/to/walletdirectory/cwallet.sso";
   *     cProps.setProperty("oracle.net.authentication_services","(TCPS)");
   *     cProps.setProperty("javax.net.ssl.trustStore", walletLoc);
   *     cProps.setProperty("oracle.net.ssl_server_dn_match", "true")  ;
   *     cProps.setProperty("javax.net.ssl.trustStoreType","SSO");
   *     cProps.setProperty("javax.net.ssl.keyStore", walletLoc);
   *     cProps.setProperty("javax.net.ssl.keyStoreType","SSO");
   */
  Properties cProps = new Properties();
 
  cManager =  new ConnectionManagerImpl(pProps, cProps);
           
  String username;
  char[] passwd;
  Connection conn = null;
 
  /* Do something */
  ...
 
  /* Retrieve and set the username and password for user1 */
  username = "user1";
  passwd   = "user1passwd".toCharArray();
 
  /* Get a connection as "user1"*/
  conn = cManager.getConnection(username, passwd);      
 
 
  /* Use the "user1" connection and do something useful */
  ...         
 
  /* Release the connection */
  cManager.releaseConnection(conn);
          
  /* Retrieve and set the username and password for user2 */
  username = "user2";
  passwd   = "user2passwd".toCharArray();
 
  /* Get a connection as "user2" */
  conn = cManager.getConnection(username, passwd);      
 
 
  /* Use the "user2" connection and do something useful */
  ...         
 
  /* Release the connection */
  cManager.releaseConnection(conn);
 
} catch (Exception e) {
  /* Take appropriate action here */
 
} finally {
  if (cManager != null) {
    try {
      cManager.destroy();
    } catch (AuditException ae) {
      /* Take appropriate action here */
    }
} 

To parse Microsoft Windows event logs, you can use the Microsoft Windows EventLog API.

The Windows EventLog API is a wrapper on Windows APIs that access the Windows Event Log. This API is available only on the Windows platform, for collectors that need to extract audit records.

The following diagram shows the classes that you can use to parse the Windows event logs.

Figure 4-3 Structure of Windows Event Logs

Description of "Figure 4-3 Structure of Windows Event Logs"

The EventLogRecord class contains one record in the event log. The EventLogReader class helps to fetch event log records one by one. Operator classes help filter the event log records. An operator works on a particular field of event log record and determines whether the record is to be filtered based on the value of the field. For example, you can use the Equals operator to filter all event log records where the value of the field does not equal the value specified. The InRange and OutsideRange operators are ternary operators. The rest are binary operators.

To collect event log records, follow these steps:

1. Create the EventLogReader instance.

   For example, to open the application event log:

   EventLogReader eventLogReader = new EventLogReader();
   eventLogReader.openLog()
   

   To open other event logs such security or system event logs, use the overloaded method openLog(String log). For example, to open a security event log:

   EventLogReader eventLogReader = new EventLogReader();
   eventLogReader.openLog("Security");
   

   To open an application event log from a specific record number, use the openLog(int startRecNum) overloaded method. For example, to open an application event log from audit record number 1234:

   EventLogReader eventLogReader = new EventLogReader();
   eventLogReader.openLog(1234);
   

   To open security or system event logs from a specific record number, use the overloaded method, openLog(String log, int startRecNum). For example, to open a security event log from record number 4321:

   EventLogReader eventLogReader = new EventLogReader();
   eventLogReader.openLog("Security",4321);
   

2. Add the appropriate filters.

   For example, to bind an equals filter to the SourceName field, so that the EventLogReader only receives records that have the source name MSSQL$SQLEXPRESS:

   eventLogReader.addFilter(EventLogReader.SOURCE_NAME,
   Equals.getInstance(), "MSSQL$SQLEXPRESS");
   

   To get event records between Timestamp, m_lowerBoundTime, and m_upperBoundTime, use following filters:

   m_eventLogReader.addFilter(EventLogReader.TIME_GENERATED, GreaterThan.getInstance(), m_lowerBoundTime);
   
   m_eventLogReader.addFilter(EventLogReader.TIME_GENERATED, LessThan.getInstance(), m_upperBoundTime);
   

3. Fetch and process the EventLogRecord.

   The following example code obtains the next EventLogRecord, and extracts various fields from it.

   if(eventLogReader.hasNext()) {
                 EventLogRecord record = (EventLogRecord)eventLogReader.next();
                 Long eventID = record.getEventId(); 
                 String userID = record.getUserSid();
                 String hostName = record.getComputerName();
     ...
      }
   

4. Close the EventLogReader instance.

   When the collector is stopped, use the following code to close down the EventLogReader instance:

   eventLogReader.closeLog();

To obtain metadata of events, you can use this Microsoft Windows Metadata Java API procedure.

Microsoft Windows provides a new API that can obtain metadata of events from version 2008 and on. Given a publisher name, this API obtains metadata for each event. The following figure illustrates how the Windows Metadata Java is a wrapper over the Windows API.

Figure 4-4 EventMetaData_Classes

Description of "Figure 4-4 EventMetaData_Classes"

The EventMetaDataRecord contains the metadata of one event. The EventMetaDataReader helps to fetch event metadata records one by one. Use this API as follows:

1. Create an instance of EventMetaDataReader.

   EventMetaDataReader eventMetaDataReader = new EventMetaDataReader();
    

2. Obtain metadata of all events for a publisher.

   Map<Long, List<EventMetaDataRecord>> eventLogRecordMap = eventMetaDataReader 
      getEventMetaData("Microsoft-Windows-Security-Auditing");
   

3. Obtain the metadata list of a particular event from the map.

   List<EventMetaDataRecord> eventRecordList = m_eventRecordMap
      get(m_eventLogRecord.getEventId());
   

4. Obtain metadata from the list, and obtain event data names from it.

   EventMetaDataRecord eventMetaDataRecord = eventRecordList.get(i);
   for(int i=0; i<eventMetaDataRecord.getNumEventDataNames(); i++) {
      String eventDataName = eventMetaDataRecord.getEventDataName(i);
      ....
   }

To log errors, warnings, informational, and debug messages into the Oracle Audit Vault and Database Firewall logs, you can use the AVLogger API.

import oracle.av.platform.common.util.AVLogger;
import oracle.av.platform.common.exception.AuditException;
import oracle.av.platform.common.AuditErrorCodes;
 
public class Test
{
  public static void main(String[] args)  {
     /* Logger objects */
     AVLogger myModule = null;
     try {
       /* get Logger instances; this will auto-create the logger instance */
       /* if one does not exist */
       myModule = AVLogger.getLogger("someModule");
       /* print INFO level message */
       /* check log level if you are concatenating strings to avoid expensive */
       /* string operations */
       if(myModule.isInfoEnabled()) {
           avServer.logInfo("Testing INFO level message...." + "another String" +
             "one more string"); 
       }
       /* No need to check the log level if there is no string concatenation */
       myModule.logInfo("Testing INFO level message for another component....");
       /* changing the log level dynamically */
       myModule.setLogLevel(AVLogger.AV_LOG_LEVEL_DEBUG);
       myModule.logWarn("Testing WARN level message ....");
       myModule.logDebug("Testing DEBUG level message ....");
       /* Reset the log level back to INFO */
       myModule.setLogLevel(AVLogger.AV_LOG_LEVEL_INFO);
       /* Testing Exceptions: For now on, all exceptions will have */
       /* an OAV-XXXX error code printed out automatically as long as */
       /* they derive from AuditException object */
       throw new AuditException (ErrorCodes.INTERNAL_ERROR, null, null);
     } catch (Exception e) {
       myModule.logError(e);
     }
  }
}

If you are developing collections, then you can use the Oracle XML Developer's Kit to parse XML files and extract audit records from them.

The Oracle XML Developer's Kit is included. and available to use to develop collections.