Search by relationship

Search for entities with specific attributes that are connected with each other to explore hypotheses, and to validate cyber threat intelligence models as you build them during an investigation.

About search by relationship

During an investigation, you may want to verify if specific type of entities have a relationship.
For example, you may want to explore if a threat actor is related to an incident or to a campaign to validate or to reject a hypothesis.

Search by relationship enables you to define specific search criteria for the entities, and it checks if the specified entities are related in the Intelligence Center.

About relationship queries

To express this type of search, we introduced a simple domain-specific language (DSL) syntax that the search input field can recognize and parse.
The relationship search DSL syntax expands on standard Intelligence Center search by adding syntax to express relationships between entities.

Format: ?()--()

  • Relationship search queries start with: ?

  • The arguments defining the search criteria for the entities whose relationships you want to explore are grouped in between round brackets: ()
    Entity search criteria between brackets comply with standard search in the Intelligence Center.

  • The relationship concept is represented by 2 consecutive hyphens in between the grouped entity criteria: --

    # Relationship query syntax
    ?(search_criteria_defining_entity_1)--(search_criteria_defining_entity_2)


    images/download/attachments/38962194/search_by_relationship.png

Search by relationship

To run a relationship search query:

  • In the side navigation bar click the search icon .

In the search input field, enter your relationship search query:

  1. Start the query with a question mark: ?

  2. Inside a pair of opening and closing round brackets, define the search criteria for the first entity using the standard search syntax for the Intelligence Center.
    For example: (data.type:indicator AND tags:["APT-X"])

  3. Add the relationship query element: --

  4. Inside a pair of opening and closing round brackets, define the search criteria for the second entity using the standard search syntax for the Intelligence Center.
    For example: (data.type:campaign AND sources.name:FireEye AND ingest_time:[now-7d TO *])

  5. Press ENTER on your keyboard.
    Returned entities are ordered in reverse chronological order based on their created_at timestamp.

Example

In this example, the relationship search query returns all indicator entity types tagged with APT-X that have a relationship with campaign entity types ingested from the FireEye data source, and that have been created in the course of the past week:

# Search by relationship example
?(data.type:indicator AND tags:["APT-X"])--(data.type:campaign AND sources.name:FireEye AND ingest_time:[now-7d TO *])

Restrictions

Currently, search by relationship has the following functionality limitations:

  • It is available only in the search input field.

  • Relational search queries can return max 5000 matches.
    If a relational search query yields more than 5000 results, only the first 5000 are actually returned.

  • Relational search queries look for relationships by analyzing the entities stored in the Intelligence Center.
    They can examine up to max 100 000 items for each entity in the query.
    If a relational search query reaches this upper limit for one or both entities in the query, it stops searching for the entity or entities whose cap is reached.