Playbooks Iterator Operator

Last Updated: May 23, 2019 07:06PM EDT
User
A Playbook that has been created

Overview

The Playbooks Iterator Operator in ThreatConnect® iterates through items in an input array or set of arrays, applies any logic available with Playbooks to each item, and returns the output to the Playbook. This capability expands Playbook applications beyond set-based use cases.

Iterator Operator

In the use case employed in this example, the user wants to iterate through a set of attachments to an email and send the attachments that contain the word “bad” further through the Playbook.

  1. On the top navigation bar (Figure 1), click Playbooks to display the Playbooks tab of the Playbooks screen (Figure 2).
  2. Create a new Playbook or open an existing Playbook. (See Playbooks.) Add Triggers, Apps, and Operators to the Playbook as desired. In this example, a Mailbox Trigger is added so that it will take an email as its input (Figure 3).
  3. Add an Iterator Operator by clicking the + OPERATOR button on the left-hand side of the Playbook Designer and selecting Iterator from the list. An Iterator operator will appear (Figure 4).
  4. Position the Iterator Operator as desired, and then connect the Mailbox Trigger to the Iterator Operator (Figure 5).
  5. Double click on the Iterator Operator, and the Edit Operator configuration panel will appear on the left-hand side of the Playbook Designer (Figure 6).
    • Job Name: Enter a name for the Iterator Operator.
    • Inputs: In the Key field, enter a name for the array on which the Operator will iterate (e.g., “Filename”). In the Value field, use the hashtag (#) to bring up a list of all upstream array variables, and then select an array from the list. Click the Plus button to the right, and a table will appear listing the newly created key/value set. Add as many inputs as desired.

      NOTE: When more than one input array is defined, all input arrays must match in length or else the iteration operation will fail when the Playbook runs.

  6. Input variables may be deleted by clicking the trash icon on the right side of the table row for the variable (Figure 7). Note that clicking the trash icon immediately deletes the variable. No window or message will appear to ask for confirmation first.
  7. Once all inputs have been entered, click the NEXT button. The Outputs section will be displayed (Figure 8).
  8. Click the SAVE button without adding output variables. The Iterator Operator has two nodes at the bottom (see Figure 5) that are used to create a loop to send items sequentially through an operation or series of operations and then return the results to the Iterator Operator. Output variables are used to pass information back to the Iterator from this loop, but first the loop must be created, and the list of potential values must be populated by the Apps that form the loop. As such, the output variables must be added after the loop has been created. On the other hand, input variables for the Iterator Operator must be configured in order to start the loop.
  9. Create and configure the Apps and Operators that compose the loop operations for the Iterator Operator, and connect them to the Iterator Operator. The white circle node is the start point of the loop, and the red square node is the end point of the loop. In Figure 9, the Iterator Operator sends each file from the Mailbox Trigger to an app that checks the filename. If the term “bad” is found, then an app reports the file as malicious, and the loop closes with a return to the Iterator Operator, which moves to the next item in the array sent by the Mailbox Trigger.

    NOTE: When dragging a connection to the red square, make sure to connect to the square itself rather than the Iterator as a whole.

  10. Double click on the Iterator Operator to edit it again. Click the NEXT button (Figure 6) to navigate to the Outputs section (Figure 8). The outputs of the Iterator Operator are non-array variables that are collected into a single array and exposed to downstream apps.

    NOTE: Array values are not allowed in this parameter.

    • Key: Enter a name for array that the Operator will return to the rest of the Playbook (e.g., “Bad_Files”).
    • Value: Use the hashtag (#) to bring up a list of all non-array variables that are available inside the loop logic, and then select a variable from the list. Click the Plus button to the right, and a table will appear listing the newly created key/value set. Add as many outputs as desired. These output variables will be available as arrays for downstream apps.
  11. Output variables may be deleted by clicking the trash icon on the right side of the table row for the variable (Figure 10). Note that clicking the trash icon immediately deletes the variable. No window or message will appear to ask for confirmation first.
  12. If desired, click the Settings icon to access the Inline Steps slider (Figure 11).
  13. Toggling the Inline Steps slider to on (orange) will cause all of the configuration steps to be available for editing on the screen at one time instead of becoming available sequentially after the user finishes each part (Figure 12).
  14. Click the SAVE button to save the configuration. To view the loop variables, hover the cursor over the icon of the Iterator Operator (Figure 13).

    NOTE: Loop variables are available to all Apps and Operators inside the loop.

Break Iterator Operator

The Break Iterator Operator is used after the If/Else Operator to define a break condition for a loop or break from a loop directly after an app failure.

  1. Add a Break Iterator Operator by clicking the + OPERATOR button on the left-hand side of the Playbook Designer and selecting Break Iterator from the list. A Break Iterator Operator will appear. Connect it to the orange node of an If/Else Operator (Figure 14).
  2. Double click on the Break Iterator Operator, and the Edit Operator configuration panel will appear on the left-hand side of the Playbook Designer (Figure 15).
    • Job Name: Enter a name for the Break Iterator.
    • Click the SAVE button to save the configuration.
  3. If the condition that leads to the Break Iterator Operator occurs, the loop will exit and continue to the success path of the Iterator Operator.

    NOTE: When the Break Iterator Operator is executed, all iterations will stop, not just the one that led to the execution of the Break Iterator Operator.

20085-01 EN Rev. A

Contact Us

  • ThreatConnect, Inc.
    3865 Wilson Blvd.
    Suite 550
    Arlington, VA 22203

    Toll Free:   1.800.965.2708
    Local: +1.703.229.4240
    Fax +1.703.229.4489

    Email Us



https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete