MalQuery

Using the MalQuery service collection

This service collection has code examples posted to the repository.

Table of Contents

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

GetMalQueryQuotasV1

Get information about search and download quotas in your environment

PEP8 method name

get_quotas

Content-Type

• Produces: application/json

Keyword Arguments

No keywords are arguments are accepted.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

response = falcon.get_quotas()
print(response)

Service class example (Operation ID syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

response = falcon.GetMalQueryQuotasV1()
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

PostMalQueryFuzzySearchV1

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.

PEP8 method name

fuzzy_search

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

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	string	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

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	string	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

Content-Type

• Produces: application/json

Keyword Arguments

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

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

Service class example (Operation ID syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

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	string	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MalQuery

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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)

PostMalQueryEntitiesSamplesMultidownloadV1

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

PEP8 method name

samples_multidownload

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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

BODY = {
  "samples": id_list
}

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

PostMalQueryExactSearchV1

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

PEP8 method name

exact_search

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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)

PostMalQueryHuntV1

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

PEP8 method name

hunt

Content-Type

• Consumes: application/json
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Data type	Description
body			body	string	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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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

falcon = MalQuery(client_id="API_CLIENT_ID_HERE",
                  client_secret="API_CLIENT_SECRET_HERE"
                  )

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 APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

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)