Audit Collection Plug-in Directory Structure

Learn about the Oracle Audit Vault collection plug-in directory structure, the development environment, and how to stage plug-in manifest.xml files.

General Directory Structure

To create your own collection plug-ins, review the general directory structure for Oracle Audit Vault collections.

The following figure shows a general directory structure.

Example 1 General Directory Structure

STAGE_DIR_ROOT
plugin-manifest.xml
      templates
          mapper.xml
       jars
          mycoll.jar
          myjdbc-lib.jar
       config
          mycoll.properties
       bin
          mycoll.exe
       patches
          p3653288_GENERIC.zip

Explanation of General Directory Structure Components

In the example of a general directory structure, the STAGE_DIR_ROOT directory is the root directory where you stage your collection plug-in files. Place the plugin-manifest.xml directly in this directory. Under the STAGE_DIR_ROOT directory, create the following directories:

jars: Holds all the binaries generated through the Java build process.

Place your collector binaries for a Java-based plug-in in the jars directory. You should package the various collector Java classes into a jar file for easier access on the file system. For collection plug-ins, you do not need to package the Collector.jar in to this directory because it is part of the core agent and is automatically available for all collectors that are managed by an agent.
config: Holds any configuration files that the collection plug-in requires to function. These configuration files can be resource bundles, property files, and so on.
bin: Holds any native non-Java binary executables. For example, if your collector code invokes any native non-Java binaries, place them in the bin directory.

Because the agent is supported on multiple platforms, you should build the non-Java binaries on all platforms that the agent supports. In addition, the collector process locates and loads the appropriate binary based on the execution platform, so use a similar naming convention.
patches: Holds any OPatch patches for target-specified event attributes that the collector needs to function. If your collector adds new event attributes that are needed during run-time, then contact Oracle Support. Oracle Support will provide you with a patch that adds these events into the Audit Vault Server repository. This approval process is necessary to avoid collisions with other event attribute names across multiple plug-ins. After you have obtained these patches, place them in the patches directory. Then they will automatically be applied to the server during collection plug-in deployment.
templates: This directory contains the mapper file which has the field mapping from source field to Oracle DBSecCentral field.

Related Topics

Description of Plug-in Manifest File

Audit Collection Plug-In Directory Structure

Learn about the structure of a stage directory for a collection plug-in for Oracle Database Security Central.

For a collection plug-in, place all mapper files in the templates directory, as shown in this example. This placement directs the collection plug-in to load the relevant template file based on the information that the file contains.

Example 2 Directory Structure For Collection Plug-In

STAGE_DIR_ROOT
plugin-manifest.xml
       templates
          mycoll-template.xml
       config
          mycoll.properties
       patches
          p3653288_GENERIC.zip

Related Topics

Description of Plug-in Manifest File

Java-Based Collection Plug-in Directory Structure

The structure of Java-based Collection plug-ins for Oracle Database Security Central is very similar to the general directory structure.

The following example shows the structure of a stage directory for Java-based Collection plug-ins.

Example 3 Directory Structure for Java-Based Collection Plug-in

STAGE_DIR_ROOT
plugin-manifest.xml
       jars
          mycoll.jar
          myjdbc-lib.jar
       config
          mycoll.properties
       bin
          mycoll.exe
       patches
          p3653288_GENERIC.zip

Staging a plugin-manifest.xml File

You must stage the plugin-manifest.xml file directly under the STAGE_DIR_ROOT directory.

The plugin-manifest.xml file for Oracle Database Security Central is a core XML file that describes the collection plug-in, and defines its attributes. The location where you place the plugin-manifest.xml file depends on which operating system your server is running.

Locations for Staging a plugin-manifest.xml File

On UNIX systems: If your stage directory is /opt/final-plugin-stage/, then stage the plugin-manifest.xml file at /opt/final-plugin-stage/plugin-manifest.xml.
On Microsoft Windows systems: If your stage directory is c:\myplugin\final-stage-dir, then stage the plugin-manifest.xml file at c:\myplugin\final-stage-dir\plugin-manifest.xml.

See Also:

Description of Plug-in Manifest File for description and lists of attributes.
Example Code for a complete sample file.
Sample Schema for a plugin-manifest.xml file

About Mapper Files

Mapper files are XML files that mainly contain information about which target fields you must collect from the audit trail, and how these target fields map to Oracle Audit Vault Server fields.

Mapper files are specific to a target type, and contains target information, such as securedTargetType, securedTargetVersion, and so on.

Mapper files cover these details:

The supported target name and target version.
Mapping information from target fields to Audit Vault Server fields.
Target fields for constructing markers, which uniquely identify each audit record.
Audit table and datasource class names, where the audit trail type is database table.
Event time timestamp format, where the audit trail type is XML file.

Package the mapper files as part of the collection plug-in. Place mapper files in the templates folder during the plug-in packaging process.

Related Topics

Description of Plug-in Manifest File

The plugin-manifest.xml file is a core XML file that describes the collection plug-in.

The plugin-manifest.xml defines the following elements and attributes:

The plugin element represents the plug-in object with these attributes:
- Name: A descriptive name for the collection plug-in.
- version: The version should be updated along with each update to the collection plug-in, and should monotonically increase based on some ordering scheme. For instance, DBSecCentral uses a versioning scheme comprising of five digits, delimited by periods: majr.minr.minr.patch.hotfix.
- provider:The name of the provider. Typically, this name is the company or organization.
- copyright: Any copyright notices for the collection plug-in.
TargetVersion: Oracle Database Security Central Version with which the collection plug-in is compatible. The min attribute represents the minimum version of the target.
extensionSet: A set of extensionPoints.
ExtensionPoint: Each extensionPoint uniquely identifies the area of Oracle Database Security Central (Oracle DBSecCentral) that is being extended by the collection plug-in. Currently, Oracle DBSecCentral supports one Extension Point, securedTargetType, as indicated by the type attribute.
- fileList: A list of all the files that ship with the collection plug-in.
  - jars: A directory that contains Java files ending with the extension .jar, in the element file.
  - templates: A directory that contains the mapper files for a collection plug-in, in the element file.
  - bin: A directory that contains executable files, typically those that end with .exe, in the element file.
  - config: A directory that contains plug-in specific configuration files, in the element file.
  - shell: A directory that contains shell or batch command files, in the element file.
  - patch: A directory that contains event patches for the collection plug-in, in the element file.
  - unresolved-external: A directory that contains files that cannot be packaged with the collection plug-in for some reason, but are needed at run-time. Packaging succeeds but the plug-in deployment will fail until these files are made available in the $OH/av/dropins folder of Oracle Audit Vault Server. These files are in the element file.
- securedTargetTypeInfo: This is a mandatory field that indicates the source type that this collection plug-in supports. Specify the source type by filling in the name attribute of this element.
- trailInfo: A mandatory field that indicates the type of audit trails, on this source type, that the collection plug-in supports.
  - trailType: A mandatory field that indicates the type of trail described by this entry. Oracle Database Security Central 12.1.1 supports these trail types: TABLE, DIRECTORY, TRANSACTIONLOG, SYSLOG, and EVENTLOG.
    
    trailType can also be any arbitrary string. In that case, it is treated as a custom trail type.
  - trailLocation: Specifies the location of the trail; this is applicable only for TABLE and CUSTOM type trails only. This field must not be set for other trail types. If set for other types, then it is ignored.
  - className: Specifies the Java class that handles the task of retrieving the audit data from this trail. Use the following:
    
    -oracle.av.platform.agent.collfwk.ezcollector.table.DatabaseTableCollector for database table collection plug-ins.
    
    -oracle.av.platform.agent.collfwk.ezcollector.xml.XMLFileCollector for XML file collection plug-ins.
    
    oracle.av.platform.agent.collfwk.ezcollector.json.MultiJSONFileCollectorFactory for JSON file collection plug-ins which reads from JSON files having one fully formed JSON per line.
    
    oracle.av.platform.agent.collfwk.ezcollector.json.JSONFileCollectorFactory for JSON file collection plug-ins which reads from JSON files having only one fully formed JSON per file, and this single JSON contains an array of JSON records.
    
    To handle audit trails of different source versions of the same source type, you can optionally set the srcVersion attribute.
- eventPatch: This is an optional field containing any event patches that must be applied as part of the collection plug-in deployment. These patches are in the eventPatch element with the name attribute as the file name and an order attribute that indicates the order to apply the patches.
  
  Events attributes to be added are extended through patches generated by Oracle Database Security Central Development. Partner developers can request specific events and attributes or both, to be added to the Oracle Audit Vault Event dictionary. If the core development team determines that a request is justified, it may issue a patch. You can bundle these patches with the collection plug-in for application during plug-in deployment.

See Also: