Using the MalQuery service collection

Documentation Version

This service collection has code examples posted to the repository.

Operation ID

Description

GetMalQueryQuotasV1
PEP 8	get_quotas

Get information about search and download quotas in your environment

PostMalQueryFuzzySearchV1
PEP 8	fuzzy_search

Search Falcon MalQuery quickly, but with more potential for false positives. Search for a combination of hex patterns and strings in order to identify samples based upon file content at byte level granularity.

GetMalQueryDownloadV1
PEP 8	get_download

Download a file indexed by MalQuery. Specify the file using its SHA256. Only one file is supported at this time

GetMalQueryMetadataV1
PEP 8	get_metadata

Retrieve indexed files metadata by their hash

GetMalQueryRequestV1
PEP 8	get_request

Check the status and results of an asynchronous request, such as hunt or exact-search. Supports a single request id at this time.

GetMalQueryEntitiesSamplesFetchV1
PEP 8	get_samples

Fetch a zip archive with password 'infected' containing the samples. Call this once the /entities/samples-multidownload request has finished processing

PostMalQueryEntitiesSamplesMultidownloadV1
PEP 8	samples_multidownload

Schedule samples for download. Use the result id with the /request endpoint to check if the download is ready after which you can call the /entities/samples-fetch to get the zip

PostMalQueryExactSearchV1
PEP 8	exact_search

Search Falcon MalQuery for a combination of hex patterns and strings in order to identify samples based upon file content at byte level granularity. You can filter results on criteria such as file type, file size and first seen date. Returns a request id which can be used with the /request endpoint

PostMalQueryHuntV1
PEP 8	hunt

Schedule a YARA-based search for execution. Returns a request id which can be used with the /request endpoint

Passing credentials

WARNING

client_id and client_secret are keyword arguments that contain your CrowdStrike API credentials. Please note that all examples below do not hard code these values. (These values are ingested as strings.)

CrowdStrike does not recommend hard coding API credentials or customer identifiers within source code.

GetMalQueryQuotasV1

Get information about search and download quotas in your environment

PEP8 method name

get_quotas

Endpoint

Method	Route
	`/malquery/aggregates/quotas/v1`

Required Scope

Content-Type

Produces: application/json

Keyword Arguments

No keywords are arguments are accepted.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

response = falcon.get_quotas()
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

response = falcon.GetMalQueryQuotasV1()
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("GetMalQueryQuotasV1")
print(response)

PostMalQueryFuzzySearchV1

PEP8 method name

fuzzy_search

Endpoint

Method	Route
	`/malquery/combined/fuzzy-search/v1`

Required Scope

Content-Type

Consumes: application/json
Produces: application/json

Keyword Arguments

Name	Type	Data type	Description
body	body	dictionary	Full body payload in JSON format.
filter_meta	body	list of strings	FQL Syntax.
limit	body	integer	Maximum number of matches to return.
patterns	body	list of dictionaries	List of patterns to match in JSON format. Example: { "type": "string", "value": "string" }

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

pattern = [{
    "type": "string",
    "value": "string"
}]

filter_m = ["string", "string"]

response = falcon.fuzzy_search(filter_meta=filter_m,
                               limit=integer,
                               patterns=pattern
                               )
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

pattern = [{
    "type": "string",
    "value": "string"
}]

filter_m = ["string", "string"]

response = falcon.PostMalQueryFuzzySearchV1(filter_meta=filter_m,
                                            limit=integer,
                                            patterns=pattern
                                            )
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

pattern = [{
    "type": "string",
    "value": "string"
}]

filter_m = ["string", "string"]

BODY = {
  "options": {
    "filter_meta": filter_m,
    "limit": 0
  },
  "patterns": pattern
}

response = falcon.command("PostMalQueryFuzzySearchV1", body=BODY)
print(response)

GetMalQueryDownloadV1

Download a file indexed by MalQuery. Specify the file using its SHA256. Only one file is supported at this time

PEP8 method name

get_download

Endpoint

Method	Route
	`/malquery/entities/download-files/v1`

Required Scope

Content-Type

Produces: application/octet-stream

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	File(s) SHA256 ID.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.ext"

response = falcon.get_download(ids=id_list)
open(save_file, 'wb').write(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.ext"

response = falcon.GetMalQueryDownloadV1(ids=id_list)
open(save_file, 'wb').write(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.ext"

response = falcon.command("GetMalQueryDownloadV1", ids=id_list)
open(save_file, 'wb').write(response)

GetMalQueryMetadataV1

Retrieve indexed files metadata by their hash

PEP8 method name

get_metadata

Endpoint

Method	Route
	`/malquery/entities/metadata/v1`

Required Scope

Content-Type

Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	File(s) SHA256 ID.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_metadata(ids=id_list)
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetMalQueryMetadataV1(ids=id_list)
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("GetMalQueryMetadataV1", ids=id_list)
print(response)

GetMalQueryRequestV1

Check the status and results of an asynchronous request, such as hunt or exact-search. Supports a single request id at this time.

PEP8 method name

get_request

Endpoint

Method	Route
	`/malquery/entities/requests/v1`

Required Scope

Content-Type

Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string	Identifier of the MalQuery request.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

response = falcon.get_request(ids="string")
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

response = falcon.GetMalQueryRequestV1(ids="string")
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("GetMalQueryRequestV1", ids="string")
print(response)

GetMalQueryEntitiesSamplesFetchV1

Fetch a zip archive with password 'infected' containing the samples. Call this once the /entities/samples-multidownload request has finished processing

PEP8 method name

get_samples

Endpoint

Method	Route
	`/malquery/entities/samples-fetch/v1`

Required Scope

Content-Type

Produces: application/zip

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
ids			query	string or list of strings	Multi-download job ID(s).
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.zip"

response = falcon.get_samples(ids=id_list)
open(save_file, 'wb').write(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.zip"

response = falcon.GetMalQueryEntitiesSamplesFetchV1(ids=id_list)
open(save_file, 'wb').write(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

save_file = "some_file.zip"

response = falcon.command("GetMalQueryEntitiesSamplesFetchV1", ids=id_list)
open(save_file, 'wb').write(response)

Method	Route
	`/malquery/entities/samples-multidownload/v1`

Required Scope

Content-Type

Consumes: application/json
Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	dictionary	Full body payload in JSON format.
samples			body	list of strings	List of MalQuery sample ID(s) to be downloaded.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.samples_multidownload(samples=id_list)
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.PostMalQueryEntitiesSamplesMultidownloadV1(samples=id_list)
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = ['ID1', 'ID2', 'ID3']

BODY = {
  "samples": id_list
}

response = falcon.command("PostMalQueryEntitiesSamplesMultidownloadV1", body=BODY)
print(response)

Method	Route
	`/malquery/queries/exact-search/v1`

Required Scope

Content-Type

Consumes: application/json
Produces: application/json

Keyword Arguments

Name	Type	Data type	Description
body	body	dictionary	Full body payload in JSON format.
filter_filetypes	body	list of strings	File types to filter on.
filter_meta	body	list of strings	File metadata to filter on.
limit	body	integer	Maximum number of matches to return.
min_date	body	string	UTC formatted date string representing the earliest date from which to return results.
max_date	body	string	UTC formatted date string representing the latest date from which to return results.
min_size	body	string	Minimum file size for returned results.
max_size	body	string	Maximum file size for returned results.
patterns	body	list of dictionaries	List of patterns to match in JSON format. Example: { "type": "string", "value": "string" }

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

pattern = [{
    "type": "string",
    "value": "string"
}]

response = falcon.exact_search(filter_filetypes=filter_types,
                               filter_meta=filter_metas,
                               limit=integer,
                               min_date="string",
                               max_date="string",
                               min_size="string",
                               max_size="string",
                               patterns=pattern
                               )
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

pattern = [{
    "type": "string",
    "value": "string"
}]

response = falcon.PostMalQueryExactSearchV1(filter_filetypes=filter_types,
                                            filter_meta=filter_metas,
                                            limit=integer,
                                            min_date="string",
                                            max_date="string",
                                            min_size="string",
                                            max_size="string",
                                            patterns=pattern
                                            )
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

pattern = [{
    "type": "string",
    "value": "string"
}]

BODY = {
  "options": {
    "filter_filetypes": filter_types,
    "filter_meta": filter_metas,
    "limit": 0,
    "max_date": "string",
    "max_size": "string",
    "min_date": "string",
    "min_size": "string"
  },
  "patterns": pattern
}

response = falcon.command("PostMalQueryExactSearchV1", body=BODY)
print(response)

Method	Route
	`/malquery/queries/hunt/v1`

Required Scope

Content-Type

Consumes: application/json
Produces: application/json

Keyword Arguments

Name	Type	Data type	Description
body	body	dictionary	Full body payload in JSON format.
filter_filetypes	body	list of strings	File types to filter on.
filter_meta	body	list of strings	File metadata to filter on.
limit	body	integer	Maximum number of matches to return.
min_date	body	string	UTC formatted date string representing the earliest date from which to return results.
max_date	body	string	UTC formatted date string representing the latest date from which to return results.
min_size	body	string	Minimum file size for returned results.
max_size	body	string	Maximum file size for returned results.
yara_rule	body	string	Yara rule to use for matching.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

response = falcon.hunt(filter_filetypes=filter_types,
                       filter_meta=filter_metas,
                       limit=integer,
                       min_date="string",
                       max_date="string",
                       min_size="string",
                       max_size="string",
                       yara_rule="string"
                       )
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

# Do not hardcode API credentials!
falcon = MalQuery(client_id=CLIENT_ID,
                  client_secret=CLIENT_SECRET
                  )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

response = falcon.PostMalQueryHuntV1(filter_filetypes=filter_types,
                                     filter_meta=filter_metas,
                                     limit=integer,
                                     min_date="string",
                                     max_date="string",
                                     min_size="string",
                                     max_size="string",
                                     yara_rule="string"
                                     )
print(response)

Uber class example

from falconpy import APIHarnessV2

# Do not hardcode API credentials!
falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

filter_types = ["string", "string"]
filter_metas = ["string", "string"]

BODY = {
  "options": {
    "filter_filetypes": filter_types,
    "filter_meta": filter_metas,
    "limit": 0,
    "max_date": "string",
    "max_size": "string",
    "min_date": "string",
    "min_size": "string"
  },
  "yara_rule": "string"
}

response = falcon.command("PostMalQueryHuntV1", body=BODY)
print(response)

The CrowdStrike Falcon Wiki for Python