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

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)

Back to Table of Contents

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

Endpoint

Method	Route
	/malquery/combined/fuzzy-search/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.
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": integer
  },
  "patterns": pattern
}

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

Back to Table of Contents

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.
stream			query	boolean	Enable streaming download of the returned file.

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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.write(response)

Back to Table of Contents

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)

Back to Table of Contents

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)

Back to Table of Contents

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.
stream			query	boolean	Enable streaming download of the returned file.

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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.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, stream=boolean)
with open(save_file, 'wb') as saved:
    saved.write(response)

Back to Table of Contents

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

Endpoint

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)

Back to Table of Contents

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

Endpoint

Method	Route
	/malquery/queries/exact-search/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.
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": integer,
    "max_date": "string",
    "max_size": "string",
    "min_date": "string",
    "min_size": "string"
  },
  "patterns": pattern
}

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

Back to Table of Contents

PostMalQueryHuntV1

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

PEP8 method name

hunt

Endpoint

Method	Route
	/malquery/queries/hunt/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.
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": integer,
    "max_date": "string",
    "max_size": "string",
    "min_date": "string",
    "min_size": "string"
  },
  "yara_rule": "string"
}

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

Back to Table of Contents