🌙
 

Subscribe to the Taegis™ XDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Custom Connector Editor


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

Custom Connector

Custom Connector

Create a Custom Connector

  1. From the Taegis™ 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 Build Connector.
  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

Custom Connector Details

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

Tip

You can skip to any panel in the Custom Connector by choosing the step icon for the panel.
Custom Connector Panel.

Custom Connector Panel

Authentication

The Authentication panel lists all available authentication methods 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

Connector Authentication

Note

This panel does not have defaults. You must select the properties that apply to the connector you are building.

Available authentication types include:

Basic Authentication

Basic Authentication includes the following properties:

API Key

API Key includes the following property:

Raw

Raw has a single property:

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:

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:

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:

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:

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:

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:

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

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

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.

Tip

If you are in the New Function panel, you can toggle back to the list of configured activities by selecting Configured Functions from the upper right hand side of the panel.

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

  1. 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.

  1. Select the HTTP Type. Available choices are:
  1. 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 Taegis™ 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
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.

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

Tip

Many of the fields support Google’s Common Expression Language. For more information, see Using Common Expression Language.

  1. 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

  1. 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

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

Tip

If you need to create a complex object, create it as a variable in Function Inputs, then in Body add a new complex object name value pair and add the complex object variable (like a pointer) in the value.

Content Type

  1. 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

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'}.

Tip

Add well defined descriptions to any property you define, because that property shows up elsewhere in playbooks in different contexts. So it’s a good idea to provide accurate explanations for the property for yourself and other users.

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

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.

Note

When you publish, and the connector is versioned you can control what version of a connector is used in a playbook template, and update the playbook template—and connector—when needed for breaking changes. For this reason, take care not to use a Draft connector in a production playbook.

 

On this page: