Guaranteed State Triggers
Triggers
As well as the SCALE - which determines what is executed when the rule is processed - a rule has one or more associated triggers which determines when the rule is processed.
The Tachyon Agent supports the following triggers:
AgentStartup — Triggers when Tachyon Agent starts.
DirectoryChange — Triggers when the specified directory is modified (including created or deleted). If the corresponding directory does not exist at the point that the trigger is initialized, the trigger will poll periodically (approx. every minute) for this directory to be created.
FileChange — Triggers when a nominated file is modified (including created or deleted). If the corresponding file does not exist at the point that the trigger is initialized, the trigger will poll periodically (approx. every minute) for this file to be created.
Interval — Triggers periodically at the specified frequency (IntervalSeconds, IntervalMinutes or IntervalHours), allowing a rule to be evaluated at the given interval.
ServiceStatusChange — Triggers when the state of e specified Windows service changes - when it is stopped, started, paused, resumed, installed or uninstalled.
WindowsEventLog — Triggers when a log entry is created in a specific Event Log, optionally matching an XPath filtering expression. This can include the "Classic" Windows Event Logs (Application, Security, Setup and System) and also the "Applications and Services Logs" (although does not include the "Analytic and Debug" logs).
WindowsRegistryChange — Triggers when a log entry is created in a specific Event Log, optionally matching an XPath filtering expression. This can include the "Classic" Windows Event Logs (Application, Security, Setup and System) and also the "Applications and Services Logs" (although does not include the "Analytic and Debug" logs).
Triggers are parameterized - for example, the "FileChange" trigger has a parameter named "FileName" which determines which file is to be monitored.
If a rule is associated with multiple triggers, that rule will be evaluated whenever ANY of the corresponding triggers fire. For example, a rule might have both an Interval trigger and a FileChange trigger, which might test the contents of a file when it is changed, and also periodically.
Additionally, a rule is evaluated automatically - irrespective of the associated triggers - when it is first received by the Tachyon Agent, and also when the Tachyon Agent starts up. This is to account for any events which might have occurred while the Tachyon Agent was offline that may have been missed.
AgentStartup trigger
Given the statement above, this raises the question of why there is an "AgentStartup" trigger at all.
Simply, this trigger is a "fake" trigger which allows creation of a rule which is only ever checked on Agent start-up, and is required because a rule must always have at least one associated trigger.
Each of the supported triggers is described in detail below. Before this, it is important to understand the concept of "de-bouncing".
Triggers vs Trigger Templates
When the Agent receives its policy, it is provided the trigger(s) for each corresponding rule, and the parameter values for each of those triggers.
However, on the Tachyon Server, there is the additional concept of Trigger Templates. A Trigger Template is a pre-configured variant of a specific Agent-based trigger, which itself may have parameters. Trigger Templates are presented to the user when creating a rule in the Guaranteed State user interface (and similarly must be specified when calling the Consumer API directly to create a rule).
In summary, a Trigger Template provides a way to simplify user selection of an event, without necessarily having to provide all the parameters for the Agent's trigger themselves.
When creating a rule, a user selects a Trigger Template - not a trigger itself.
Consider the following example:
We may wish to have several rule evaluate whenever any of the settings for an item of software are changed in the registry, which can be achieved using the WindowsRegistryChange trigger
This trigger, as per the earlier section, takes three parameters (Hive, Subkey, IncludeSubkeys)
Rather than having the user type in "
HKLM", "SOFTWARE\Acme\SpreadsheetApplication" and "true" for the corresponding parameter values for this trigger, it is preferable to have a "specialized" Trigger Template which contains these parameters pre-configuredIn this way, a user creating a rule could simply select a Trigger Template called "Whenever the settings for Spreadsheet Application change" and not have to provide any parameter values
To do this, a Trigger Template could be created which specializes the WindowsRegistryChange trigger.
A trigger template has the following properties:
Property | Description | Notes |
|---|---|---|
Name | The name of the trigger | Must be unique |
Description | Textual description of the trigger | |
Type | The corresponding trigger type for the Tachyon Agent to use (e.g. ServiceStatusChange) | |
ReadablePayload | Textual description with placeholders for user-supplied parameters, which gets interpolated to form the description of the trigger | Similar to ReadablePayload for Fragments and Instruction Definitions Each user parameter's placeholder should appear at least once in the ReadablePayload |
AgentParameters | The set of parameter name-and-value pairs to be sent to the Tachyon Agent, as per the "Parameters" section for each of the trigger types defined in the previous section | The "value" for each parameter can contain placeholders for user-supplied parameters, which will be interpolated before being sent to the Tachyon Agent |
UserParameters | The set of parameters - if any - to be presented to the user when this trigger is selected | The values supplied by the user for each parameter can be injected into the parameters passed to the Tachyon Agent |
To better understand the concept of Agent Parameters and User Parameters, we'll consider a second Trigger Template example, and then look at how the Trigger Templates for both examples might be defined.
For our second example:
We may wish to have a rule evaluate whenever the configuration of a specific Windows Service is modified
Again, we can use the WindowsRegistryChange trigger to achieve this by asking it to monitor changes under
HKLM\SYSTEM\CurrentControlSet\Services\<SomeService>To avoid the user having to provide "
HKLM" and "SYSTEM\CurrentControlSet\Services" each time, a Trigger Template could be created which simply prompts the user for the name of the service whose settings should be monitoredThis service name could then be "injected" into the "Subkey" parameter for the Agent's trigger
Here's the definition of the Trigger Template for our first example (monitoring changes to the Spreadsheet Application's registry):
Property | Value | Explanation |
|---|---|---|
Name | SpreadsheetApplicationSettingChanges | Short name for the trigger template; free-form, but convention is to sentence-case |
Description | When the settings for My Spreadsheet Application change | |
Type | WindowsRegistryChange | This is the type of trigger that the Agent should use (i.e. check for registry changes) |
ReadablePayload | On change of My Spreadsheet Application settings | |
AgentParameters | Hive=HKLM Subkey=SOFTWARE\Acme\SpreadsheetApplication IncludeSubkeys=true | These are the parameters for the trigger that the Agent will receive |
UserParameters | (none) | The user is not required to enter any parameters to use this trigger template |
Again - note that in that example, the user is not required to provide the values for any parameters in order to use that trigger template.
Here's the definition of the Trigger Template for the second example, where the user needs to enter the name of the service whose settings should be monitored:
Property | Value | Explanation |
|---|---|---|
Name | ServiceConfigurationChange | As per previous example |
Description | When the settings for a Windows service change | |
Type | WindowsRegistryChange | As per previous example |
ReadablePayload | On change of settings for the %ServiceName% service | Note that in this case, the readable payload contains the substitution value for our "service name" parameter. When this Trigger Template is used and a value is supplied, e.g. "WinMgmt" (to monitor for changes in WMI service configuration), the user would see: "On changes of settings for the WinMgmt service" |
AgentParameters | Hive=HKLM Subkey=SYSTEM\CurrentControlSet\Services\ %ServiceName% IncludeSubkeys=true | These are the parameters for the trigger that the Agent will receive. Note that the substitute value for the ServiceName user parameter occurs in the "Subkey" parameter; this will be interpolated at the point that it is sent to the Agents |
UserParameters | ServiceName | We define a single parameter - the "ServiceName" which the user will be prompted to enter. The value supplied by the user will be injected into the resultant ReadablePayload and AgentParameters when it is associated with a policy rule. Note that the actual definition of a user parameter is more complex than just providing a name; user parameters follow the same convention as parameters for Instruction Definitions, and have additional attributes such as the data type, maximum length, "hint" text, etc. These additional attributes are not shown here for brevity. |
Trigger de-bouncing
Some triggers - either implicitly (FileChange trigger) or explicitly (WindowsEventLog trigger) - employ the concept of "de-bouncing". This is a technique to prevent a trigger firing multiple times in rapid succession (and therefore causing a rule to be evaluated repeatedly) when, in practice, only a single "logical" event has happened.
Consider the case of the FileChange trigger: behind the scenes, this hooks into the Windows file monitoring API to determine when a file has been modified. However, when an application modifies a file, it might make a number of successive modifications in a very short space of time - for example, it might write a block of data, close the file, re-open the file, write another block of data, and then close the file. This manifests itself as a burst of events when really it should be seen as a single change.
To cater for this, the FileChange trigger automatically de-bounces. When a notification is received from the operating system to say that the file has changed, the Agent waits a small amount of time (in the case of the FileChange trigger, this is two seconds). If another notification is received within those two seconds, this wait is cancelled and a new two second wait is immediately started. When the two second period has elapsed and no further notifications have been received from the operating system, the trigger is fired. In this way, the trigger waits for the notifications to "calm down" before it causes the associated rule to be evaluated.
Another example would be using the EventLog trigger to detect a change of network. If a laptop is unplugged from a wired Ethernet connection and switches to WiFi, there may be two successive "network change" events generated: "Wired network disconnected" followed shortly afterwards by "WiFi network connected". By employing de-bouncing (e.g. waiting for 10 seconds for network connectivity to stabilize), it is possible to view this as a single "Network connectivity has changed" event, rather than two independent events that occur one after the other (which would otherwise have caused the associated rule to be evaluated twice unnecessarily).