uberAgent

Test Scripts

July 19, 2024

Contributed by:

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": ""
   }
]
<!--NeedCopy-->

Please note that the dashboard is designed to handle Security and Compliance Inventory test results as JSON objects only. Adding tests that do not use JSON output format may result in faulty dashboard panels or misleading information.

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:

Field name	Format	Valid values	Description
Name	String	Any string	The name of the test. Must be quoted to avoid parsing errors.
Score	Number	0-10	The resulting test score on a scale from 0 (very bad) to 10 (excellent).
RiskScore	Number	0-100	The severity of the test (how risky is the tested thing).
ResultData	String	Any string	Configuration information determined by the test. Should be quoted to avoid parsing errors.
ErrorCode	Number	Any number	Indicates success or failure. 0 = success.
ErrorMessage	String	Any string	Optional error message returned by the test. This message is logged to the agent log.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Test Scripts

July 19, 2024

Contributed by:

July 19, 2024

Contributed by:

Test Scripts

Test Script Execution

Test Script Output

Multiple Tests per Script

Console Output

Output Encoding

Output Format

Format Specification

JSON Format

Modify Test Names and Descriptions

Output Fields

In this article