Using the Automation GraphQL APIs
Important
Before proceeding, complete the API Authentication steps in order to obtain a working client_id and client_secret.
Regions
The URL to access XDR APIs may differ according to the region your environment is deployed in:
- US1—
https://api.ctpx.secureworks.com - US2—
https://api.delta.taegis.secureworks.com - US3—
https://api.foxtrot.taegis.secureworks.com - EU—
https://api.echo.taegis.secureworks.com
The examples in this XDR API documentation use https://api.ctpx.secureworks.com throughout. If you are in a different region substitute appropriately.
Important
On May 15th, 2023, the IP address range used for Automations is changing to 216.9.204.0/22.
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.
Connectors ⫘
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.
ConnectorInterface/ConnectorAction ⫘
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.
Connector/ConnectorActionDefinition ⫘
Connectors store any configuration required to implement one or more ConnectorInterface, whereas 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.
Connection ⫘
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.
Playbooks ⫘
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.
Playbook/PlaybookVersion ⫘
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.
PlaybookInstance/PlaybookExecution ⫘
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.
PlaybookTriggerType/PlaybookTrigger ⫘
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.