Product documentation
uberAgent
Current Release (7.3.0) 7.2.1 7.2.0 7.1.2 7.1.1 7.1.0 7.0.2 7.0.1 7.0.0

Custom Scripts

July 9, 2024
Contributed by: 
C

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.

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
<!--NeedCopy-->

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.

Script

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., key1=value1 key2=value2).

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., 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.

Deployment

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
<!--NeedCopy-->

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
<!--NeedCopy-->

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.

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.

Examples

For examples that make use of the custom script functionality please see the practice guide section. Another example can be found here.

Custom Scripts
July 9, 2024
Contributed by: 
C
July 9, 2024
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.