Task 3. Add tasks

Add playbook tasks in Cortex XSOAR On-prem 8.7 (EoL).

Playbook tasks are the building blocks of playbooks. Tasks enable you to run scripts and sub-playbooks, communicate with end users, set conditions, and store relevant data.

Cortex XSOAR supports different task types for different actions to be taken in a playbook, and each task can receive and generate data in the form of inputs and outputs. For example, for enrichment, you might want to run an enrichment sub-playbook or a command that returns additional information for an indicator.

Tasks can be reused across playbooks and you can copy, cut, paste, and delete tasks within or between playbooks using keyboard shortcuts. To see a list of keyboard shortcuts, see Keyboard shortcuts.

The Task Library contains scripts, tasks, and playbooks. You can create new tasks from scripts, repurpose existing tasks, and use existing playbooks as sub-playbooks.

You can add a brief description for each task, explaining what the task does. Descriptions are added in the Task Description task field.

Note

To open multiple playbooks at the same time, edit the first playbook and then click the New icon next to the playbook name to create a new tab. You can either create a new playbook, or add an existing one.

Once you add tasks to your playbook, connect the tasks in their logical order by dragging and dropping a wire from one task to another.

Task type	Description
Section	Use a section header task to group related tasks to organize and manage the flow of your playbook. Section headers can also be used for time tracking between phases in a playbook. This data can be used to display in dashboards and report time trends. For example, in a phishing playbook you would have a section for the investigative phase of the playbook such as indicator enrichment, and a section for communication tasks with the user who reported the phishing. For more information, Create a section header.
Standard	Standard tasks can be manual tasks such as manual verification to prompt an analyst to verify the severity or classification of an incident before proceeding with automated actions. They can also be automated tasks such as parsing a file or enriching indicators. Automated tasks are based on scripts that exist in the system. These scripts can be created by you or come out-of-the-box as part of a content pack. For example, the !ad-get-user command retrieves detailed information about a user account using the Active Directory Query V2 integration. You can also automatically remediate an incident by interacting with a third-party integration, open tickets in a ticketing system such as Jira, or detonate a file using a sandbox. For more information, see Create a standard task.
Conditional	Use conditional tasks to validate conditions based on values or parameters and take appropriate direction in the playbook workflow, like a decision tree in a flow chart. For example, a conditional task may ask whether indicators are found. If yes, you can have a task to enrich them, and if not you can proceed to determine that the incident is not malicious. Alternatively, you can use conditional tasks to check if a certain integration is available and enabled in your system. If yes, you can use that integration to perform an action, and if not, you can continue on a different branch in the decision tree. Conditional tasks can also be used to communicate with users through a single question survey, the answer to which determines how a playbook will proceed. For more information, see Create a conditional task.
Data Collection	Use a data collection task to interact with users through a survey, for example to collect responses or escalate an incident. All responses are collected and recorded in the incident context data, from a single user or multiple users. You can use the survey questions and answers as input for subsequent playbook tasks. You can collect responses in custom fields, for example, a grid field. For more information, see Create a communication task.

Set playbook inputs and outputs

Depending on the task type that you select and the script that you are running, your playbook task may have inputs and outputs.

Inputs are data pieces used in a task. The inputs are often manipulated or enriched and they produce outputs. Outputs generated from the result of a task or command can be used as inputs to subsequent tasks or as information generated to help resolve or escalate an investigation.

An input may come from an incident, such as the role to assign an incident to, or an input can be provided by an integration, for example the Active Directory integration can be used in a task to extract a user's credentials.

At the beginning of any playbook, click the Playbook Triggered task and enter the playbook inputs and outputs, grouping them as relevant.

Use the task cheat sheet to use context keys in playbook inputs and outputs

When you create your playbook task inputs, the task cheat sheet enables quick access to system and custom fields to populate playbook task inputs and outputs.

1. Click .

   The cheat sheet opens displaying incident fields.
2. Select an incident field, it populates the task input with the corresponding context key.

   

   xsiam-playbook-cheat-sheet.png

Example 12.

The following example uses incident context data as the playbook input from the Access Investigation - Generic playbook.

Click the top task Playbook Triggered. The playbook is triggered based on incident context data.

Inputs

The first two inputs are SrcIP, retrieved from the incident.src key, and DstIP, retrieved from the incident.dest key.

access-investigation-pb-2.png

Outputs

The Access Investigation - Generic playbook creates an output object that can be used in subsequent playbook tasks.

For example, the Access Investigation - Generic playbook Endpoint.IP output creates a list of endpoint IP addresses which can later be enriched by an IP enrichment task, and the Endpoint.MAC output creates a list of endpoint MAC addresses which can be used to get information about the hosts that were affected by the incidents.

Outputs can also be data that was extracted or derived from the inputs. For example, the Access Investigation - Generic playbook contains the Account Enrichment - Generic v2.1 sub-task, which uses the account username (and optionally domain) as input to Active Directory to retrieve user information as output, such as the user's email address, manager, and any groups to which they belong.

An output can then serve as input for a subsequent task. For example, in the Account Enrichment - Generic v2.1 sub-task, the Get account info from Active Directory task output Account.Username is used as an input for the Active Directory - Get User Manager Details task to retrieve manager details for that user.

Group playbook inputs and outputs

Playbook input and output fields are collected into groups. This organizes the inputs and outputs, providing clarity and context to understand which inputs are relevant to which playbook flow.

For example, the following playbook inputs are grouped under Mailbox selection.

playbook-input-grouping.png

Playbook group permissions

Users with permission to edit playbooks can add, edit, and delete groups and input and output fields. Users without this permission can only view groups, inputs, and outputs.

Work with playbook groups

You can do the following with groups:

• Add or delete a group. Deleting a group deletes all the fields defined in the group.
• Change the name and/or description of the group.
• Change the order groups appear by dragging.
• Collapse and expand a group.

How to add a new group

1. Click + Add Input Group or + Add Output Group.
2. Enter a group name and description and click the check mark.
3. Add fields to the group.

   Note

   If you do not add any fields, the group will be deleted when you click Save.

Manage input or output fields within a group

You can do the following with input or output fields within a group:

• Add, edit, or delete fields within a group. Input or output fields are always part of a group.
• Move fields between groups by dragging.
• Change field order within a group by dragging.

How to add an input or output field in a group

Inputs

1. Within a group, click + Add Input at the bottom of the list of input fields. You may need to scroll down to see it.
2. Enter the input field Name (required), Value, and Description.
3. When you are done adding fields, click Save.

Outputs

1. Within a group, click + Add Output or + Add Manually at the bottom of the list of output fields. You may need to scroll down to see these options.

   • If you click + Add Output, select from the outputs from previous tasks.
   • If you click + Add Manually, enter the context path and description for the output.
2. When you are done adding fields, click Save.

Create a section header

Section headers are used to manage the flow of your playbook and help you organize your tasks efficiently. You create a section header to group a number of related tasks.

Section headers can also be used for time tracking between phases in a playbook. When you start time tracking, apply the Start action for the section header. Because you are using this to time track a particular phase of an investigation, add a stop timer section header when the phase completes. The time tracking data can be used to display in dashboards and report time trends.

1. In a playbook, click + to create a task.
2. Select the Section Header option.
3. Enter a meaningful name in the Task Name field for the section header.
4. Configure the relevant fields.

   Tab	Fields in the tab
   Details	Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
   Timers	For a time tracking header, select the action to take when the timer is triggered (start, stop, or pause). Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down.

5. Click Save.

Create a standard task

Standard tasks can be manual tasks such as manual verification to prompt an analyst to verify the severity or classification of an incident before proceeding with automated actions. They can also be automated tasks such as parsing a file or enriching indicators.

1. In a playbook, click + to create a task.
2. Select the Standard option.
3. Enter a meaningful name in the Task Name field for the task that corresponds to the data you are collecting.
4. Select the options you want to configure for the Standard task.

   Standard tasks include the following field and tabs.

   Field / tab	Settings
   Choose script field	From a drop down list, select a script for the playbook to run. In the following tabs you can set: Inputs: Each script has its own set of input arguments (or none). You can set each argument to a specific value (by typing directly on the line under the argument name) or you can click the curly brackets to define a source field to populate the argument. Outputs: Each script has its own set of output arguments (or none). Mapping: Map the output from a playbook task directly to an incident field. The value for an output key populates the specified field per incident. This is a good alternative to using a task with the setIncident command. Note The output value is dynamic and is derived from the context at the time that the task is processed. As a result, parallel tasks that are based on the same output may return inconsistent results. 1. In the Mapping tab, click Add custom output mapping. 2. Under Outputs, select the output parameter whose output you want to map. Click the curly brackets to see a list of the output parameters available from the script. 3. Under Field to fill, select the field that you want to populate with the output. 4. Click Save. Advanced: Includes the following fields. Using: Choose which integration instance will execute the command, or leave empty to use all integration instances. Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'" Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs). Execution timeout (seconds): Sets the command execution timeout in seconds. Indicator Extraction mode: Choose when to extract indicators: None: Do not perform indicator extraction Inline: Before other playbook tasks Out of band: While other tasks are running Mark results as note Mark results as evidence Run without a worker Skip this branch if this script/playbook is unavailable Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level. Details: Includes the following fields. Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs. Timers: Includes the following fields. Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down. On Error: Includes the following fields. Number of retries: How many times the task should retry running if there is an error. Default is 0. Retry interval (seconds): How long to wait between retries. Default is 30 seconds. The maximum retry interval is 800 seconds (13.3 minutes). If you enter a value greater than 800 seconds, the retry interval will be limited to 800 seconds. Error handling: How the task should behave if there is an error. Options are: Stop Continue Continue on error path(s) This option configures the task to handle potential errors that may occur when executing the current task's script.
   Manual task settings tab	Default assignee: Assign an owner to this task. Only the assignee can complete the task: Stop the playbook from proceeding until the task assignee completes the task. By default, in addition to the task assignee, the default administrator can also complete the blocked task. You can also block tasks until a user with an external email address completes the task. Task SLA: Set the SLA in granularity of weeks, days, hours, and minutes. Set task Reminder at: Set a reminder for the task in granularity of weeks, days, hours, and minutes.
   Advanced tab	Quiet Mode: Determines whether this task uses the playbook default setting for quiet mode. When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
   Details tab	Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
   Timers tab	Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down.

Create a conditional task

Conditional tasks are used for determining different paths for your playbook. For example, in a playbook for handling phishing emails, a conditional task can be used to check if an email contains suspicious attachments. If the attachment is identified as malicious, the playbook can automatically quarantine the email; otherwise, it can proceed to manual review by a security analyst.

Conditional task types

You can create different types of conditional tasks.

• Built-in: Creates a logical statement using an entity from within the playbook. For example, in an access investigation playbook, you can determine that if the Asset ID of the person whose account was being accessed exists in a VIP list, set the incident severity to High. Otherwise, proceed as normal.
• Manual: Creates a conditional task that must be manually resolved. For example, a security analyst is prompted to review and validate a suspicious file. The playbook task might involve instructions for the analyst to analyze the file, determine if it is malicious, and provide feedback or take specific actions based on their assessment.
• Ask: Creates a single-question survey communication task, the answer to which determines how a playbook proceeds. For more details about ask tasks, see Create a communication task.
• Choose script: Creates a conditional task based on the result of a script. For example, check if an IP address is internal or external using the IsIPInRanges script. When using a script, the inputs and outputs are generated by the automation script.

How to create a conditional task

1. In a playbook, click + Create Task.
2. Select the Conditional option.
3. In the Task Name field, type a meaningful name for the task that corresponds to the data you are collecting.
4. Select the relevant conditional task option. Some field configurations are required, and some are optional.

Built-in

• Condition: Define one or more logical conditions for the task.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Includes the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down.
  • Add Trigger: You can add other trigger timer fields from the drop down.
• Advanced: Determines whether this task uses the playbook default setting for Quiet Mode. When in Quiet Mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn Quiet Mode on or off at the task or playbook level.
• On Error: Includes the following fields.

  • Number of retries: How many times the task should retry running if there is an error. Default is 0.
  • Retry interval (seconds): How long to wait between retries. Default is 30 seconds.

Manual

• Manual task settings: Includes the following fields.

  • Default assignee: Assign an owner to this task.
  • Only the assignee can complete the task: Stop the playbook from proceeding until the task assignee completes the task. By default, in addition to the task assignee, the default administrator can also complete the blocked task. You can also block tasks until a user with an external email address completes the task.
  • Task SLA: Set the SLA in granularity of weeks, days, hours, and minutes.
  • Set task Reminder at: Set a reminder for the task in granularity of weeks, days, hours, and minutes.
• Advanced: Determines whether this task uses the playbook default setting for Quiet Mode. When in Quiet Mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn Quiet Mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Includes the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down.
  • Add Trigger: You can add other trigger timer fields from the drop down.

Ask

• Message: Includes the following fields.

  • Ask by: The method for sending the message and survey. Options are:

    • Task (can always be completed directly in the Workplan)
    • Generated link (appears in the context data)
    • Email
  • To: The message and survey recipients. You can define by:

    • Selecting from a predefined drop down list.
    • Manually typing email addresses for users and/or external users.
    • Clicking the context icon to define recipients from a context data source.
  • CC of the email: A CC email address.
  • Subject of the email: The message subject that displays to message recipients. You can write the survey question in the subject field or in the message body field.
  • Message body: The text that displays in the body of the message. This field is optional, but if you don't write the survey question in the subject field, include it in the message body. This is a long-text field.
  • Reply options: Reply options are sent via the selected channels as options for an answer.
  • Require users to authenticate: Enable this option to have your SAML or AD authenticate the recipient before allowing them to answer. You must first set up an authentication integration instance and check Use this instance for external users authentication only in the integration instance settings.
• Timing: Includes the following fields.

  • Retry interval (minutes): Determines the wait time between each execution of a command. For example, the frequency (in minutes) that a message and survey are resent to recipients before the response is received.
  • Number of retries: Determines how many times a command attempts to run before generating an error. For example, the maximum number of times a message is sent. If a reply is received, no additional retry messages will be sent.
  • Task SLA: Set the SLA in granularity of weeks, days, and hours.
  • Set task Reminder at: Set a task reminder in granularity of weeks, days, and hours.
  • Complete automatically if SLA passed without a reply: Select this checkbox to complete the task if the SLA is breached before a reply is received. You can select yes or no.
• Advanced: Includes the following fields.

  • Using: Choose which integration instance will execute the command, or leave empty to use all integration instances.
  • Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\[path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'\]"
  • Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs).
  • Execution timeout (seconds): Sets the command execution timeout in seconds.
  • Indicator Extraction mode: Choose when to extract indicators:

    • None: Do not perform indicator extraction
    • Inline: Before other playbook tasks
    • Out of band: While other tasks are running
  • Mark results as note
  • Mark results as evidence
  • Run without a worker
  • Skip this branch if this script/playbook is unavailable
  • Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.

Choose script

From a drop down list, select a script for the playbook to run. In the following tabs you can set:

• Inputs: Each script has its own set of input arguments (or none). You can set each argument to a specific value (by typing directly on the line under the argument name) or you can click the curly brackets to define a source field to populate the argument.
• Outputs: Each script has its own set of output arguments (or none).
• Mapping:

  Map the output from a playbook task directly to an incident field.

  The value for an output key populates the specified field per incident. This is a good alternative to using a task with a set incident command.

  The output value is dynamic and is derived from the context at the time that the task is processed. As a result, parallel tasks that are based on the same output may return inconsistent results.

  1. In the Mapping tab, click Add custom output mapping.
  2. Under Outputs, select the output parameter whose output you want to map. Click the curly brackets to see a list of the output parameters available from the automation.
  3. Under Field to fill, select the field that you want to populate with the output.
  4. Click Save.
• Advanced: Includes the following fields.

  • Using: Choose which integration instance will execute the command, or leave empty to use all integration instances.
  • Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\[path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'\]"
  • Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs).
  • Execution timeout (seconds): Sets the command execution timeout in seconds.
  • Indicator Extraction mode: Choose when to extract indicators:

    • None: Do not perform indicator extraction
    • Inline: Before other playbook tasks
    • Out of band: While other tasks are running
  • Mark results as note
  • Mark results as evidence
  • Run without a worker
  • Skip this branch if this script/playbook is unavailable
  • Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Includes the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down.
  • Add Trigger: You can add other trigger timer fields from the drop down.
• On Error: Includes the following fields.

  • Number of retries: How many times the task should retry running if there is an error. Default is 0.
  • Retry interval (seconds): How long to wait between retries. Default is 30 seconds.
  • Error handling: How the task should behave if there is an error. Options are:

    • Stop
    • Continue
    • Continue on error path(s)

      This option configures the task to handle potential errors that may occur when executing the current task's script.

1. Click Save.