USM Anywhere™

AlienVault Agent IDs

The AlienVault Agent uses two universally unique identifier (UUID)-formatted IDs to interact with the USM Anywhere infrastructure. These are the host identifier UUID and the asset identifier UUID.

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

  • If the agent is deployed with the multiple assets deployment script, then the installation process generates a random host identifier, which will start with a block of 8 zeros (00000000-).
  • If the agent is deployed with the single asset deployment script, then the user is prompted to choose which existing asset the deployment will be associated with. This appends the install command with an -assetid flag followed by a pre-determined ID. The pre-determined ID happens to be the asset identifier of the associated asset.

The agent’s host identifier is stored on the agent system in the osquery.flags file as the --specified_identifier flag, which is located in the following places on the endpoint's directory:

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

The second ID used by the agent is the asset identifier UUID, 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, instead it is provided in its designated AlienVault Agent Configuration Profiles, which is served over Transport Layer Security (TLS) to the agents as they run.

Once associated to an asset, the agent will report both its host identifier UUID (hostIdentifier) and asset identifier UUID (souce_asset_id) 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.

AlienVault Agent ID Usage

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

Agents installed on fresh endpoints with the multiple assets deployment script will always have to be associated to an asset once. Agents installed with the single asset deployment scripts will automatically be associated to their designated asset. In an update scenario, the installation process will detect the presence of a preexisting osquery.flags file and use the specified_identifier contained there for continuity. If the single asset deployment script is run on top of an existing agent installation, the -controlnodeid and -assetid flag values passed to the script will override any values found on the endpoint system.

Agent Deployments in Virtual Environments

When deploying the AlienVault Agent, you should have an understanding of the two agent identifiers detailed previously, especially if deploying to virtual machines (VMs) or using a templated image, or "golden image" to be distributed to multiple pieces of hardware. Consider your use case if deploying to these environments:

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

    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 report with a unique 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 once at first startup so that a unique host identifier UUID is generated during installation.
  • If you are building a templated “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 asset deployment script once at first startup so that a unique host identifier UUID is generated during installation.

In the last two use cases, each agent will be designated an unassociated “orphan” 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. That will only need to be done once per instance, and can be done in bulk if creating new assets from the agent's Associations page.