LevelBlue Agent IDs

The LevelBlue Agent uses two universally unique identifier (UUID)-formatted IDs to interact with the USM Anywhere infrastructure: a host identifier UUID and an asset identifier UUID.

The host identifier UUID, hostIdentifier, signifies a specific agent installation. This UUID is generated in one of two ways:

  • If you deploy the agent with the single asset deployment script, then you must choose which existing asset the deployment can be associated with or create the asset on the fly. This appends the install command with the -assetid flag followed by a pre-determined ID. The pre-determined ID is the asset ID of the associated asset.
  • If you deploy the agent with the multiple assets deployment script, then the installation process generates a random host identifier, which starts with a block of 8 zeros (00000000-).

The agent’s host identifier UUID is stored under the --specified_identifier flag in the osquery.flags file, which is located in the following directories on the endpoint:

  • Microsoft Windows: C:\Program Files\osquery\osquery.flags
  • Linux: /etc/osquery/osquery.flags
  • Apple macOS: /var/osquery/osquery.flags

The second ID used by the agent is the asset identifier UUID, souce_asset_id, which is generated by USM Anywhere whenever an asset is created. USM Anywhere uses this ID to associate events with an asset. The agent does not store its asset identifier UUID; instead, it is provided in its designated LevelBlue Agent Configuration Profiles, which is served over Transport Layer Security (TLS) to the agents as they run.

Note: Once associated with an asset, the agent reports both its host identifier UUID and asset identifier UUID to USM Anywhere through events, providing USM Anywhere a means of correlating those events to an asset. If the agent has been deployed with the single asset deployment script, the host identifier UUID and asset identifier UUID should match.

LevelBlue Agent ID Usage

When USM Anywhere receives an event from the LevelBlue Agent, it looks for the asset ID in the metadata of the event. If the asset ID belongs to a valid and existing asset, USM Anywhere will correlate that event to the asset using that asset ID. If the agent has not been associated with an asset or the asset ID is not recognized, USM Anywhere will identify the agent as unassociated or “orphan”, on the Data Sources > Agents page. See LevelBlue Agent and Asset Associations for more information on associating assets with the agents.

If you install the agents using the single asset deployment script, the agents are automatically associated with their designated assets. When the agent is updated, the installation process detects the presence of an existing osquery.flags file and uses its --specified_identifier flag to identify the agent, thus maintaining its continuity. However, if you run the single asset deployment script on a host that already has an LevelBlue Agent installed, the deployment script will overwrite the -controlnodeid and -assetid flags found on the host system.

Agent Deployments in Virtual Environments

Understanding the two LevelBlue Agent IDs detailed previously is important when you deploy agents in virtual machines (VMs), especially when deploying the same image to multiple VMs. Consider the following use cases:

  • If the VM can be identified by the same host identifier UUID every time it starts up, then you can install the agent and snapshot the image containing the installation’s host identifier UUID in the osquery.flags file.

    Note: If the image is reverted to that snapshot, or applied to another machine, the same host identifier UUID will be used on each machine, and all events reported by these instances of the agent will be associated with the same asset in USM Anywhere.

  • If you require that every instance of the VM carries a host identifier UUID to be discernible from another instance of the same VM, then you need to set up a scheduled task to run the multiple asset deployment script at the first start-up so that a unique host identifier UUID is generated during installation.
  • If you are building a template, or golden image, to be distributed to individual systems that need to be uniquely identifiable, then you should also set up a scheduled task to run the multiple assets deployment script at the first start-up so that a unique host identifier UUID is generated during installation.

In the last two use cases, each agent will be designated as unassociated by USM Anywhere because their events will contain no asset identifier information. Agents installed this way must be associated with a new or existing asset after installation. You only need to do it once per instance, and they can be done in bulk if creating new assets from the agent's associations page. See LevelBlue Agent and Asset Associations for more information.

Warning: If multiple VMs carry the same host identifier UUID and are associated with the same asset in USM Anywhere, you may see some strange behaviors. For example:

  • The asset changes its name from time to time.
  • The agent's heartbeat events appear more frequently than every 10 minutes.
  • The asset has alarms that are false positive because not all events aggregated under this asset originated from the same endpoint.