uberAgent

Central Config File Management

The ability to retrieve configuration sets from an SMB file share is called Central Config File Management (CCFM). It has the advantage of automatic deployment via an agent-based pull mechanism and full support for uberAgent ESA Threat Detection rules and inventory tests (which cannot be distributed by Group Policy alone). With Central Config File Management, either a single configuration can be used for all endpoints, or different types of agents can be configured to pull different configurations.

Central Config File Management is an alternative to configuring uberAgent via local configuration files or Group Policy.

Requirements

File Share Access

uberAgent must have read permissions on the file share to copy the central configuration to the local cache.

Windows

The uberAgent service runs as SYSTEM. Hence, in an Active Directory domain environment, the computer account must have read permissions on the central file share.

macOS

Mount the file share as SMB share.

Azure Files

You can use Azure Files to store the central configuration in the same way that you can use it for the license file.

Availability Requirements

There is no need for the configured file share to be available all of the time. Endpoints always use the local configuration cache.

Enabling CCFM

If a base path is specified via one of the methods described in this section, Central Config File Management is enabled.

Windows

uberAgent checks the following registry values at startup. If one of them exists, the agent uses the specified value as the base path to the central configuration file share.

Via Group Policy

Specify the base path to the configuration file share in the registry value HKLM\Software\Policies\vast limits\uberAgent\Config\ConfigFilePath (REG_SZ). This setting can be deployed via uberAgent’s Group Policy settings.

Via the Registry

Specify the base path to the configuration file share in the registry value HKLM\Software\vast limits\uberAgent\Config\ConfigFilePath (REG_SZ).

macOS

  1. Add the path to the config file share in the file /Library/Application Support/uberAgent/Config Templates/uberAgent-remote-config-macOS.conf: Section: RemoteConfiguration Key: ConfigFilePath

  2. Copy the updated file to /Library/Application Support/uberAgent.

How CCFM Works

If Central Config File Management is enabled, uberAgent tries to retrieve its configuration from the file share specified in the ConfigFilePath setting. It does so by looking for the configuration matching its own version the closest.

If a central configuration is found, and its timestamp differs from the previously cached configuration on the endpoint, uberAgent downloads the central configuration. It then compares the currently applied configuration with the downloaded central configuration for meaningful changes. If any are detected, the newly downloaded central configuration is applied.

Configuration Archive (uberAgent.uAConfig)

uberAgent expects the central configuration in a single file, uberAgent.uAConfig. Technically, this file is a zipped archive of all of uberAgent’s configuration files.

Base Path Subdirectory Precedence

Assuming the agent’s version is 7.1.0.5050 and the file share path is \\server\share, uberAgent looks in the following directories for the configuration archive uberAgent.uAConfig and uses the first config archive it finds:

  1. \\server\share\7.1.0.5050
  2. \\server\share\7.1.0
  3. \\server\share\7.1
  4. \\server\share\7
  5. \\server\share

CCFM Application Matrix

The following matrix helps to understand how Central Config File Management updates the local agent configuration.

File share accessible Central configuration found Local cache valid Meaningful change detected uberAgent behavior
yes yes no n/a The configuration is downloaded and applied; the local cache folder is updated.
no n/a no n/a uberAgent pauses for 60 s, after which it retries, repeating this until uberAgent.uAConfig is found.
yes yes yes yes The configuration is downloaded and applied; the local cache folder is updated.
yes no yes n/a uberAgent uses the cached configuration.
no n/a yes n/a uberAgent uses the cached configuration.

Refresh Interval & Auto-Update

Each agent regularly checks the CCFM file share for updates and applies new configurations automatically. See this document for details.

Creating or Updating a Custom CCFM Archive (uberAgent.uAConfig)

Note: the CCFM archive of the default configuration can always be found in the config-dist subdirectory of the uberAgent Configuration GitHub repository. Creating your own CCFM archive is only necessary if customizations are to be applied to the default configuration.

Downloading the Latest Files from GitHub

We provide a PowerShell script to help automate the process of downloading a subset of uberAgent’s configuration files from GitHub.

With the help of this script, download those files that you want to update, leaving your customized config files unchanged. Then proceed to create the CCFM archive as explained below.

Creating the CCFM Archive (uberAgent.uAConfig)

Create an archive of all uberAgent configuration files you want to be part of your central configuration and name it uberAgent.uAConfig. This can either be done in Windows Explorer, macOS Finder, or on the command line. The steps to produce a configuration archive on the terminal are as follows:

  1. Copy all configuration files into a folder.
  2. Change to this folder on the command line.
  3. Execute one of the following commands, depending on the platform you are creating the archive on.

Windows

Compress-Archive * -DestinationPath config-temp.zip
Move-Item config-temp.zip uberAgent.uAConfig
<!--NeedCopy-->

macOS

zip -r uberAgent.uAConfig ./ -x "*.DS_Store"
<!--NeedCopy-->

Switching Between Configuration Options (CCFM ↔ Local ↔ Group Policy)

Switching from one configuration option to another at runtime is possible anytime.

From Central to Local Configuration

Windows

Remove the value ConfigFilePath where you configured it (registry or Group Policy, see above).

macOS

Remove the file uberAgent-remote-config-macOS.conf from the folder /Library/Application Support/uberAgent.

From Local to Central Configuration

Windows

Add the value ConfigFilePath either via the registry or via Group Policy (see above).

macOS

Add the path to the file share in file uberAgent-remote-config-macOS.conf (see above).

CCFM Reporting & Monitoring

uberAgent reports configuration metadata in the sourcetype uberAgent:Config:ConfigInfo (docs). The transmitted data is visualized in the uberAgent Versions Splunk dashboard.

Central Config File Management