CrowdStrike Falcon CrowdStrike Subreddit

Using the MalQuery service collection

Uber class support Service class support Documentation Version Page Updated Samples Available

This service collection has code examples posted to the repository.

Table of Contents

Operation IDDescription
GetMalQueryQuotasV1
PEP 8get_quotas
Get information about search and download quotas in your environment
PostMalQueryFuzzySearchV1
PEP 8fuzzy_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 8get_download
Download a file indexed by MalQuery. Specify the file using its SHA256. Only one file is supported at this time
GetMalQueryMetadataV1
PEP 8get_metadata
Retrieve indexed files metadata by their hash
GetMalQueryRequestV1
PEP 8get_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 8get_samples
Fetch a zip archive with password 'infected' containing the samples. Call this once the /entities/samples-multidownload request has finished processing
PostMalQueryEntitiesSamplesMultidownloadV1
PEP 8samples_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 8exact_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 8hunt
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

MethodRoute
GET/malquery/aggregates/quotas/v1

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

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

MethodRoute
POST/malquery/combined/fuzzy-search/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
filter_meta
Service Class Support

Uber Class Support
bodylist of stringsFQL Syntax.
limit
Service Class Support

Uber Class Support
bodyintegerMaximum number of matches to return.
patterns
Service Class Support

Uber Class Support
bodylist of dictionariesList 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

MethodRoute
GET/malquery/entities/download-files/v1

Content-Type

  • Produces: application/octet-stream

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsFile(s) SHA256 ID.
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/malquery/entities/metadata/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsFile(s) SHA256 ID.
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/malquery/entities/requests/v1

Content-Type

  • Produces: application/json

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystringIdentifier of the MalQuery request.
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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

MethodRoute
GET/malquery/entities/samples-fetch/v1

Content-Type

  • Produces: application/zip

Keyword Arguments

NameServiceUberTypeData typeDescription
ids
Service Class Support

Uber Class Support
querystring or list of stringsMulti-download job ID(s).
parameters
Service Class Support

Uber Class Support
querydictionaryFull 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)

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

MethodRoute
POST/malquery/entities/samples-multidownload/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
samples
Service Class Support

Uber Class Support
bodylist of stringsList 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)

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

MethodRoute
POST/malquery/queries/exact-search/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
filter_filetypes
Service Class Support

Uber Class Support
bodylist of stringsFile types to filter on.
filter_meta
Service Class Support

Uber Class Support
bodylist of stringsFile metadata to filter on.
limit
Service Class Support

Uber Class Support
bodyintegerMaximum number of matches to return.
min_date
Service Class Support

Uber Class Support
bodystringUTC formatted date string representing the earliest date from which to return results.
max_date
Service Class Support

Uber Class Support
bodystringUTC formatted date string representing the latest date from which to return results.
min_size
Service Class Support

Uber Class Support
bodystringMinimum file size for returned results.
max_size
Service Class Support

Uber Class Support
bodystringMaximum file size for returned results.
patterns
Service Class Support

Uber Class Support
bodylist of dictionariesList 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)

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

MethodRoute
POST/malquery/queries/hunt/v1

Content-Type

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

Keyword Arguments

NameServiceUberTypeData typeDescription
body
Service Class Support

Uber Class Support
bodydictionaryFull body payload in JSON format.
filter_filetypes
Service Class Support

Uber Class Support
bodylist of stringsFile types to filter on.
filter_meta
Service Class Support

Uber Class Support
bodylist of stringsFile metadata to filter on.
limit
Service Class Support

Uber Class Support
bodyintegerMaximum number of matches to return.
min_date
Service Class Support

Uber Class Support
bodystringUTC formatted date string representing the earliest date from which to return results.
max_date
Service Class Support

Uber Class Support
bodystringUTC formatted date string representing the latest date from which to return results.
min_size
Service Class Support

Uber Class Support
bodystringMinimum file size for returned results.
max_size
Service Class Support

Uber Class Support
bodystringMaximum file size for returned results.
yara_rule
Service Class Support

Uber Class Support
bodystringYara 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)