Integration Custom Command

LAST UPDATED: OCT 15, 2024

Steps to Create Integration Custom Command

Create Custom Integration

To create your own custom integration, follow these steps:

1. Click on the Configuration tab at the top navigation bar.

2. Click on the Integration tab on the left sidebar.

3. Click on the + button next to the search field, underneath the breadcrumb.

   

4. Enter in a unique integration name. You may also optionally choose a more appropriate category and provide a description

5. Click the Save button.

   

READER NOTE

You must choose a unique integration name. Changing the integration name will result in changes in all Webhook URLs of the commands under this integration.

For custom integrations, there are no system commands and scripts — this means you will have to create your own commands. For more information on commands, see Integration Commands.

Configure Integration Connection

Connection Parameters

To enable your integration, you need to establish a connection for API calls. The initial stage of configuring an integration involves setting up the connection parameters. You will need to include either a custom parameter or choose from a set of predefined parameters.
In the integration script, the global variable runtime['connector'] holds a dictionary containing connection parameters. The keys for these parameters are lowercase and without spaces, like runtime['connector']['serverurl'] or runtime.get("connector").get("serverurl", "").

READER NOTE

For more information on creating custom connection parameters, see Custom Connection Parameter. For more information on adding connections, see Add Connections.

Preconfigured Connection Parameter Sets (MS SQL / Oracle / MySQL / ODBC)

By default, a newly created integration will not have any connection parameters.

To establish a connection parameter, set up the connection by following the steps below.

1. Hover your cursor over the + Connection Parameter dropdown.

2. Click on your desired connection parameter set.

   

You will now see a row populated under the headers of the Connection Parameters table.

Create the Custom Command

Setup Command Features

In the Overview > Settings tab of the integration command level, you will find the Features section, comprising five checkbox options. These options dictate the availability of the command across the system. To enhance accessibility, D3 suggests checking all options whenever feasible, expanding the command's reach to multiple areas within the system. Select at least one feature in order to use the command (not required if solely triggered by a schedule).

The Default Connection is required to enable use of the Transform Command feature.

MS SQL / Oracle / MySQL / ODBC

Upon setting up the connection parameter sets, users will be able to see MS SQL/Oracle/MySQL/ODBC as an implementation option in the modal Add Command form. To render this form, click on the + Custom Command button within the Commands section.

Command Input Setup

To add a new input parameter:

1. Click on the Inputs tab within the Overview tab.

2. Click on the New Input Parameter button.

   

   In the New Parameter popup, you will see nine or ten fields depending on the input type.

   

Field	Description
Parameter Name	The internal identifier assigned to a parameter. It is an identical match to the parameter name in the function definition.
Display Name	The display name of the parameter.
Parameter Type	The data type of the parameter.
Is Required?	Whether or not the parameter is required when running the command.
Parameter Index	The order of the parameter, starting from 0.
Input Type	The data type of this parameter. Input Type Options: Custom Input: match and support parameter type, change input method according to parameter type Text Template: text input HTML Template: HTML input Drop Down Option: selection, only support Text parameter type Multi Select Option: multiple selection, only support Text Array parameter type
Options Input	The options to appear in the input field; these should be listed with each option input on a separate line.
Default Value	Whether the parameter has a default value. It can be empty.
Description	The description of the parameter.
Sample Data	Sample data of the parameter.

The parameter type dynamically adjusts based on the selected input type. The default value format will also adapt accordingly – adhere to the one shown in the placeholder.

To observe the dynamically generated input field:

1. Fill in the appropriate fields within the New Parameter popup.

2. Click on the + Add button of the New Parameter popup.

3. Click on the Test tab next to the Overview tab.

The newly added test input field will now be positioned beneath its display name.

Command Output Setup

To set up the command output:

1. Click on the Overview tab.

2. Click on the nested Outputs tab.

3. Click on the Raw Data category.

4. Click on the + Add Raw Data button.

   

5. Select the data type and input sample data accordingly.

6. Click the Save button.

   

7. Click on the Key Fields category.

8. Click on the Add Key Fields button.

9. Enter a key field name, select the appropriate type, provide a JSON Path, and enter sample data.

10. Click on the + Add button.

    

11. Click on the Return Data category.

12. Click on the Add Return Data button.

13. Enter “Successful”, “Failed”, or “Partially Successful” in the Sample Data section.

14. Click on the Save button.

    

After completing these steps, you should see the output data presented somewhat similar to the following:

Write your Python Script

See Python Script.

Clone Integration System Command

Clone Integration System Command

Integration System commands can be cloned by following these steps:

1. Click on the Configuration tab at the top navigation bar.

2. Click on the Integration tab on the left sidebar.

3. Search for your integration underneath the breadcrumb.

4. Click on your integration within the expanded accordion.

5. Click on the row in the Custom Commands table that you would like to clone.

6. Click on the Clone Command option.

   

   If the above steps are completed successfully, you will see a new Python function displayed in the code editor. The name of this cloned command will automatically differ from the original command. Additionally, consistent with all commands, the function name will be identical to the internal name (Pascal case to the displayed command name).

   

Pre-defined Custom Commands

There are six special command templates in the Add Command form:

• checkIPReputation

• checkUrlReputation

• checkFileReputation

• OnDismissEvent

• OnEscalateEvent

• TestConnection

Here we will focus on the last one, TestConnection.

Connection (TestConnection) Custom Command

The TestConnection command is used to verify the ability or health status of the D3 system to communicate with an external one (ie. an integration). To render the Add Command form, click on the + Custom Command button within the Commands section.

The TestConnection will appear as the last option under the command template section.

Click on the + Add button to enable the test connection functionality.

You will be redirected to the Python editor page. Here, consistent with integration commands, there will be a function name for the test connection identical to its internal name (Pascal case to the displayed command name). Click on the Submit button.

Due to the Python script's hard-linked nature for all commands, including TestConnection, a popup will emerge if any of the commands within the Python script are used elsewhere in the D3 system. Simply click the Update button, then the OK button to continue.

Navigate back to the second level of the breadcrumb and click on the + Connection button. To test the Connection, click the Test Connection button.

Data Ingestion (FetchEvent/FetchIncident) Custom Command

The Fetch Event and Fetch Incident commands serve essential roles in incident response and management. Fetch Event is used to retrieve relevant events or data related to security incidents, while Fetch Incident is used to retrieve incident details themselves. These functions are crucial because they allow security analysts to access historical data, aiding in investigation, analysis, and response.

Following the retrieval of events or incidents, the next step typically involves performing event field extraction mapping. This process involves defining how data within events or incidents should be structured and labeled for downstream analysis. By mapping specific fields within events to standardized or custom labels, analysts can better interpret and process security data, ultimately enabling faster identification and mitigation of threats.

To set up the Fetch Event command:

1. Click on the + Set Up button in its ingestion container.

   

2. Click on the + Set Up button in the confirmation popup.

   

To set up event field extraction mapping:

1. Click on the Set up Event Field Mapping button in the Overview tab.

   

2. Click on the + Add Field button.

   

3. Enter in a field name.

4. Enter in the source field.

5. Click on the Save button.

   

You will now see a new row in the table of the Event Field Mapping popup.

READER NOTE

See Event and Incident Intake Field Mapping for details.