Skip to content

Query#

Overview#

This is a module that defines a set of utility methods used to easily build valid search query without the need to use JSON objects.

Query objects are used by APIs that allow searchinf for objects like:

A query is a defined by on of the criteria described below.

A query could be used like below:

# Define the query
query = And(
    Eq('owner', 'admin'),
    Between('tlp', 1, 3),
    Not(Eq('status', 'Deleted')),
    Child('case_artifact', And(
        Eq('ioc', True),
        In('dataType', ['file', 'ip', 'domain'])
    ))
)

# Call find_cases method to search for all the case, sorted by descending created date, 
# and verifying the following set of conditions:
# - owned by admin
# - having tlp between GREEN and RED
# - not deleted
# - having observables of type file, ip or domain that are flagged as IOC

api.find_cases(query=query, sort=['-createdAt'], range='all')

And(*criteria) #

A criterion used to search for records that verfies all the specified criteria. For example

  • search for observables flagged as IOC and having TLP <= 2
  • search for closed cases related to customFields.customer "Company" and having a WHITE tlp

Parameters:

Name Type Description Default
criteria Array

A set of criteria, can be any operator defined in the query module (Eq, In, Not, And...)

 ()

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for cases with customer custom field set to 'Company', having a TLP less than Amber and are resolved
query = And(
    Eq('customFields.customer.string', 'Company'),
    Lte('tlp', 2),
    Eq('status', 'Resolved')
)
produces 
{
    "_and": [
        {
            "_field": "customFields.customer.string",
            "_value": "Company"
        },
        {
            "_lte": {
                "tlp": 2
            }
        },
        {
            "_field": "status",
            "_value": "Resolved"
        }
    ]
}

Between(field, from_value, to_value) #

A criterion used to search for records having field's value included in a range defined by from_value and to_value. This is an idea criterion to seahrch using date conditions. For example

  • search for cases created between two dates
  • search for alerts with cvss custom field greater that 2 and lesser than 9

Parameters:

Name Type Description Default
field str

field name

 required
from_value Number

Lower limit of the range

 required
to_value Number

Higher limit of the range

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for alerts with cvss custom field greater that 2 and lesser than 9
query = Between('customFields.cvss.float', 2, 9)
produces 
{
    "_between": {
        "_field": "customFields.cvss.float",
        "_from": 2,
        "_to": 9
    }
}

Child(tpe, criterion) #

A criterion used to search for records by applying a filter on their children using a criterion. For example

  • search for cases having file observables
  • search for cases having a specific ip observable

Parameters:

Name Type Description Default
tpe str

class name of the child: case_task, case_artifact...

 required
criterion Any

Any criterion defined by functions from the query module

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for cases having iocs of type file
query = Child('case_artifact', And(
    Eq('dataType', 'file'),
    Eq('ioc', True)
))
produces 
{
    "_child": {
        "_type": "case_artifact",
        "_query": {
            "_and": [
                [
                    {
                        "_field": "dataType",
                        "_value": "file"
                    },
                    {
                        "_field": "ioc",
                        "_value": true
                    }
                ]
            ]
        }
    }
}

Contains(field) #

A criterion used to search for records where field id defined. For example

  • search for cases that have the custom field customer

Parameters:

Name Type Description Default
field str

field name

required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for cases having a 'customer' custom field
query = Contains('customFields.customer')
produces 
{
    "_contains": "customFields.customer"
}

ContainsString(field, value) #

A criterion used to search for objects having a text field's value like the specified value. It's a wildcard operator that wraps the searched value with asteriscs. It operates the same way a the Like criterion For example:

  • search for cases where title is like *malspam*
  • search for observable where description contains the text *malware*

Parameters:

Name Type Description Default
field value

field name

 required
value Any

searched value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Search for tasks where title contains 'Communication'
query = ContainsString('title', 'Communication')
produces 
{
    "_wildcard": {
        "_field": "title",
        "_value": "*Communication*"
    }
}

EndsWith(field, value) #

A criterion used to search for objects having a text field's value end with value. It's a wildcard operator that adds the * if not specified, at the beginning of value. For example:

  • search for filename observables ending with .exe

Parameters:

Name Type Description Default
field value

field name

 required
value Any

searched value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Search for tasks where title stats with 'Communication'
query = EndsWith('data', '.png')
produces 
{
    "_wildcard": {
        "_field": "data",
        "_value": "*.png"
    }
}

Eq(field, value) #

A criterion used to search for a equality. For example

  • search for TLP = 2
  • search for flag = True
  • search for title = 'Sample case'

Parameters:

Name Type Description Default
field value

field name

 required
value Any

field value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

query = Eq('tlp', 3)
produces 
{"_field": "tlp", "_value": 3}

Gt(field, value) #

A criterion used to search for a field greater than a certain value. For example

  • search for TLP > 2
  • search for customFields.cvss > 4.5
  • search for date > now

Parameters:

Name Type Description Default
field value

field name

 required
value Any

field value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

query = Gt('tlp', 1)
produces 
{"_gt": {"tlp": 1}}

Gte(field, value) #

A criterion used to search for a field greater or equal than a certain value. For example

  • search for TLP >= 2
  • search for customFields.cvss >= 4.5
  • search for date >= now

Parameters:

Name Type Description Default
field value

field name

 required
value Any

field value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

query = Gte('tlp', 1)
produces 
{"_gte": {"tlp": 1}}

Id(id) #

A criterion used to search for records by id. For example

  • search for a case by its id
  • search for an alert by its id

Parameters:

Name Type Description Default
id str

the id's value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for as case by id
query = Id('1234545643')
produces 
{
    "_id": "1234545643"
}

In(field, values) #

A criterion used to search for records where field has one of the values. For example

  • search for observables of type domain, fqdn, ip
  • search for cases tagged as malspam, or phising

Parameters:

Name Type Description Default
field str

field name

 required
values Array

A set of values the field must be in

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for observables of one of the following types: domain, fqdn, ip
query = In('dataType', ['domain', 'fqdn', 'ip'])
produces 
{
    "_in": {
        "_field": "dataType",
        "_values": [
            "domain",
            "fqdn",
            "ip"
        ]
    }
}

Like(field, value) #

A criterion used to search for objects having a text field's value like the specified value. It's a wildcard operator when the searched value must specify asteriscs. For example:

  • search for cases where title is like *malspam*
  • search for observable where description contains the text *malware*

Parameters:

Name Type Description Default
field value

field name

 required
value Any

searched value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Search for tasks where title contains 'Communication'
query = Like('title', '*Communication*')
produces 
{
    "_like": {
        "_field": "title",
        "_value": "*Communication*"
    }
}

Note

If the * are not specified, the exact same text will be searched for. Like('title', 'MISP') will search for titles equal to 'MISP'

Lt(field, value) #

A criterion used to search for a field less than a certain value. For example

  • search for TLP < 2
  • search for customFields.cvss < 4.5
  • search for date < now

Parameters:

Name Type Description Default
field value

field name

 required
value Any

field value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

query = Lt('tlp', 3)
produces 
{"_lt": {"tlp": 3}}

Lte(field, value) #

A criterion used to search for a field less or equal than a certain value. For example

  • search for TLP <= 2
  • search for customFields.cvss <= 4.5
  • search for date <= now

Parameters:

Name Type Description Default
field value

field name

 required
value Any

field value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

query = Lte('tlp', 3)
produces 
{"_lte": {"tlp": 3}}

Not(criterion) #

A criterion used to search for records that verfies the opposite of the specified criterion. For example

  • search for observables not marked as ioc
  • search for cases not having a MISP tag

Parameters:

Name Type Description Default
crietrion Any

The base criterion to use for negation

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for cases assigned to jdoe or are flagged and open
query = Not(Eq('ioc', True))
produces 
{
    "_not": {
        "_field": "ioc",
        "_value": false
    }
}

Or(*criteria) #

A criterion used to search for records that verfies one of the specified criteria. For example

  • search for observables of type domain or fqdn
  • search for cases assigned to a given user or have a specific tag

Parameters:

Name Type Description Default
criteria Array

A set of criteria, can be any operator defined in the query module (Eq, In, Not, And...)

 ()

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for cases assigned to jdoe or are flagged and open
query = Or(
    Eq('owner', 'jdoe'),
    And(
        Eq('status', 'Open'),
        Eq('flag', True),
    )
)
produces 
{
    "_or": [
        {
            "_field": "owner",
            "_value": "jdoe"
        },
        {
            "_and": [
                [
                    {
                        "_field": "status",
                        "_value": "Open"
                    },
                    {
                        "_field": "flag",
                        "_value": true
                    }
                ]
            ]
        }
    ]
}

Parent(tpe, criterion) #

A criterion used to search for records by filtering the parents using a criterion. For example

  • search for observables of TLP:RED cases
  • search for logs of tasks called 'Communication'

Parameters:

Name Type Description Default
tpe str

class name of the parent: case, case_task, case_artifact...

 required
criterion Any

Any criterion defined by functions from the query module

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for tasks belonging to open cases with TLP=RED
query = Parent('case', And(
    Eq('status', 'Open'),
    Eq('tlp', 3)
))
produces 
{
    "_parent": {
        "_type": "case",
        "_query": {
            "_and": [
                [
                    {
                        "_field": "status",
                        "_value": "Open"
                    },
                    {
                        "_field": "tlp",
                        "_value": 3
                    }
                ]
            ]
        }
    }
}

ParentId(tpe, id) #

A criterion used to search for records by their parent's id. For example

  • search for observables by case id
  • search for tasks by case id
  • search for logs by task id
  • search for jobs by observable id

Parameters:

Name Type Description Default
tpe str

class name of the parent: case, case_task, case_artifact...

 required
id str

the parent id's value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for tasks of a case by id
query = ParentId('case', '1234545643')
produces 
{
    "_parent": {
        "_type": "case",
        "_id": "1234545643"
    }
}

StartsWith(field, value) #

A criterion used to search for objects having a text field's value start with value. It's a wildcard operator that adds the * if not specified, at the end of value. For example:

  • search for cases having a tag starting with malspam
  • search for filename observables starting with dridex

Parameters:

Name Type Description Default
field value

field name

 required
value Any

searched value

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Search for tasks where title stats with 'Communication'
query = StartsWith('title', 'Communication')
produces 
{
    "_wildcard": {
        "_field": "title",
        "_value": "Communication*"
    }
}

String(query_string) #

A criterion used to search for objects using Elasticsearch querystring syntax. For example

  • search for case using title:misp AND tlp:2

Parameters:

Name Type Description Default
tpe str

object type's name as defined in TheHive:

Possible values: all, case, case_task, case_task_log, case_artifact, alert, case_artifact_job, audit

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for casee with TLP:AMBER and having the word 'misp' on the title
query = String('title:misp AND tlp:2')
produces 
{
    "_string": "title:misp AND tlp:2"
}

Warning

This criterion is deprecated and won't be ported to TheHive 4

Warning

This criterion is available in TheHive 3 ONLY

Type(tpe) #

A criterion used to search for records of the type defined by tpe. For example

  • search for objects of type 'audit'
  • search for objects of type 'alert'

Parameters:

Name Type Description Default
tpe str

object type's name as defined in TheHive: all, case, case_task, case_task_log, case_artifact, alert, case_artifact_job, audit

 required

Returns:

Type Description
dict

JSON repsentation of the criterion 

# Query to search for alerts
query = Type('alert')
produces 
{
    "_type": "alert"
}

Last update: May 29, 2020 15:27:12