Detects

Using the Detects service collection

Table of Contents

Method	Operation ID	Description
get_aggregate_detects	GetAggregateDetects	Get detect aggregates as specified via json in request body.
update_detects_by_ids	UpdateDetectsByIdsV2	Modify the state, assignee, and visibility of detections
get_detect_summaries	GetDetectSummaries	View information about detections
query_detects	QueryDetects	Search for detection IDs that match a given query

GetAggregateDetects

Get detect aggregates as specified via json in request body.

Content-Type

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

Parameters

Required	Name	Type	Datatype	Description
✅	body	body	string	Query criteria and settings

Usage

Service class example (PEP8 syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Service class example (Operation ID syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Uber class example

from falconpy.api_complete import APIHarness

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

BODY = {
    "Body Payload": "See body description above"
}

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

UpdateDetectsByIdsV2

Modify the state, assignee, and visibility of detections

Content-Type

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

Parameters

Required	Name	Type	Datatype	Description
✅	body	body	string	This endpoint modifies attributes (state and assignee) of detections. This endpoint accepts a query formatted as a JSON array of key-value pairs. You can update one or more attributes one or more detections with a single request. assigned_to_uuid values A user ID, such as 1234567891234567891 ids values One or more detection IDs, which you can find with the /detects/queries/detects/v1 endpoint, the Falcon console, or the Streaming API. show_in_ui values - true: This detection is displayed in Falcon - false: This detection is not displayed in Falcon. Most commonly used together with the status key's false_positive value. status values - new - in_progress - true_positive - false_positive - ignored comment values Optional comment to add to the detection. Comments are displayed with the detection in Falcon and usually used to provide context or notes for other Falcon users. A detection can have multiple comments over time.

Usage

Service class example (PEP8 syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Service class example (Operation ID syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Uber class example

from falconpy.api_complete import APIHarness

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

BODY = {
    "Body Payload": "See body description above"
}

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

GetDetectSummaries

View information about detections

Content-Type

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

Parameters

Required	Name	Type	Datatype	Description
✅	body	body	string	View key attributes of detections, including the associated host, disposition, objective/tactic/technique, adversary, and more. Specify one or more detection IDs (max 1000 per request). Find detection IDs with the /detects/queries/detects/v1 endpoint, the Falcon console, or the Streaming API.

Usage

Service class example (PEP8 syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Service class example (Operation ID syntax)

from falconpy.detects import Detects

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

BODY = {
    "Body Payload": "See body description above"
}

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

Uber class example

from falconpy.api_complete import APIHarness

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

BODY = {
    "Body Payload": "See body description above"
}

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

QueryDetects

Search for detection IDs that match a given query

Content-Type

• Produces: application/json

Parameters

Required	Name	Type	Datatype	Description
	offset	query	integer	The first detection to return, where 0 is the latest detection. Use with the limit parameter to manage pagination of results.
	limit	query	integer	The maximum number of detections to return in this response (default: 9999; max: 9999). Use with the offset parameter to manage pagination of results.
	sort	query	string	Sort detections using these options: - first_behavior: Timestamp of the first behavior associated with this detection - last_behavior: Timestamp of the last behavior associated with this detection - max_severity: Highest severity of the behaviors associated with this detection - max_confidence: Highest confidence of the behaviors associated with this detection - adversary_id: ID of the adversary associated with this detection, if any - devices.hostname: Hostname of the host where this detection was detected Sort either asc (ascending) or desc (descending). For example: `last_behavior
	filter	query	string	Filter detections using a query in Falcon Query Language (FQL) An asterisk wildcard * includes all results. Common filter options include: - status - device.device_id - max_severity The full list of valid filter options is extensive. Review it in our documentation inside the Falcon console.
	q	query	string	Search all detection metadata for the provided string

Usage

Service class example (PEP8 syntax)

from falconpy.detects import Detects

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

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

Service class example (Operation ID syntax)

from falconpy.detects import Detects

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

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

Uber class example

from falconpy.api_complete import APIHarness

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

PARAMS = {
    "offset": integer,
    "limit": integer,
    "sort": "string",
    "filter": "string",
    "q": "string"
}

response = falcon.command("QueryDetects", parameters=PARAMS)
print(response)