uberAgent ESA’s Security & Compliance Inventory (SCI) test scripts can be authored in any interpreted or compiled programming language. Typically, an interpreted language such as PowerShell or Python is used. This page documents conventions and requirements for SCI test scripts.

Test Script Execution

Tests are scheduled by uberAgent’s endpoint agent according to the test configuration.

Tests are run sandboxed according to the principle of least privilege. Please see the sandbox docs for details.

If a test is executed in user context, it is checked whether the user has read permissions. If not, the built-in group Users is added to the parent directory. If this is not desired, it can be disabled via the ConfigFlag DisableSetFilePermissionsOnExec.

Test Script Output

Multiple Tests per Script

A Security & Compliance Inventory test script may perform multiple independent tests per script invocation.

Console Output

uberAgent expects a test script’s output on the console (stdout). The script must only print test output to the console. Any other console output must be suppressed.

Output Encoding

Set the encoding to Unicode. When using PowerShell scripts, the following line should be specified at the beginning of each script:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Output Format

Format Specification

The expected output format is configured in the OutputFormat setting of the [SecurityInventoryTest] stanza (docs).

JSON Format

A test result that uses JSON output format looks like this:

[
   {
      "Name": "PowerShell v2 disabled",
      "Score": 2,
      "RiskScore": 0,
      "ResultData": "Yes",
      "ErrorCode": 0,
      "ErrorMessage": ""
   },
   {
      "Name": "PowerShell remoting allowed",
      "Score": 2,
      "RiskScore": 80,
      "ResultData": "Yes",
      "ErrorCode": 0,
      "ErrorMessage": ""
   }
]

Modify Test Names and Descriptions

uberAgent ESA ships with an extensive set of pre-defined tests than can be executed through its Security and Compliance Inventory functionality. Each test is displayed with a human readable name and a short description. As customers may add their own tests, test display names and descriptions have to be added as well.

To modify existing or add new tests to this table, change the following input lookup file in $SPLUNK_HOME/etc/apps/uberAgent_ESA/lookups/security_inventory_checknames.csv. Please make sure to distribute the changed input lookup file to all search heads.

The lookup file contains three columns.

• SecurityInventoryName: this field contains the test name that was used in the script. To save data volume, this name may be abbreviated. Example: CMProtRoot
• SecurityInventoryDisplayName: this field contains the display name of the test to improve readability. Example: protected root certificates
• SecurityInventoryNameDescription: this field contains a description of the test to be displayed in the data table after selecting a test in the SCI test analysis chart. Example: Checks if root certificates can be installed by users.

Output Fields

The following table describes the fields that may be part of a test script’s output: