Database Table Collection Plug-ins

To use Oracle Audit Vault to collect audit data from the table type of trail, you can use database table collection plug-ins

Database table collection plug-ins support the collection of audit data from the table type of trail. They collect audit data from a single audit table. You can specify details of the audit table in the mapper file. These mapper files must conform to the schema.

Related Topics

Database Table Collection Plug-in Mapper File

Requirements for Database Table Collection Plug-ins

To use database table collection plug-ins for reading audit trails from target database tables, your data must meet Oracle Database Security Central requirements.

You can use database table collection plug-ins for reading audit trails from target database tables if your data meets the requirements for collection.

Data Requirements for Table Collection Plug-Ins toOracle Database Security Central

Audit data must be stored in a single database table.
The target system has a user with privileges to read the audit data stored in this table.
The columns in the audit tables can be mapped to various Audit Vault core fields and large fields.

Also single or multiple fields can be mapped to extension and marker fields. Fields mapped to Audit Vault core fields, extension fields, and marker fields must be of String data type or convertible to String. They cannot be of large data type, such as a CLOB. Columns having CLOB data type should use large Audit Vault fields, such as CommandText or CommandParam.
The audit trail must contain fields which map to the CommandClass Audit Vault core fields.

The value of the CommandClass core field must not be null. If it is null, then the record is treated as an invalid record, so you must provide the proper mapping.
The audit file must have a field that can be mapped to the UserName core field. If a record has its UserName field as null, then the record is treated as invalid.
The collection plug-in can collect the text of any command issued, as well as any parameters passed to the command, in large fields. No other fields can be mapped to large fields in Database Security Central.
The audit trail must contain a single column or group of columns that uniquely identify each audit record.
The audit trail must contain a field of type Timestamp that is monotonically increasing, that is, the value of the field increases with every new audit record inserted into the trail. This field must mapped to the EventTimeUTC core field in the mapper file. If, for any audit record, this field value becomes null, the collector treats this as an abnormal condition and shuts down.

Related Topics

Schemas

Example Audit Trail for a Database Table Collection Plug-in

This example audit trail shows the details of audit trail. This example file is used in other locations to demonstrate the creation and structure of a sample mapper file for Oracle Database Security Central.

The following table lists the structure for the hypothetical target type, DBSOURCE, that generates and stores audit data in a table AUD:

Table 1 AUD Audit Table Data Fields and Mappings

Target Field	Data Type	Audit Vault Server Field	Map to Field Type
`USER_ID`	`varchar`	`UserName`	core field
`OS_USER_ID`	`varchar`	`OSUserName`	core field
`ACTION`	`int`	`CommandClass`	core field
`STATUS`	`int`	`EventStatus`	core field
`EVENT_TIME`	`timestamp`	`EventTimeUTC`	core field
`OBJ_NAME`	`varchar`	`TargetObject`	core field
`OBJ_CREATOR`	`varchar`	`TargetOwner`	core field
`USER_HOST`	`varchar`	`ClientHostName`	core field
`SQL_TEXT`	`clob`	`CommandText`	core field
`SQL_BIND`	`clob`	`CommandParam`	core field
`TERMINAL`	`varchar`	`TerminalName`	extension field
`DB_ID`	`varchar`	extension field	extension field
`INSTANCE`	`varchar`	extension field	extension field
`PROCESS`	`int`	extension field	extension field
`SESSION_ID`	`int`	marker field	marker field
`ENTRY_ID`	`int`	marker field	marker field

Not all of the target fields map to core fields. The target fields that do not map to core fields map to extension fields, or to designated marker fields, which test the uniqueness of an audit record.

Creating a Database Table Mapper File

Learn how to create an Oracle Audit Vault XML mapper file for a database table collection plug-in, and learn about each XML element and attribute used in this type of mapper file.

See Also:

Database Table Collection Plug-in Mapper File for the complete example.
Example Audit Trail for a Database Table Collection Plug-in
Oracle Database Security Central Fields for descriptions of all fields.
Target Collection Attributes to make sure that the mandatory collection attributes are set up for the target.

Example of Creating a Mapper File for Database Table Collection Plug-ins

Top Level Element
```
<AVTableCollectorTemplate securedTargetType="DBSOURCE" minSecuredTargetVersion="10.2.0"
           maxSecuredTargetVersion="11.0" version="1.0" >
```
The AVTableCollectorTemplate is the top level element, which marks the start of the mapper file. It has these mandatory attributes: securedTargetType, maxSecuredTargetVersion, and version. The minSecuredTargetVersion attribute is optional.

The accepted format for the minSecuredTargetVersion, maxSecuredTargetVersion, and version attributes uses numbers, separated by dots, such as 12.2, 10.3.2, 11.2.3.0.
Table Name Information
```
<TableName>AUD</TableName>
```
You must provide the TableName of the audit table. This is a mandatory field.

The TableName field in this file must match the trail location in the Add Audit Trail screen.
Note:

The collector checks if the trail location matches the TableName specified in the mapper file and does not start if they do not match.

The collector chooses the appropriate mapper file in the templates folder by validating the target collection attribute av.collector.securedtargetversion version and if it is within the range specified in the top level element minSecuredTargetVersion and maxSecuredTargetVersion attributes.

For example, if the target collection attribute av.collector.securedtargetversion = 11.1.0.0, then the collector picks a mapper file that has a top level element in a range within the specified version:
```
<AVTableCollectorTemplate securedTargetType="Oracle Database" minSecuredTargetVersion="10.2.0" maxSecuredTargetVersion="12.3" version="1.0">
```
This enables multiple versions of the same plug in (different mapper files inside the templates folder) to address different target versions.
Target Connection Information
```
<ConnectionInfo>
   <DataSource>platform.jdbc.dbsource.DBSourceDataSource</DataSource>
</ConnectionInfo>
```
You must provide the full name for the datasource class implementing javax.sql.DataSource interface. This is a mandatory field.
Field Mapping Information
```
<FieldMappingInfo>
```
FieldMappingInfo must provide mapping information from target fields to various Audit Vault fields, along with the value transformations if any. This is a mandatory element.

Field mappings include <Map> elements, which contain <Name> elements that hold target field names, and <MapTo> elements that hold Audit Value field names to which targets are mapped.

There should be no many-to-one mappings from target fields to Audit Vault Server fields. For example, the following is invalid:
```
<Map>
    <Name>USER_ID</Name>
    <MapTo>UserName</MapTo>
</Map>
<Map>
    <Name>OS_USER_ID</Name>
    <MapTo>UserName</MapTo>
</Map>
```

About Mappings for Core, Large, Extension, and Marker Fields

The following sections explain mappings for core, large, extension, and marker fields:
- Core Fields
```
<CoreFields>
```
  CoreFields provides mapping from target fields to core fields of Audit Vault Server. The data type of target fields specified must belong to either a SQL string data type or a data type that can convert to a String.
  
  The following elements contain core fields.
```
<Map>
  <Name>EVENT_TIME</Name>
  <MapTo>EventTimeUTC</MapTo>
</Map>
```
  EventTimeUTC provides event time mapping information. It is a mandatory field.
  
  EVENT_TIME target fields must be of the SQL data type Timestamp.
```
<Map>
  <Name>USER_ID</Name>
  <MapTo>UserName</MapTo>
</Map>
```
  UserName represents the user who performs the action. If the mapping is not provided, Audit Data Collection still starts successfully, but every audit record will be treated as invalid.
```
<Map>
  <Name>OS_USER_ID</Name>
  <MapTo>OSUserName</MapTo>
</Map>
```
```
<Map>
  <Name>ACTION</Name>
  <MapTo>CommandClass</MapTo>
</Map>
```
  CommandClass represents the action of the event. If the mapping is not provided, Audit Data Collection still starts successfully, but all audit records are treated as invalid.
```
<Transformation>
          <ValueTransformation from="1" to="CREATE"/>
          <ValueTransformation from="2" to="INSERT"/>
          <ValueTransformation from="3" to="SELECT"/>
          <ValueTransformation from="4" to="CREATE"/>
          <ValueTransformation from="15" to="READ"/>
          <ValueTransformation from="30" to="LOGON"/>
          <ValueTransformation from="34" to="LOGOFF"/>
          <ValueTransformation from="35" to="ACQUIRE"/>
        </Transformation>
      </Map>
```
  CommandClass contains a Transformation field with ValueTransformation values, from targets to the Audit Vault CommandClass field. These transformations are mandatory.
  
  The to attributes are values for the CommandClass field. If you can meaningfully map an event to one of these values, then Oracle recommends that you do so. If this is not possible, then use a value that appropriately reflects the action that generated the audit event.
```
<Map>
  <Name> OBJ_NAME</Name>
  <MapTo>TargetObject</MapTo>
</Map>

<Map>
   <Name>TERMINAL</Name>
   <MapTo>TerminalName</MapTo>
</Map>
```
```
<Map>
  <Name>USER_HOST</Name>
  <MapTo>ClientHostName</MapTo>
</Map>
```
```
<Map>
  <Name>OBJ_CREATOR</Name>
  <MapTo>TargetOwner</MapTo>
 </Map>
```
```
<Map>
  <Name>STATUS</Name>
  <MapTo>EventStatus</MapTo>
        <Transformation>
          <ValueTransformation from="0" to="FAILURE"/>
          <ValueTransformation from="1" to="SUCCESS"/>
          <ValueTransformation from="2" to="UNKNOWN"/>
        </Transformation>
 </Map>
```
  EventStatus contains a Transformation field with ValueTransformation values, from targets to Audit Vault EventStatus fields. These transformations are mandatory.
```
</CoreFields>
```
- Large Fields Information
```
<LargeFields>
  <Map>
    <Name>SQL_TEXT</Name>
    <MapTo>CommandText</MapTo>
 </Map>
<Map>
   <Name>COMMAND_PARAMETER</Name>
   <MapTo>CommandParam</MapTo>
 </Map>
</LargeFields>
```
  LargeFields are target fields mapped to large fields in the Audit Vault Server, such as CommandText or CommandParam. The specified target fields must be of SQL data type CLOB or String, or be convertible to String.
- Extension Field
```
<ExtensionField>
   <Name>DB_ID</Name>
   <Name>INSTANCE</Name>
   <Name>PROCESS</Name>
</ExtensionField>
```
  The ExtensionField is a target field name that must be stored as a name-value pair in the Extension field in Audit Vault Server. Target columns specified here should have a String value or a value that can be converted to String without loss of information.
  
  ComplexName
```
<ExtensionField>
    <ComplexName>
        <Name>column_name</Name>
        <RegExp>exp</RegExp>
    </ComplexName>
</ExtensionField>
```
  ComplexName is a tag in the ExtensionField.
  
  The column_name is an audit table column name which is a string. For example: comment$text
  
  exp is the regular expression from which we get a list of key value pairs from the text after processing. It should contain 2 groups, out of which one is for key and the other one for value. For example: ([^;]+):([^;]+)
- Marker Field
```
<MarkerField>
  <Name>SESSION_ID</Name>
  <Name>ENTRY_ID</Name>
</MarkerField>
```
  The MarkerField contains a list of target field names that uniquely identify each audit record. The target fields specified must be of SQL data type String or convertible to String. MarkerField is mandatory.
- End Tags
  
  The field tags must be properly closed in order for the file to be valid. The following are examples of field end tags:
```
</FieldMappingInfo>

</AVTableCollectorTemplate>
```

See Also: