Payload Handling
There are multiple types of payloads that are consumed by CrowdStrike API endpoints.
Passing credentials
WARNING
client_idandclient_secretare 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 payloads
Query string payloads are typically used for GET or DELETE operations, but this is not a hard restriction. Query string payloads are typically JSON formatted.
Query string payloads 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
parameterskeyword.
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 header payloads, 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)