Payload Handling

Payload Handling

There are multiple types of parameters and payloads that are consumed by CrowdStrike API endpoints.

• Body
  • Body Payload Abstraction
• Query string
  • Parameter Abstraction
• Form data
• File data
  • Raw file data
  • File arrays

• Headers

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.

Body payloads

Body payloads are typically used for PATCH, POST, PUT and UPDATE operations, but this is not a hard restriction. They are either JSON formatted or binary depending on the endpoint.

Body payloads are specified using the body keyword.

Example

from falconpy import RealTimeResponse

falcon = RealTimeResponse(client_id=CLIENT_ID,
                          client_secret=CLIENT_SECRET
                          )

BODY = {
    "device_id": "123a4bc567de890f123a4b56cde"
}

response = falcon.init_session(body=BODY)
print(response)

Body Payload Abstraction

The Body Payload Abstraction feature was released for a limited number of Service Classes starting with version 0.7.0, and was completed (e.g. available in all Service Classes) in version 0.7.4. This feature allows developers to specify body payload parameters as keywords instead of crafting the necessary JSON dictionary to provide as the body keyword.

Example

from falconpy import RealTimeResponse

falcon = RealTimeResponse(client_id=CLIENT_ID,
                          client_secret=CLIENT_SECRET
                          )

response = falcon.init_session(device_id="123a4bc567de890f123a4b56cde")
print(response)

Body Payload Abstraction functionality is only available in Service Classes.

Query string parameters

Query string parameters are typically used for GET or DELETE operations, but this is not a hard restriction. Query string parameters are key / value pairs that are provided as part of the URL used for the request.

Query string parameters can be specified individually as keywords (Parameter Abstraction), or as a singular JSON dictionary using the parameters keyword.

Example

from falconpy import SensorVisibilityExclusions

falcon = SensorVisibilityExclusions(client_id=CLIENT_ID,
                                    client_secret=CLIENT_SECRET
                                    )
PARAMS = {
    "limit": 100
}
# Query string provided as a dictionary
response = falcon.query_exclusions(parameters=PARAMS)
print(response)

Parameter Abstraction

The Parameter Abstraction feature was released for Service Classes in version 0.5.4. This functionality allows developers to specify query string parameters as keywords as opposed to crafting a JSON dictionary and then providing this newly created dictionary as the parameters keyword value.

Example

Available starting in v0.5.4.

from falconpy import SensorVisibilityExclusions

falcon = SensorVisibilityExclusions(client_id=CLIENT_ID,
                                    client_secret=CLIENT_SECRET
                                    )

# Query string provided using parameter abstraction
response = falcon.query_exclusions(limit=100)
print(response)

Available starting in v0.8.0.

# Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("querySensorVisibilityExclusionsV1", limit=100)
print(response)

NOTE! Prior to version 0.8.0, the Uber Class did not support Parameter Abstraction. Developers using versions below v0.8.0 will need to provide query string payloads to the Uber Class using the parameters keyword.

Example

# Uber class example for version prior to v0.8.0
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )
PARAMS = {
    "limit": 100
}
# Query string must be provided as a dictionary
response = falcon.command("querySensorVisibilityExclusionsV1", parameters=PARAMS)
print(response)

Form data payloads

Form data payloads are typically used for PATCH, POST or PUT requests, but this may not always be the case. They are frequently JSON formatted, but may contain (or be completely comprised) of binary data.

Form data payloads can be specified using the data keyword.

Example

from falconpy import RealTimeResponseAdmin

falcon = RealTimeResponseAdmin(client_id=CLIENT_ID,
                               client_secret=CLIENT_SECRET
                               )

PAYLOAD = {
    "description": "Just a test file",
    "name": "testfile.txt",
    "comments_for_audit_log": "Testing"
}

file_upload = [('file', ('file.ext', open('file.ext','rb').read(), 'application/script'))]

response = falcon.create_put_files(data=PAYLOAD, files=file_upload)
print(response)

File data payloads

There are two types of file data payloads, raw file data and file arrays.

Raw file data

Raw file data payloads are typically used for PATCH, POST or PUT operations and contain binary data.

Raw file data payloads can be specified using the file_data keyword.

Example

from falconpy import SampleUploads

falcon = SampleUploads(client_id=CLIENT_ID,
                       client_secret=CLIENT_SECRET
                       )

FILENAME = 'test_file.ext'
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.upload_sample(file_data=PAYLOAD,
                                file_name="string",
                                comment='string',
                                is_confidential=boolean
                                )
print(response)

File arrays

File array payloads are typically used for PATCH, POST or PUT operations. They contain a list of tuples that provide file information as well as the binary file data.

File array payloads can be specified using the files keyword.

Example

from falconpy import RealTimeResponseAdmin

falcon = RealTimeResponseAdmin(client_id=CLIENT_ID,
                               client_secret=CLIENT_SECRET
                               )

filename = "somefile.ext"
with open(filename, "rb") as upload_file:
    file_upload = [('file', ('MyPutFile', upload_file.read(), 'application/octet-stream'))]

response = falcon.create_put_files(comments_for_audit_log="string",
                                   description="string",
                                   name="string",
                                   files=file_upload
                                   )
print(response)

Customizing headers

Most API operations do not require custom headers, as a default header dictionary is maintained for every operation. For operations that specifically allow (or require) custom headers, they will provide a keyword to accept this value. Typically custom headers are used to specify content type or encoding, but can be used for other payload delivery purposes.

Example

from falconpy import FalconXSandbox

falcon = FalconXSandbox(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
# For this example we will define a dictionary that contains the header we want to provide.
HEADERS = {
    "Accept-Encoding": "gzip"
}
# Our resulting binary that we receive from the API will be saved here.
save_file = "downloaded.gz"
# This operation allows for the specification of the content encoding via
# the "Accept-Encoding" header. We can specify this using the headers keyword.
response = falcon.get_artifacts(id="123456", name="testfile.gz", headers=HEADERS)
# We can leverage a context manager to handle opening and closing our save file.
with open(save_file, 'wb') as save_to:
    save_to.write(response)

This does not preclude developers from defining additional headers to be sent along with every API request. FalconPy supports the definition of custom headers to be sent along with standard headers for every API operation performed.

Service Class Example

In a Service Class, we can define custom headers using the ext_headers keyword when constructing an instance of the class.

from falconpy import Hosts

# We define a dictionary that contains our custom header.
extra_headers = {
    "X-MY-CUSTOM-HEADER": "CUSTOM_VALUE"
}
# We then inform the Service Class to add these headers to every request it makes.
falcon = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, ext_headers=extra_headers)

result = falcon.query_devices_by_filter_scroll()

Uber Class Example

In the Uber Class, custom headers can be specified per request using the headers keyword that is available to the command method.

from falconpy import APIHarnessV2

uber = APIHarnessV2(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)

# We define a dictionary that contains our custom header.
extra_headers = {
    "X-MY-CUSTOM-HEADER": "CUSTOM_VALUE"
}
# The Uber Class command method will accept these headers for every operation performed.
result = uber.command("QueryDevicesByFilterScroll", headers=extra_headers)