Search query syntax#
Basic operators and syntax#
Search fields in EclecticIQ Intelligence Center use the Elasticsearch DSL query syntax unless otherwise specified.
Query syntax element |
Description |
---|---|
|
Boolean operator between filters. |
|
Boolean operator between filters. |
|
Boolean operator between filters. |
|
Use double quotes to group multiple search entries into one single search string. The search query looks for matches for the string as one token. |
|
Searches for words containing criteria. Use the |
|
Searches for words containing criteria. Use the |
|
Searches for similar words. Fuzzy search. |
|
Use the |
|
Prefix |
|
Prefix |
|
Searches using Elasticsearch DSL query syntax regular expressions. |
Wildcards#
Currently supported wildcards:
*
and?
Escape character:
\
Avoid starting a wildcard query term with
*
or?
, as it may result in an extremely slow-running query.Search and rules use literal values and regex patterns to look for matching values assigned to the corresponding JSON path fields.
Example
Use Boolean operators and wildcards to create more refined searches.
enrichment_extracts.kind:domain AND enrichment_extracts.meta.classification:high
Search for entities#
Search for entiites by going to Search > Go to search and browse > Observables.
Tip
You can search for entities by querying the observables they
are connected to.
See the extracts
or meta.bundled_extracts
keywords
in the Entity attributes table below.
Entity attributes#
The table below lists common attributes you can use to search for entities.
Tip
There are more granular attributes you can search with. Use the search bar’s autocomplete to help you find attributes to use, see individual entity documentation for more information.
Query key |
Looks for |
Query value examples |
---|---|---|
|
Entities whose creation date matches the specified pattern or literal. |
|
|
Entities whose user ID integer value matches the specified pattern or literal. |
|
|
Entities whose observable maliciousness confidence value matches the specified pattern or literal. |
|
|
Entities whose kill chain phase name matches the specified pattern or literal. |
|
|
Entities whose official or standard name matches the specified pattern or literal. |
|
|
Entities whose integer order value matches the specified pattern or literal. This value defines the order of a kill chain phase within a kill chain. |
|
|
Entities with at least an observable whose title/header matches the specified pattern or literal. |
|
|
Entities whose data producer name matches the specified pattern or literal. The Entity per producer gauge on the dashboard used this field to display the total amount of ingested entities, based on the corresponding producer. |
|
|
Entities whose creation time at the data producer matches the specified pattern or literal. Fractions of seconds are optional and may not always be included in the time value. Input format: Description: year, month, day, hour, T (the date and time separator), minutes, seconds, time zone |
|
|
Entities whose reception time at the data producer matches the specified pattern or literal. Fractions of seconds are optional and may not always be included in the time value. Input format: Description: year, month, day, hour, T (the date and time separator), minutes, seconds, time zone |
|
|
Entities with at least an observable that has actually been sighted. This is a counter whose integer value reports the number of sightings recorded for the corresponding observable. |
|
|
Entities whose data creation time matches the specified pattern or literal. Fractions of seconds are optional and may not always be included in the time value. Input format: Description: year, month, day, hour, T (the date and time separator), minutes, seconds, time zone |
|
|
Entity type. See Table of possible entity types. |
|
|
Entities with at least an observable that has actually been sighted. When entities are associated with a sighting, they are exposed. Entities with |
|
|
Entities whose data source reliability matches the specified pattern or literal. |
|
|
Entities whose TLP color matches the specified pattern or literal. |
|
|
Entities whose custom tag values match the specified pattern or literal. |
|
|
Entities whose custom tag and standard taxonomy values match the specified pattern or literal. |
|
Table of possible entity types:
Entity type |
JSON value |
---|---|
Attack Pattern |
|
Campaign |
|
Course of Action |
|
Exploit target |
|
Sighting |
|
Identity |
|
Indicator |
|
Incident |
|
Infrastructure |
|
Intrusion set |
|
Location |
|
Malware |
|
Malware analysis |
|
Report |
|
Threat actor |
|
Tactics, Techniques, Procedures |
|
Tool |
|
Search entities by observables#
Entities can have embedded observables. These are usually entities and observables ingested through incoming feeds.
You can search for entities that are directly related
to or embed certain observables by
using the extracts
or enrichment_extracts
keyword.
See Search for observables for a list of attributes to use with these keywords.
E.g. To search for entities containing an extract with an ID of 4
:
extracts.id: 4
Search entities by outgoing feeds#
Outgoing feeds are indexed as destinations
. Search for
entities and observables published through an outgoing feed
based on the feed name, type, or ID.
Query key |
Description |
---|---|
|
Outgoing feed name. Example: Note
|
|
Outgoing feed transport type. Example: `destinations.type: “TAXII Poll” |
|
(Deprecated. Search using UUID of outgoing feed. To find the UUID of an outgoing
feed, make a request to the Tip Outgoing feeds have two IDs:
To find the UUID of an outgoing feed:
|
Search for observables#
Search for observables by going to Search > Go to search and browse > Observables.
Observables are indexed and searchable using the
extracts
and enrichment_extracts
keywords.
Tip
enrichment_extracts
are extracts created as a result
of running an enricher.
When searching for observables in
Search > Go to search and browse > Observables,
you can omit the extracts
keyword
and search directly using attributes.
E.g. To search for an observable with an ID of 4
:
id: 4
Observable attributes#
The table below lists common attributes you can use to search observables with.
Entity JSON path |
Description |
Example values |
---|---|---|
|
Unique ID of observable. |
|
|
Entities with at least an observable whose value matches the specified pattern or literal. The |
|
|
Entities with at least an observable whose data type matches the specified pattern or literal. |
|
|
Confidence assigned to an observable.
Used together with |
|
|
Classification assigned to an observable.
Used together with |
|
|
Whether or not an observable has been ignored by an Observable rules. |
|
Observables by link name#
Use link names to search for specific observables, based on the type of relationship they have with their parent entity.
The type of relationship between an observable and and entity adds context, and it can help understand the function of the observable within the broader threat landscape it belongs to.
Let’s assume that an analyst is investigating a threat scenario where a threat actor exploits the CVE-2017-8793 vulnerability to gain access to the targeted victim’s assets.
The analyst may want to search EclecticIQ Intelligence Center for any exploit target entities containing observables that are related to the parent exploit target because they represent a vulnerability.
Example query:
data.type:exploit-target AND \
extracts.kind:domain AND \
meta.bundled_extracts.link_types:vulnerability OR \
extracts.instance_meta.link_types:vulnerability
In the search query example:
meta.bundled_extracts.link_types
is the JSON path pointing to the JSON field in the entity data structure that holds the link name value defining the relationship between entities and the corresponding bundled observables.extracts.instance_meta.link_types
is the JSON path pointing to the JSON field in the entity data structure that holds the link name value defining the relationship between entities and non-embedded observables.vulnerability
is the link name value defining the the type of entity-observable relationship you are looking for.
If the link name value search string contains multiple words
separated by spaces, wrap the search string in double quotes
(example: "my multiple word search string"
).
The following table maps the link name values you can enter in a search query to the corresponding options displayed in the GUI (campaign entities have no link names to define relationships with observables):
Search input value |
GUI option |
Linked to entity |
---|---|---|
|
Parameter |
Course of action |
|
Affected |
Exploit target |
|
Configuration |
Exploit target |
|
Vulnerability |
Exploit target |
|
Weakness |
Exploit target |
|
Affected asset |
Incident |
|
Related |
Incident |
|
Observable |
Indicator |
|
Sighted |
Indicator |
|
Test mechanism |
Indicator |
|
Malicious infrastructure |
TTP |
|
Targeted victim |
TTP |
|
Observable |
Report |
|
Identity |
Threat actor |
Relationships#
From release 3.3.0 onward, use the relational query UI to search entity relationships.
Search with date and time#
Use only ISO 8601 date-time formats:
YYYY-MM-DD
YYYY-MM-DDTHHZ
YYYY-MM-DDTHH:mmZ
YYYY-MM-DDTHH:mm:ssZ
As a complete example, 12:35 p.m. on 25 January 2020 in
Bucharest, Romania would be expressed as
2020-01-25T12:35:00+0200
Entity date-time attributes#
There are several entity attributes that you can use to search by date and time. The most commonly used are listed below along with their explanations.
Entity attribute |
Description |
---|---|
|
The date and time that an entity was created in EclecticIQ Platform. |
|
The date and time that an entity’s details were last edited in EclecticIQ Intelligence Center. |
|
The date and time that an incident was created. This field is specific to incidents. You have to type the date value as a full string (for
example: |
|
The date and time that an incident was reported. This field is specific to incidents. You have to type the date value as a full string (for
example: |
|
The date and time of the first malicious of an incident. This field is specific to incidents. You have to type the date value as a full string (for
example: |
|
A specific version of an entity. |
|
The start of the time window during which an indicator is valid. This field is specific to indicators. You have to type the date value as a full string (for
example: |
|
The end of the time window during which an indicator is valid. This field is specific to indicators. You have to type the date value as a full string (for
example: |
|
The date and time of an entity’s most recent ingestion into an organization’s cluster of platforms. You can only search using a single value. |
|
The date and time of an entity’s ingestion into a particular platform. You can search using a single value or a range of values. |
|
The date and time when an entity is estimated to have been first observed. You can search using a single value or a range of values. |
|
The date and time when the threat posed by an entity is estimated to have started. You can search using a single value or a range of values. |
|
The date and time when the threat posed by an entity is estimated to have ended You can search using a single value or a range of values. |
Date ranges#
Elasticsearch allows you to specify date ranges in your queries. Please be aware however that Elasticsearch treats queries using single dates differently to queries using date ranges. In the case of single dates, Elasticsearch only compares date values; it ignores time values and timezones. That’s why if you use ranges in your search queries you are more likely to get the results you expect.
Tip
If you use single date values in your search queries, make sure that the timezone in your user profile is the same as your system timezone, which is also the timezone of all the entities and observables in your system.
To specify ranges, enclose them either square or curly brackets:
[<min_datetime> TO <max_datetime>]
{<min_datetime> TO <max_datetime>}
Note
The TO
operator must be written in uppercase.
Examples:
Query string |
Description |
---|---|
|
Returns all entities that were ingested on and after 1 January 2020 |
|
Returns all entities that were ingested on 2 and 3 January |
|
Returns all entities that were ingested on 1 January 2020 from 13:00 up to but excluding 14:00 |
You can also use the following shortened syntax:
Query string |
Description |
---|---|
|
Returns all entities that were ingested today. |
|
Returns all entities that were ingested this month. |
|
Returns all entities that were ingested during last 24 hours |
User timezone#
The timezone you specified in your platform profile affects the value displayed for the timestamp of, for example, an entity, observable or relationship. It also serves as the default timezone for Elasticsearch queries.
If you specify a timezone in your query, Elasticsearch ignores your user timezone for the actual search. However, the search results are displayed according to your user timezone.
For example:
User timezone: CET (+0100)
Entity ingestion date-time: 21 Feb 2020 at 7:00 a.m. GMT (+0000)
Search string:
meta.ingest_time:["2020-02-21T06:30:00+0000" TO "2020-02-21T07:30:00+0000"]
The entity appears in the search results, but because the user timezone is an hour later, the entity is displayed with a timestamp of 8:00 a.m.
This may be confusing; unless you need to share results with users in different timezones, it is preferable to avoid specifying a timezone in a search query.