🌙
 

Subscribe to the Taegis™ XDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Connector Definition Language


Connector definitions are defined in YAML and describe the properties, function mappings, and documentation for the connector. Definitions contain all required details for a connector, including the metadata, inputs, and actions.

Connector Definition Example

Connector Definition Example

Currently supported fields are as follows:

Note

Items in light gray are not exposed in the connector builder, but are populated automatically in the YAML and can be seen, and are required, when editing exported definitions outside the platform.

apiVersion

This field is used by Secureworks only to indicate the first API version that supports this definition.

Default Value— v0.0.1

Data Type— string

This field is not exposed in the connector builder; it is for Secureworks use only.

kind

Defines the type of definition file. In the case of a connector, the value should always be Connector.

Default Value— Connector

Data Type— string

This field is not exposed in the connector builder; it is for Secureworks use only.

name

Defines the name of the connector. Connector names must be unique within a given tenant. Connector names that start with the reserved Taegis prefix are global and can only be added by Secureworks. Connector names should not contain spaces, and any special characters outside of underscore (_) and period (.).

Value— Use the name of the vendor/product/service in Title case.

Data type— string

This field is available in the connector builder.

title

Defines the value displayed in Taegis™ XDR when viewing the connector. This field can contain spaces and other special characters.

Default Value— Use the name of the vendor/product/service as it is commonly used in the market or on public websites.

Data Type— string

This field is available in the connector builder.

description

Describes the connector. This is not a documentation field, but a short one or two sentence description of the connector.

Suggested Value— one or two sentences that clearly identify the purpose of the connector.

Data Type— string

This field is available in the connector builder.

tags

A list of labels associated with the connector. Tags are not currently displayed or searchable in Taegis™ XDR.

Data Type— An array of strings.

This field is not exposed in the connector builder; it is for Secureworks use only.

Categories

A list of predefined categories associated with the connector. Categories are not currently displayed or searchable in Taegis™ XDR.

Data Type— An array of strings

This field is not exposed in the connector builder; it is for Secureworks use only.

method

Defines the method used to connect to the product or service. Currently supported method is HTTP REST.

Default Value— HTTP

Data Type— string

This field is not exposed in the connector builder; it is for Secureworks use only.

version

Used to set the version of the connector definition. Connector definition versioning follows the major.minor.patch version schema. Major version changes should be used to communicate breaking changes that require connections to be reconfigured. Major and patch can be used at the author’s discretion.

Note

The version must be unique for a given tenant/connector, and versions must increment on every change or import.

Default Value— 1.0.0

Data Type— string

This field is exposed in the connector builder.

parameters

Allows the connector author to define any required inputs for the connection. The parameter value is formatted as JSON schema that defines the structure of the inputs.

Important

Do not use this field to collect passwords, OAuth tokens, etc.

Default Value— n/a

Data Type— JSON string (JSON schema)

This field is exposed in the connector builder.

functions

Contains the definition for each function supported by the connector. Each function contains a set of fields which are documented in detail in Defining Functions in Taegis™.

Default Value— n/a

Data Type— array

The actions field is not exposed in the connector builder, but the individual actions are. For more information on actions, see Defining Functions in Taegis™.

Special Actions

There are a few special actions:

validate

Causes Taegis™ XDR to display a “Test” button which runs the validate action directly. This allows you to validate that the connection is working properly (authentication, access, etc).

authenticate

Runs prior to other actions in order to handle custom authentication.

authTypes

This field defines the supported authentication types for a connector. One or more authentication types can be set. Supported authentication types include:

Note

Taegis™ XDR automatically provides the required inputs for a given authentication type when creating a connection. Collecting and defining authentication inputs for a connector is not required.

Default Value— n/a

Data Type— string

This field is exposed in the connector builder.

 

On this page: