Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
JupiterOne Data Model - AskJ1 Community
<main> <article class="userContent"> <p>The <strong>JupiterOne Data Model</strong> is a reference model used to describe digital resources and the complex interconnections among all the resources in a technology organization as an <strong>entity-relationship graph</strong>.</p> <p>The data model is defined by a set of Entities and their Relationships. It represents a reference model, not a strict or rigid structure.</p> <h2 data-id="entity">Entity</h2> <p>An Entity is a node/vertex in the graph that represents a resource within your digital infrastructure.</p> <p>See the full data model schema in this <a rel="nofollow" href="https://github.com/JupiterOne/data-model">GitHub repo</a>.</p> <h3 data-id="class-and-type-of-an-entity">Class and Type of an Entity</h3> <p>Each Entity has a specific <strong>type</strong> that defines what that entity is, and is assigned one or more higher level <strong>class</strong> that represents a more abstract categorization or labeling of the entity in the perspective of security and technical operations.</p> <h4 data-id="type">Type</h4> <p>The <strong>type</strong> property represents the specific type that entity is as defined by the source. For example, an AWS resource may be of type <code class="code codeInline" spellcheck="false" tabindex="0">aws_instance</code> or <code class="code codeInline" spellcheck="false" tabindex="0">aws_s3_bucket</code> or <code class="code codeInline" spellcheck="false" tabindex="0">aws_iam_user</code>.</p> <h4 data-id="class">Class</h4> <p>The <strong>class</strong> of an entity is considered an abstract, super-type that defines what that entity is within the general framework of IT and security operations. In the above example, an <code class="code codeInline" spellcheck="false" tabindex="0">aws_instance</code> entity has a class of <code class="code codeInline" spellcheck="false" tabindex="0">Host</code>, while an <code class="code codeInline" spellcheck="false" tabindex="0">aws_s3_bucket</code> is a <code class="code codeInline" spellcheck="false" tabindex="0">DataStore</code>, and an <code class="code codeInline" spellcheck="false" tabindex="0">aws_iam_user</code> a <code class="code codeInline" spellcheck="false" tabindex="0">User</code>.</p> <h3 data-id="common-entity-properties">Common Entity Properties</h3> <p>Most Entities will have the following common properties:</p> <p><br></p> <p></p><details><summary>Common Entity Properties</summary><pre class="code codeBlock" spellcheck="false" tabindex="0">Property | Type | Description --------- | -------- | ------------ `id` | `string`,`array` | Identifiers of this entity assigned by the providers. Values are expected to be unique within the provider scope. `name` | `string` | Name of this entity `displayName` | `string` | Display name, e.g. a person's preferred name or an AWS account alias `summary` | `string` | A summary / short description of this entity. `description` | `string` | An extended description of this entity. `classification` | `string`,`null` | The sensitivity of the data; should match company data classification scheme `criticality` | `integer` | A number that represents the value or criticality of this entity, on a scale between 1-10. `risk` | `integer` | The risk level of this entity, on a scale between 1-10. `trust` | `integer` | The trust level of this entity, on a scale between 1-10. `complianceStatus` | `number` | The compliance status of the entity, as a percentage of compliancy. `status` | `string` | Status of this entity set by the external source system or by a user, e.g. Active, Inactive, Decommissioned `active` | `boolean` | Indicates if this entity is currently active. `public` | `boolean` | Indicates if this is a public-facing resource (e.g. a public IP or public DNS record) or if the entity is publicly accessible. Default is false. `validated` | `boolean` | Indicates if this node has been validated as a known/valid Entity. `temporary` | `boolean` | Indicates if this node is a temporary resource, such as a lambda instance or an EC2 instance started by ECS. `trusted` | `boolean` | Indicates if this is a trusted resource. For example, a trusted Network, Host, Device, Application, Person, User, or Vendor. `createdOn` | `number` | The timestamp (in milliseconds since epoch) when the entity was created at the source. This is different than `_createdOn` which is the timestamp the entity was first ingested into JupiterOne. `updatedOn` | `number` | The timestamp (in milliseconds since epoch) when the entity was last updated at the source. `deletedOn` | `number` | The timestamp (in milliseconds since epoch) when the entity was deleted at the source. `discoveredOn` | `number` | The timestamp (in milliseconds since epoch) when the entity was discovered. `expiresOn` | `number` | If the entity is a temporary resource, optionally set the expiration date. For example, the expiration date of an SSL cert. `createdBy` | `string` | The source/principal/user that created the entity `updatedBy` | `string` | The source/principal/user that updated the entity `deletedBy` | `string` | The source/principal/user that deleted the entity `discoveredBy` | `string` | The source/principal/user that discovered the entity `webLink` | `string` | Web link to the source. For example: https://console.aws.amazon.com/iam/home#/roles/Administrator. This property is used by the UI to add a hyperlink to the entity. `owner` | `string` | The owner of this entity. This could reference the name of the owner, or as reference ID/key to another entity in the graph as the owner. `tags` | `array` | An array of unnamed tags `notes` | `array` | User provided notes about this entity </pre> <p></p></details><br><h3 data-id="class-specific-entity-properties">Class Specific Entity Properties</h3> <p>Each specific class of Entity also has its own defined properties. For example, a <code class="code codeInline" spellcheck="false" tabindex="0">Person</code> entity will have properties including <code class="code codeInline" spellcheck="false" tabindex="0">firstName</code> and <code class="code codeInline" spellcheck="false" tabindex="0">lastName</code>, while a <code class="code codeInline" spellcheck="false" tabindex="0">Device</code> entity may have properties such as <code class="code codeInline" spellcheck="false" tabindex="0">hardwareVendor</code>, <code class="code codeInline" spellcheck="false" tabindex="0">hardwareModel</code>, and <code class="code codeInline" spellcheck="false" tabindex="0">hardwareSerial</code>.</p> <h3 data-id="custom-properties">Custom Properties</h3> <p>Entities can also have custom properties that are specific to the type of that entity, defined by the source system where the resource belongs to, or defined by the individual or team managing the resource.</p> <h3 data-id="defined-entities">Defined Entities</h3> <p>Here is a list of reference entities defined by the JupiterOne Data Model, each with its own defined set of properties in addition to the shared common properties:</p> <p><br></p> <p></p><details><summary>Defined Entities Table</summary><pre class="code codeBlock" spellcheck="false" tabindex="0">Entity | Description ------ | ----------- `AccessKey` | A key used to grant access, such as ssh-key, access-key, api-key/token, mfa-token/device, etc. `AccessPolicy` | A policy for access control assigned to a Host, Role, User, UserGroup, or Service. `AccessRole` | An access control role mapped to a Principal (e.g. user, group, or service). `Account` | An organizational account for a service or a set of services (e.g. AWS, Okta, Bitbucket Team, Google G-Suite account, Apple Developer Account). Each Account should be connected to a Service. `Application` | A software product or application. `ApplicationEndpoint` | An application endpoint is a program interface that either initiates or receives a request, such as an API. `Assessment` | An object to represent an assessment, including both compliance assessment such as a HIPAA Risk Assessment or a technical assessment such as a Penetration Testing. Each assessment should have findings (e.g. Vulnerability or Risk) associated. `Attacker` | An attacker or threat actor. `Backup` | A specific repository or data store containing backup data. `Certificate` | A digital Certificate such as an SSL or S/MIME certificate. `Channel` | A communication channel, such as a Slack channel or AWS SNS topic. `Cluster` | A cluster of compute or database resources/workloads. `CodeCommit` | A code commit to a repo. The commit id is captured in the _id property of the Entity. `CodeDeploy` | A code deploy job. `CodeModule` | A software module. Such as an npm_module or java_library. `CodeRepo` | A source code repository. A CodeRepo is also a DataRepository therefore should carry all the required properties of DataRepository. `CodeReview` | A code review record. `Configuration` | A Configuration contains definitions that describe a resource such as a Task, Deployment or Workload. For example, an `aws_ecs_task_definition` is a `Configuration`. `Container` | A standard unit of software that packages up code and all its dependencies and configurations. `Control` | A security or IT Control. A control can be implemented by a vendor/service, a person/team, a program/process, an automation code/script/configuration, or a system/host/device. Therefore, this is most likely an additional Class applied to a Service (e.g. Okta SSO), a Device (e.g. a physical firewall), or a HostAgent (e.g. Carbon Black CbDefense Agent). Controls are mapped to security policy procedures and compliance standards/requirements. `ControlPolicy` | An technical or operational policy with rules that govern (or enforce, evaluate, monitor) a security control. `CryptoKey` | A key used to perform cryptographic functions, such as an encryption key. `DataObject` | An individual data object, such as an aws-s3-object, sharepoint-document, source-code, or a file (on disk). The exact data type is described in the _type property of the Entity. `DataStore` | A virtual repository where data is stored, such as aws-s3-bucket, aws-rds-cluster, aws-dynamodb-table, bitbucket-repo, sharepoint-site, docker-registry. The exact type is described in the _type property of the Entity. `Database` | A database cluster/instance. `Deployment` | A deployment of code, application, infrastructure or service. For example, a Kubernetes deployment. An auto scaling group is also considered a deployment. `Device` | A physical device or media, such as a server, laptop, workstation, smartphone, tablet, router, firewall, switch, wifi-access-point, usb-drive, etc. The exact data type is described in the _type property of the Entity. `Directory` | Directory, such as LDAP or Active Directory. `Disk` | A disk storage device such as an AWS EBS volume `Document` | A document or data object. `Domain` | An internet domain. `DomainRecord` | The DNS Record of a Domain Zone. `DomainZone` | The DNS Zone of an Internet Domain. `Finding` | A security finding, which may be a vulnerability or just an informative issue. A single finding may impact one or more resources. The `IMPACTS` relationship between the Vulnerability and the resource entity that was impacted serves as the record of the finding. The `IMPACTS` relationship carries properties such as 'identifiedOn', 'remediatedOn', 'remediationDueOn', 'issueLink', etc. `Firewall` | A piece of hardware or software that protects a network/host/application. `Framework` | An object to represent a standard compliance or technical security framework. `Function` | A virtual application function. For example, an aws_lambda_function, azure_function, or google_cloud_function `Gateway` | A gateway/proxy that can be a system/appliance or software service, such as a network router or application gateway. `Group` | A defined, generic group of Entities. This could represent a group of Resources, Users, Workloads, DataRepositories, etc. `Host` | A compute instance that itself owns a whole network stack and serves as an environment for workloads. Typically it runs an operating system. The exact host type is described in the _type property of the Entity. The UUID of the host should be captured in the _id property of the Entity `HostAgent` | A software agent or sensor that runs on a host/endpoint. `Image` | A system image. For example, an AWS AMI (Amazon Machine Image). `Incident` | An operational or security incident. `Internet` | The Internet node in the graph. There should be only one Internet node. `IpAddress` | An re-assignable IpAddress resource entity. Do not create an entity for an IP Address _configured_ on a Host. Use this only if the IP Address is a reusable resource, such as an Elastic IP Address object in AWS. `Key` | An ssh-key, access-key, api-key/token, pgp-key, etc. `Logs` | A specific repository or destination containing application, network, or system logs. `Module` | A software or hardware module. Such as an npm_module or java_library. `Network` | A network, such as an aws-vpc, aws-subnet, cisco-meraki-vlan. `NetworkEndpoint` | A network endpoint for connecting to or accessing network resources. For example, NFS mount targets or VPN endpoints. `NetworkInterface` | An re-assignable software defined network interface resource entity. Do not create an entity for a network interface _configured_ on a Host. Use this only if the network interface is a reusable resource, such as an Elastic Network Interface object in AWS. `Organization` | An organization, such as a company (e.g. JupiterOne) or a business unit (e.g. HR). An organization can be internal or external. Note that there is a more specific Vendor class. `PR` | A pull request. `PasswordPolicy` | A password policy is a specific `Ruleset`. It is separately defined because of its pervasive usage across digital environments and the well known properties (such as length and complexity) unique to a password policy. `Person` | An entity that represents an actual person, such as an employee of an organization. `Policy` | A written policy documentation. `Procedure` | A written procedure and control documentation. A Procedure typically `IMPLEMENTS` a parent Policy. An actual Control further `IMPLEMENTS` a Procedure. `Process` | A compute process -- i.e. an instance of a computer program / software application that is being executed by one or many threads. This is NOT a program level operational process (i.e. a Procedure). `Product` | A product developed by the organization, such as a software product. `Program` | A program. For example, a bug bounty/vuln disclosure program. `Project` | A software development project. Can be used for other generic projects as well but the defined properties are geared towards software development projects. `Queue` | A scheduling queue of computing processes or devices. `Record` | A DNS record; or an official record (e.g. Risk); or a written document (e.g. Policy/Procedure); or a reference (e.g. Vulnerability/Weakness). The exact record type is captured in the _type property of the Entity. `Repository` | A repository that contains resources. For example, a Docker container registry repository hosting Docker container images. `Requirement` | An individual requirement for security, compliance, regulation or design. `Resource` | A generic assignable resource. A resource is typically non-functional by itself unless used by or attached to a host or workload. `Review` | A review record. `Risk` | An object that represents an identified Risk as the result of an Assessment. The collection of Risk objects in JupiterOne make up the Risk Register. A Control may have a `MITIGATES` relationship to a Risk. `Root` | The root node in the graph. There should be only one Root node per organization account. `Rule` | An operational or configuration compliance rule, often part of a Ruleset. `Ruleset` | An operational or configuration compliance ruleset with rules that govern (or enforce, evaluate, monitor) a security control or IT system. `Scanner` | A system vulnerability, application code or network infrastructure scanner. `Section` | An object to represent a section such as a compliance section. `Service` | A service provided by a vendor. `Site` | The physical location of an organization. A Person (i.e. employee) would typically has a relationship to a Site (i.e. located_at or work_at). Also used as the abstract reference to AWS Regions. `Standard` | An object to represent a standard such as a compliance or technical standard. `Subscription` | A subscription to a service or channel. `Task` | A computational task. Examples include AWS Batch Job, ECS Task, etc. `Team` | A team consists of multiple member Person entities. For example, the Development team or the Security team. `ThreatIntel` | Threat intelligence captures information collected from vulnerability risk analysis by those with substantive expertise and access to all-source information. Threat intelligence helps a security professional determine the risk of a vulnerability finding to their organization. `Training` | A training module, such as a security awareness training or secure development training. `User` | A user account/login to access certain systems and/or services. Examples include okta-user, aws-iam-user, ssh-user, local-user (on a host), etc. `UserGroup` | A user group, typically associated with some type of access control, such as a group in Okta or in Office365. If a UserGroup has an access policy attached, and all member Users of the UserGroup would inherit the policy. `Vault` | A collection of secrets such as a key ring `Vendor` | An external organization that is a vendor or service provider. `Vulnerability` | A security vulnerability (application or system or infrastructure). A single vulnerability may relate to multiple findings and impact multiple resources. The `IMPACTS` relationship between the Vulnerability and the resource entity that was impacted serves as the record of the finding. The `IMPACTS` relationship carries properties such as 'identifiedOn', 'remediatedOn', 'remediationDueOn', 'issueLink', etc. `Weakness` | A security weakness. `Workload` | A virtual compute instance, it could be an aws-ec2-instance, a docker-container, an aws-lambda-function, an application-process, or a vmware-instance. The exact workload type is described in the _type property of the Entity. </pre> <p></p></details><br><h4 data-id="special-entities">Special Entities</h4> <p>There are three special entities defined. These are singleton entities.</p> <table><thead><tr><th>Entity</th> <th>Description</th> </tr></thead><tbody><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">Everyone</code></td> <td>The global <code class="code codeInline" spellcheck="false" tabindex="0">UserGroup</code> that represents "everyone" publicly.</td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">Internet</code></td> <td>The Internet -- i.e. a <code class="code codeInline" spellcheck="false" tabindex="0">Network</code> entity with CIDR <code class="code codeInline" spellcheck="false" tabindex="0">"0.0.0.0/0"</code>.</td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">Root</code></td> <td>The entity that represents the top level organization.</td> </tr></tbody></table><h2 data-id="relationships">Relationships</h2> <p>A relationship is the edge between two entity nodes in the graph. The <code class="code codeInline" spellcheck="false" tabindex="0">_class</code> of the relationship should be, in most cases, a generic descriptive verb, such as <code class="code codeInline" spellcheck="false" tabindex="0">HAS</code> or <code class="code codeInline" spellcheck="false" tabindex="0">IMPLEMENTS</code>.</p> <p>Relationships can also carry their own properties.</p> <p>For example, <code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo -- DEPLOYED TO -> Host</code> may have <code class="code codeInline" spellcheck="false" tabindex="0">version</code> as a property on the <code class="code codeInline" spellcheck="false" tabindex="0">DEPLOYED</code> relationship. This represents the mapping between a code repo to multiple deployment targets, while one deployment may be of a different version of the code than another. Storing the version as a relationship<br> property allows us to avoid duplicate instances of the code repo entity to be created to represent different versions.</p> <p>Relationships have the same metadata properties as entities, which are managed by the integration providers.</p> <h3 data-id="example-defined-relationships-between-abstract-entity-classes">Example defined Relationships between abstract Entity Classes</h3> <h4 data-id="has-contains">HAS / CONTAINS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Account -- HAS -> User Account -- HAS -> UserGroup Account -- HAS -> AccessRole Account -- HAS -> Resource CodeRepo -- HAS -> Vulnerability Host -- HAS -> Vulnerability Organization -- HAS -> Site Organization -- HAS -> Organization (e.g. a business unit) Application -- HAS -> Vulnerability CodeRepo -- HAS -> Vulnerability Host -- HAS -> Vulnerability Service -- HAS -> Vulnerability Site -- HAS -> Network Site -- HAS -> Site UserGroup -- HAS -> User Network -- CONTAINS -> Host Network -- CONTAINS -> Database Network -- CONTAINS -> Network (e.g. a subnet) </pre> <h4 data-id="is-owns">IS / OWNS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">User -- IS -> Person Vulnerability -- IS -> Vulnerability (e.g. a Snyk Vuln IS a CVE) Person -- OWNS -> Device </pre> <h4 data-id="exploits-impacts">EXPLOITS / IMPACTS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Vulnerability -- EXPLOITS -> Weakness Vulnerability -- IMPACTS -> CodeRepo | Application </pre> <h4 data-id="uses">USES</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Host -- USES -> Resource (e.g. aws_instance USES aws_ebs_volume) </pre> <h4 data-id="connects-triggers-extends">CONNECTS / TRIGGERS / EXTENDS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Application -- CONNECTS -> Account Gateway -- CONNECTS -> Network Gateway -- TRIGGERS -> Function HOST -- EXTENDS -> Resource </pre> <h4 data-id="implements-mitigates">IMPLEMENTS / MITIGATES</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Procedure -- IMPLEMENTS -> Policy Control -- IMPLEMENTS -> Policy Control -- MITIGATES -> Risk </pre> <h4 data-id="manages">MANAGES</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Person -- MANAGES -> Person Person -- MANAGES -> Organization Person -- MANAGES -> Team User -- MANAGES -> Account User -- MANAGES -> UserGroup ControlPolicy -- MANAGES -> Control AccessPolicy -- MANAGES -> AccessRole </pre> <h4 data-id="evaluates-monitors-protects">EVALUATES / MONITORS / PROTECTS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">ControlPolicy -- EVALUATES -> <any entity> HostAgent -- MONITORS -> Host HostAgent -- PROTECTS -> Host </pre> <h4 data-id="trusts">TRUSTS</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">AccessRole -- TRUSTS -> AccessRole AccessRole -- TRUSTS -> Service AccessRole -- TRUSTS -> Account </pre> <h4 data-id="assigned">ASSIGNED</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">User -- ASSIGNED -> Application User -- ASSIGNED -> AccessRole UserGroup -- ASSIGNED -> AccessRole </pre> <h4 data-id="identified-performed-completed">IDENTIFIED / PERFORMED / COMPLETED</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Person -- PERFORMED -> Assessment Person -- COMPLETED -> Training Assessment -- IDENTIFIED -> Risk Assessment -- IDENTIFIED -> Vulnerability </pre> <h4 data-id="provides">PROVIDES</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">Vendor -- PROVIDES -> Service </pre> <h4 data-id="contributes-to">CONTRIBUTES TO</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">User -- CONTRIBUTES TO -> CodeRepo </pre> <h4 data-id="opened">OPENED</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">User -- OPENED -> CodeReview (i.e. PR) </pre> <h4 data-id="deployed-to">DEPLOYED TO</h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">CodeRepo -- DEPLOYED TO -> Account CodeRepo -- DEPLOYED TO -> Host CodeRepo -- DEPLOYED TO -> Container CodeRepo -- DEPLOYED TO -> Function </pre> <h2 data-id="what-does-this-look-like">What does this look like?</h2> <p>The diagram below is an abstract illustration of the entities and relationships<br> defined by the data model.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/D1Q9NYFV14BL/data-model.png" alt="data-model" class="embedImage-img importedEmbed-img"></img></p> </article> </main>
.png)