Custom Connector Editor

Use the Custom Connector panel to map external web-based APIs into functions that Playbook templates can leverage in Secureworks® Taegis™ Automations.

Custom Connector

Create a Custom Connector ⫘

1. From the XDR side menu bar, select Automations→Connections.
2. The Connections Panel displays, showing any configured connectors you have. Select the Connector Library button on the upper right-hand side.
3. The Connector Library displays. From the Actions pull down button on the right-hand side, select Create.
4. The Create a Custom Connector panel displays.

There are four sections in custom connector creation: Details, Authentication, Functions, and Documentation.

Details ⫘

Enter connector metadata, like name, vendor, version (optional).

Custom Connector Details

• The connector name has to be unique.
• Optionally add a thumbnail image.

After you have made your desired settings in Details, select Next. The Authentication panel displays.

Authentication ⫘

The Authentication panel lists all available authentication methods Secureworks® Taegis™ XDR supports. Choose all that apply for your connector. For example, if your connector involves Microsoft Defender and you need Basic Authentication, API Key, and OAuth AuthCode, select all of those.

Connector Authentication

Available authentication types include:

Basic Authentication ⫘

Basic Authentication includes the following properties:

• Username
• Password
• Headers — This is optional.
• Base URL

API Key ⫘

API Key includes the following property:

• Header/Query Param Name

Raw ⫘

Raw has a single property:

• Value

OAuth Client Credentials ⫘

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user.

OAuth Client Credentials includes the following properties:

• Grant URL
• Client ID
• Client Secret
• Scopes

OAuth AuthCode ⫘

The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.

OAuth AuthCode includes the following properties:

• Grant URL
• Client ID
• Client Secret
• Scopes
• Code
• Redirect URI

OAuth Password ⫘

The Password grant type is a way to exchange a user’s credentials for an access token. Because the client application must collect the user’s password and send it to the authorization server, it is not recommended that this grant be used.

OAuth Password includes the following properties:

• Grant URL
• Client ID
• Client Secret
• Scopes
• Username
• Password

OAuth JWT ⫘

JSON Web Token (JWT, RFC 7519) enables you to encode claims in a JSON file that is then signed.

OAuth JWT includes the following properties:

• Grant URL
• Client ID
• Client Secret
• Scopes
• ISS
• Sub
• Aud
• Lifetime
• Signing Method
• Signing Key

Custom Configuration ⫘

The Custom Configuration section at the bottom of the Authentication panel allows you to define any additional inputs that are required for this connector. Inputs defined in this panel are made available as variables when building connector activities. The values for these inputs are provided when creating a connection from this connector.

Add a property by clicking and dragging a Property Field on the right into the Custom Configuration Builder window on the left.

Available Properties ⫘

The following properties are available in the custom configuration section for authentication:

• Array
• Boolean
• Integer
• Object
• String

When you have the authentication configured, select the Save and Next button at the bottom of the panel.

Functions ⫘

The functions panel is where you configure the meat of your connector. You can add multiple functions to a connector. The functions you can add are things like:

• Isolate a host
• Look up a user
• Resolve an event
• Resolve an alert

In general, a function represents an API call to an endpoint for the product of this connector. These functions can then be used as steps within a playbook template.

Functions List ⫘

If you already have a function configured, the Functions list view displays when you move to this section:

Custom Functions List

New Function ⫘

If there are no activities configured yet, select + Add New Function and the New Function panel displays:

Add New Function

The New Function panel has a Configuration tab, and a Test tab. You can toggle between these two as you build your function. The Test tab auto-populates from the Configuration tab.

Create a New Function ⫘

1. From the New Function Panel under the Configuration tab, give the function a name and a description. The name and description display when you build a playbook template that uses this connector.

Function Inputs ⫘

2. Under Function Inputs define any inputs that are required for this function. For example, if you are building a function to isolate a host, under the Function Builder you would add a String with host_id as the name. The value for this input populates when the playbook is executed. Any inputs defined here are exposed as variables which can be used in the rest of the function definition.

You can drag properties from the right-hand Property Field area into the Builder window, then define the fields as needed.

HTTP Resource ⫘

Under HTTP Resource, you define all of the parameters and properties needed to to make the necessary HTTP request for the function.

3. Select the HTTP Type. Available choices are:

• GET
• POST
• PUT
• DELETE
• PATCH

4. Enter the Domain. You can hardcode this (that is, just type in the domain), but it’s a good idea to take advantage of the XDR Connector Language variables which were defined in the previous steps. You can use a variable for the domain value by dragging it into the form field from the Variables list on the right-hand side of the HTTP Resource Panel.

Taegis Variables ⫘

The Taegis Variables side panel allows you to leverage variables in your custom connectors.

Custom Connector Variables

When you define a property in Authentication Custom Inputs or Function Inputs, it becomes an available variable you can select from the Variables side panel.

5. Add a valid URL Endpoint, like /api/v1/host. Note that this field also supports variables.

6. Add any URL Parameter Name and Value. You can add a variable to the Value field. You can add as many URL parameters as needed.

Headers ⫘

7. Add any required Headers needed to to make the necessary HTTP request for the function. For example, if the Tenant ID is required, you can add it with something like X-Tenant-Id = ${inputs.tenant_id}), where ${inputs.tenant_id} is a variable that you can define in the Builder section.

Body ⫘

8. Define what you want in the Body of the HTTP request.

Content Type ⫘

9. Select the Content Type of the HTTP request. This list is pre-populated with types you may need, but you can also enter anything required. The default is the most commonly used application/json.

Function Outputs ⫘

After you have defined your inputs and HTTP Request behavior, you can define any outputs the function may produce. The Function Outputs section has a Builder and below that, an output table. To add an output to the table, you must first define the property with the Builder. So, you:

1. Define the property in the Builder, then:
2. Add the value for the property (or properties) you add in the output table. You can use the Variable list on the right to set the output property value from one of the variables.

Function Outputs

For example, if you are creating a host isolation function, you can set logic for that output: Create a string with a Boolean value (success, failure) for isolating a host. For example, the value for that could be ${status.code == 200 ? 'success' : 'failure'}.

Error Condition ⫘

You can optionally add a custom error condition expression to define when the function is considered a failure. By default, all HTTP responses that are not in the 2xx range are considered a failure. The function is considered a failure if the error condition evaluates to a non-empty or non-null value.

Test ⫘

After you have configured your function, you can test it. The Test tab automatically populates with what you have built in the configuration tab.

Test Function

Set up a Function Test ⫘

1. Enter the Authentication options for the test.
2. After you’ve added authentication credentials, select Save. The credentials are saved for the remainder of your work on this connector.
3. Define the Test Function. This section is pre-populated with the entries you built in the configuration tab.
4. Select the Execute button to test the function.
5. The Response panel on the right fills with the outputs from the function.
6. To make changes based on the results, move back to the Configuration tab to update the function, then come back to the Test tab to try out the changes.
7. When you are finished testing, select Save And Next.
8. The Documentation step displays.

Documentation ⫘

The Documentation panel gives you a markdown writing editor where you can fully describe your connector. Include a summary of what the connector is for, and define and describe any parameters that a user needs to fill in to use the connector. Standard markdown syntax is supported. For more information, see Markdown Guide: Basic Syntax.

When you have completed the documentation, you can either save it as a draft, or publish it.

• To publish it, select Publish. This versions your connector, and makes it available for use in a playbook template.
• To save the draft, select Save Draft As. You can pull the draft up at any time from the Function List.