Entities

Entities are intelligence objects that are used to record and convey information about a given intelligence target. Each Entity is a self-contained unit of information that can reference or be connected to other Entities or Observables through relationships.

Get started

This guide uses the example API client at https://github.com/zed-eiq/eiq_simpleclient_demo.

To get started:

1. Install the eiq_simpleclient_demo library with pip.
2. Initialize the APIClient object with your Intelligence Center URL and API key.

Retrieve entities

First, we'll retrieve an entity to see its structure.

You can retrieve an entity with:

• GET /entities
• GET /entities/{id}

Making a GET /entities request retrieves a list of entities:

Making a GET /entities/{id} request retrieves a single entity data object:

✅

{id} can be the value of an entity's .id field (e.g. 761e9c9a-eeaa-4770-b78e-37783b02783b) or .data.id field (e.g. {https://www.eclecticiq.com/ns}indicator-a8b9f982-39c0-44d4-97fe-b54c10813a01). See Entity IDs below.

Data envelope

All data exchanged with the IC REST API is contained inside a .data envelope:

{
  'count': <number_of_objects_in_response_int>,
  'data': <objects>,
  'limit': <page_size_int>,
  'offset': <page_offset_int>,
  'total_count': <total_number_of_objects_available_int>
}

To keep things short, we'll only be addressing the data contained in the .data field when referring to an object's data.

For example, given the response below:

{
  'count': 1,
  'data': { 
      'data': {
        'title': 'http://117.201.34.54:35392/Mozi.m'
      },
      'id': '761e9c9a-eeaa-4770-b78e-37783b02783b'
    },
  'limit': 100,
  'offset': 0,
  'total_count': 1
}

we would refer to the title field by writing .data.title instead of .data.data.title.

What's in an entity

✅

Entity permissions

You need read entities to view entities, and modify entities to create, modify, and delete entitiies.

Entities may also contain embedded objects that require additional permissions to access or modify. For example, you need read intel-sets to be able to access the objects in the .datasets[] field of a given entity.

For more information, see User permissions.

Entity objects contain a range of information that can contain intelligence or describe the state of that intelligence. In this section, we'll cover a few properties to pay attention to when working with entities.

Entity Title and description

The .data.title field of an entity is what is displayed in the IC when searching for entities or working with entities in a graph.

data.title can contain any text, but usually contains the value of the intelligence object the entity represents. For example, to describe a malicious URL (http://malicious.example.com), we can create an indicator entity and set

"data": {
  "title": "http://mailicious.example.com"}
}

.data.description is a free-form text field that can contain content that describes the intelligence represented by this entity. This content may be written as plain-text or HTML. HTML-formatted content in the description field is rendered when viewing the entity in the IC UI.

Entity IDs

Entities have two ID fields:

• .id values are always assigned by the IC, and used to internally identify the entity in the IC.
• .data.id values are meant to be globally unique identifiers that can be used to reference entities when shared outside of the IC they originate from. These values are assigned by the IC when a value is not specified during entity creation.

✅

.data.id values are designed to contain the same information as qualified names used in the STIX 1.2 Common Data Model.

You can use either IDs when retrieving entities using the GET /entities/{id} endpoint.

The eiq_simpleclient library provides a helper method to construct STIX-like IDs

Entity types

Entities have a primary type.

An entity's type is analogous to the components of the STIX 1.2 Data Model.

Entities have the following possible types: