InTrust 11.6 - Customization Kit

Generating Events

To generate an event for InTrust to process, a data source script should do the following:

1. Create one or more event structures using the CreateEvent() function.

2. Fill in the fields of the events based on data analysis results.

3. Pass the events on with the Submit() method.

The CreateEvent() function does not have any arguments. Use the function as follows:

var myEvent = CreateEvent();
//myEvent now stores the event structure

After making the event accessible through a variable, you can fill in the event fields with values. The fields can be either predefined or created "on the fly". By convention, the names of some predefined fields start with underscore characters (_). Such fields should not be edited.

The predefined event fields are listed in Event Fields.

The following is an ECMAScript example of field-processing operation:

myEvent["MyField"] = "myValue";
// Creates the MyField field
// and writes the value "myValue" to it
//
myEvent.MyField = "myValue";
// Does the same as the previous example

In Windows Script Host languages, the syntax for setting field values differs. Here is a JScript example:

myEvent.Values("MyField") = "myValue";
// Creates and fills in a custom field

Before you submit an event from a script in ECMAScript, make sure the TimeWritten and TimeGenerated fields are set.

Like CreateEvent(), the Submit() method does not take any arguments. Use it as in the following example:

myEvent.Submit();

The events that scripted data sources submit are passed on to real-time monitoring rules or cached.

Typical Custom Text Log Data Source Logic

Glossary

The audit script host provides access to scripting objects specific to InTrust auditing. The terms audit script host and GenericScriptProvider can be used interchangeably.

The audit script engine is the intermediary between the audit script host and the computer where the script is running.

The audit script object model is exposed by the script engine to the scripts.

The audit script position processor is the object that executes the position comparer script.

Typical Usage

The following logic is typically used in custom text log data sources:

1. The audit script host creates an audit script host instance initialized by a script.

2. The audit script host makes an Audit_EnumInstances call from the script, and uses a computer name as a parameter. The computer can be represented by a NetBIOS name, an IP address, and so on.
   The call returns a two-dimensional array, in which the "parent" array has only one element, and the nested array has two elements. The first of these two elements is the same computer name that was passed to Audit_EnumInstances. The second element is the display name of that computer, which is then passed to Audit_Connect. For Windows systems, this is the NetBIOS name; for UNIX systems it is the local name of the host. The display name is exposed in the session list of the InTrust Manager snap-in.

3. The audit script host makes an Audit_BeforeCollection call, which can perform all kinds of preparatory activity before gathering.

4. The audit script host makes an Audit_Connect call with an instance parameter. The instance parameter is the value previously returned by Audit_EnumInstances. The log parameter corresponds to the EventLog field in an InTrust data store.

5. The audit script host makes an Audit_Seek call, which expects a Position object. The script can use the Position object to gather audit trails in increments. The object stores information required by Audit_Seek to find the place in the audit trail where gathering stopped the last time. If the precise position is found, true is returned. Otherwise, the result is false. If false is returned, the details of the corresponding session state that the position could not be found.

6. The audit script host makes an Audit_CollectEvents call. This is the stage at which gathering takes place. During the gathering, the script must call the AuditProvider.SubmitEventPositionPair method. This method returns pairs each composed of an Event object and a corresponding Position object.
   For the custom text log data source to work properly, each Position object must contain an element with the following index in the values array:
   {3C2E0E29-790F-47bf-99B2-8F71DD23FA07}
   The element with this index must contain the code of the function that compares positions using Audit_ComparePositions. The audit script position processor uses this code for comparison. The text must be identical in both positions; otherwise comparison will produce an error.
   This is required so that the custom script can implement a comparison function and positions can be compared without the custom script.
   To see an example of how the {3C2E0E29-790F-47bf-99B2-8F71DD23FA07} index is used, open the properties "Custom Text Log data source template" script and click Edit. Locate the definition of the PosHelper function and note the way the index is handled.

7. Gathering finishes after Audit_CollectEvents completes.

8. The audit script host makes an Audit_AfterCollection call. If the success parameter is true, it means that events submitted by the script have been successfully stored. If success is false, this indicates that event storing has failed. For example, the script can use this parameter to clear a previously gathered log. However, you may lose some events in this case.

The script can use the following methods to output diagnostic information:

• AuditProvider.Trace to write to the AdcEventDataManager trace

• AuditProvider.LogMessage to write to session details

• AuditProvider.OperationStatus to write to session details

For details about the InTrust object model, see Object Library.

Customizing Data Source Filters

Filters on data sources are defined for gathering, consolidation and import policies; these filters can be customized using REL.

The filters are available for editing in the properties of a data source. You can open the properties of an existing data source directly in InTrust Manager. Alternatively, you can configure the filters as you create a new policy.

The following is an example of a simple filter:

<filter type="EventFilter" version="1.0">
  <arguments>
    <argument displayname="Computer List" name="Computer List" description="" class="List">
      <value />
    </argument>
  </arguments>
  <body>
    _DataSourceName="Security" and in(_HostName, "wi", array(<parameter name="Computer List">))
  </body>
</filter>

In this example, the filter accepts events only from a specific (case-insensitive, wildcard-enabled) list of computers.

For details about defining parameters, see Customizable Parameters. For a list of predefined event fields that you can filter by, see Event Fields.

Event Fields

The following table lists predefined fields in event records. When you create an event, do not modify any of the bolded fields.