Defining Functions in Taegis
Connector definitions expose functions that can be called as playbook tasks. The following fields are used to create connector functions. Examples can be found by exporting a connector from the library in Secureworks® Taegis™ XDR.
Tip
Connector Variables ⫘
When building a connector, you have access to some default variables to make building connectors more convenient:
${TDR.API}— the API url for Taegis.${TDR.URL}— the portal url for Taegis.${TDR.tenant}— the tenant ID when the connector is executed.${TDR.user}— the user ID that triggered the connector/action.${body}— the response body. Note that this can only be used in outputs.${headers}— list of response headers. Note that this only be used in outputs.${status.code}— the response status (HTTP) code. Note that this can only be used in outputs.${status.message}— the response message. Note that this can only be used in outputs.
name ⫘
Defines the name of the function. Must be unique within a given connector. Function names should not contain spaces, and any special characters outside of underscore (_) and period (.).
Default Value— n/a
Data Type— string
This field is exposed in the connector builder.
description ⫘
Used to describe the function. This is not a documentation field, but a short one or two sentence description for the function.
Suggested Value— one or two sentences that clearly identify the purpose of the function.
Data Type— string
This field is exposed in the connector builder.
inputs ⫘
Allows the connector author to define any required inputs for the function to work. Value is a JSON schema that defines the structure of inputs. As a playbook author, the inputs defined here are displayed when adding this function as a step in a playbook.
Default Value— n/a
Data Type— string (JSON schema)
This field is exposed in the connector builder.
outputs ⫘
Allows the connector author to define any outputs the function produces. Format is a JSON schema that defines the structure of the outputs. As a playbook author, the outputs defined are displayed when adding this function as a step in a playbook.
Default Value— n/a
Data Type— string (JSON schema)
This field is exposed in the connector builder.
config ⫘
An object that contains the configuration for the function.
Default Value— n/a
Data Type— object/map
config is not exposed in the connector builder but the individual fields listed below that make up the configuration are exposed:
contentType ⫘
The HTTP content type value for the request.
Default Value— application/json
Data Type— string
This field is exposed in the connector builder.
method ⫘
The HTTP method value for the request.
Default Value— GET, POST, DELETE, PUT, or PATCH
Data Type— string
This field is exposed in the connector builder.
body ⫘
The HTTP body value for the request. Do not set this field if the query field is defined.
Default Value— n/a
Data Type— object/map
This field is exposed in the connector builder.
outputs ⫘
Allows the connector author to define the output values for the function. The structure of the outputs should match the JSON schema defined for the function.
Default Value— should match the outputs JSON schema
Data Type— object/map
This field is exposed in the connector builder.
url ⫘
The full URL for the HTTP request.
Default Value— n/a
Data Type— string
This field is exposed in the connector builder.
query ⫘
The graphql query/mutation for the request.
Default Value— n/a
Data Type— string
This field is not exposed in the connector builder.
headers ⫘
The HTTP header value(s) for the request.
Default Value— list of objects setting the name/value pairs (name and value keys)
Data Type— array
This field is exposed in the connector builder.
error ⫘
Allows the connector author to define an error when the function fails. A null/empty value informs the automation engine that the function was successful. A non-null/non-empty value results in the function failing and the value provided is displayed as the error.
Default Value— n/a
Data Type— string
This field is exposed in the connector builder.
variables ⫘
Allows the connector author to set variables for a graphql query/mutation. Variables are defined as key/value pairs. This field should only be set if the query field is defined.
Default Value— n/a
Data Type— object/map
This field is not exposed in the connector builder.