Cybereason

LAST UPDATED: JULY 30, 2025

Overview

The Cybereason Defense Platform is a military-grade, real-time detection and response platform. It moves beyond endless alerting to instead recognize, expose, and end malicious operations before they take hold. The Cybereason Defense Platform allows organizations to get a complete picture of malicious activities and terminate attacks in minutes. This integration provides incident query, enrichment, and active responses to malicious operations.

D3 SOAR is providing REST operations to function with Cybereason.

Cybereason is available for use in:

D3 SOAR	V14.5.64.0+
Category	Endpoint Protection
Deployment Options	Option II, Option IV

Connection

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

Parameter	Description	Example
Server URL	The URL of the Cybereason server.	https://integration.cybereason.net:8443
Authentication Type	The type of authentication used for the integration connection. The two options are Basic Authentication and Client Certificate Authentication.	Basic Authentication
Authentication Type: Basic Authentication
User Name	The user name of the Cybereason account	test@example.com
Password	The password of the user account.	#E***sx=
Authentication Type: Client Certificate Authentication
Certificate	The authentication certificate	-----BEGIN CERTIFICATE----- MIIJWgglAa9fkKHn/5JZFZ0qf0IvBD+ftC3yE1sz35rut/4grE3c0TI7tYq1Ya****************************VaaG6PQinQ== -----END CERTIFICATE-----
Private Key	The authentication RSA private key.	-----BEGIN RSA PRIVATE KEY----- MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQCKE***********************R8eUohZCtt0V9lg== -----END RSA PRIVATE KEY-----

Permission Requirements

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

READER NOTE

Cybereason recommends that you do not use the API User role for anyone performing API requests as it has limited permissions. Instead, it is recommended to use the Super user role, as this role has permission to send all API requests. Please refer to Cybereason Required permission for more information.

Command	Required Permission
Add Comment To Malops	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer
Add Malop Labels	L1 Analyst, L2 Analyst, L3 Analyst, Executive
Delete Malop Labels	L1 Analyst, L2 Analyst, L3 Analyst, Executive
Download Files	L2 Analyst, L3 Analyst, System Admin, Sensor Viewer
Exclude Behavior From Malops	L3 Analyst
Fetch Event	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Fetch Incident	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Get Malop Labels	L1 Analyst, L2 Analyst, L3 Analyst, Executive
Get Malop Remediation Details	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer
Get All Malops	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Get Remediation Progress	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer
Is Host Connected	System Admin
Isolate Machine	L3 Analyst
Kill Process	L3 Analyst, Sensor Viewer
Query Domain	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Query File	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Query Malops	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Query Processes	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Query Sensors	System Admin
Query User	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Remediate	L3 Analyst, Sensor Viewer
Run Query	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer, Executive
Set IOC Reputation	Responder (L1/L2)
Unisolate Machine	L3 Analyst, Sensor Viewer
Update Malop Labels	L1 Analyst, L2 Analyst, L3 Analyst, Executive
Update Malops Status	L1 Analyst, L2 Analyst, L3 Analyst, Sensor Viewer
Test Connection	At Least one of L3 Analyst and Responder (L1/L2)

Configuring Cybereason to Work with D3 SOAR

No additional configurations are needed in Cybereason to work with D3 SOAR. Please note that any password changes made in the Cybereason platform must also be updated in D3 for the connection to continue working.

Configuring D3 SOAR to Work with Cybereason

Log in to D3 SOAR.
Find the Cybereason integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Cybereason 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 Cybereason.
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.
  Basic Authentication
  
  1. Copy the URL from the Cybereason platform and input it for the Server URL (domain level) field. The default server URL is https://integration.cybereason.net:8443.
  2. Select Basic Authentication.
  3. Input your User Name.
  4. Input your Password.
  Client Certificate Authentication
  
  1. Copy the URL from the Cybereason platform and input it for the Server URL (domain level) field. The default server URL is https://integration.cybereason.net:8443.
  2. Select Client Certificate Authentication.
  3. Input the Certificate provided by Cybereason.
  4. Input the Private Key provided by Cybereason.
10. 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.
11. 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.
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

Cybereason 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 Cybereason API, please refer to the Cybereason API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Cybereason 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.

Add Comment To Malops

Adds a comment to the specified Malops.

READER NOTE

The parameter Malop IDs is required to run this command.

Run the Get All Malops command to obtain Malop IDs. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Malop IDs	Required	The IDs of the malops to add a comment. Malop IDs can be obtained using the Get All Malops command. If the input Malop IDs are invalid, no new Malop will be created and the error message “Malop does not exist” will be returned.	["***"]
Comment	Required	The comment text to add the specified Malops.	This is a test Comment to the malop

Output

To view the sample output data for all commands, refer to this article.

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.	Add Comment To Malops failed. An error occurred (MalopIDNotFound) when calling the Add Comment To Malops operation.
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 Cybereason 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: The Malop ID does not exist.

Error Sample Data

Add Comment To Malops failed. An error occurred (MalopIDNotFound) when calling the Add Comment To Malops operation.

Status Code: 404.

Message: The Malop ID does not exist.

Add Malop Labels

Adds new Malop label(s) to the list of labels. If the label(s) already exist, an error will return.

READER NOTE

When adding Malop labels, please keep in mind, the labels are case sensitive. For example, “security” and “Security” will be added as two different labels.
If your label text input already exists, D3 SOAR will return the existing label with the corresponding label ID.
An improper input format may result in only one label created. For example, you use the input format “label1, label2” or label1, label2 to create two new labels. These formats are incorrect and will create one label. The correct format [“label1”, “label2”] will output two labels: “label1” and “label2”.

Input

Input Parameter	Required/Optional	Description	Example
Label Texts	Required	The label text to add to the label list.	["Spear Phishing label"]

Output

To view the sample output data for all commands, refer to this article.

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.	Add Malop Labels failed. An error occurred when calling the Add Malop Labels operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Label Texts) is invalid.

Error Sample Data

Add Malop Labels failed. An error occurred when calling the Add Malop Labels operation.

Status Code: 400.

Message: The value for parameter (Label Texts) is invalid.

Delete Malop Labels

Deletes existing Malop label(s) from the list of labels.

READER NOTE

The parameter Label IDs is required to run this command.

Run the Get Malop Labels command to obtain Label IDs. Label IDs can be found in the returned raw data at the path $[*].id.

Please note:

The same Label cannot be deleted twice.
If some of your input Label IDs do not exist, existing labels won’t be deleted and D3 SOAR will return an error about Label IDs not existing.
If some malops are using the labels you want to delete, the labels will be removed from the malops after deletion.

Input

Input Parameter	Required/Optional	Description	Example
Label IDs	Required	The IDs of the labels to remove from the label list. Label IDs can be obtained using the Get Malop Labels command. If the input Label IDs do not exist, no labels will be deleted and the error message “Label ID Not Exist” will be returned.	[***]

Output

To view the sample output data for all commands, refer to this article.

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.	Delete Malop Labels failed. An error occurred (LabelDoesNotExist) when calling the Delete Malop Labels operation.
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 Cybereason 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: Label Does Not Exist.

Error Sample Data

Delete Malop Labels failed. An error occurred (LabelDoesNotExist) when calling the Delete Malop Labels operation.

Status Code: 404.

Message: Label Does Not Exist.

Download Files

Downloads files from the Element Details screen and saves them in the D3 database.

READER NOTE

The parameter File GUIDs is required to run this command.

Run the Query File command to obtain File GUIDs. The File GUIDs can be found in the returned raw data at the path $.data.resultIdToElementDataMap.<id>.guidString.

Initiator User Name is an optional parameter to run this command.

Run the Get Malop Remediation Details command to obtain the Initiator User Name. The Initiator User Names can be found in the returned Raw Data, under path $.initiatingUser.

Input

Input Parameter	Required/Optional	Description	Example
File GUIDs	Required	The GUIDs (globally unique identifiers) of the files to download. File GUIDs can be obtained using the Query File command. Note: Files from a machine that is not connected to Cybereason cannot be downloaded.	["-*.-*"]
Initiator User Name	Optional	The username of the user initiating the file download.	test@example.com

Output

To view the sample output data for all commands, refer to this article.

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.	Download Files failed. An error occurred when calling the Download Files operation.
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 Cybereason 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: Please check if the FIle GUIDs are correct.

Error Sample Data

Download Files failed. An error occurred when calling the Download Files operation.

Status Code: 404.

Message: Please check if the FIle GUIDs are correct.

Exclude Behavior From Malops

Instructs the Cybereason platform to not trigger additional Malops for behavior in specified Malops.

READER NOTE

The parameter Malop IDs is required to run this command.

Run the Get All Malops command to obtain Malop IDs. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Malop IDs	Required	The IDs of the Malops to exclude their behaviour from triggering additional malops. Malop IDs can be obtained using the Get All Malops command.	["***"]

Output

To view the sample output data for all commands, refer to this article.

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.	Exclude Behavior From Malops failed. An error occurred (MalopIDNotExist) when calling the Exclude Behavior From Malops operation.
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 Cybereason 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: The Malop ID does not exist.

Error Sample Data

Exclude Behavior From Malops failed. An error occurred (MalopIDNotExist) when calling the Exclude Behavior From Malops operation.

Status Code: 404.

Message: The Malop ID does not exist.

Fetch Event

Returns events (AI Hunting Malops) from the Cybereason environment based on specified criteria.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to fetch events in UTC time. Time ranges can be defined by the event’s updated time or start time.	2022-05-04 00:00
End Time	Optional	The end time of the time range to fetch events in UTC time. Time ranges can be defined by the event’s updated time or start time.	2022-05-05 00:00
Top Recent Event Number	Optional	The maximum number of events (up to 1,000) to return. The default value is 100.	100
Search Condition	Required	The JSON-formatted queries to filter results. See Generic Queries for more on the query syntax. It is recommended to use the provided sample data as a template to build your query by modifying the “filters” object. Note: Do not input a value for the totalResultLimit key in the JSON object. It will be overwritten by the defined value of the Top Recent Events Number parameter of this command. The defined values for the Start Time and End Time parameters will be used to set the time range filter. There is no need to define it in the JSON object here.	{ "templateContext": "MALOP", "queryPath": [ { "requestedType": "MalopProcess", "filters": [ { "facetName": "hasRansomwareSuspendedProcesses", "values": [ false ], "filterType": "Equals" } ], "result": true } ] }
Query Time Type	Optional	Specifies whether the query is performed by Malop Last Update Time or Malop Start Time. The default value is Malop Last Update Time.	Malop Last Update Time
Tolerance Scope(Minute)	Optional	The tolerance scope in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	10

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 D3 system fields which are standardized by the D3 data model. You can edit the provided mapping or customize new mappings by need. Please refer to Event and Incident Intake Field Mapping for details.

As a system integration, the Cybereason integration has some pre-configured field mappings for default field mapping.

Default Event Source

The Default Event Source is the default set of field mappings that is applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events (e.g., Original event ID and File Hash). The default event source has a Main Event JSON Path used to extract a batch of events from the raw response data.

Main Event JSON Path: $.data.resultIdToElementDataMap

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 data.resultIdToElementDataMap. The child node denoting the Original event ID field would be guidString. Putting it together, the JSON Path expression to extract the Original event ID is $.data.resultIdToElementDataMap.guidString.

Field Name	Source Field
Original event ID	.guidString
Malop Activity Types	.simpleValues.malopActivityTypes.values
Malop Last Update Time	.simpleValues.malopLastUpdateTime.values
Malop Creation Time	.simpleValues.creationTime.values
File Hash	.simpleValues.rootCauseElementHashes.values
Comments	.simpleValues.comments.values[*].message
Root Cause ID	.elementValues.primaryRootCauseElements.elementValues[*].guid
Root Cause Name	.elementValues.primaryRootCauseElements.elementValues[*].name
Affected Users	.elementValues.affectedUsers.elementValues[*].name
Affected Machines ID	.elementValues.affectedMachines.elementValues[*].guid
Affected Machines Name	.elementValues.affectedMachines.elementValues[*].name
Priority	.malopPriority
Event Type	.simpleValues.detectionType.values
Start Time	.simpleValues.malopStartTime.values
Root Cause Element Names	.simpleValues.rootCauseElementNames.values
Root Cause Element Types	.simpleValues.rootCauseElementTypes.values
Management Status	.simpleValues.managementStatus.values
Decision Feature	.simpleValues.decisionFeature.values
Process ID	.elementValues.primaryRootCauseElements.elementValues[?(@.elementType=='Process')].guid

Output

To view the sample output data for all commands, refer to this article.

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. An error occurred when calling the Fetch Event operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: SearchCondition is not valid JSON input.

Error Sample Data

Fetch Event failed. An error occurred when calling the Fetch Event operation.

Status Code: 400.

Message: SearchCondition is not valid JSON input.

Fetch Incident

Returns incident(s) from the Cybereason environment based on specified criteria.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to fetch incidents in UTC time. Time ranges can be defined by the incident’s updated time or start time.	2022-05-04 00:00
End Time	Optional	The end time of the time range to fetch incidents in UTC time. Time ranges can be defined by the incident’s updated time or start time.	2022-05-05 00:00
Top Recent Incident Number	Optional	The maximum number of incidents (up to 1,000) to return. The default value is 100.	100
Search Condition	Required	The JSON-formatted queries to filter results. See Generic Queries from Cybereason’s API documentation for more information on the query syntax. It is recommended to use the provided sample data as a template to build your query by modifying the “filters” object. Note: Do not input a value for the totalResultLimit key in the JSON object. It will be overwritten by the defined value of the Top Recent Events Number parameter of this command. The defined values for the Start Time and End Time parameters will be used to set the time range filter. There is no need to define it in the JSON object here.	{ "templateContext": "MALOP", "queryPath": [ { "requestedType": "MalopProcess", "filters": [ { "facetName": "hasRansomwareSuspendedProcesses", "values": [ false ], "filterType": "Equals" } ], "result": true } ] }
Query Time Type	Optional	Specifies whether the query is performed by Malop Last Update Time or Malop Start Time. The default value is Malop Last Update Time.	Malop Last Update Time
Tolerance Scope(Minute)	Optional	The tolerance scope in minutes of the query to fetch incidents between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	10

Incident Field Mapping

For this integration, the default incident fields in D3 SOAR are fixed with no built-in source fields. Users can specify the source fields as needed.

Event and Incident Intake Field Mapping

Please note that incident and event intake commands require both Event Field and Incident Field Mapping. These field mappings are the default event/incident field mappings for D3 system integrations. You can edit the provided mappings or create custom mappings as needed. Please refer to Event and Incident Intake Field Mapping for more details.

Incident Main JSON Path: $.data.resultIdToElementDataMap

A JSON path expression begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). This format is known as the dot notation. Square brackets with nested quotation marks ([‘...’]), known as the bracket notation, should be used to separate child elements in JSON arrays.

For example, the root node of a JSON Path is data.resultIdToElementDataMap. The child node denoting the Title field would be guidString. Putting it together, the JSON Path expression to extract Title is $.data.resultIdToElementDataMap.guidString.

Field Name	Source Field
Title	User to define
Description	User to define
Severity	User to define, default is “Low”
Incident Type *	User to define, default is the first Incident form in D3 SOAR system
Incident Creator	User to define
Incident Owner	User to define
Incident Playbook	User to define
Due In Date	User to define
Unique Key	User to define
Tactics	User to define
Techniques	User to define

Event Field Mapping

Main Event JSON Path

$.data.resultIdToElementDataMap

The event field mapping in Fetch Incident is the same as the one in Command Fetch Event.

Please refer to the command Fetch Event for detail.

Output

To view the sample output data for all commands, refer to this article.

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 Incident failed. An error occurred when calling the Fetch Incident operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: 'searchCondition' is not valid JSON input.

Error Sample Data

Fetch Incident failed. An error occurred when calling the Fetch Incident operation.

Status Code: 400.

Message: 'searchCondition' is not valid JSON input

Get Malop Labels

Returns a list of all Malop labels.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

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.	Get Malop Labels failed. An error occurred when calling the Get Malop Labels operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please ensure username and password are correct.

Error Sample Data

Get Malop Labels failed. An error occurred when calling the Get Malop Labels operation.

Status Code: 400.

Message: Please ensure username and password are correct.

Get Malop Remediation Details

Retrieves details about remediation actions performed on a particular Malop.

READER NOTE

Malop ID is an optional parameter to run this command.

Run the Get All Malops command to obtain Malop ID. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

If Malop ID is empty, a list of NOMALOP remediations will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Malop ID	Optional	The unique ID of the Malop to retrieve remediation details. Malop IDs can be obtained using the Get All Malops command. The default value of this Malop ID is NOMALOP.	11.***

Output

To view the sample output data for all commands, refer to this article.

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.	Get Malop Remediation Details failed. An error occurred when calling the Get Malop Remediation Details operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please check if the Malop IDs are correct.

Error Sample Data

Get Malop Remediation Details failed. An error occurred when calling the Get Malop Remediation Details operation.

Status Code: 400.

Message: Please check if the Malop IDs are correct.

Get All Malops

Returns details about all Malops, including the last updated time, the detection engine, and detection type of EDR in your environment. This command will return details about all Auto Hunt Malops and Endpoint Protection Malops in your environment, including active, remediate, close, and excluded malops.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to retrieve Malops in UTC time.	2021-11-01 00:00
End Time	Required	The end time of the time range to retrieve Malops in UTC time.	2022-04-21 00:00

Output

To view the sample output data for all commands, refer to this article.

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.	Get All Malops failed. An error occurred when calling the Get All Malops operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please ensure username and password are correct.

Error Sample Data

Get All Malops failed. An error occurred when calling the Get All Malops operation.

Status Code: 400.

Message: Please ensure username and password are correct.

Get Remediation Progress

Gets the remediation progress statuses.

READER NOTE

The parameter Remediation IDs is required to run this command.

Run the Remediate command to obtain Remediation IDs. Remediation IDs can be found in the returned Raw Data at the path $.remediationId.

Malop ID is an optional parameter to run this command.

Run the Remediate command to obtain Malop ID. Malop IDs can be found in the returned Raw Data at the path $.malopId.

Please note that the Malop ID must match to Remediation IDs. Please run the Remediate command and use the pair of values you get.

Input

Input Parameter	Required/Optional	Description	Example
Malop ID	Optional	The unique ID of the Malop to return the remediation status. Malop IDs can be obtained using the Remediate command. The default value of this Malop ID is NOMALOP.	**
Remediation IDs	Required	The IDs of the remediations to query. Remediation IDs can be obtained using the Remediate command.	["*----**"]

Output

To view the sample output data for all commands, refer to this article.

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.	Get Remediation Progress failed. An error occurred when calling the Get Remediation Progress operation.
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 Cybereason 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: Remediation IDs Not Found.

Error Sample Data

Get Remediation Progress failed. An error occurred when calling the Get Remediation Progress operation.

Status Code: 404.

Message: Remediation IDs Not Found.

Is Host Connected

Checks if the specified machine is connecting to the Cybereason server currently.

READER NOTE

The parameter Machine Names is required to run this command.

Run the Query Sensors command to obtain Machine Names. Machine Names can be found in the returned raw data at the path $.sensors[*].pylumId.

Input

Input Parameter	Required/Optional	Description	Example
Machine Names	Required	The names of the machines to check connection statuses. Machine names can be obtained using the Query Sensors command.	[ "machine1","machine2" ]

Output

To view the sample output data for all commands, refer to this article.

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.	Is Host Connected failed. An error occurred when calling the Is Host Connected operation.
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 Cybereason 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: Machine Names Not Found.

Error Sample Data

Is Host Connected failed. An error occurred when calling the Is Host Connected operation.

Status Code: 404.

Message: Machine Names Not Found.

Isolate Machine

Isolates a machine or machines involved in a specific Malop.

READER NOTE

The parameter Machine Names is required to run this command.

Run the Query Sensors command to obtain Machine Names. Machine Names can be found in the returned raw data at the path $.sensors[*].pylumId.

Malops ID is an optional parameter to run this command.

Run the Get All Malops command to obtain Malop ID. Malop ID can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Machine Names	Required	The names of the machines to isolate. Machine names can be obtained using the Query Sensors command.	[ "***" ]
Malop ID	Optional	The GUID of the Malop associated with the specified machine names. Malop IDs can be obtained using the Get All Malops command. The default value of this Malop ID is NOMALOP.	***

Output

To view the sample output data for all commands, refer to this article.

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.	Isolate Machine failed. An error occurred when calling the Isolate Machine operation.
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 Cybereason 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: Machine Names Not Found.

Error Sample Data

Isolate Machine failed. An error occurred when calling the Isolate Machine operation.

Status Code: 404.

Message: Machine Names Not Found.

Kill Process

Kills specified processes running on a machine.

READER NOTE

The parameter Process IDs is required to run this command.

Run the Query Process command to obtain Process IDs. Process IDs can be found in the returned raw data at the path $.data.resultIdToElementDataMap.<id>.

Input

Input Parameter	Required/Optional	Description	Example
Process IDs	Required	The IDs of the processes to kill. Process IDs can be obtained using the Query Process command.	[ "**" ]

Output

To view the sample output data for all commands, refer to this article.

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.	Kill Process failed. An error occurred when calling the Kill Process operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Process IDs Not Found.

Error Sample Data

Kill Process failed. An error occurred when calling the Kill Process operation.

Status Code: 400.

Message: Process IDs Not Found.

Query Domain

Retrieves information of domain(s) based on domain name(s).

READER NOTE

All input parameters are optional. If all inputs are empty, the first 100 domains from the cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Domains	Optional	The names of the domains to query.	[ "***.co.uk" ]
Limit	Optional	The maximum number of domains to return. A valid input value is an integer between 1 and 1000. The default value is 100.	10

Output

To view the sample output data for all commands, refer to this article.

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.	Query Domain failed. An error occurred when calling the Query Domain operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Limit) is invalid.

Error Sample Data

Query Domain failed. An error occurred when calling the Query Domain operation.

Status Code: 400.

Message: The value for parameter (Limit) is invalid.

Query File

Retrieves information of file(s) based on file hash(es).

READER NOTE

The parameter File Hashes is optional to run this command.

You should already have your desired file hashes on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired file hashes. It can be found in the returned raw data at the path $.data.resultIdToElementDataMap[*].rootCauseElementHashes.
You can also find file hashes from the Cybereason user interface.

All input parameters of this command are optional. If all inputs are empty, the first 100 files from the Cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
File Hashes	Optional	The file hashes to query.	[ "***" ]
Limit	Optional	The maximum number of files to return. A valid input value is an integer between 1 and 1,000. The default value is 100.	10

Output

To view the sample output data for all commands, refer to this article.

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.	Query File failed. An error occurred when calling the Query File operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Limit) is invalid.

Error Sample Data

Query File failed. An error occurred when calling the Query File operation.

Status Code: 400.

Message: The value for parameter (Limit) is invalid.

Query Malops

Retrieves Malop process(es) from defined search conditions.

READER NOTE

The parameter Malops IDs is required to run this command.

Run the Get All Malops command to obtain Malops IDs. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

All input parameters of this command are optional. If all inputs are empty, the first 100 malops from the Cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Results Limit	Optional	The maximum number of results (up to 1,000) to return. The default value is 100.	10
Template Context	Optional	The level of detail to provide in the response data. The available options are Overview, Details, Specific, Full, Malop, Malop_Communication and Custom. The default value is Malop.	Specific
Malop IDs	Optional	The GUIDs of the Malops to query. Malop IDs can be obtained using the Get All Malops command.	[ "***" ]
Filters	Optional	The JSON array of filter conditions to narrow down query results. See Add Filters to a Request from Cybereason’s API documentation for more information about the filter syntax.	[ { "facetName": "creationTime", "filterType": "GreaterThan", "values": [ *** ] } ]

Output

To view the sample output data for all commands, refer to this article.

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.	Query Malops failed. An error occurred when calling the Query Malops operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Malop IDs Not Valid.

Error Sample Data

Query Malops failed. An error occurred when calling the Query Malops operation.

Status Code: 400.

Message: Malop IDs Not Valid.

Query Processes

Retrieves process(es) from a specified query criteria.

READER NOTE

For details about the parameters used in this command, see PROCESS (EDR) in Query Elements and Features from Cybereason’s API documentation.

All input parameters in this command are optional. If all inputs are empty, the first 100 processes from the Cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Machine	Optional	The name of the owner machine to query.	“***-2016”
Process Name	Optional	The name of the process to query.	“**.exe”
Limit	Optional	The maximum number of results (up to 1,000) to return. The default value is 100.	10
Has Suspicions	Optional	The option to query processes associated with any suspicious activities.	True
Has Incoming Connection	Optional	The option to query processes with incoming connections.	False
Has Outgoing Connection	Optional	The option to query processes with outgoing connections.	False
Has External Connection	Optional	The option to query processes with external connections.	False
Unsigned Unknown Reputation	Optional	The option to query processes with unsigned process image files and unknown to reputation services.	False
From Temporary Folder	Optional	The option to query processes running from a temporary folder.	False
Privilege Escalation	Optional	The option to query processes that behave like a privilege escalation tool.	False
Malicious Psexec	Optional	The option to query processes that were executed by the PsExec service maliciously.	False
Custom Fields	Optional	An array containing a list of features of selected elements to return data. Refer to PROCESS (EDR) in see Query Elements and Features from Cybereason’s API documentation for details about the available features to use.	[ "elementDisplayName", "creationTime", "endTime", "commandLine", "productType" ]

Output

To view the sample output data for all commands, refer to this article.

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.	Query Processes failed. An error occurred when calling the Query Processes operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Custom Fields are not valid json input.

Error Sample Data

Query Processes failed. An error occurred when calling the Query Processes operation.

Status Code: 400.

Message: Custom Fields are not valid json input.

Query Sensors

Retrieves details of sensors according to filter conditions.

READER NOTE

All input parameters in this command are optional. If all inputs are empty, the first 100 sensors from the Cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Limit	Optional	The maximum number of sensors to send the query request. A valid input value is an integer between 1 and 1,000. The default value is 100.	10
Offset	Optional	The number of pages to paginate the returned results. The default value of 0 denotes the first page.	0
Sort Direction	Optional	The sorting order (i.e. Ascending or Descending) of the returned results.	Ascending
Filters	Optional	The JSON object of filters to query sensors. See Query Sensors from Cybereason’s API documentation for more information about using filters.	[ { "fieldName": "osType", "operator": "Equals", "values": [ "WINDOWS", "LINUX" ] } ]

Output

To view the sample output data for all commands, refer to this article.

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.	Query Sensors failed. An error occurred when calling the Query Sensors operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Filters) is invalid.

Error Sample Data

Query Sensors failed. An error occurred when calling the Query Sensors operation.

Status Code: 400.

Message: The value for parameter (Filters) is invalid.

Query User

Retrieves details of a user.

READER NOTE

Username is an optional parameter to run this command.

You can obtain usernames from the Cybereason UI. Navigate to Investigation>User Account>Get results>choose to get details for one user account>Copy the User name.

All input parameters in this command are optional. If all inputs are empty, the first 100 users from the Cybereason dataset will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Username	Optional	The username to query.	admin
Limit	Optional	The maximum number of users to return. A valid value is an integer between 0 and 1,000. The default value is 100.	10

Output

To view the sample output data for all commands, refer to this article.

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.	Query User failed. An error occurred when calling the Query User operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Filters) is invalid.

Error Sample Data

Query User failed. An error occurred when calling the Query User operation.

Status Code: 400.

Message: The value for parameter (Filters) is invalid.

Remediate

Remediates a specific process or file. Run the Get Remediation Progress command with Remediation IDs to view the remediation progress.

READER NOTE

The parameter Target IDs is required to run this command.

Run the Query Processes or Query Files command to obtain Target IDs. Target IDs can be found in the returned raw data at the path $.data.resultIdToElementDataMap.<id>.
For Unquarantine File, you can obtain the Target IDs by running the Run Query command.
- Please note: Run Query Search conditions must contain: "requestedType" with value "QuarantineFile" and "templateContext" with value "OVERVIEW".
- Please refer to the Run Query command example to get Unquarantine File Target ID.

Malop ID is an optional parameter to run this command.

Run the Get All Malops command to obtain Malop ID. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Malop ID	Optional	The unique ID of the Malop containing processes or files to remediate. Malop IDs can be obtained using the Get All Malops command. The default value of this Malop ID is NOMALOP.	11.***
Target IDs	Required	The GUID of the process or file to remediate. Target IDs can be obtained using the Query Process or Query Files command. For Unquarantine Files, you can retrieve the Target ID using the Run Query command. Note: The value of the “requestedType” key must be “QuarantineFile”, and the value of the “templateContext” key must be “OVERVIEW” in the Run Query command’s Search Condition parameter.	["-*.-*"]
Action Type	Required	The remediation action to perform. The available action types are KILL PROCESS, QUARANTINE FILE, UNQUARANTINE FILE, BLOCK FILE, KILL PREVENT SUSPEND, and UNSUSPEND PROCESS.	QUARANTINE FILE

Output

To view the sample output data for all commands, refer to this article.

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.	Remediate failed. An error occurred when calling the Remediate operation.
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 Cybereason 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: Malop IDs Not Found.

Error Sample Data

Remediate failed. An error occurred when calling the Remediate operation.

Status Code: 404.

Message: Malop IDs Not Found.

Run Query

Searches for specific indicators and behaviors throughout your environment.

Input

Input Parameter

Required/Optional

Description

Example

Search Condition

Required

The JSON-formatted queries to filter results. See Run a Query from Cybereason’s API documentation for more information about the query syntax.

{

"totalResultLimit": 1000,

"perGroupLimit": 100,

"perFeatureLimit": 100,

"templateContext": "MALOP",

"queryPath": [

{

"requestedType": "DomainName",

"filters": [

{

"facetName": "elementDisplayName",

"values": [

"syoblnnhsupt.co.uk"

],

"filterType": "ContainsIgnoreCase"

}

],

"isResult": true

}

]

}

Output

To view the sample output data for all commands, refer to this article.

Request Example (Get Unquarantine File Target ID)

CODE

{

    "totalResultLimit": 100,

    "perGroupLimit": 100,

    "templateContext": "OVERVIEW",

    "queryPath": [

        {

            "requestedType": "QuarantineFile",

            "filters": [

                {

                    "facetName": "ownerMachine",

                    "values": [

                        "***-poc"

                    ]

                },

                {

                    "facetName": "elementDisplayName",

                    "values": [

                        "**.dll"

                    ],

                    "filterType": "ContainsIgnoreCase"

                }

            ],

            "isResult": true

        }

    ],

    "customFields": [

        "elementDisplayName",

        "ownerMachine"

    ]

}

Result Example (Get Unquarantine File Target ID)

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.	Run Query failed. An error occurred when calling the Run Query operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Search Condition) is invalid.

Error Sample Data

Run Query failed. An error occurred when calling the Run Query operation.

Status Code: 400.

Message: The value for parameter (Search Condition) is invalid.

Set IOC Reputation

Sets a custom, organization-specific reputation (whitelist or blacklist) for a file, IP address, or domain name.

Input

Input Parameter	Required/Optional	Description	Example
Keys	Required	The file hash value (MD5 or SHA1), IP address, or domain name to set the IOC reputation.	[ "***" ]
Malicious Type	Required	The reputation to set (Blocklist or Allowlist).	Blocklist
Prevent	Required	Indicates whether to prevent the file's execution with Application Control. Note this option is ONLY applicable for the File type. You cannot prevent a file's execution if Malicious Type is Allowlist. If your request includes IP addresses or domain names to update, you must set this parameter to false.	True
Remove	Required	The option to remove the current reputation (True) or add a reputation (False). Note: Setting the value to True will override other parameters.	True

Output

To view the sample output data for all commands, refer to this article.

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.	Set IOC Reputation failed. An error occurred when calling the Set IOC Reputation operation.
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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The file hash value is invalid.

Error Sample Data

Set IOC Reputation failed. An error occurred when calling the Set IOC Reputation operation.

Status Code: 400.

Message: The file hash value is invalid.

Unisolate Machine

Removes machine(s) associated with a Malop from isolation.

READER NOTE

The parameter Machine Names is required to run this command.

Run the Query Sensors command to obtain Machine Names. Machine Names can be found in the returned raw data at the path $.sensors[*].pylumId.

Malop ID is an optional parameter to run this command.

Run the Get All Malops command to obtain Malop ID. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Machine Names	Required	The names of the machines to unisolate. Machine names can be obtained using the Query Sensors command.	[ "*-*" ]
Malop ID	Optional	The associated Malop ID of the sensor. Malop IDs can be obtained using the Get All Malops command. The default value of this Malop ID is NOMALOP.	11.-***

Output

To view the sample output data for all commands, refer to this article.

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.	Unisolate Machine failed. An error occurred when calling the Unisolate Machine operation.
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 Cybereason 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: Machine Names Not Found.

Error Sample Data

Unisolate Machine failed. An error occurred when calling the Unisolate Machine operation.

Status Code: 404.

Message: Machine Names Not Found.

Update Malop Labels

Updates the labels of the specified Malops.

READER NOTE

The parameter Malop IDs is required to run this command.

Run the Get All Malops command to obtain Malop IDs. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Added Labels and Removed Labels are optional parameters to run this command.

Run the Get Malops Label command to obtain Added Labels and Removed Labels. The label IDs can be found in the returned raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Malop IDs	Required	The GUID of Malops to update labels. Malop IDs can be obtained using the Get All Malops command.	["***"]
Added Labels	Optional	The list of label IDs to add to the specified Malops. Label IDs can be obtained using the Get Malops Label command. If an input label has already been added to the Malop, no error will return.	[59,60]
Removed Labels	Optional	The list of label IDs to remove from the specified Malops. Label IDs can be obtained using the Get Malops Label command. If the input label does not exist on the specified Malop, no error will be returned.	[59]

Output

To view the sample output data for all commands, refer to this article.

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 Malop Labels failed. An error occurred when calling the Update Malop Labels operation.
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 Cybereason 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: Malop IDs Not Found.

Error Sample Data

Update Malop Labels failed. An error occurred when calling the Update Malop Labels operation.

Status Code: 404.

Message: Malop IDs Not Found.

Update Malops Status

Updates the status of specified malops.

READER NOTE

The parameter Malop IDs is required to run this command.

Run the Get All Malops commands to obtain Malop IDs. Malop IDs can be found in the returned raw data at the path $.malop[*].guid.

Input

Input Parameter	Required/Optional	Description	Example
Malop IDs	Required	The GUIDs of the Malops to update statuses. Malop IDs can be obtained using the Get All Malops command.	["*", "*" ]
Malop Status	Required	The updated status to apply to the specified Malops. The available statuses are To review, Remediated, Unread, Not relevant, or Under investigation.	Remediated

Output

To view the sample output data for all commands, refer to this article.

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 Malops Status failed. An error occurred when calling the Update Malops Status operation.
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 Cybereason 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: Malop IDs Not Found.

Error Sample Data

Update Malops Status failed. An error occurred when calling the Update Malops Status operation.

Status Code: 404.

Message: Malop IDs 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

Output Type

Description

Return Data Type

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

More details about an error can be viewed in the Error tab.

String

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 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 Cybereason portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please ensure username and password are correct.

Error Sample Data

Test Connection failed. Failed to check connector.

Status Code: 400.

Message: Please ensure username and password are correct.