MalQuery - CrowdStrike/falconpy GitHub Wiki

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 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
GET /malquery/aggregates/quotas/v1

Required Scope

malquery:read

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

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

Required Scope

malquery:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
filter_meta
Service Class Support
Uber Class Support
 body list of strings FQL Syntax.
limit
Service Class Support
Uber Class Support
 body integer Maximum number of matches to return.
patterns
Service Class Support
Uber Class Support
 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
GET /malquery/entities/download-files/v1

Required Scope

malquery:read

Content-Type

  • Produces: application/octet-stream

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings File(s) SHA256 ID.
parameters
Service Class Support
Uber Class Support
 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
GET /malquery/entities/metadata/v1

Required Scope

malquery:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings File(s) SHA256 ID.
parameters
Service Class Support
Uber Class Support
 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
GET /malquery/entities/requests/v1

Required Scope

malquery:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string Identifier of the MalQuery request.
parameters
Service Class Support
Uber Class Support
 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
GET /malquery/entities/samples-fetch/v1

Required Scope

malquery:read

Content-Type

  • Produces: application/zip

Keyword Arguments

Name Service Uber Type Data type Description
ids
Service Class Support
Uber Class Support
 query string or list of strings Multi-download job ID(s).
parameters
Service Class Support
Uber Class Support
 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)

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
POST /malquery/entities/samples-multidownload/v1

Required Scope

malquery:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
samples
Service Class Support
Uber Class Support
 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)

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
POST /malquery/queries/exact-search/v1

Required Scope

malquery:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
filter_filetypes
Service Class Support
Uber Class Support
 body list of strings File types to filter on.
filter_meta
Service Class Support
Uber Class Support
 body list of strings File metadata to filter on.
limit
Service Class Support
Uber Class Support
 body integer Maximum number of matches to return.
min_date
Service Class Support
Uber Class Support
 body string UTC formatted date string representing the earliest date from which to return results.
max_date
Service Class Support
Uber Class Support
 body string UTC formatted date string representing the latest date from which to return results.
min_size
Service Class Support
Uber Class Support
 body string Minimum file size for returned results.
max_size
Service Class Support
Uber Class Support
 body string Maximum file size for returned results.
patterns
Service Class Support
Uber Class Support
 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)

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
POST /malquery/queries/hunt/v1

Required Scope

malquery:write

Content-Type

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

Keyword Arguments

Name Service Uber Type Data type Description
body
Service Class Support
Uber Class Support
 body dictionary Full body payload in JSON format.
filter_filetypes
Service Class Support
Uber Class Support
 body list of strings File types to filter on.
filter_meta
Service Class Support
Uber Class Support
 body list of strings File metadata to filter on.
limit
Service Class Support
Uber Class Support
 body integer Maximum number of matches to return.
min_date
Service Class Support
Uber Class Support
 body string UTC formatted date string representing the earliest date from which to return results.
max_date
Service Class Support
Uber Class Support
 body string UTC formatted date string representing the latest date from which to return results.
min_size
Service Class Support
Uber Class Support
 body string Minimum file size for returned results.
max_size
Service Class Support
Uber Class Support
 body string Maximum file size for returned results.
yara_rule
Service Class Support
Uber Class Support
 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)

⚠️ **GitHub.com Fallback** ⚠️