Skip to main content

Entity relationship mapping

The JupiterOne data model stores entities and relationships that represent your organization's critical resources, their configurations, and the relationships they have to one another.


Relationships between entities may be derived from a system's APIs, and leveraging integrations within JupiterOne allows access to that information in order to establish those relationships between entities within your own JupiterOne workspace.

In other cases, relationships need to be inferred from properties common to a set of related entities. This inference can extend across entities from multiple systems so that relationships can be automatically mapped. In some cases, entities will be generated to represent a resource that doesn't exist as an explicit thing in your systems, but is implied, such as the Internet.

Entity relationship mappings provide the context necessary to support this automatic relationship building. To understand how these relationships are mapped, it is important to start by understanding JupiterOne's mapping rules. Becoming familiar with this concept will allow you to get more out of JupiterOne and your data, being able to:

  1. Recognize entities and relationships that are produced by mappings within data.
  2. Leverage the entities and relationships created by mappings within your JupiterOne queries.
  3. Identify where to add properties to existing entities in order to create inferred relationship mappings.

System mapper​

As entities are created and updated in JupiterOne, the system mapper will check to see if the entity matches a mapping rule. This newly created entity is considered the source of the relationship to be built. The target of the relationship is determined by performing a search according to the mapping's target filter parameters.

When more than one entity matches the target filter, a relationship is established between the source and each target entity. If no target is found, then no relationship will be created. A single target entity will be created when no existing entities match, unless skipTargetCreation: true.

Each mapping specifies the properties transferred to a target created by the mapper. The values of those properties may be static, being explicitly defined in the rule, or the values may be transferred from the source entity. When multiple mapping rules resolve to the same mapper-created target entity, the target entity will accumulate these properties. This allows for a target to include properties from any mapped source entity.

The mapper will produce operations to create, update, or delete the target entities and relationships it manages. The entities produced by the mapper may themselves match a mapping rule, leading to a cascading effect that builds a graph of relationships.

You can view entities created by the system-mapper within your JupiterOne workspace by running the following query:

FIND * WITH _source="system-mapper" LIMIT 10

Additionally, the query below will return relationships that have been created by the system-mapper:

FIND * THAT RELATES TO AS r Root
WHERE r._source="system-mapper"
RETURN r.* LIMIT 10

Example: Identifying Accounts That Belong to a Person​

Integrations with an identity provider have mapping rules, causing the mapper to produce a Person entity when the users of the IdP have properties that identify the record as a real person (and not a bot or service account). Once that Person entity exists, whenever a User entity is produced by any system, the User will be related to the Person as well when there are properties that identify the account with the Person, such as an email or username.

If you have an IdP integration configured, such as Okta or OneLogin, you may find user accounts that belong to a person:

FIND User AS u THAT RELATES TO Person AS p
RETURN u.email, u._type, u.displayName, p.employeeType
LIMIT 5

Relationship Mapping Rules​

Below is an example JSON representation of how the mapping rules are organized for a Person entity:

{
  "sourceFilter": {
    "_class": "Person"
  },
  "relationshipProperties": {
    "_class": "IS"
  },
  "relationshipDirection": "REVERSE",
  "targetFilterKeys": [
    ["_class", "email"],
    ["_class", "username"]
  ],
  "propertyMappings": [
    {
      "sourceProperty": "email",
      "targetProperty": "email"
    },
    {
      "sourceProperty": "email",
      "targetProperty": "username"
    },
    {
      "targetValue": "User",
      "targetProperty": "_class"
    }
  ],
  "skipTargetCreation": true
}

  • "sourceFilter": Declares the properties of the source entity that the rule matches

  • "relationshipProperties": Declares the properties to place on generated relationships

  • "relationshipDirection": Declares the directionality of the relationship

  • "targetFilterKeys": Declares the properties to query when resolving the target entities

  • "propertyMappings": Declares the properties to assign to target entities created by the mapper and provides the values used to search for the target entities

  • "skipTargetCreation": Instructs the mapper to avoid creating the target entity when none already exist

Mappings​

The Global Mappings apply to entities no matter how they are produced, whether by a managed integration or through the JupiterOne API. Each managed integration may also specify mappings that are applied only to entities managed by that integrations.

  • SOURCE is always the entity that triggers the mapping configuration. The label is the _class or _type that will be matched. Other match properties are listed in the summary body.
  • RELATIONSHIP is relative to SOURCE, and the label of comes from the _class.
    • Forward: -CLASS->
    • Reverse: <-CLASS-
  • TARGET is determined by a search, or one will be created when not found (unless skipTargetCreation: true). The label is the _class or _type that will be matched. Other match properties are listed in the summary body.
note

The summaries have a title taking the form SOURCE RELATIONSHIP TARGET.

It is important to remember:

  • Mapping rules are triggered when a SOURCE entity matches. Rules are NOT automatically reversed so that relationships are updated when a TARGET is created/updated.
  • Any change to the SOURCE entity triggers the mapping rule to be evaluated/re-evaluated.
  • The Source Filters must match an entity or the rule will not trigger. It may be necessary to add properties to entities at the data source so that when they are ingested they will match the rule.
  • A rule produces relationships to all TARGET entities matching the Target filters. It may be necessary to add properties to entities at the data source so that when they are ingested they will match the rule.
  • Transferred Properties are listed only when the mapper will create a target entity if none are found (skipTargetCreation: false).

Next steps​

For additional reference material outlining JupiterOne's mapping rules, refer to the following resources:

Contents