🌙☀
 

Subscribe to the Taegis™ XDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Defining Your First Connector


Let’s build a sample connector with the Connector Editor. The following example uses RequestBin to visualize the requests we are making with the sample connector.

  1. Create a new RequestBin endpoint (it’s free) and save it for later for testing and using the connector.

  2. Log in to Secureworks® Taegis™ XDR.

  3. From the left-hand XDR menu, select Automations→Connections and choose the Connector Library.

  4. The Connector Library displays. From the Actions pull down menu, select Build Connector.

Define Metadata ⫘

  1. In order to build a connector you need to first define metadata about the connector such as the Vendor, Product, Description, etc. Set the Vendor to RequestBin and the Product to Demo.
  2. Select Save then Next.

Define Authentication Types ⫘

  1. Define the Authentication type(s) required by the service that the connector is integrating with. RequestBin doesn’t require any authentication, so select None as the authentication type.

  2. Define any required input variables for the connection. Examples of common variables include the URL for the service, an organization or tenant ID. Use the Custom Configuration section to define the type and structure of these input variables. For this example, define an instance URL for the RequestBin service. To do this, select the String property field into the Custom Configuration pane and set the Name as url and the Title as RequestBin URL.

  3. Select Save then Next.

Define the Connector Functions ⫘

The following steps define the Functions that this Connector supports.

Tip

Defining a Connector Activity allows a playbook author to use the activity as a step in a Playbook Template.

  1. Define the name for the Activity. This name should represent the purpose of the REST API call for the endpoint that is defined in the Activity. For this example, name the Activity PostData.
  2. Next, define any input variables that are required in order to use the REST API endpoint. RequestBin doesn’t require any variables, but for this example send a userId and a status value.
  3. Add a String variable with the name userId and a Title of User ID.
  4. Add another String variable with the name status and a Title of User Status.

HTTP Resource Definition ⫘

  1. Expand the HTTP Resource section and define the HTTP resource properties for this activity.
  2. From the drop down menu, select POST as the request type.
  3. Add the RequestBin URL variable to the Domain value.

Tip

When you add the variable to the value, notice that the value transforms to the underlying variable structure ${config.url}. config is the parent for all of the Connector input variables that are defined in the Authentication step.

  1. Send the userId and status fields/values as URL parameters. To do this, define the URL parameter name userId, and select the User ID variable as its value. Notice that the value transforms to the underlying variable structure ${inputs.userId}. inputs is the parent for all Activity input variables that you defined in the Activity Inputs step above. In the next row that appears in the URL parameters, set the name as status and select the User Status variable as the value.

Note

There aren’t any Headers or Body set in this example, but these fields function nearly the same way as the URL parameters.

  1. Set the Content Type to application/json.

Define Outputs ⫘

  1. Complete Function configuration by defining the outputs the function produces. In this example, return true if the HTTP response code is 200. Output variables must be defined in the same way that input variables are defined. Since we want to return a boolean value (true), select the Boolean property in the Function Outputs pane. Name it result and title it Result.

  2. The Function Outputs table automatically populates after the Result property is added. Define how the Result variable populates. When a Function executes, it exposes the status code and status message in two variables, status.code and status.message. Evaluate the status code and set the result output variable to true if the status code value is equal to 200. To do this, enter the following CEL expression as the result output variable: ${status.code == 200 ? true : false}. This ternary expression reads: if the status.code is equal to 200, then return true, else return false. Select Save and Next.

PostData Activity ⫘

  1. You can now view your newly added PostData activity. This page displays a list of the activities that this connector supports. You can add as many activities as you want. You can also edit existing activities. Select the PostData activity to open it in the editor. You can also test the activity.
  2. Select the Test tab to the right of the Configuration tab.
  3. Select None from the Authentication drop down menu (for this example, remember, RequestBin doesn’t require authentication).
  4. Fill in the RequestBin URL variable value from your RequestBin endpoint. Select Save.

  5. To test the activity, provide the input values that you want to test for. Type in an example User ID and Status value and select Execute.

  6. Confirm that the Activity Outputs on the lower right have result variables with a value of true. Select Save and Next.

Complete the Connector ⫘

  1. Define any required documentation for the connector. The documentation supports Markdown; a simple editor is provided.
  2. Once you are done adding documentation, select Publish or Save Draft As. Publishing the connector is strongly suggested if you want to begin using the connector in a playbook template. Save Draft As is useful if you plan to continue editing the connector and are not using the connector in a playbook template just yet.

 

On this page: