uberAgent can collect data for arbitrary custom metrics through a generic script execution engine. It runs any type of script at any desired interval, either per machine or per user session.
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 the LocalSystem account. This is particularly relevant when running scripts stored on a network file share.
You can use any script written in your preferred scripting language, e.g., PowerShell, Python, 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 to the backend as one event. Script output must be formatted as key-value pairs (e.g.,
The key name may contain characters that are invalid for field names on some backends. Such characters are automatically replaced with underscores (
_). If field names do not start with a letter, they are prepended with
uA_. This is done for every type of receiver to ensure that field names are identical on every backend.
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.,
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.
An alternative for PowerShell scripts is to encode the script in Base64 and reference the result as parameter.
# Place the script content in the variable MyScript $MyScript = @' script content goes here '@ # Convert to base64 and output to a file to avoid word wrapping on the commandline. [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($MyScript)) > C:\base64_output.txt
Add the result as parameter to PowerShell in a timer:
[Timer] Name = Some name Interval = 30000 Script = powershell.exe -executionpolicy bypass -EncodedCommand "JABFAHIAcgB ... vAGkAbgAgACcAIAAnACkA" ScriptContext = UserSessionAsUser
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.
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.
Scripts can read session GUIDs from the registry key
HKLM\SOFTWARE\vast limits\uberAgent\SessionGuids. Each value name is the ID of a Windows session. The associated value data contains uberAgent’s session GUID.
The sourcetype used for the script’s output is a concatenation of
uberAgent:Script: and the timer name specified in uberAgent’s configuration.