Payload Handling

Payload Handling

There are multiple types of 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 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 APIHarness

falcon = APIHarness(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 APIHarness

falcon = APIHarness(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
                               )

PAYLOAD = {
    "description": "string",
    "name": "string",
    "comments_for_audit_log": "string",
    "permission_type": "string",
    "content": "string",
    "platform": [
       "string",
       "string"
    ]
}

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

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

Customizing headers

Custom headers can be used with any endpoint and any HTTP method. Most operations do not require custom header payloads, as a default header dictionary is maintained for every operation. Typically custom headers are used to specify content type, but can be used for other payload delivery purposes.

Example

from falconpy import FalconXSandbox

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

HEADERS = {
    "Accept-Encoding": "gzip"
}

save_file = "downloaded.gz"

response = falcon.get_artifacts(id="123456", name="testfile.gz", headers=HEADERS)
open(save_file, 'wb').write(response)