Chat now with support
Chat with Support

InTrust 11.3.1 - 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.

Note: Renaming and editing the filter instance that you have added to a data source does not affect the predefined list of available filters. Your modified filter is stored with its respective data source.

To modify the parameters and matching conditions, click the Advanced button in the properties of the filter.

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.

FIELD

DESCRIPTION

RecordNumber

Number of the record in the event log, used for storing the position of the last gathered event.

TimeGenerated

Time when the event was generated.

TimeWritten

Time when the event was written to the log.

EventID

ID of the event in the InTrust gathering session.

EventType

Type of the event.

NumericCategory

Integer representation of the event category.

StringCategory

String representation of the event category.

Source

Name of the event source.

Computer

Computer on which the event occurred.

ComputerDomain

Domain of the computer on which the event occurred.

UserBinarySid

SID of the user who produced the event.

UserName

Name of the user who produced the event.

UserDomain

Domain of the user who produced the event.

Description

Description of the event.

EventData

Binary data of the event.

VersionMajor

Major operating system version number of the computer on which the event occurred. For example, the major version of Windows XP is 5.

VersionMinor

Minor operating system version number of the computer on which the event occurred. For example, the minor version of Windows XP is 1.

PlatformID

Platform (operating system) ID of the computer on which the event occurred.

AccountName

Name of the user who produced the event, in domain\user format.

TimeLocal

Time when the event was written to the log; this time is local to the computer where the event was logged.

_ID

Unique identifier of the event (a string that represents the object's GUID)

_LocalTime

Local time of event generation.

_GMT

GMT time of event generation.

_Priority

Event priority. This field is not used, and is always set to 2, meaning Normal.

_DataSourceName

Name of the log.

_ProviderName

Name of the InTrust data source.

_DataSourceId

GUID of the log.

_HostName

Name of the host where the event was generated.

Related Documents