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
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 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 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 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 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:
- None
- Platform
- Raw
- Basic
- APIKey
- OAuthClientCredentials
- OAuthPassword
- OAuthAuthCode
- Custom.
Note
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.