Message Center

Using the Message Center service collection

Table of Contents

Operation ID	Description
AggregateCases PEP8 aggregate_cases	Retrieve aggregate case values based on the matched filter
GetCaseActivityByIds PEP8 get_case_activity	Retrieve activities for given id's
CaseAddActivity PEP8 add_case_activity	Add an activity to case. Only activities of type comment are allowed via API
CaseDownloadAttachment PEP8 download_case_attachment	retrieves an attachment for the case, given the attachment id
CaseAddAttachment PEP8 add_case_attachment	Upload an attachment for the case.
CreateCase PEP8 create_case	create a new case
UpdateCase PEP8 update_case	update an existing case
GetCaseEntitiesByIDs PEP8 get_cases	Retrieve message center cases
QueryActivityByCaseID PEP8 query_activities	Retrieve activities id's for a case
QueryCasesIdsByFilter PEP8 query_cases	Retrieve case id's that match the provided filter criteria

AggregateCases

Retrieve aggregate case values based on the matched filter

PEP8 method name

aggregate_cases

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	list of dictionaries	Full body payload in JSON format.
date_ranges			body	list of dictionaries	Applies to date_range aggregations. Example: [   {     "from": "2016-05-28T09:00:31Z",     "to": "2016-05-30T09:00:31Z"   },   {     "from": "2016-06-01T09:00:31Z",     "to": "2016-06-10T09:00:31Z"   } ]
field			body	string	The field on which to compute the aggregation.
filter			body	string	FQL syntax formatted string to use to filter the results.
interval			body	string	Time interval for date histogram aggregations. Valid values include: year month week day hour minute
min_doc_count			body	integer	Only return buckets if values are greater than or equal to the value here.
missing			body	string	Missing is the value to be used when the aggregation field is missing from the object. In other words, the missing parameter defines how documents that are missing a value should be treated. By default they will be ignored, but it is also possible to treat them as if they had a value.
name			body	string	Name of the aggregate query, as chosen by the user. Used to identify the results returned to you.
q			body	string	Full text search across all metadata fields.
ranges			body	list of dictionaries	Applies to range aggregations. Ranges values will depend on field. For example, if max_severity is used, ranges might look like: [   {     "From": 0,     "To": 70   },   {     "From": 70,     "To": 100   } ]
size			body	integer	The max number of term buckets to be returned.
sub_aggregates			body	list of dictionaries	A nested aggregation, such as: [   {     "name": "max_first_behavior",     "type": "max",     "field": "first_behavior"   } ] There is a maximum of 3 nested aggregations per request.
sort			body	string	FQL syntax string to sort bucket results. _count - sort by document count _term - sort by the string value alphabetically Supports asc and desc using | format. Example: _count|desc
time_zone			body	string	Time zone for bucket results.
type			body	string	Type of aggregation. Valid values include: date_histogram - Aggregates counts on a specified time interval. Requires use of “interval” field. date_range - Aggregates counts on custom defined date range buckets. Can include multiple ranges. (Similar to time series, but the bucket sizes are variable). Date formats to follow ISO 8601. terms - Buckets detections by the value of a specified field. For example, if field used is scenario, then detections will be bucketed by the various detection scenario names. range - Buckets detections by specified (numeric) ranges of a specified field. For example, if doing a range aggregation on the max_severity field, the detects will be counted by the specified ranges of severity. cardinality - Returns the count of distinct values in a specified field. max - Returns the maximum value of a specified field. min - Returns the minimum value of a specified field. avg - Returns the average value of the specified field. sum - Returns the total sum of all values for the specified field. percentiles - Returns the following percentiles for the specified field: 1, 5, 25, 50, 75, 95, 99.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

date_ranges = [
    {
        "from": "2021-05-15T14:55:21.892315096Z",
        "to": "2021-05-17T13:42:16.493180643Z"
    }
]

ranges = [
    {
        "From": 1,
        "To": 100
    }
]

response = falcon.aggregate_cases(date_ranges=date_ranges,
                                  field="string",
                                  filter="string",
                                  interval="string",
                                  min_doc_count=integer,
                                  missing="string",
                                  name="string",
                                  q="string",
                                  ranges=ranges,
                                  size=integer,
                                  sort="string",
                                  time_zone="string",
                                  type="string"
                                  )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

date_ranges = [
    {
        "from": "2021-05-15T14:55:21.892315096Z",
        "to": "2021-05-17T13:42:16.493180643Z"
    }
]

ranges = [
    {
        "From": 1,
        "To": 100
    }
]

response = falcon.AggregateCases(date_ranges=date_ranges,
                                 field="string",
                                 filter="string",
                                 interval="string",
                                 min_doc_count=integer,
                                 missing="string",
                                 name="string",
                                 q="string",
                                 ranges=ranges,
                                 size=integer,
                                 sort="string",
                                 time_zone="string",
                                 type="string"
                                 )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

date_ranges = [
    {
        "from": "2021-05-15T14:55:21.892315096Z",
        "to": "2021-05-17T13:42:16.493180643Z"
    }
]

ranges = [
    {
        "From": 1,
        "To": 100
    }
]

BODY = [{
    "date_ranges": date_ranges,
    "field": "string",
    "filter": "string",
    "interval": "string",
    "min_doc_count": 0,
    "missing": "string",
    "name": "string",
    "q": "string",
    "ranges": ranges,
    "size": 0,
    "sort": "string",
    "sub_aggregates": [
        null
    ],
    "time_zone": "string",
    "type": "string"
}]

response = falcon.command("AggregateCases", body=BODY)
print(response)

GetCaseActivityByIds

Retrieve activities for given id's

PEP8 method name

get_case_activity

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	dictionary	Full body payload in JSON format.
ids			body	string or list of strings	One or more Case IDs.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_case_activity(ids=id_list)
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetCaseActivityByIds(ids=id_list)
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

id_list = ['ID1', 'ID2', 'ID3']

BODY = {
    "ids": id_list
}

response = falcon.command("GetCaseActivityByIds", body=BODY)
print(response)

CaseAddActivity

Add an activity to case. Only activities of type comment are allowed via API

PEP8 method name

add_case_activity

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	dictionary	Full body payload in JSON format.
case_id			body	string	Case ID to attach the activity to.
content			body	string	Case activity content. Used for the body key within the BODY payload.
type			body	string	Case activity type.
user_uuid			body	string	UUID of the user attached to the case activity.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.add_case_activity(case_id="string"
                                    content="string",
                                    type="string",
                                    user_uuid="string"
                                    )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.CaseAddActivity(case_id="string"
                                  content="string",
                                  type="string",
                                  user_uuid="string"
                                  )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

# Raw BODY payload uses the key `body` not `content`
BODY = {
    "body": "string",
    "case_id": "string",
    "type": "string",
    "user_uuid": "string"
}

response = falcon.command("CaseAddActivity", body=BODY)
print(response)

CaseDownloadAttachment

retrieves an attachment for the case, given the attachment id

PEP8 method name

download_case_attachment

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
id			query	string	Attachment ID to retrieve.
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

with open("savefile.exe", "w") as save_file:
    save_file.write(falcon.download_case_attachment(id="string"))

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

with open("savefile.exe", "w") as save_file:
    save_file.write(falcon.CaseDownloadAttachment(id="string"))

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

with open("savefile.exe", "w") as save_file:
    save_file.write(falcon.command("CaseDownloadAttachment", id="string"))

CaseAddAttachment

Upload an attachment for the case.

PEP8 method name

add_case_attachment

Content-Type

• Consumes: multipart/form-data
• Produces: application/json

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
case_id			formData	string	Case ID to update.
data			formData	file	Content of the attachment in binary format. Max file size is 15 MB. Filename must start with a-zA-Z0-9_- and has a maximum of 255 characters. Allowed characters in file name are a-zA-Z0-9-_.. Accepted file formats: Images: .bmp, .jpg, .jpeg, .gif, .png Adobe PDF: .pdf Office documents: .doc, .docx, .ppt, .pptx, .xls, .xlsx Text files: .csv, .txt
file_data or sample or upfile			formData	file	Content of the attachment in binary format. Max file size is 15 MB. sample and upfile are also accepted as this parameter. Filename must start with a-zA-Z0-9_- and has a maximum of 255 characters. Allowed characters in file name are a-zA-Z0-9-_.. Accepted file formats: Images: .bmp, .jpg, .jpeg, .gif, .png Adobe PDF: .pdf Office documents: .doc, .docx, .ppt, .pptx, .xls, .xlsx Text files: .csv, .txt
parameters			query	dictionary	Full query string parameters payload in JSON format.
user_uuid			formData	string	UUID of the user providing the attachment.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

FILENAME = "testfile.png"
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.add_case_attachment(case_id="string",
                                      file_data=PAYLOAD,
                                      user_uuid="string"
                                      )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

FILENAME = "testfile.png"
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.CaseAddAttachment(case_id="string",
                                    file_data=PAYLOAD,
                                    user_uuid="string"
                                    )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

FILENAME = "testfile.png"
PAYLOAD = open(FILENAME, 'rb').read()

response = falcon.command("CaseAddAttachment",
                          data=PAYLOAD,
                          case_id="string",
                          user_uuid="string",
                          content_type="multipart/form-data"
                          )
print(response)

CreateCase

create a new case

PEP8 method name

create_case

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	dictionary	Full body payload in JSON format.
content			body	string	Case content. Used for the body key within the BODY payload.
detections			body	list of dictionaries	List of detections to attach to the case. Dictionary format: {     "id": "string",     "url": "string" }
incidents			body	list of dictionaries	List of incidents to attach to the case. Dictionary format: {     "id": "string",     "url": "string" }
title			body	string	Case title.
type			body	string	Case type.
user_uuid			body	string	UUID of the user attached to the case.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

response = falcon.create_case(content="string",
                              detections=detect_list,
                              incidents=incident_list,
                              title="string",
                              type="string",
                              user_uuid="string"
                              )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

response = falcon.CreateCase(content="string",
                             detections=detect_list,
                             incidents=incident_list,
                             title="string",
                             type="string",
                             user_uuid="string"
                             )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

# Raw BODY payload uses the key `body` not `content`
BODY = {
    "body": "string",
    "detections": detect_list,
    "incidents": incident_list,
    "title": "string",
    "type": "string",
    "user_uuid": "string"
}

response = falcon.command("CreateCase", body=BODY)
print(response)

UpdateCase

update an existing case

PEP8 method name

update_case

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	dictionary	Full body payload in JSON format.
content			body	string	Case content. Used for the body key within the BODY payload.
detections			body	list of dictionaries	List of detections to attach to the case. Dictionary format: {     "id": "string",     "url": "string" }
incidents			body	list of dictionaries	List of incidents to attach to the case. Dictionary format: {     "id": "string",     "url": "string" }
id			body	string	Case ID to be updated.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

response = falcon.update_case(content="string",
                              detections=detect_list,
                              id="string",
                              incidents=incident_list
                              )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

response = falcon.UpdateCase(content="string",
                             detections=detect_list,
                             id="string",
                             incidents=incident_list
                             )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

detect_list = [
    {
        "id": "string",
        "url": "string"
    }
]

incident_list = [
    {
        "id": "string",
        "url": "string"
    }
]

# Raw BODY payload uses the key `body` not `content`
BODY = {
    "body": "string",
    "detections": detect_list,
    "incidents": incident_list,
    "id": "string"
}

response = falcon.command("UpdateCase", body=BODY)
print(response)

GetCaseEntitiesByIDs

Retrieve message center cases

PEP8 method name

get_cases

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
body			body	dictionary	Full body payload in JSON format.
ids			body	string or list of strings	One or more Case IDs.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_cases(ids=id_list)
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.GetCaseEntitiesByIDs(ids=id_list)
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

id_list = ['ID1', 'ID2', 'ID3']

BODY = {
    "ids": id_list
}

response = falcon.command("GetCaseEntitiesByIDs", body=BODY)
print(response)

QueryActivityByCaseID

Retrieve activities id's for a case

PEP8 method name

query_activities

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
case_id			query	string	Case ID to search for activities.
filter			query	string	The filter expression that should be used to limit the results. FQL Syntax.
limit			query	integer	Maximum number of records to return. (Max: 500)
offset			query	string	Starting index of overall result set from which to return ids.
sort			query	string	The property to sort by. (Ex: case.created_time.desc) Available sort fields case.created_time case.id case.last_modified_time case.status case.type
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.query_activities(case_id="string",
                                   limit=integer,
                                   sort="string",
                                   filter="string",
                                   offset="string"
                                   )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.QueryActivityByCaseID(case_id="string",
                                        limit=integer,
                                        sort="string",
                                        filter="string",
                                        offset="string"
                                        )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

response = falcon.command("QueryActivityByCaseID",
                          case_id="string",
                          limit=integer,
                          sort="string",
                          filter="string",
                          offset="string"
                          )
print(response)

QueryCasesIdsByFilter

Retrieve case id's that match the provided filter criteria

PEP8 method name

query_cases

Content-Type

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

Keyword Arguments

Name	Service	Uber	Type	Datatype	Description
filter			query	string	The filter expression that should be used to limit the results. FQL Syntax.
limit			query	integer	Maximum number of records to return. (Max: 500)
offset			query	string	Starting index of overall result set from which to return ids.
sort			query	string	The property to sort by. (Ex: case.created_time.desc) Available sort fields case.created_time case.id case.last_modified_time case.status case.type
parameters			query	dictionary	Full query string parameters payload in JSON format.

Usage

Service class example (PEP8 syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.query_cases(limit=integer,
                              sort="string",
                              filter="string",
                              offset="string"
                              )
print(response)

Service class example (Operation ID syntax)

from falconpy import MessageCenter

falcon = MessageCenter(client_id="API_CLIENT_ID_HERE",
                       client_secret="API_CLIENT_SECRET_HERE"
                       )

response = falcon.QueryCasesIdsByFilter(limit=integer,
                                        sort="string",
                                        filter="string",
                                        offset="string"
                                        )
print(response)

Uber class example

from falconpy import APIHarness

falcon = APIHarness(client_id="API_CLIENT_ID_HERE",
                    client_secret="API_CLIENT_SECRET_HERE"
                    )

response = falcon.command("QueryCasesIdsByFilter",
                          limit=integer,
                          sort="string",
                          filter="string",
                          offset="string"
                          )
print(response)