Crowdstrike Identity Protection

LAST UPDATED: OCT 31, 2024

Overview

CrowdStrike Falcon® Identity Protection stops breaches faster by protecting workforce identities everywhere leveraging advanced AI in the world's largest unified, threat-centric data fabric. It improves organizations' security posture by segmenting identities and automating analysis and enforcement of AD security. The Falcon Identity Protection solution consists of two products: Falcon Identity Threat Detection (ITD) and Falcon Identity Threat Protection.

D3 SOAR is providing REST operations to function with CrowdStrike Identity Protection.

CrowdStrike Identity Protection is available for use in:

D3 SOAR	V15.4.76.0+
Category	Identity & Access Management
Deployment Options	Option II, Option IV

Connection

To connect to CrowdStrike Identity Protection from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL for the API connection.	https://api.crowdstrike.com
Client ID	The client ID to authenticate the API connection.	acb*****66a9
Client Secret	The client secret to authenticate the API connection.	m13*****etf
API Version	The version of the API to use for the connection.	v1

Permission Requirements

Each endpoint in the CrowdStrike Identity Protection API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permission
Fetch Event	Fetching for "identity detection" type of events	Read: Alerts
	Fetching for "incidents" type of events	Read: Identity Protection Detections Write: Identity Protection GraphQL
Search Entities	Read: Identity Protection Entities Write: Identity Protection GraphQL
Update Identity-based Detections	Read + Write: Alerts
Update Incidents	Read + Write: Identity Protection Detections Write: Identity Protection GraphQL
Test Connection	Read: Identity Protection Detections Write: Identity Protection GraphQL

As CrowdStrike Identity Protection is using role-based access control (RBAC), the API access token is generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the CrowdStrike Identity Protection console for each command in this integration.

READER NOTE

For more information about user roles, see https://falcon.crowdstrike.com/documentation/184/identity-protection-apis#before-you-begin.

Configuring CrowdStrike Identity Protection to Work with D3 SOAR

Log in to the CrowStrike portal (https://falcon.crowdstrike.com/login/).
Use the shortcut Ctrl + K (Windows) or Cmd + K (macOS) to bring up the search bar. Use it to find and select API clients and keys.
On the API clients and keys page, click Add new API Client.
The Add new API client will appear. Input a Client Name and a description (optional). Select the scopes for the API client according to your use case. Click Add.

READER NOTE

The screenshot above provides a sample permissions configuration. For a detailed list of API scopes, see Permissions Requirement.

The API client created window will appear with a Client ID and Secret.

READER NOTE

This is the only time you can view the Secret Key. Store it in a secure location for future reference.

(Optional) You can edit the permission scopes for the created API client by clicking the Edit icon under the Action column of the API client. An Edit API client window will appear for you to edit the permission scopes. Click Save to complete editing.
(Optional) You can reset the Secret Key by clicking the Reset Secret icon under the Action column of the API client. A Reset the secret window will appear asking you to confirm. Click Reset.

Configuring D3 SOAR to Work with CrowdStrike Identity Protection

Log in to D3 SOAR.
Find the CrowdStrike Identity Protection integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type CrowdStrike Identity Protection in the search box to find the integration, then click it to select it.
4. Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to CrowdStrike Identity Protection.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL.
  2. Input your Client ID. Please check Step 5 of Configuring CrowdStrike Identity Protection to Work with D3 SOAR to obtain the client ID.
  3. Input your Client Secret. Please check Step 5 of Configuring CrowdStrike Identity Protection to Work with D3 SOAR to obtain the client Secret.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
11. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click Add to create and add the configured connection.

Commands

CrowdStrike Identity Protection includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the CrowdStrike Identity Protection API, please refer to the CrowdStrike Identity Protection API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring CrowdStrike Identity Protection to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Fetch Event

Returns event(s) from the platform based on specified criteria. You can filter the event type (i.e. identity-based detections or incidents) to fetch.

READER NOTE

All input parameters are optional to run this command. If no input parameters are defined, all Identity-based Detection type events will be fetched by default.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range of the specified query time type to fetch events in UTC time. Note: This parameter applies to both Identity-based Detection and Incident event types.	2022-08-05 00:00
End Time	Optional	The end time of the time range of the specified query time type to fetch events in UTC time. Note: This parameter applies to both Identity-based Detection and Incident event types.	2022-08-12 00:00
Query Time Type	Optional	The time field to filter retrieved events, based on the selected value for the Event Type parameter. If the event type is Identity-Based Detection, the options available are First Activity Time, Last Activity Time, Created Time, and Updated Time. If no option is specified, the default time field used for Identity-Based Detection is Last Activity Time. If the event type is Incident, the options available are Created Time and Updated Time. If no option is specified, the default time field used for Incident is Updated Time.	First Activity Time(Identity-Based Detection)
Event Type	Optional	The type of events to retrieve. The available event types are Identity-based Detection and Incident. The default value will be Identity-based Detection if no event type is specified.	Identity-Based Detection
Number of Event(s) Fetched	Optional	The maximum number of the most recent events fetch. The valid input value is an integer between 1 and 10,000. If the input value is not within the valid range or not specified, all events that match the filters will be returned. Note: This parameter applies to both Identity-based Detection and Incident event types.	10
Severity	Optional	The minimum severity level of the events to retrieve. For instance, events with a "High" or "Critical" security level will be returned if you select High. If this parameter is not specified, events of all severity levels will be returned. Note: This parameter is applicable to both Identity-based Detection and Incident event types.	High
Identity-based Detection filter	Optional	The query to filter Identity-based Detection results. For more information about the query syntax, see Crowdstrike Falcon Query Language. If this parameter is not specified, all Identity-based Detections matching the other specified criteria will be returned. Note: This parameter is only valid for Identity-based Detection events.	status:['new'] + tactic_id:[ '*****' ]
Incident filter	Optional	The query to filter Incident results. For more information about the query syntax, see Crowdstrike Falcon Query Language. For the available incident filter parameters, see Crowdstrike-Incident parameters. If this parameter is not specified, all Incident matching the other specified criteria will be returned. Note: This parameter is only valid for Incident events.	alertTypes:[ ALERT_TYPE ], type:[ INCIDENT_TYPE ]
Tolerance Scope	Optional	The tolerance scope (in minutes) for the query to fetch events between the specified start and end time to avoid event loss or fetch failure. The events will be fetched between {Start Time - Tolerance Scope, End Time}. The default value is 0.	0

Output

Return Data

Indicates one of the possible command execution states: Successful, Successful with No Event Data, or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

eventType: Identity-based Detection
{
    "meta": {
        "query_time": 0.004553092,
        "writes": {
            "resources_affected": 0
        },
        "powered_by": "detectsapi",
        "trace_id": "*****"
    },
    "errors": [],
    "resources": [{
            "eventType": "idp",
            "activity_id": "*****",
            "aggregate_id": "*****",
            "cid": "*****",
            "composite_id": "dca1-XXXX-*****",
            "confidence": 30,
            "context_timestamp": "2022-05-15T10:32:00.000Z",
            "created_timestamp": "2022-05-15T11:34:56.887790892Z",
            "description": "User access from an unusual location",
            "display_name": "Unusual user geolocation",
            "end_time": "2022-05-15T10:32:00.000Z",
            "falcon_host_link": "https://falcon.crowdstrike.com/*****",
            "id": "*****",
            "location_country_code": "US",
            "name": "AnomalousGeoLocationAccess",
            "objective": "Gain Access",
            "okta_application_id": "*****",
            "pattern_id": 51125,
            "product": "idp",
            "scenario": "machine_learning",
            "severity": 31,
            "show_in_ui": true,
            "source_account_name": "*****.*****@*****.***",
            "source_account_okta_id": "*****",
            "source_endpoint_address_ip4": "***.***.***.***",
            "source_endpoint_ip_address": "***.***.***.***",
            "sso_application_identifier": "Okta ***** Console",
            "sso_application_uri": "*****",
            "start_time": "2022-05-15T10:32:00.000Z",
            "status": "new",
            "tactic": "Initial Access",
            "tactic_id": "*****",
            "technique": "Valid Accounts",
            "technique_id": "T1078",
            "timestamp": "2022-05-15T10:34:56.509Z",
            "type": "idp-session-source-user-endpoint-target-info",
            "updated_timestamp": "2022-05-15T11:34:56.887790892Z"
        }
    ]
}

SAMPLE DATA

CODE


eventType: Incident
{
    "resources": [{
            "eventType": "incident",
            "type": "POTENTIAL_RISKY_ACTIVITY",
            "startTime": "2021-02-28T06:10:34.000Z",
            "endTime": "2021-03-01T06:11:25.209Z",
            "compromisedEntities": [{
                    "primaryDisplayName": "*****",
                    "type": "USER"
                }, {
                    "primaryDisplayName": "*****",
                    "type": "ENDPOINT"
                }
            ],
            "alertEvents": [{
                    "alertType": "GeoLocationAnomalyAlert",
                    "eventLabel": "Unusual User Geolocation",
                    "entities": [{
                            "primaryDisplayName": "*****"
                        }, {
                            "primaryDisplayName": "*****"
                        }
                    ],
                    "relatedEvents": {
                        "nodes": [{
                                "eventType": "SUCCESSFUL_AUTHENTICATION",
                                "timestamp": "2021-02-28T06:04:31.971Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "SRV-PATENT-FILE"
                                },
                                "targetEntity": null
                            }, {
                                "eventType": "SUCCESSFUL_AUTHENTICATION",
                                "timestamp": "2021-02-28T06:10:34.000Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "targetEntity": null
                            }, {
                                "eventType": "ALERT",
                                "timestamp": "2021-02-28T06:10:59.999Z"
                            }, {
                                "eventType": "ALERT",
                                "timestamp": "2021-02-28T06:10:59.999Z"
                            }, {
                                "eventType": "SERVICE_ACCESS",
                                "timestamp": "2021-02-28T06:11:34.000Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "targetEntity": {
                                    "primaryDisplayName": "SRV-FILESHARE01"
                                }
                            }
                        ]
                    }
                }, {
                    "alertType": "ForbiddenCountryAlert",
                    "eventLabel": "Access from Forbidden Country",
                    "entities": [{
                            "primaryDisplayName": "*****"
                        }, {
                            "primaryDisplayName": "*****"
                        }
                    ],
                    "relatedEvents": {
                        "nodes": [{
                                "eventType": "SUCCESSFUL_AUTHENTICATION",
                                "timestamp": "2021-02-28T06:04:31.971Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "SRV-PATENT-FILE"
                                },
                                "targetEntity": null
                            }, {
                                "eventType": "SUCCESSFUL_AUTHENTICATION",
                                "timestamp": "2021-02-28T06:10:34.000Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "targetEntity": null
                            }, {
                                "eventType": "ALERT",
                                "timestamp": "2021-02-28T06:10:59.999Z"
                            }, {
                                "eventType": "ALERT",
                                "timestamp": "2021-02-28T06:10:59.999Z"
                            }, {
                                "eventType": "SERVICE_ACCESS",
                                "timestamp": "2021-02-28T06:11:34.000Z",
                                "userEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "endpointEntity": {
                                    "primaryDisplayName": "*****"
                                },
                                "targetEntity": {
                                    "primaryDisplayName": "SRV-FILESHARE01"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Start Time (UTC)	2022-05-08 12:00
End Time (UTC)	2022-08-12 12:00
Incidents Count	20

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

The Crowdstrike Identity Protection integration in D3 SOAR has some pre-configured field mappings for the Identity-based Detections and Incidents, which correspond to the Default Event Source and Event Source for Incidents mappings:

Default Event Source
Configures the field mapping which are specific to the Identity-based Detections-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. The default event source has a “Main Event JSON Path” (i.e., $.resources) that is used to extract a batch of events from the response raw data. Click Edit Main JSON Path to view the “Main Event JSON Path”. Click Edit Event Source to view the “Main Event JSON Path”.
- Main Event JSON Path for Identity-based Detections: $.resources
  The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
  For example, the root node of a JSON Path is resources. The child node denoting the Unique Event Key field would be id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.$.resources.id.
Event Source for Incidents

Configures the field mapping which are specific to the incident-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the incident-related events have a character that the value of the eventType field is incident, the incident-related events can be defined by the Search String: {$.eventType}=incident. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $.resources)
Activity ID	.activity_id
Confidence	.confidence
Event Internal Name	.name
Event Time	.created_timestamp
Falcon Host Link	.falcon_host_link
Location Country Code	.location_country_code
Location Latitude	.location_latitude
Location Longitude	.location_longitude
Objective	.objective
Pattern ID	.pattern_id
Source Account Azure ID	.source_account_azure_id
Source Account Domain	.source_account_domain
Source Account ID	.source_account_object_sid
Source Account Okta ID	.source_account_okta_id
SSO Application URI	.sso_application_uri
Technique ID	.technique_id
UpdateTime	.updated_timestamp
UTCEventTime	.timestamp
Webhook Extrainfo	.webhookExtraInfo
Last Behavior Time	.end_time
Webhook URL	.webhookURL
Unique Event Key	.id
Event name	.display_name
Event Type	.type
Start Time	.start_time
Severity	.severity
Source Device	.source_endpoint_host_name
Source Device IP address	.source_endpoint_ip_address
Source username	.source_account_name
Status	.status
Description	.description
Tactics	.tactic
Techniques	.technique
Event Source for Alerts (Search String:{$.eventType}=incident) The search string format is {jsonpath}=value. If the value of the eventType key is incident in the event object under raw data, then the incident-related events will use the field mapping below.
Severity	.severity
Status	.lifeCycleStage
Sub Event	.alertEvents
Start Time	.startTime
Alert type	.alertEvents[*].alertType
Event code	.incidentId
Last Behavior Time	.endTime
Webhook Extrainfo	.webhookExtraInfo
Webhook URL	.webhookURL
Related Endpoint Entities	.alertEvents[].relatedEvents.nodes[].endpointEntity.primaryDisplayName
Related Target Entities	.alertEvents[].relatedEvents.nodes[].targetEntity.primaryDisplayName
Related User Entities	.alertEvents[].relatedEvents.nodes[].userEntity.primaryDisplayName
Incident Type	.type
Event Labels	.alertEvents[*].eventLabel
Comments	.comments.text
Compromised Endpoints	.compromisedEntities[?(@.type == 'ENDPOINT')].primaryDisplayName
Compromised Users	.compromisedEntities[?(@.type == 'USER')].primaryDisplayName

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the CrowdStrike Identity Protection portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: access denied, authorization failed.

Error Sample Data

Fetch Event failed.

Status Code: 403.

Message: access denied, authorization failed.

Search Entities

Retrieves entites with corresponding information basd on the specified criteria.

READER NOTE

All input parameters are optional to run this command. If no input parameters are defined, all entities will be returned.
By default, the returned entities are sorted by primaryName, in ascending order.

Input

Input Parameter	Required/Optional	Description	Example
Entity Type	Optional	The type of entities to retrieve. If this parameter is not specified, entities of all types will be returned.	USER
Entity Primary Names	Optional	The primary display names of the entities to return.	[ "*****" ]
Minimum Risk Score Severity	Optional	The minimum risk score severity to filter returned entities. If this parameter is not defined, entities with any score severities will be returned.	Medium
Email Addresses	Optional	The email addresses of the user entities to return. Note: This parameter is only valid then the selected "Entity Type" is "User".	[ "***@*.*" ]
Host Names	Optional	The names of the host entities to return. Note: This parameter is only valid when the selected "Entity Type" is "Endpoint".	[ "win-10-host" ]
Entity Filter	Optional	The condition to filter returned entities. This parameter can be used if the other input parameters are inadequate to fulfill your query conditions. If the fields used for filtering in this parameter overlap with other input parameters, the other input parameters will be ignored. For more information about the query syntax, see Crowdstrike Falcon Query Language. For more information on entity filter parameters, see Crowdstrike-Entity parameters.	hasOpenIncidents:true, secondaryDisplayName:[ "***\\***" ]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "entities": {
        "nodes": [
            {
                "primaryDisplayName": "*****",
                "secondaryDisplayName": "*****\\*****",
                "entityId": "*****",
                "isHuman": true,
                "isProgrammatic": false,
                "emailAddresses": [
                    "*****@*****.***"
                ],
                "riskScore": 0.86,
                "riskScoreSeverity": "HIGH",
                "riskFactors": [
                    {
                        "type": "OBJECT_SID_HISTORY_PRIVILEGES_TAKEOVER",
                        "severity": "HIGH"
                    },
                    {
                        "type": "WEAK_PASSWORD",
                        "severity": "MEDIUM"
                    },
                    {
                        "type": "HAS_SPNS",
                        "severity": "MEDIUM"
                    },
                    {
                        "type": "STALE_ACCOUNT",
                        "severity": "NORMAL"
                    }
                ]
            }
        ]
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
  "EntityPrimaryNames": [ "*****" ],
  "RiskScores": [0.86],
  "RiskScoreSeverities": ["HIGH"],
  "EntityIDs": ["*****"]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Entities Count

1

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Entities failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Crowdstrike Identity Protection portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: access denied, authorization failed.

Error Sample Data

Search Entities failed.

Status Code: 403.

Message: access denied, authorization failed.

Update Identity-based Detections

Updates the specified Identity-based Detections, including status, assigned user and comments with additional info. You can update Identity-based Detection(s) by specifying the corresponding Detection ID(s) or using a filter condition.

READER NOTE

The input parameter Detection IDs is optional to run this command.

You should already have your desired Detection IDs on hand to run this command. If you don’t, you may use the Fetch Event command with the Event Type parameter set to Identity-based Detection to view a list of Detection IDs. The Detection IDs can be found in the raw data at the path $.resources.id.

Input

Input Parameter	Required/Optional	Description	Example
Detection IDs	Optional	The ID(s) of the detection(s) to update. Identity-based IDs can be obtained using the Fetch Event command. Note: You must define one of the "Detection IDs" or "Filter" parameters. If both are defined, only the "Detection IDs" parameter will be used. The "Filter" parameter will be ignored.	["*****"]
Filter	Optional	The condition to filter the detections to update. For more information about the query syntax, see Crowdstrike Falcon Query Language. Note: You must define one of the "Detection IDs" or "Filter" parameters. If both are defined, only the "Detection IDs" parameter will be used. The "Filter" parameter will be ignored.	severity:>=80
Status	Optional	The updated status of the detection(s).	In Progress
Comment	Optional	The comment to add to the detection(s).	testAlertComment0208a
Assignee	Optional	The email address of the user assigned to the detection(s).	sysint@d3security.com
Add Tag	Optional	The associated value to add to the detections as a tag.	Malicious1_tag
Remove Tag	Optional	The option to remove tags from the detection(s).	Suspicious1_tag

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "meta": {
        "query_time": 0.677153432,
        "writes": {
            "resources_affected": 1
        },
        "powered_by": "detectsapi",
        "trace_id": "*****"
    }
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

query_time	0.677153432
writes	{'resources_affected': 1}
powered_by	detectsapi
trace_id	*****

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Identity-based Detections failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Crowdstrike Identity Protection portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Detection IDs Not Found.

Error Sample Data

Update Identity-based Detections failed.

Status Code: 404.

Message: Detection IDs Not Found.

Update Incidents

Updates the specified Incidents, including status and comments with additional info.

READER NOTE

The input parameter Incident IDs is required to run this command.

You should already have your desired Incident IDs on hand to run this command. If you don’t, you may use the Fetch Event command with the Event Type parameter set to Incident to view a list of Incident IDs. The Incident IDs can be found in the raw data at the path $.incidentId.

Input

Input Parameter	Required/Optional	Description	Example
Incident IDs	Required	The ID(s) of the incident(s) to update. Incident IDs can be obtained using the Fetch Event command.	[ "*****" ]
Status	Optional	The updated status of the incident(s).	RESOLVED
Update Status Reason	Optional	The reason for the updated incident status.	Fixed already.
Comment	Optional	The comment to add to the incident(s).	testComment0215

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "data": {
            "setIncidentState": {
                "incidents": {
                    "incidentId": "*****",
                    "lifeCycleStage": "RESOLVED",
                    "comments": {
                        "author": {
                            "displayName": "*****"
                        },
                        "text": "testComment0215"
                    }
                }
            }
        }
    }
]

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Updated Incidents Count

1

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Incidents failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Crowdstrike Identity Protection portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Incident ID Not Found.

Error Sample Data

Update Incidents failed.

Status Code: 404.

Message: Incident ID Not Found.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the CrowdStrike Identity Protection portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: access denied, authorization failed.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: access denied, authorization failed.