Skip to main content

Terminologies

When troubleshooting or managing agents in Xshield, it is important to understand the differences between commonly used flags, identifiers, and tokens. These terms often sound similar but serve very different purposes. Misinterpreting them can lead to issues such as accidental data loss, duplicate asset entries, or failed agent communication with the backend.

This section explains the purpose and differences of these terminologies, helping operators use them correctly and avoid operational mistakes.

Agent Removal:​

Remove​

Remove flag will locally remove all the agent information from the machine

CleanServer​

CleanServer flag will locally remove all the agent information from the machine and also remove the agent data from the dashboard.

In most cases, the remove flag is recommended, as it ensures that the agent data remains available in the dashboard.

Agent Identifiers:​

During agent registration, three identifiers are created:

Deterministic ID​

A unique identifier for the machine.

Asset ID​

Generated based on the deterministic ID, representing the asset in the system.

Agent ID​

Also derived from the deterministic ID, representing the agent instance.

In the ColorTokens database, a mapping is maintained between the deterministic ID and the asset ID. This ensures that when an agent is removed and then re-registered, the asset continues to report under the same asset entry, preserving data consistency.

Authentication Tokens:​

During agent registration, authentication tokens are issued to enable secure communication with the Xshield dashboard and backend.

The agent uses the deployment key during its first registration call to Xshield Platform and in return, the agent receives a refresh token and an auth token.

Auth Token:​

The agent uses auth token to complete the registration process with the dashboard and perform all API calls to the Xshield Platform (Auth token is is valid for 5 minutes and not stored in file)

Refresh Token:​

The agent uses refresh token to obtain a new auth token and a new refresh token when the previous auth token expires.

(Refresh token is valid for 90 days and stored in file. If the refresh token expires, no further communication can occur with the platform and the agent has to be re-registered)