Utility Commands

In D3 SOAR, Utility Commands are out-of-the-box commands that you can use to manipulate system data. Our platform provides hundreds of Built-In Utility Commands to automate data manipulation, enrichment, and actions within the system. You can also create and customize your own Utility Command to perform data-processing and utility functions, with maximum flexibility and control.

The Utility Commands module is a central repository of all Commands accessible to you. This module provides you with an editor interface to build your own custom Commands using Codeless Playbook or Python implementation. As you build your Commands, you have maximum flexibility in creating the custom tool that fits best into your workflow.

Anatomy of the Utility Commands Module

You can access the Utility Commands module in Configurations by clicking on the Tool icon in the left side navigation bar.

Additional Utility Commands can also be accessed in Playbooks

The Utility Command module consists of the main Command Editor canvas and a panel for configuring its basic details and input/output data. The following is an overview of:

• Action Bar

• Command Details

• Command Editor

Action Bar

The Action Bar provides quick access to key actions that you can take on a Utility Command:

• Back button: Navigate back to the previous page.

• Live / Edit Mode: The Edit and Live modes allow you to make changes to an existing Command without affecting the Commands currently being used in other Playbooks.

• Submit: Submit this Command to be used by others after editing.

• More Button

• Clone Command: Make a copy of the current Command.

• Delete Command: Delete the Live or Draft version of the Command. You’ll need to delete both in order to completely remove the Command.

• Command Reference: See the relationships between other Playbooks and Commands. This feature is only available for Commands built with the Playbooks.

Reader Note

Editing features of the Action Bar are only available for custom Commands. For System commands, users are not allowed to edit them.

Command Details

Command Details is located on the left side of the screen and provides high-level information about the selected Command. This panel provides you with the following tabs, depending on the type of implementation:

• Overview

  • Settings

  • Inputs

  • Outputs

• New Task (Playbook only): displays a list of Playbook Tasks, Integration, and Utility Commands for configuring your Playbook.

• Test (Python only): Test your Python implemented Command

Overview

The Overview tab allows you to configure the basic essential information of a Command such as name, description, and so on. It also provides a space to configure the Input and Output parameters of the Command.

There are 300+ out-of-the-box Utility Commands ready for use immediately. These system commands will not be editable. To create your own custom Command, use the + button. See Creating a Utility Command for more details.

Custom commands will require either python implementation or codeless playbook implementation. This will determine the view of the Command Editor, and cannot be changed later.

Settings

The Settings tab provides you with a view of the Command’s basic information, and the ability to edit these basic fields.

Inputs

Inputs are the parameters this Command requires to execute. For a custom command, you can add input parameters you may need.

Outputs

Outputs defines the type of output this Command can return after execution.

You can define 4 different types of outputs for increased flexibility

1. Key Fields: the most important fields to be extracted out as individual fields.

2. Return Data: shows the Success / Failure status of a Task for Integration Commands. For Transformation and Condition Commands, the return data is specified with corresponding output data types.

3. Context Data: the raw data that has been parsed and formatted which can then be stored in D3 Playbooks for data sharing.

4. Raw Data: shows the unformatted and raw output data

You can also set the Sample Data fields to show an example of the data this Command can output.

Command Editor

The workspace in which you can create a Command, in 2 ways of implementation: as a Codeless Playbook, or in Python script. Each implementation method has a different editor interface.

Implementation Method	Screenshot
Python This method is suitable for those with advanced experience in writing Python scripts. It allows them to create and edit the Python scripts used to execute the Custom Command.
Codeless Playbook This method allows you to create a Codeless Playbook that will execute the Custom Command. This implementation type contains the same interface as the Incident Playbook Editor, where you can simply drag and drop the relevant task nodes from the right panel to create their desired workflow.

Categories of Utility Commands

There are 3 main categories of Utility Commands: Basic Utility, Cyber Utility, and System Utility.

Creating a Utility Command

To create a custom Utility Command:

Configuring Input Parameters

Configuring the input parameters allows you to define the type of data the Command can ingest for processing.

In this example, we’re going to create an add_string command that appends two strings. The input parameters for this command are text strings.

Follow the steps below to create an Input Parameter.

Configuring Output

You can define the sample outputs of a Utility Command to provide context for other users to understand the Utility Command.

1. Key Fields: the most important fields to be extracted out as individual fields.

2. Return Data: shows the Success / Failure status of a Task for Integration Commands. For Transformation and Condition Commands, the return data is specified with corresponding output data types.

3. Context Data: the raw data that has been formatted into a structured JSON object format, which can then be stored in D3 Playbooks for data sharing.

4. Raw Data: shows the unformatted and raw information of external Events provided by third-party vendors.

You can also set the Sample Data fields to show an example of the data this Command can output.

Testing & Submitting a Command

The D3 SOAR platform allows you to test any custom and built-in Commands to test the function. Each implementation method has a different Test UI, but they function similarly.

To test a Command (Python Implementation)

To test a Command (Codeless Playbook Implementation)

To test a Utility Command built with the Playbook implementation, click the Run Test button located at the top of the editor.

Once the playbook is ran, you can click on the ✅ icon of the first task to view the Test Result of the command. You can also view individual results of each task by clicking on their respective ✅ icons.

Command’s Overall Test Result

In the base task’s Test Result, you can see a list of individual Tasks in the current Command, and their test status. Clicking on a Task will also open the selected Task Details to view the execution and input details.

Pending Tasks did not automatically proceed through the test and could be awaiting further action.

Done Tasks shows all tasks that were able to run through the test. It will contain both failed and successful tasks.

Remote Utility Command with D3 Webhook API

A Utility Command can be run remotely via third-party or another D3 SOAR Instance through the D3 Webhook API. In order to do so, you must enable Webhook to allow access to the D3 API and use a REST API such as Postman.

For this example, we will demonstrate the use of a remote utility command with the command Create Task to create an ad hoc task. You can create an ad hoc task through Postman or any other program through REST API. The response of the API call will indicate the result of the task, and you can also view this created task in the Incident module.

Create A New Ad Hoc Task Via D3 API Using Postman:

1. Navigate to Configurations > Utility Commands.

   

2. Search for Create Task.

   

3. Select Create Task Command from the list.

   

4. Enable Webhook under Webhook Settings

   

5. Click on the Setup Webhook Keys button to set up webhook keys.

6. Click on the + button to generate a new webhook key.

   

7. A new Key is generated. This key can be reused as many times as needed. Use the refresh button to generate a new key.

   

8. Open Postman. Prepare for a REST API request.

   

9. Prepare for the JSON data in the request body.
   Go to Investigation Dashboard, find an incident as an example.
   For this example we will input these parameters:

   • Incident No.: 20220502-20

   • Site: Security Operations

   • Username: admin

Reader Note

The following code snippet is only a template. You will need to fill in the values according to your system’s information because every instance of D3 SOAR will have different sites, incidents, users, and task types.

   {
    //Environment Variables
    "Site": "",
    "Username": "",
    //Input Parameters
    "CommandParams": {
        "Task Name": "SampleTask",
        "Task Type": "",
        "Task Description": "",
        "Assignee": "",
        "Due Date": "",
        "Required": "No",
        "Incident Number": ""
    }
}

• The response status of the request indicates the success of the request.

• The returnData in the response body indicates the success of the task creation.

10. Result: The Command Center shows the log of the command execution.

    

The task is also created in the Pending Tasks section.

Exporting & Importing Custom Utility Commands

D3 SOAR allows you to export and import custom utility commands from one D3 SOAR environment to another. This document will provide you with the step-by-step instructions on the entire exporting and importing process.

Reader Note

The prerequisites for using this guide are:

• An active custom utility command created in D3 SOAR

• Another D3 SOAR environment to import the custom utility command to

Exporting a Custom Utility Command

1. Once you are logged into the D3 SOAR environment with the created custom utility command, navigate to Configuration on the top menu bar. On the left side bar menu, click Utility Commands. Use the search box to find and select the custom utility command you want to export.

   

2. Ensure the command status is Live. You should see an indicator near the top right corner. If the command status is Draft, you will need to submit it to go live. Click the three-dot button, then Version History.

   

3. Select the version of the custom utility command to export. Click Export This Version, then Export to confirm. The custom utility command will be exported and downloaded as an XML file. You will need this file to import the utility command in later steps.

   

Importing a Custom Utility Command

1. Log in to the D3 SOAR environment you wish to import the custom utility command to. Navigate to Configuration on the top menu bar. On the left side bar menu, click Utility Commands, then + to add a new custom utility command.

   

2. Configure the custom utility command to add.

   

   1. Command Name: Enter a relevant name for the command. Please note that the command name must start with a letter, and can only contain letters, numbers and underscores!

   2. Implementation: Select Codeless Playbook for the purposes of importing a custom utility command.

   3. Command Category: Select the appropriate command category for the command you will import. Available categories include Basic Utility, Cyber Utility, and System Utility.

   4. Click Add to confirm and add the custom utility command.

3. Click on the three-dot button found near the top right corner, then Replace Command.

   

4. Replace the command with the exported XML file. Click Browse to locate and select the previously exported XML file, then Replace to confirm the configuration.

   

5. You will see the custom utility command tasks appear in the editor. Click Submit (found at the top right corner) to allow the command to be live and available for use in the D3 SOAR environment.

6. Done! You have successfully imported a custom utility command from another D3 SOAR environment.