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.
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
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.
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
Derived Properties
Unified Devices have 3 additional properties that are derived from the source Device
and Host
entities, or their extended relationships in the graph. Each of these properties is available as a filter on the left hand side of the Unified view.
The derived properties rely on the relevant integrations to provide the required information. JupiterOne is continually reviewing integrations to ensure that all relevant properties are ingested where available. If you believe a property should be available for a specific integration please let us know!
Encrypted
This propery is a rollup of the encrypted
property from the source Device
and Host
entities. On a Host
or Device
this property should be a boolean value. On a UnifiedDevice
entity it will roll up to one of four values:
Encrypted if any of the source Device
or Host
entities have the encrypted
property set to true
, and there are no conflicting values
Not Encrypted if any of the source Device
or Host
entities have the encrypted
property set to false
, and there are no conflicting values
Conflicting if some of the source Device
or Host
entities have the encrypted
property set to true
and some are set to false
Unknown if none of the source Device
or Host
entities have the encrypted
property set, i.e. encrypted is undefined
for all sources
Managed
The managed
property is summary of the incoming relationships to the source Device
and Host
entities. If the Unified Device has any sources that have an incoming MANAGES
relationship it will be set to Managed
. If the Unified Device does not have any such sources the propery will be set to Not Managed
.
Managed if any of the source Device
or Host
entities have an incoming MANAGES
relationship.
Not Managed if none of the source Device
or Host
entities have an incoming MANAGES
relationship.
The J1QL equivalent for when this property is Managed
:
FIND UnifiedDevice
THAT IS (Device|Host)
THAT MANAGES *
To find the specific sources that contribute to a Unified Device's Managed status, you can use the following J1QL query:
FIND UnifiedDevice WTIH _id = <The _id of the UnifiedDevice>
THAT IS (Device|Host)
THAT MANAGES *
RETURN TREE
Protected
The protected
property is summary of the incoming relationships to the source Device
and Host
entities. If the Unified Device has any sources that have an incoming PROTECTS
relationship it will be set to Protected
. If the Unified Device does not have any such sources the propery will be set to Not Protected
.
Protected if any of the source Device
or Host
entities have an incoming PROTECTS
relationship.
Not Protected if none of the source Device
or Host
entities have an incoming PROTECTS
relationship.
The J1QL equivalent for when this property is Protected
:
FIND UnifiedDevice
THAT IS (Device|Host)
THAT PROTECTS *
To find the specific sources that contribute to a Unified Device's Protected status, you can use the following J1QL query:
FIND UnifiedDevice WTIH _id = <The _id of the UnifiedDevice>
THAT IS (Device|Host)
THAT PROTECTS *
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:
- Creation: The
UnifiedDevice
entity is created from the sourceHost
andDevice
entities. - Correlation: The
UnifiedDevice
entity is correlated with otherUnifiedDevice
entities. - 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 |
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.