Working with entities

Working with entities

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.
# Install the demo REST API client from https://github.com/zed-eiq/eiq_simpleclient_demo
!python -m pip install -U git+https://github.com/zed-eiq/eiq_simpleclient_demo.git --quiet
  Building wheel for eiq-simpleclient-demo (setup.py) ... 
# Set up dependencies and connection to Intelligence Center (IC) host
from eiq_simpleclient import APIClient
from pprint import pprint as pp
from getpass import getpass

# Add new client to access zed's TIP
BASEURL = "https://ic-playground.eclecticiq.com/api/beta"
APIKEY = getpass("Enter your API key:")
client = APIClient(BASEURL, APIKEY)
··········

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:

client.get("entities", {"limit": 1})
{'count': 1,
 'data': [{'attachments': [],
   'created_at': '2022-04-08T03:42:39.267484+00:00',
   'data': {'confidence': 'medium',
    'description': "<p>Status: online</p>\n                             <p>Observed Time: 2021-07-18 01:35:06</p>\n                             <p>Blacklist: {'spamhaus_dbl': 'not listed', 'surbl': 'not listed'}</p>",
    'id': '{https://www.eclecticiq.com/ns}indicator-a8b9f982-39c0-44d4-97fe-b54c10813a01',
    'producer': {'description': 'URL Haus by abuse.ch',
     'identity': 'lrz_urlhaus',
     'references': ['https://urlhaus.abuse.ch/url/1462665/'],
     'roles': ['Initial Author'],
     'type': 'information-source'},
    'timestamp': '2021-07-18T02:01:34.076807+00:00',
    'title': 'http://117.201.34.54:35392/Mozi.m'},
   'id': '761e9c9a-eeaa-4770-b78e-37783b02783b',
   'last_updated_at': '2022-04-08T03:42:39.249766+00:00',
   'meta': {'estimated_observed_time': '2021-07-18T01:35:06+00:00',
    'estimated_threat_end_time': None,
    'estimated_threat_start_time': '2021-07-18T01:35:06+00:00',
    'half_life': 30,
    'source_reliability': 'B',
    'tags': ['elf', 'Mozi', 'malware_download', 'online'],
    'tlp_color': 'WHITE'},
   'observables': ['https://ic-playground.eclecticiq.com/api/beta/observables/7072653',
    'https://ic-playground.eclecticiq.com/api/beta/observables/7072652'],
   'relevancy': 0.002045496333634036,
   'sources': ['https://ic-playground.eclecticiq.com/api/beta/sources/f533dc6b-98e7-4bdd-8326-570093f0e191'],
   'type': 'indicator'}],
 'limit': 1,
 'offset': 0,
 'total_count': 5641018}

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.

# Retrieve one entity with GET /entities/{id}
client.get("entities/{}".format("{https://www.eclecticiq.com/ns}indicator-a8b9f982-39c0-44d4-97fe-b54c10813a01"))
{'data': {'attachments': [],
  'created_at': '2022-04-08T03:42:39.267484+00:00',
  'data': {'confidence': 'medium',
   'description': "<p>Status: online</p>\n                             <p>Observed Time: 2021-07-18 01:35:06</p>\n                             <p>Blacklist: {'spamhaus_dbl': 'not listed', 'surbl': 'not listed'}</p>",
   'id': '{https://www.eclecticiq.com/ns}indicator-a8b9f982-39c0-44d4-97fe-b54c10813a01',
   'producer': {'description': 'URL Haus by abuse.ch',
    'identity': 'lrz_urlhaus',
    'references': ['https://urlhaus.abuse.ch/url/1462665/'],
    'roles': ['Initial Author'],
    'type': 'information-source'},
   'timestamp': '2021-07-18T02:01:34.076807+00:00',
   'title': 'http://117.201.34.54:35392/Mozi.m'},
  'id': '761e9c9a-eeaa-4770-b78e-37783b02783b',
  'last_updated_at': '2022-04-08T03:42:39.249766+00:00',
  'meta': {'estimated_observed_time': '2021-07-18T01:35:06+00:00',
   'estimated_threat_end_time': None,
   'estimated_threat_start_time': '2021-07-18T01:35:06+00:00',
   'half_life': 30,
   'source_reliability': 'B',
   'tags': ['elf', 'Mozi', 'malware_download', 'online'],
   'tlp_color': 'WHITE'},
  'observables': ['https://ic-playground.eclecticiq.com/api/beta/observables/7072652',
   'https://ic-playground.eclecticiq.com/api/beta/observables/7072653'],
  'relevancy': 0.002045496333634036,
  'sources': ['https://ic-playground.eclecticiq.com/api/beta/sources/f533dc6b-98e7-4bdd-8326-570093f0e191'],
  'type': 'indicator'}}

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:

Field nameDescription
.idAn entity's internal UUID.
.data.idThis is an entity's STIX-like ID.

A STIX-like ID looks like this: {http://www.alienvault.com}Indicator-1b482840-b3f0-51c8-9011-9d189bcf4f55
  • .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

client.make_id("namespace-uri.example.com", "entity_type", "title_of_entity")
{"type":"string"}

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:

TypeDescription
IndicatorAn arbitrary piece of information, such as an Email address, domain name, or an IPv4 address.
Threat ActorA threat actor.
TTPTechniques, Tactics, and Procedures (TTP) observed in a given context.
CampaignA set of intelligence that share a common intent or desired effect.
Exploit TargetA vulnerability or weakness in a given technical target such as software, hardware, or networks.
IncidentA cybersecurity incident.
Course of ActionMitigations taken or a response to a possible or actual attack.
ReportShared context around a set of intelligence. Used by analysts to present their research.
SightingAn instance where one or more intelligence targets (e.g., Indicators, Observables) have been observed in a given context.