uberAgent Custom Scripts

uberAgent determines a lot of metrics which are generally available for all customers. Sometimes it is needed to create a custom script to determined customer specific values.

As of uberAgent version 4.1, we introduced the feature of collecting custom metrics with a generic script execution engine. It runs any type of script at any desired interval, either per machine or per user session.

Overview: How to Configure Custom Script Execution

The execution of custom scripts is handled by uberAgent’s endpoint agent. Scripts are configured as part of timer stanzas in uberAgent’s configuration. The following lists the relevant configuration options:

#   Setting name: Name
#   Description: Arbitrary name for the timer.
#   Valid values: any string
#   Default: empty
#   Required: yes
#   Setting name: Interval
#   Description: How long to wait before collecting data again. Unit: milliseconds.
#   Valid values: any number
#   Default: [none]
#   Required: yes
#   Setting name: Script
#   Description: Run a script once or periodically, depending on the configured Interval (0 = run only once). The script's output to stdout is sent to Splunk, each line as a new event. Can be specified more than once per timer.
#   Valid values: Any valid command line, optionally including command line parameters.
#   Default: empty
#   Required: no
#   Setting name: ScriptContext
#   Description: The user context to run a script in.
#   Valid values: Session0AsSystem | UserSessionAsSystem | UserSessionAsUser
#   Default: Session0AsSystem
#   Required: no

Please note that the uberAgent service on the endpoint is running in the context of LocalSystem, so the referenced script must be accessible by an executable to the LocalSystem account. This is particularly relevant when running scripts stored on a network file share.

The Script

You can use any script written in your preferred scripting language, e.g. PowerShell or VBScript. Our agent will capture all script output sent to standard output (stdout), i.e. printed to the console. Every line of output is sent as its own event to the backend. Script output must be formatted as key-value pairs (e.g. key=value).

Please keep in mind that any data collected in addition to our default dataset has an impact on the generated data volume. Running custom scripts generates additional load on the endpoint the amount of which depends on the executed process (e.g. powershell.exe or cscript.exe) and the underlying data source. Especially Windows Management Instrumentation (WMI) can cause a significant load.

Additionally, please choose an appropriate timer interval for your script. Data that does not change often, like inventory information, probably only need to be collected once a day whereas volatile metrics like network throughput might have to be collected once per minute.

uberAgent does not manage the deployment process of custom scripts to the endpoints. Please feel free to use either your existing software distribution system or Splunk’s Deployment Server.

The Script Context

Custom scripts can be executed in three different contexts:

  • Session0AsSystem: the script runs in session 0 as LocalSystem
  • UserSessionAsSystem: the script runs in every interactive user session as LocalSystem
  • UserSessionAsUser: the script runs in every interactive user session as the user logged on to the session

The script context is configured per timer. Of course, you can configure multiple timers for independent execution of different scripts.

Session GUIDs

To uniquely identify RDS sessions, uberAgent creates its own session GUIDs. These GUIDs are part of all sourcetypes containing data related to user sessions (e.g. logon and logoff).

If the data from a custom script needs to be associated with a specific session, the script should make use of the session’s GUID.

The session GUID is written to the registry key HKEY_LOCAL_MACHINE\SOFTWARE\vast limits\uberAgent\SessionGuids. In that key, each value name is the ID of a Windows session. The associated value data contains uberAgent’s internal session GUID.

An example of how to use custom scripts can be found here.

The sourcetype used for the script’s output is a concatenation of uberAgent:Script: and the timer name specified in uberAgent’s configuration.