Understanding Entity IDs in VM

Document created by Martin Walker Employee on Apr 28, 2017Last modified by Martin Walker Employee on Apr 28, 2017
Version 4Show Document
  • View in full screen mode


Qualys uses several types of ID’s to identify both hosts in your network and assets in the Qualys asset data (there is a subtle difference). It is important to understand these different IDs and how they can be used in VM and other modules. This varies depending on how the data is collected, there is not a one-to-one mapping of hosts in your network and assets in the Qualys asset database.  For network-based scanning each individually addressable interface on a host that has been scanned will have a separate asset in the Qualys database.  This makes sense as we are measuring attack surface, and each network interface is an attack surface with potentially unique vulnerabilities affecting it.  Each Cloud Agent host and each EC2 host will be a single asset regardless of the number of interfaces.

Host ID

The first of the three identifiers is the Host ID, which is exposed in the Vulnerability Management module and shown at top of the General Information tab of the asset details window (for example, by clicking on the asset from an asset search results windows).  Host ID is labeled “ID” and is a 9 digit number. A Host ID is created for each asset (IP address or interface) when scanned.  Additionally each Cloud Agent and EC2 host will have a unique Host ID.


The HOST_ID is a primary key of USER_HOST table, so it is unique within a POD.  Since it is unique within a POD, it is unique within a subscription.  So, for customers who have multiple subscriptions on the same POD it is guaranteed there will be no collision of Host ID between their subscriptions.  This ID is NOT guaranteed to be unique between PODs.  So for customers with subscriptions on different PODs there is a possibility, albeit low, that there can be collisions.



The Host ID is also exposed via Asset View and is an indexed field that can be used in Asset View queries. It is called hostId. For example the query “hostId: 172052470” returns the asset shown above. The ID is shown on the asset details in Asset View, labeled "Host ID”.



Where do these get used in the API?

The Host ID referenced from Asset Search is also used in the Qualys Cloud Platform API, specifically the v1 and v2 APIs. This is VM and PC centric, and only used by the assets there. In the Host Detection API (v2 Guide page 168) this is the first value under each HOST record labeled <ID>. ALL APIs in the VM and PC technology umbrella (called QWEB internally) and of the form /api/2.0/fo/... use this ID to reference assets.



Qualys Host ID

There is also the similarly named but quite different Qualys Host ID. This is a GUID format ID found on assets that have either the Cloud Agent installed or have been scanned with an authenticated scan and Agentless Tracking enabled. Note the difference, the Qualys Host ID GUID represents hosts, and there will be a maximum of one Qualys Host ID for any host in the network, regardless of the number of interfaces it has. The Host ID discussed above represents scanned assets, so a single host with 5 scanned interfaces will be represented by five entries in the Qualys asset database, each with a unique ID, but only one Qualys Host ID if and only if it has an Agent or has been scanned with authentication and Agentless Tracking enabled. The GUID is also used for merging agent asset data and scan asset data for authenticated scans. In order for this to work correctly, the "Unified View" option in Users->Setup must be enabled, and for *nix hosts, the location specified in the authentication record when enabling Agentless Tracking must be /etc.

The GUID is created using three different mechanisms depending on the asset and which happens first, scanning or agent activation.

The Linux Agent uses the poco library for UUID generation. The poco library implements a Universal Unique Identifier, as specified in Appendix A of the DCE 1.1 Remote Procedure Call Specification (http://www.opengroup.org/onlinepubs/9629399/), RFC 2518 (WebDAV), section 6.4.1 and the UUIDs and GUIDs internet draft by Leach/Salz from February, 1998 (http://www.ics.uci.edu/~ejw/authoring/uuid-guid/draft-leach-uuids-guids-01.txt) and also http://tools.ietf.org/html/draft-mealling-uuid-urn-05. The Mac and the upcoming AIX agent use the same library as will any other future *nix agent version.

The Windows agents call the Win32 API CoCreateGuid() which uses a similar process to generate an RFC 2518 compliant GUID.

When the GUID is created for assets scanned with Agentless Tracking enabled, it is created by the local scanner appliance performing the scan job. This GUID contains the scanner MAC address in bytes 10-15, and uses ephemeral state data about the local system to generate the remaining bytes in a manner that ensures uniqueness relative to the MAC address. The GUID is both unique and unpredictable, and cannot be used to derive any information about the asset itself.

GUIDs aren't 'guaranteed' to be unique in the same way that the centrally generated IDs are, however because there's an extremely small chance of a collision for all GUIDs created universally anywhere in the world (the chance of bit-wise collision between any two randomly assigned GUIDs you would have to generate 23 billion billion GUIDS before having a 50% chance for a collision (1.25 * sqrt(2^128) from birthday paradox), it can be relied on to be globally unique (meaning across all current and future PODs). The whole point of using a GUID is to allow decentralized generation of unique identifiers without a central enforcement point. If a central enforcement point was acceptable then it would be easier to have that enforcement point just assign incrementing serial numbers. In the highly unlikely event of a collision within the same subscription then the agent will re-provision and will end up generating another UUID which will be unique.

Note in the API screenshot above, this value is referenced as <QG_HOSTID>.


The Qualys Host ID is exposed in the Vulnerability Management module, also on the General Information tab of the asset detail windows assets, when the asset has been scanned with authentication and agentless tracking enabled, or if it is a cloud agent asset. The Qualys Host ID value is written to the registry or the user specific location in the authentication record and is reported in QID 45179.



The Qualys Host ID is also exposed in Asset View, and is an indexed and searchable field called “agentID”. It is displayed on the Agent Summary tab of the asset details window in Asset View, labeled "Agent ID”.



NOTE: While the Qualys Host ID is used on both Agent-enabled hosts and hosts scanned with authentication and agentless tracking, because non-agent enabled hosts do not have an Agent Summary tab in Asset View, this identifier cannot be viewed in Asset View other than by examining the value of QID 45719 in the Vulnerabilities tab (by viewing vulnerabilities of type “Information Gathered”).



Asset ID (Products other than VM or PC)

In addition to the two IDs described above, there is an additional Asset ID assigned to all assets in your subscription. It is exposed in Asset View on the asset summary windows and labeled Asset ID. The Asset ID is not exposed in the Vulnerability Management or Policy  Compliance modules.



Asset ID in the API

The non-VM and PC products use a different asset engine and technology (we call it PORTAL internally) - these API's are of the form /qps/rest/2.0/... For example:



NOTE that here the <id> used is specfic to PORTAL API's. The QWEB API is referenced in this call via <qwebHostId>.