Device Unification

Device Unification is the process by which JupiterOne attempts to produce a single representation of a device or host across all integrations.

Unified Devices have a very specific data model and are designed to be used as an entry point for asking more interesting questions about your infrastructure.

JupiterOne ingests data from a variety of sources, and each source may represent the same physical device in a different way. For example, a server may be represented by an integration as a Host or Device. Device Unification is used to present a single view of Device and Hosts across all integrations. The unification is driven by an accumulation of correlations, and is intended to provide a single node in the JupiterOne graph for each uniquely identified device or host.

This unified entity has the _class of UnifiedDevice, and the _type of unified_entity. It will be related to the source Host and Device entities via an IS relationship, used to indicate the entites it is derived from. Additionally the system will produce a CORRELATES relationship between the source Host and Device entities and the UnifiedDevice entity, and between UnifiedDevice entities.

To complement this data modeling JupiterOne provides an enhanced "Unified" view which auto-displays when querying for UnifiedDevice entities. This view is intended to provide an intuitive view of the hierarchical data represented in the graph.

Searching for Unified Devices

There are lots of ways to search for Unified Devices, the most simple approach is to use the following J1QL query to directly open the UnifiedDevice unified view:

FIND UnifiedDevice

This unified view is the most intuitive way to view the Unified Device data, and typically meets the needs of most users. As you interact with the filters on the left you will see the data dynamically update, but also the query used to power the view. This can help build queries you may wish to use in dashboards or alerts.

Visualising Relationships

Visualise the IS relationships between the Unified Device and their source Device or Host entities:

FIND UnifiedDevice
  THAT IS (Device|Host)
RETURN TREE

Inspect the CORRELATES relationships between the Unified Devices and their source Device or Host entities:

FIND UnifiedDevice
  THAT CORRELATES (Device|Host)
RETURN TREE

Finding Over-Correlated UnifiedDevices

Find Unified Devices that represent more than one source Device or Host entity:

FIND UnifiedDevice AS t
  THAT IS (Device|Host) AS s
RETURN t.displayName, COUNT(s) AS sources
ORDER BY sources DESC

This query will show you the UnifiedDevice entities that have the most source entities linked to them. If there is bad / invalid data on source devices it can cause a UnifiedDevice to have many source entities linked to it (i.e. over-correlation). This is a good query to find that situation.

Inspecting Correlation Reasons

Finding pairs of UnifiedDevice entities that have been correlated, ranked by the correlation strength:

FIND UnifiedDevice AS left
  THAT CORRELATES AS r UnifiedDevice AS right
RETURN left.displayName, left._id, SUM(r.CorrelationScore) AS score, right.displayName, right._id
ORDER BY score DESC

Looking at the specific correlation reasons between two UnifiedDevice entities:

FIND UnifiedDevice AS left
  THAT CORRELATES AS r UnifiedDevice AS right
RETURN left.displayName, r.CorrelationReason, r.CorrelationScore, right.displayName

Ideally the left and right Unified Device entities in this query would have a WITH clause to filter on a specific pair.

Finding Unified Devices with context

Looking at Unified Devices that are protected by a Host Agents

FIND UnifiedDevice
  THAT IS (Device|Host)
  THAT PROTECTS HostAgent
RETURN TREE

Finding Owners of Unified Devices

FIND UnifiedDevice
  THAT IS (Device|Host)
  THAT OWNS User
RETURN TREE

How Does it Work?

The device unification process is multi-step, and will not happen immediately. The three main phases of the process are:

1. Creation: The UnifiedDevice entity is created from the source Host and Device entities.
2. Correlation: The UnifiedDevice entity is correlated with other UnifiedDevice entities.
3. Merging: Highly correlated UnifiedDevice entities are merged.

Depending on the size of your graph and the number of integrations you have enabled, this process can take some time to complete.

Source Data

The unified representation is driven from the data found in Device and Host entities in your graph. Any integration or custom data that creates such entities will be part of the Unified Device experience.

Unified Device expects to find the following normalized properties on the source Device and Host entities:

Property	Type	Description	Notes
ipv4Addresses	string[]	The IPv4 addresses of the device, public or private
ipv6Addresses	string[]	The IPv6 addresses of the device, public or private	IPv6 Addresses should be in their long format (e.g. 2607:FB90:1000:0000:0000:0000:0000:0001)
macAddresses	string[]	The MAC addresses of the device	MAC Addresses should be lowercase and colon delineated (e.g. a4:83:e7:25:3e:f1). Managed or randomized MAC addresses should be excluded where possible
publicIpAddresses	string[]	The public IP addresses of the device, both IPv4 and IPv6	IP addresses that do not fall under private or reserved ranges
privateIpAddresses	string[]	The private IP addresses of the device, both IPv4 and IPv6	IP addresses that fall under private or reserved ranges
hostname	string	The hostname of the device, or the leaf node of the FQDN	Case should be preserved. This is just the hostname, not the FQDN. For example the output of hostname -s
fqdn	string	The fully qualified domain name of the device	Case should be preserved. This is the FQDN for the host. For example the output of hostname -f
serial	string	The serial number of the device	As close as possible to the BIOS serial number. For example the output of dmidecode -t system on Linux, ioreg -l \| grep IOPlatformSerialNumber on macOS, or wmic csproduct get uuid on Windows
deviceId	string[]	Other unique identifiers for the device
lastSeenOn	date	The last seen date of the device
make	string	The hardware make of the device	The hardware manufacturer for the device, such as Dell, HP, Lenovo, etc.
model	string	The hardware model of the device	The device model, such as PowerEdge R740, EliteBook 840 G3, ThinkPad X1 Carbon 7th, etc.
osName	string	The name of the operating system
osType	string	The type of the operating system
osDetails	string	The details of the operating system
osVersion	string	The version of the operating system
status	string	The status of the device

info

Only some of these properties are used for correlation, although where possible integrations and custom data uploads should include as many of these properties as possible.

Correlation and Unification

There are various weighted properties that are used to determine if two devices are the same. The most important property is the serial property, which has a very strong weighting to determine if two devices are the same.

Additional correlation properties include macAddresses, hostname, fqdn, privateIpAddresses, and publicIpAddresses.

It is possible to view the correlations either between two UnifiedDevice entities that have not been merged, or between the source Hosts and their UnifiedDevice representations.