JSON File Collection Plug-ins

Learn how to use Oracle DBSecCentral JSON file collection plug-ins to collect audit data from a JSON file type of trail.

JSON file collection plug-ins support collection of audit data from an JSON file type of trail. All these JSON audit files must be present in single directory. You can specify details of the JSON audit data in the mapper file.

Related Topics

Schema For JSON File Collection Plug-in Mapper File

Requirements for JSON File Collection Plug-ins

To use JSON collection plug-ins for reading audit trails from JSON files, your data must meet Oracle Database Security Central requirements.

You can use collection plug-ins for reading audit trails from JSON audit record files if the JSON files meet the requirements for collection.

JSON File Audit Record File Requirements for Oracle Database Security Central

The audit trail must be stored in one or more JSON files in a single directory path.
The user must have read permission on the directory containing the JSON audit files.
JSON files in this directory must be valid, well-formed JSON documents, within the constraints of the JSON specification.
The file and record start elements must be as specified in the mapper file.
The JSON audit file must have a field whose JSONPath can be mapped to the CommandClass core field. If a record has its CommandClass field as null, then the record is treated as invalid.
In the JSON file, each audit record must have a timestamp as one of its element values.

The value of the timestamp element must be monotonically increasing, that is, the value of the field increases with every new audit record inserted into the trail. The timestamp value should be strictly Not Null. Timestamp format must be according to SimpleDateFormat Java class.

This field must mapped to the EventTimeUTC core field in the mapper file. If mapping for event time is not specified in the mapper file, then the collection plug-in shuts down. If the field value for the event time in audit records is found null, then the collection plug-in takes the time of the record last sent from the same JSON audit file.
The audit trail must contain a single element value or group of element values in the audit record that uniquely identify each audit record in JSON Audit files.
If an audit data target produces audit files with multiple JSON formats, then the user must provide a separate mapper file for each audit file format having a different start element.
JSON files in this directory should be of the same locale and encoding as the agent, as described in the examples below:
- Valid: The user has an agent in a Chinese locale (env). JSON files are also generated in a Chinese locale with same encoding (for example, ZHS16GBK). This setup is valid.
- Invalid: The user has an agent in a German locale (env). JSON files are generated/moved from some other computer, which are Chinese encoded. The collectors fail to start because of an encoding mismatch, as well as a locale mismatch, in this case. This setup is invalid.

Example Audit Trail for a JSON File Collection Plug-in

This example audit trail for a JSON file collection plug-in shows the details of a JSON file collection plug-in.

This example file is used in other locations to demonstrate the creation and structure of a sample mapper file for the creation and structure of a sample mapper file for a JSON file collection plug-in, in the Oracle Database Security Central documentation.

The following table lists the audit record structure and mappings to Oracle Audit Vault Server fields for the hypothetical target type, JSONSOURCE, which generates and stores audit data in JSON audit files.

Table 3 Audit Data Fields in JSON Audit Records and Mappings

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

Example 5 Sample JSON Audit Record

{
   "ITEMS":[
      {
         "SESSION_ID":123,
         "AUDIT_TYPE":1,
         "USER_ID":"scott",
         "OS_USER_ID":"usr1",
         "ACTION":"select",
         "STATUS":0,
         "EVENT_TIME":"2020-11-28 12:23:59.166",
         "OBJ_NAME":"emp",
         "OBJ_CREATOR":"scott",
         "TERMINAL":"t1",
         "DB_ID":136,
         "ENTRY_ID":1
      },
      {
         "SESSION_ID":123,
         "AUDIT_TYPE":1,
         "USER_ID":"scott",
         "OS_USER_ID":"usr1",
         "ACTION":"delete",
         "STATUS":0,
         "EVENT_TIME":"2020-11-28 12:24:22.177",
         "OBJ_NAME":"emp",
         "OBJ_CREATOR":"scott",
         "TERMINAL":"t1",
         "DB_ID":136,
         "ENTRY_ID":2
      }
   ]
}

Creating the JSON File Audit Collection Mapper File

To create a JSON file collection plug-in mapper file, you must describe the collection plug-in mappings in this mapper file in accordance with Oracle Database Security Central standards.

You must describe the collection plug-in mappings in this mapper file as follows:

Standards for Collection Plug-in Mappings in Mapper Files for Oracle Database Security Central

Top-Level Element
```
<AVJSONCollectorTemplate securedTargetType="JSONSOURCE"
      maxSecuredTargetVersion="11.0"
      version="1.0">
```
The AVJSONCollectorTemplate is the top level element and 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.
Header Information
```
<HeaderInfo>
  <StartTag>ITEMS</StartTag>
</HeaderInfo>
```
HeaderInfo is mandatory. It contains one child element, StartTag, which names the top-level element of the audit record file.
Record Information
```
<RecordInfo>
  <StartTag>SESSION_ID</StartTag>
</RecordInfo>
```
RecordInfo provides the starting element of audit records in JSON audit files. RecordInfo is mandatory.

StartTag is the starting element of each audit record in JSON audit files. If the JSON file has one fully formed JSON record per line, then the HeaderInfo and RecordInfo also have the same start tag, which is the first element of the JSON record.
Field Mapping Information
```
<FieldMappingInfo>
```
FieldMappingInfo provides mapping information from target fields to various Audit Vault fields, contained in these child elements, CoreFields, LargeFields, ExtensionField, and MarkerField.

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

There should be no many-to-one mappings from target fields to Audit Vault Server fields. For example, the following is invalid:
```

```
- Core Fields
```
<CoreFields>
```
  CoreFields provides mapping from target fields to core fields of Audit Vault Server. Target fields specified in core field mappings must be of SQL data type, either a string or a data type that can convert to string.
  
  The following elements contain core fields.
```
<Map>
 <Name>$.EVENT_TIME</Name>
  <MapTo>EventTimeUTC</MapTo>
  <TimestampPattern>yyyy-MM-dd HH:mm:ss.SSS</TimestampPattern>
</Map>
```
  EventTimeUTC provides event time mapping information. The value in TimestampPattern specifies the timestamp format for event time. EventTimeUTC and TimestampPattern are mandatory.
  
  When specifying the TimestampPattern, use the supported patterns and characters of the Java SimpleDateFormat class, NOT Oracle Database specific patterns.
  
  For multibyte characters such as Chinese, specific words such as Month should be added into the pattern as characters in SimpleDateFormat. The AM and PM indicators are obtained based on locale, but should be explicitly mentioned in the TimestampPattern that you provide in the mapper file.
```
<Map>
  <Name>$.USER_ID</Name>
  <MapTo>UserName</MapTo>
</Map>
```
  UserName represents the user who performed the action. If the mapping is not provided, Audit Data Collection still starts successfully, but every audit record is 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>
```
  CommandClass contains a Transformation field with ValueTransformation values, from targets to the Audit Vault Server 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, Oracle recommends that you do so. If this is not possible, use a value that appropriately reflects the action that generated the audit event.
```
<Map>
  <Name>$.OBJ_NAME</Name>
  <MapTo>TargetObject</MapTo>
</Map>
<Map>
  <Name>$.USER_HOST</Name>
  <MapTo>ClientHostName</MapTo>
</Map>

<Map>
   <Name>$.TERMINAL</Name>
   <MapTo>TerminalName</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. The specified target fields must be of SQL data type CLOB or String, or be convertible to String.
- Extension Fields
```
<ExtensionField>
   <Name>$.DB_ID</Name>
   <Name>$.INSTANCE</Name>
   <Name>$.PROCESS</Name>
</ExtensionField>
```
  ExtensionFields are target field names that must be stored as a name-value pair in the Extension field in Audit Vault Server. Target fields specified must be of SQL data type CLOB or String, or be convertible to String.
- Marker Fields
```
<MarkerField>
  <Name>$.SESSION_ID</Name>
  <Name>$.ENTRY_ID</Name>
</MarkerField>
```
  MarkerField contains a list of target fields that uniquely identify each audit record. The target fields specified must be of SQL data type CLOB or String, or be convertible to String. MarkerField is mandatory.

See Also: