Registration & Duplicate Prevention

1\ introduction accurately identifying unique devices and preventing the creation of duplicate records is critical for maintaining cmdb integrity, accurate licensing, and reliable management within commandit this is especially challenging in environments where agents might be reinstalled on the same hardware or where system images containing an agent are deployed to new, distinct hardware (cloning) this document outlines the agent registration process and the backend logic designed to handle these scenarios robustly 2\ registration process (initial installation / no existing identity) this process occurs when the commandit service starts for the first time on a machine or after its local identity ( device id , device secret ) has been cleared collect hardware identifiers the agent service gathers multiple pieces of hardware information expected to be relatively stable and unique primary smbios uuid (from bios/uefi) secondary system serial number (from chassis/bios) tertiary baseboard (motherboard) serial number quaternary primary non virtual network adapter mac address (agent retrieves these via os apis, wmi, system profiler, etc ) call registration api the agent makes a post /api/v1/agent/register call to the backend payload includes the collected hardware identifiers (uuid, system serial, baseboard serial, mac address), the assigned org id and location id (provided during installation/configuration), and potentially a transient agent guid for tracking the request backend matching logic the backend api receives the registration request and performs a prioritized matching sequence within the specified org id to find an existing devices record representing this hardware a match on smbios uuid query devices where org id = ? and smbios uuid = ? if one unique, active record is found > match successful if multiple active records match (indicates potential existing duplicates or non unique uuids) > conflict requires manual review if smbios uuid is null, invalid (e g , all zeros/fs), or no match > proceed to next step b match on system serial number query devices where org id = ? and serial number = ? if one unique, active record is found > match successful if multiple active records match > conflict requires manual review if serial number is null, unreliable, or no match > proceed to next step c match on baseboard serial number query devicehardware for the baseboard serial, join to devices where org id = ? if one unique, active record is found > match successful if multiple active records match > conflict requires manual review if baseboard serial not found or no match > proceed to next step d match on primary mac address (fallback use cautiously) query devicenetworkadapters for the mac, join to devices where org id = ? because macs can change (adapters replaced, vms cloned, docking stations), matching solely on mac is unreliable this step should ideally be combined with other less unique identifiers (e g , manufacturer + model + mac) or used only as a last resort if enabled by configuration if a potential match is found > may require manual review or have lower confidence backend action unique match found the backend associates the registration request with the existing device id it generates a new secure device secret for the agent and returns the existing device id and new secret (invalidating any previous secret for that device) no match found the backend creates a new record in the devices table, populating org id , smbios uuid , serial number , and other basic info provided it generates a new device id (uuid) and a new device secret , returning these to the agent conflict/multiple matches found the backend logs the conflict, potentially creates a temporary placeholder record requiring admin intervention, and returns a specific status code indicating manual review is needed it does not return a standard device id /secret agent action on response success (new or matched) the agent securely stores the received device id and device secret (using dpapi/keychain) for all future communication failure/conflict the agent logs the error and enters a retry loop for registration 3\ re imaging / cloning detection (during check in) this process detects when an agent with a valid existing identity checks in from hardware that doesn't match the database record, typically after an image deployment agent check in the agent service initiates its regular post /api/v1/agent/{deviceid}/checkin call, authenticating with its stored deviceid and device secret crucially, the payload includes the current key hardware identifiers (smbios uuid, system serial, baseboard serial, primary mac) backend check in validation the backend api performs these checks authenticate verifies the deviceid and device secret retrieve stored hw ids fetches the hardware identifiers ( smbios uuid , serial number , etc ) associated with the requesting deviceid from the database compare hw ids compares the ids received in the check in payload against the stored ids backend response match if the key identifiers match (within acceptable tolerance defined by business logic, prioritizing uuid/serials), the backend processes the check in normally, updates devices last agent checkin , and returns any pending commands mismatch if a significant mismatch is detected (e g , different smbios uuid or system serial), the backend determines this is likely a cloned agent on new hardware it rejects the check in for the original deviceid and responds with a specific status/error code "hardware mismatch re register required" it does not update last agent checkin for the original deviceid agent response to mismatch the agent service, upon receiving "re register required" clears identity deletes its local device id and device secret initiates registration immediately restarts the full registration process described in section 2, sending its current (new) hardware ids this results in a new devices record being created for the new hardware instance 4\ conclusion this two pronged approach – robust hardware matching during initial registration and continuous hardware validation during check in – combined with the agent's ability to clear its identity and re register upon backend instruction, provides a strong mechanism to prevent duplicate device entries caused by agent reinstalls or os imaging/cloning onto new hardware the accuracy depends on the quality of hardware identifiers collected by the agent and the strictness of the backend matching logic