Building Your First Playbook

The following uses the Secureworks® Taegis™ XDR template editor to build a “Hello World” template.

1. Log in to XDR.

2. From the left-hand menu, navigate to Automations→Playbooks, then select the Templates tab.

3. From the right-hand Actions pull down menu, select Templates, select Build New Template.

4. Define a name for the template. For this example, Hello World.

5. Define the required template inputs. These values are provided when a playbook using this template is configured or when the playbook is executed. To define the inputs, select the INPUTS & OUTPUTS tab in the editor.

Template inputs are defined as a JSON schema in YAML format. For this example, define an input object called configuration and a string input variable called userId. The inputs should look like:

inputs:
  type: object
  properties:
    configuration:
      type: object
      properties:
        userId:
          type: string
          title: User ID

6. Define the outputs produced by this playbook.

Template outputs are defined as JSON schema in yaml format. For this example, let’s define a single string output called result. The outputs should look like:

outputs:
  type: object
  properties:
    result:
      type: string

7. Both the inputs and outputs should now display in the INPUTS & OUTPUTS tab. The full value should look like:

inputs:
  type: object
  properties:
    configuration:
      type: object
      properties:
        userId:
          type: string
          title: User ID
outputs:
  type: object
  properties:
    result:
      type: string

8. Define the tasks in the template by navigating to the DSL tab in the editor. Tasks are executed one-by-one in order from the first task to the last task. For the first task, set some variables to demonstrate this type of task.

9. Add a new task by defining a name for the task:

- name: setup

10. Define the type of task. In order to set variables the task type use let:

- name: setup
  let:

11. The let task can define one or more variables or even complex data structures (map and/or list). For this example, set a single variable called status and a hard coded value of started:

- name: setup
  let:
    status: 'started'

12. Execute the PostData activity (function) from the RequestBin Demo connector. This activity expects two inputs, userId and status.

• userId comes from the template inputs.
• status comes from the previous task where it was hard-coded to started.

13. Add a new task by defining a name for the task:

- name: post_data

14. Define the type of task. To call a connector function, use the task type of action:

- name: post_data
  action: RequestBin_Demo.PostData

15. Define the inputs that this activity requires:

- name: post_data
  action: RequestBin_Demo.PostData
  inputs:
    userId: inputs.configuration.userId
    status: setup.variables.status

The inputs for this task are referencing variables from two distinct locations. inputs.configuration.userId is an input field we defined on this template. setup.variables.status is a variable that we set in the first task of the template. The path to the variable is in the format: <name of the task>.variables.<variable name>.

16. Define the output values that the template produces. The template output structure has been defined, but now the values must be set. To set the template outputs, define an outputs object at the same level as tasks.

17. In the template outputs structure, set a single output field called result with a value of a string. Set this value to the output from the post_data task, which is boolean. You must use an expression to make a string value:

outputs:
  result: has(post_data, outputs.result) && post_data.outputs.result ? 'success' : 'failure'

This expression uses the has() macro to test if the post_data task produces the result value in its outputs. If it did, it then checks the value assigned to the result variable. If the result value is true, then the expression returns success, else it returns failure.

The entire value in the DSL tab should now look like this:

name: Hello_World
tasks:
  - name: setup
    let:
      status: 'started'
  - name: post_data
    action: RequestBin_Demo.PostData
    inputs:
      userId: inputs.configuration.userId
      status: setup.variables.status
outputs:
  result: has(post_data, outputs.result) && post_data.outputs.result ? 'success' : 'failure'

18. Since this is a task that calls a connector action, you must define that connector as a requirement for this template. To do that, navigate to the Connectors tab in the editor.

19. From Connectors tab, define a list of connectors by their ID that this template requires. In this example, there is only one required connector, RequestBin_Demo.

20. In a new tab, navigate to the Taegis portal and go to Automations→Connections→Connector Library. Search for the RequestBin connector then select the RequestBin_Demo connector card to open it.

21. Copy the ID of the connector by selecting Copy connector ID.

22. Return to the template editor and add the connector ID to the list of connectors:

connectors:
  - id: Q29ubmVjdG9yOjQzMWI5OGYyLWVlMjMtNGM0OS05MGRiLTEzYmI4YTk5ODY4Yg==

23. Save the template. To save the template as a draft, select Save As and fill in the required fields. To save the template as a published version, which is recommended for production use, select Publish.