Using the Automation GraphQL APIs
Before proceeding, complete the API Authentication steps in order to obtain a working
The URL to access Taegis™ XDR APIs may differ according to the region your environment is deployed in:
The examples in this Taegis™ XDR API documentation use
https://api.ctpx.secureworks.com throughout. If you are in a different region substitute appropriately.
On May 15th, 2023, the IP address range used for Automations is changing to
Prior to May 15th, random AWS Elastic IP addresses (eIPs) have been used for making connections to integrated product APIs.
The change is being made in order to use specified source IP ranges for connector authentication.
This change will likely not impact you, but it if you have configured firewall rules, allow-lists, or any other application configuration that specifies AWS eIPs, you’ll need to update the configuration.
Contact your Taegis™ XDR representative if you have questions.
The Connectors GraphQL API maintains a catalog of available connectors to third-party services, metadata on how they are configured, and instances of those (connections) that are configured on a per-tenant basis. This provides a consistent configuration API for all Secureworks® Taegis™ XDR Automation connectors.
An interface defines a contract between the user of a connector (playbook/UI) and the implementation of the required behavior. Behavior is defined by a set of actions such as
block IP or
disable user and their corresponding input/output data requirements. A connector interface is analogous to an interface in a programming language such as golang or java, allowing the consumer/user to write to a specified behavior without regard to the implementation.
Connectors store any configuration required to implement one or more
ConnectorActionDefinition holds the configuration for each action implemented by the connector. As an example, a Connector could be created for ServiceNow integration with an action of create ticket. The create ticket
ConnectorActionDefinition would store the configuration needed to connect to the ServiceNow API, such as the URL, HTTP verb, post body, etc. A connector also specifies any additional configuration parameters that must be provided by the end-user such as a service endpoint or supported authentication methods.
In object-oriented terms a Connection is an instance of a Connector. You can create a connection in your account to configure the connector for your specific environment. For the ServiceNow example mentioned above, this might require you to specify the base URL of your ServiceNow instance and the credentials to access it.
The Playbook GraphQL API maintains a catalog of available Automation playbooks and instances of the playbooks that are configured to execute on a per-tenant basis.
A Playbook defines a desired set of behaviors that should be taken in response to external events by codifying a set of actions into an executable workflow. Playbooks are defined in a domain-specific language (DSL).
Playbooks are versioned to track any changes to their structure or configuration. Any change to a playbook generates a new version and updates a head pointer on the Playbook to point to the current version, as multiple versions of a playbook can execute simultaneously.
You can configure a playbook to run in your account by creating a
PlaybookInstance. The instance points to a specified
PlaybookVersion to run (defaults to head), configures any input parameters, and defines trigger criteria. As playbooks are executed, instances of
PlaybookExecution are created to track the state of the playbook execution and record any playbook outputs.
Playbook instances can optionally be triggered when events occur either in the platform or externally.
PlatformTriggerType defines the supported triggers while
PlatformTrigger defines an instance of that specific type.