uberAgent ESA’s Security & Compliance Inventory tests are part of the configuration. This page documents the configuration syntax.

Example

Timer

In the following example, uberAgent runs all Security & Compliance Inventory tests from the category Antivirus once every 24 hours:

[Timer]
Name              = Security & Compliance Inventory timer
Interval          = 86400000
Start delay       = 600000
Persist interval  = true
UA metric         = SecurityInventory.Antivirus

SecurityInventoryTest

Each Security & Compliance Inventory test is defined in a stanza such as the following. Note the Category assignment, which corresponds to SecurityInventory.Antivirus from the Timer stanze above.

[SecurityInventoryTest]
Name              = Antivirus
ScriptId          = 71270F6B-7160-4629-90C4-F36E621D43E1
Category          = Antivirus
ScriptCommandline = "###UA_SI_LOCALPATH###\Antivirus\Antivirus.ps1"
Interpreter       = PowerShell
OutputFormat      = JSON
ScriptContext     = Session0AsSystem
IntegrityLevel    = High

ScriptInterpreter

The method of execution is configured in ScriptInterpreter stanzas. PowerShell scripts are invoked as defined in the following example:

[ScriptInterpreter]
Name       = PowerShell
Executable = C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Parameter  = -ExecutionPolicy Bypass -file ###UA_SCRIPT###

Test Definition

There can be any number of [SecurityInventoryTest] stanzas, each defining one test script. Tests are processed in the order in which they are defined in the configuration. uberAgent ESA always processes all scripts for every timer run containing the metric SecurityInventory.CATEGORY where the timer stanza’s CATEGORY matches the category from the SecurityInventoryTest stanza.

A [SecurityInventoryTest] stanza may contain the following settings.

ScriptId

• Setting name: ScriptId
• Description: a GUID that represents the script. Must be unique.
• Valid values: a GUID
• Default: empty
• Required: yes

Category

• Setting name: Category
• Description: a category name for the test. Multiple tests can have the same category name (e.g., Antivirus).
• Valid values: Any string
• Default: empty
• Required: no

Name

• Setting name: Name
• Description: a name for the test which is logged in the uberAgent log file in case of an error.
• Valid values: Any string
• Default: empty
• Required: no

ScriptCommandline

• Setting name: ScriptCommandline
• Description: the full path to the script.
• Valid values: any valid file system object
• Default: empty
• Required: yes

Interpreter

• Setting name: Interpreter
• Description: the interpreter that starts the script. See stanza [ScriptInterpreter]. If left empty, the ScriptCommandline is run “as is” without prepending the invocation of an interpreter.
• Valid values: any string
• Default: empty
• Required: no

OutputFormat

• Setting name: OutputFormat
• Description: defines the output format of the script.
• Valid values: JSON
• Default: JSON
• Required: no

ScriptContext

• Setting name: ScriptContext
• Description: defines the context in which the script is started.
• Valid values:
  • Session0AsSystem: runs the script once per timer run in the context of the local SYSTEM user.
  • UserSessionAsSystem: runs the script for each user logged in during the timer run in the context of the local SYSTEM user.
  • UserSessionAsUser: runs the script for each user logged in during the timer run in the context of the user.
• Default: Session0AsSystem
• Required: no

IntegrityLevel

This setting is available on Windows only.

• Setting name: IntegrityLevel
• Description: defines the integrity level at which the script is started.
  Format: LEVEL [+Mitigation1] [-Mitigation2] [+Mitigation3] [...]
  See the sandbox documentation for details on the available mitigations.

• Valid values for LEVEL:
  • Low: integrity level is set to low.
  • Medium: integrity level is set to medium.
  • High: integrity level is set to high.
• Default: medium
• Required: no

Script Interpreter Definition

A [ScriptInterpreter] stanza may contain the following settings.

Name

• Setting name: Name
• Description: a unique name for the interpreter. This name must be referred to in the Interpreter setting of the [SecurityInventoryTest] setting.
• Valid values: any string
• Default: empty
• Required: yes

Executable

• Setting name: Executable
• Description: the full path to the interpreter that executes the script.
• Valid values: full path to the script.
• Default: empty
• Required: yes

Parameter

• Setting name: Parameter
• Description: parameters for the interpreter. The script name must be specified here via the placeholder UA_SCRIPT (see below).
• Valid values: any string
• Default: empty
• Required: yes

UA_SCRIPT Placeholder

A script interpreter stanza specifies how to execute scripts from a given language. The script to be executed is specified via the placeholder ###UA_SCRIPT###, a variable that is replaced with the ScriptCommandline from the SecurityInventoryTest stanza before running a script.