InTrust 11.6 - Customization Kit

InTrust Customization Overview

By using scripts and Quest InTrust as the framework to execute them, you can enhance the InTrust toolset. Scripting extends the following areas of InTrust functionality:

• Creation of real-time monitoring rules
• Creation of scripted data sources (primarily for real-time monitoring)
• Fine-tuning data sources for custom event logs in text format (for auditing purposes)
• Editing filters for gathering, consolidation and import policies
• Configuring custom response actions for rules
• Enumeration of sites

InTrust Script Objects

InTrust script objects provide logic and automation facilities accessible from different parts of InTrust: response actions in real-time monitoring rules, advanced site enumeration algorithms, and so on. In InTrust Manager, script objects are located in Configuration | Advanced | Scripts, and contain the following:

• Parameters used in the body of the script but defined outside it

• Actual script code

Parameters

Parameters are variables that the script exposes to its callers. For example, if a script is a response action designed to disable a user account, it must get the user name as a parameter.

Parameters are specified in the properties dialog box of the script object. The parameter list must include all parameters that the script expects to get from the rule. Use the Add, Remove and Edit buttons to work with the parameter list. For details about supported parameter types, see Customizable Parameters.

Script Body

To supply or edit the script code, open the properties of the script object you need and click the Edit button with the "Edit the script" label next to it. Use the scripting language selected from the Language list box.

Using Parameters in Script Code

Scripts retrieve this parameter differently, depending on the scripting language used.

ECMAScript

Access the keys of the Parameters object, which is defined automatically. Use parameter names (such as CurrentComputer) as the keys.

Example:

var strComputerName = Parameters["CurrentComputer"];

As long as the CurrentComputer parameter is included in the parameter list of the script object, the value is returned.

JScript and VBScript

Call the Parameters method of the ScriptContext object and pass the parameter name (such as CurrentComputer) as the argument.

Example (JScript):

ScriptContext.Parameters("CurrentComputer")

As long as the CurrentComputer parameter is included in the parameter list of the script object, this is a valid call.

PowerShell

You cannot use the raw parameter ID (such as CurrentComputer) due to PowerShell syntax peculiarities. The parameter variable name must start with a dollar sign just like any PowerShell variable (in this case, $CurrentComputer).

To initialize parameters, use the param statement at the start of the script. For example, if the parameters User and Domain are defined for your PowerShell script, then begin it as follows:

param(
    $User,
    $Domain
)

Customizable Parameters

Script parameters can be exposed by several types of InTrust objects: rules, script objects, and data source filters. This topic describes the supported data types for parameters.

AccessType

Lets you specify access types used by events in Windows logs. In the user interface, this type is represented by a check box list in a dedicated selector dialog box.

Example: "*%%1023*", "*%%1111*", "*%%2222*"

Here, numbers correspond to access type IDs.

Getting the Access Type Selector

InTrust provides an access type selector dialog box so that you don't have to search for references and look up the types you need. To make it available, start by editing the XML rule definition by clicking Advanced on the Matching tab in the rule properties. Insert an empty parameter of the AccessType class, as in the following example:

<argument displayname="Access Types" name="Access_Types" class="AccessType" description="Access types to include">

    <value></value>

</argument>

Save the XML definition. Back on the Matching tab, select your new AccessType parameter and click Edit. The Edit Access Type dialog box is displayed with a list of acceptable values that you can select.

Text

Example: Some text.

Number

Example: 512.

List

Comma-separated list. Example: "dog", "cat", "bird". Commas and quotation marks cannot be used inside list elements.

DateTimeRange

This type has the following format:

"yyyy/mm/dd hh:mm:ss"

The number of digits in a field is not fixed. You do not have to insert leading zeros. You can omit either the date part (yyyy/mm/dd) or the time part (hh:mm:ss) but not both at once. If you omit the date, do not leave a leading white space.

The mm (month), dd (day), mm (minute) and ss (second) fields can be omitted. In this case, they are assumed to be 0.

Example:

"0/0 1:0" is the same as "0/0 1" or "1", meaning one hour.

If you omit the entire date, the minutes and the seconds, the specified number is assumed to be a date. For example, if only the number 1 is specified, it is treated as a year, although you might expect it to mean an hour.

To determine which part is omitted, look at the separator characters (/ or :).

ExpectedTime

Time at which an event is expected in a "missing event" rule. Specified in the cron format, meaning five numbers separated by spaces or tabs. The order is as follows:

• minute (0-59),

• hour (0-23),

• day of the month (1-31),

• month of the year (1-12),

• day of the week (0-6 with 0=Sunday).

Example: "0 1 * * 4,6", "1:00". Here, the event is expected every Wednesday and Saturday at 1 AM.

RangeList

This type has the following format:

"min_1-max_1,min_2-max_2,...,min_N-max_N"

Here, min_x is the minimum value in a range; max_x is the maximum value. The maximum value and its leading hyphen are optional. Both the minimum and the maximum are non-negative integers.

EventType

This type is a list of values enclosed in quotation marks for the EventType field in Windows logs. The selection dialog box for this parameter is shown in the screenshot:

This selection corresponds to the value "0,2,8".

In the XML markup for REL-based rules, this type can be used as in the following example:

in_range(EventType, <parameter name="MyEventTypes"/>)

Filter

This type of argument is a container for an expression, which can optionally have its own arguments.

The referenced arguments are enclosed in the <filter> tag pair, as follows:

<argument name="My Event Filter" class="Filter">
  <value>
    <filter type="EventFilter" version="1.0">
      <arguments>
        ...
      </arguments>
    </filter>
  </value>
</argument>

For a usage example, create a rule for a Windows event log or Syslog based on the "Single event" template and using one of the predefined filters. View the resulting markup.

Choice

This type lets you select one or more values from a list. Use the "List" type to represent the choice in the user interface, as follows: type = "List".

Usage example:

<argument usedefault="true" name="sample_arg" class="Choice" type="List">
  <choices>
    "arg_value1", "arg_value2", "arg_value3", "arg_value4"
  </choices>
  <value>
    "arg_value2"
  </value>
  <default description="descr">
    "arg_value1", "arg_value2"
  </default>
</argument>

The <choices> tag pair stores the list of possible values that you can select from.

<filter type="EventFilter" version="1.0">
 <arguments>
    <argument usedefault="false" name="sample_arg" description="" class="guid">
      <value>
        ...
      </value>
      <default description="descr">
        Sample description
      </default>
    </argument>
  </arguments>
  <body>
    ...
    <parameter name="sample_arg"/>
    ...
  </body>
</filter>

Password

This type lets you securely specify a password for an authentication operation. Do not specify the password directly in the XML code. The implementation of this parameter type permits password editing only in a graphical prompt.

<argument displayname="password" name="password" description="Password" class="Password">
  <value/>
</argument>

InTrust Server Tracing

InTrust Server provides tracing capabilities in most of its components. Tracing is enabled and disabled for particular components in the adctracer.ini file.

For InTrust Server, the location of this file is Server\ADC\adctracer.ini in the folder where InTrust Server is installed. For InTrust agents, the location is ADCAgent\adctracer.ini on the processed computer.

The first line of the file specifies the location of the traces. The default locations are as follows:

• InTrust Server traces are written to Server\ADC\tracing in the folder where InTrust Server is installed.

• InTrust agent traces are written to ADCAgent\tracing on the processed computer.

Configuration File Format

The entries in the adctracer.ini file use the following format:

ComponentName=Number

Here, ComponentName is the name of the InTrust component for which you want to see traces; Number is the tracing level. Example:

MSNNSiteProvider=40
RELMatcher=40

By default, all entries are commented out with the number sign (#). Uncomment those entries for which you need traces.

The adctracer.ini file sets the default tracing level for each component. For the trace to be recorded, the tracing level in the trace-writing function must be less than the value specified in adctracer.ini. For example, if you specify level 50 in a tracing function in your site enumeration script, and the MSNNSiteProvider entry is set to the default value of 40, your trace will not be recorded.