1. Developer's Guide
  2. Setting Up Your Development Environment

2 Setting Up Your Development Environment

Learn about the process of setting up the Oracle Audit Vault Server development environment.

2.1 Before Setting Up the Development Environment

To develop audit collection plug-ins, you must first set up the development environment. This set up provides a consistent environment for developing and testing the collection plug-ins.

Before you set up a developer environment, you must complete the following tasks:

  • Obtain and install Oracle AVDF 20: You must have this version so that you can test the collection plug-in execution and determine whether it captures the correct audit records from the target, and makes them available in the server. Also, doing early end-to-end integration tests helps to eliminate any connectivity problems, and other bugs in your code.

  • Decide the type of collection plug-in to use.

Related Topics

See Also:

Oracle Audit Vault and Database Firewall Installation Guide for more information on installation of Oracle Audit Vault and Database Firewall.

2.2 Setting Up the Development Environment

To set up your development environment, you must first download the Oracle Audit Vault and Database Firewall SDK, and then set up the operating system environment.

To set up your environment for developing collection plug-ins you must follow these steps to download the SDK, and then configure the operating system folders, environment variables, and paths.

To download the SDK, do the following:

  1. Log in to the Audit Vault Server console as an administrator.

  2. Click the Settings tab.

  3. Click the System tab in the left navigation menu.

  4. Click the Plug-ins link under the Monitoring section on the main page.

  5. In the Plug-ins dialog, click Download SDK.

  6. Unzip the SDK into an empty directory.

  1. Set the AV_SDK_HOME variable to the directory to which you extracted the SDK.

    For example:

    $ export AV_SDK_HOME=/home/username/avsdk

  2. Set the PATH environment variable to bin directory of the Audit Vault Server.

    For example:

    $ export PATH=$AV_SDK_HOME/bin:$PATH

    This setting enables you to use existing scripts during the development cycle.

  3. Set the CLASSPATH environment variable to include the $AV_AGENT_HOME/av/jlib/agentre.jar for your collection plug-in project.

    For example:

    $ export CLASSPATH=$AV_SDK_HOME/av/jlib/av.jar:$AV_SDK_HOME/av/jlib/av-common.jar:$AV_AGENT_HOME/av/jlib/agentre.jar

  4. Create directories as necessary.
  5. If you are using Java, ensure that the environment is set to point to the appropriate JDK (PATH and JAVA_HOME variables).

    Compile your classes with JDK by setting the -target option of the javac compiler to the same version. Refer to the JDK documentation for details.

Related Topics

2.3 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.

2.3.1 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 2-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 AVDF field.

Related Topics

2.3.2 Audit Collection Plug-In Directory Structure

Learn about the structure of a stage directory for a collection plug-in for Oracle Audit Vault and Database Firewall.

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-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

2.3.3 Java-Based Collection Plug-in Directory Structure

The structure of Java-based Collection plug-ins for Oracle Audit Vault and Database Firewall 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 2-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

2.3.4 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 Audit Vault and Database Firewall 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:

2.3.5 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

2.3.6 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, AVDF 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 Audit Vault and Database Firewall 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 Audit Vault and Database Firewall (Oracle AVDF) that is being extended by the collection plug-in. Currently, Oracle AVDF 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 Audit Vault and Database Firewall 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 Audit Vault and Database Firewall 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: