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
Key Fields: the most important fields to be extracted out as individual fields.
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.
Context Data: the raw data that has been parsed and formatted which can then be stored in D3 Playbooks for data sharing.
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 |  |
Codeless Playbook |  |
Categories of Utility Commands
There are 3 main categories of Utility Commands: Basic Utility, Cyber Utility, and System Utility.
Command Type | Details | Example Commands |
Basic Utility | Enables simple data processing on the following data types:
The types of data manipulation functions include:
| Append Text Contains Number Contains Text Convert Number to Text Ends with Less or equal |
Cyber Utility | Performs cyber-specific data processing that generally focuses on enrichment or extraction of information on your artifacts. Examples of artifacts are:
| Extract Artifacts From Excel File Check Email Authenticity Extract URLs from JSON Object |
System Utility | Performs actions on system objects such as:
| Close Incident Add to Global List Generate Summary Report Resume SLA Send Email Add TTP to Incident |
Creating a Utility Command
To create a custom Utility Command:
Click the + button.
In the Add Command pop-up, provide the Command Name, choose your Implementation and Command Category.
Reader Note
Both the implementation method and category cannot be changed once the Command is created.
Click + Add to create custom Utility Command.
In the Settings tab, fill out the following details for the Command’s information.
Command Name: sets a name for the Command, which must match the function name used in the Python script.
Command Description: provides a clear description of the Command.
Webhook Settings: enable D3 Webhook API and set up a webhook key to run this command remotely.
Implementation: provides 2 ways of creating a Command, between Codeless Playbook or Python script. This is selected when you first add the Command and cannot be changed.
Category: you can choose one of the following categories: Basic Utility, Cyber Utility, System Utility. This cannot be changed in settings.
Tags: further categorize and improve searchability and classification.
Features: decides where the Command will be available for use within the D3 SOAR platform.
Schedule: sets specific time intervals and frequency for when the action will run. This action can be performed by selecting the Enable Schedule checkbox.
After clicking on the + New Schedule button, you can create a new schedule and job recurrence for a custom Command. This is only available when the command is live.
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.
Insert the Input Parameter name that is used within the Command.
Define what Display Name will be displayed. The parameter name will be used if this field is blank.
Select the data type this parameter should have.In our add_string example, the parameter type will be “Text.”
Define the parameter’s order in which it will appear in the Inputs tab.
Select the type of input this Command can use (Custom Input, Text Template, or HTML template).
Set the pre-filled Default Value for this parameter.
Provide a description of the current parameter’s function and purpose.
Provide a sample of possible input for this Command.
Click on Save
Configuring Output
You can define the sample outputs of a Utility Command to provide context for other users to understand the Utility Command.
Key Fields: the most important fields to be extracted out as individual fields.
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.
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.
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)
Select the Command you want to test.
Navigate to the Test tab on the left panel.
After, specify the following:
Select the Site you want to test the Command on.
Provide the necessary Inputs.
Click Test Command.
Result: A new Show Test Result button and Test Summary will appear.
Click Show Test Result
Result: The test result of the command will appear in a pop-up.
Outputs are provided for the following (if applicable): Result, Return Data, Context Data, Passdown Data, Raw Data.
Once the Command is working as you intended, you can click Submit to publish the Command. Once submitted, it will be available for use.
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.
The following is a general how-to for setting up a remote utility command with D3's webhook API.
Find and select the desired utility command. Navigate to Configuration > Utility Commands > [Your Desired Utility Command]. If you are using a custom utility command, verify that it has been submitted.
Under Webhook Authentication, toggle on Remote Command. Select the desired authentication method.
Authentication Method: API Key
In the Setup API Keys window, you can select an existing key or generate a new one for authentication. To generate a new key, click on the + button adjacent to ALL KEYS.
If you are generating a new key, enter an alias for your key. Click Generate.
For detailed information about configuring the remote command API key, refer to the Authentication Method: API Keys subsection under Remote Command in the Webhook Configuration Guide document.
Authentication Method: JSON Web Token (JWT)
In the Setup JWT window, you can select an existing key or generate a new one for authentication. To generate a new key, click on the + button adjacent to ALL KEYS.
If you are generating a new key, enter an alias for your key and select the assigned user. You have the option to allow all users to view the key. Click Generate.
Reader Note
The assigned user will be recognized as the user when a command requires a user parameter.
For detailed information about configuring the JSON web token, refer to the Authentication Method: JWT subsection under Remote Command in the Webhook Configuration Guide document.
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
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.
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.
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
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.
Configure the custom utility command to add.
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!
Implementation: Select Codeless Playbook for the purposes of importing a custom utility command.
Command Category: Select the appropriate command category for the command you will import. Available categories include Basic Utility, Cyber Utility, and System Utility.
Click Add to confirm and add the custom utility command.
Click on the three-dot button found near the top right corner, then Replace Command.
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.
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.
Done! You have successfully imported a custom utility command from another D3 SOAR environment.