Fortinet black logo

Playbooks Guide

Introduction to Playbooks

Copy Link
Copy Doc ID 68bdf840-ba26-11ec-9fd1-fa163e15d75b:331279
Download PDF

Introduction to Playbooks

Playbooks in FortiSOAR allow you to automate your security processes across external systems while respecting the business process required for your organization to function. Playbook templates can be customized to follow an organization's current procedures while leveraging the automation capabilities of FortiSOAR.

Tooltip

Playbooks are the key to empowering your organization with the full benefits of orchestration for both the human and machine side.

Playbooks can leverage a number of different FortiSOAR capabilities, such as inserting new data records, sending email notifications, and even referencing specified conditions to determine what path(s) to continue executing. Playbooks are highly configurable and provide consistent and thorough execution of IR response plans, enabling swift triage and containment of any potential cybersecurity threats.

The Playbook Engine runs asynchronously, meaning as an independent service, within the FortiSOAR application. This allows for better scalability and also frees the Application Engine to focus on request execution for better responsiveness to human users.

Overview of Playbook Collections

Use Playbook Collections to organize your playbooks. A playbook collection is similar to a folder structure in which you create and store playbooks that can be used for a particular strategy in your environment.

We recommend the following organizational scheme for storing your playbooks in Collections.

  • Each integration target should have its own Collection, e.g., Splunk
  • Actions should have their own Collections, such as Forensics, Enrichment, and Remediation, and further, the actions can leverage the integration playbooks
  • Response Plans should have their own Collection and should leverage the Actions in a sequence based on the standard categories of incidents

Overview of Playbooks

Playbooks are individual sequences of steps designed to accomplish a specific purpose. Playbooks are akin to a functional programming language, with capabilities to handle internal processes and external integrations.

Note

FortiSOAR supports RBAC for playbooks and therefore administrators require to assign roles with appropriate permissions to users who require to work with playbooks. For example, for users who require to run playbooks must be assigned the Execute permission on the Playbooks module.

The Playbook Designer supports Pan and Zoom tools. In case of large playbooks, you can use the Pan tool to scroll through your playbook, and you can use the Zoom tools to view the details of the playbook.

Playbooks are executed by default in the context of Playbook Appliance (PBA).

Tooltip

Ensure that when you are creating a playbook that you give the PBA all the necessary privileges on all the modules that will be consumed while executing the playbook. For example, if you want to extract indicators from an incident record using a playbook, then the playbook must have a minimum of Read permission on the Incident module and the Create permission on the Indicator module..

Permissions required to work with playbooks

  • To create Playbooks; you must be assigned a role with a minimum of Create, Read, and Update permission on the Playbooks module.
  • To modify steps and to view steps in-depth, you must be assigned a role with a minimum of Read and Update permission on the Playbooks module.
  • To view the Playbook Designer (you cannot view the steps in detail), you must be assigned a role with a minimum of Read permission on the Playbooks module.
  • To create and delete Playbooks, you must be assigned a role with a minimum of Create, Read, Update, and Delete permission on the Playbooks module.

Setting the logging levels for playbooks

From version 7.0.2 onwards, you can choose to set the logging levels for individual playbooks to either INFO (default) or DEBUG. Your administrator sets the global playbook logging levels; however, an administrator can also enable a setting that allows users to change the logging level for individual playbooks, which in turn overrides the global playbook logging levels. Set the playbook level logging to INFO for production instances and in scenarios where you want to use storage space efficiently; whereas use the DEBUG option only while designing or debugging playbooks since this option can quickly fill up the storage space.

To set the logging levels of a playbook, open the playbook in the playbook designer, and then click INFO or DEBUG (depending on the logging level set), which is present at the top of the Playbook Designer, as shown in the following image:
Playbook Designer: Top bar - Logging Level Mode

Clicking INFO or DEBUG displays the Playbook Execution Log Level dialog:
Playbook Execution Log Level Dialog
From the Select Execution Log Level field, select the logging level that you want to set for this playbook and click Apply. For example, if you select DEBUG, you will see that text at the top of the Playbook Designer changes to Running in DEBUG mode. Click Save Playbook to apply this change to the playbook.

For more information on playbook execution logs, see the Debugging and Optimizing Playbooks chapter.

Assigning ownership of playbooks

You can assign ownership to playbooks, i.e., if you want certain playbooks to be executed only by certain teams, then you can create a Private playbook and assign the playbook to only those teams.

By default, when you are creating a playbook, the playbook is created as a Public playbook, i.e., the playbook can be executed by all (if they have other appropriate rights). However, you can change this to Private by clicking the Private button that is present at the top of the Playbook Designer, as shown in the following image:

Playbook Designer: Top bar - Public Switch

To assign the playbook to a particular team, click the Teams icon (Teams icon). This opens the Assign Owners dialog. In the Assign Owners dialog, from the Owners drop-down list select the team that will own this playbook and click Assign.

Playbook Designer - Ownership Dialog

You can make multiple teams, owners of this playbook in a similar manner. If you want to remove ownership from a particular team, click the red cross that appears besides the team name.

Playbook Designer - Ownership Dialog: Removing teams

It is important to note that execute actions such as Escalate, Resolve, or any actions, which are displayed in the Execute drop-down list in records of modules such as Alerts, are shown based on ownership. For example, if you have created a Private playbook with a Manual Trigger or a Custom API Endpoint trigger on the Alerts module, and if you go to the alerts module and select the record, then Execute drop-down list will contain only those playbooks that belong to your team(s). In case of On Create or On Update triggers, RBAC is honored by matching the team defined in the playbook with the teams associated with the record.

Tooltip

When you export a playbook collection then all the playbooks within that collection become "Public" playbooks, even if some were marked as "Private playbooks, and the owners of the private playbooks become blank. Therefore, when you import these playbooks back into FortiSOAR, and you want the playbooks to be private, then open the playbook and click "Private" and reassign the owners. Exporting a single private playbook also marks it as public and its owners also become blank, and therefore, after importing this playbook into FortiSOAR, you will have to follow the same steps to make it "Private", if you want this playbook to be a "Private" playbook.

Creating Playbooks

  1. Click Automation > Playbooks in the left navigation bar.
  2. On the Playbook Collections page, click New Collection to define a new playbook collection in which to save the playbook you want to create, or, click an existing playbook collection and add the new playbook in that collection.
    Note: You cannot add a playbook directly on the Playbook Collections page, you require to add playbooks to a playbook collection.
  3. In the Add New Playbook Collection dialog, add the name of the collection in the Name field and optionally in the Description field, add the description for the playbook collection.
    You can optionally change the icon that represents the playbook collection, by clicking Change Image and dragging and dropping your icon to the Upload an Image dialog, or browsing to the icon on your system, selecting the icon and then clicking Save Image.
    You can optionally also add keywords in the Tags field that you can use to reference the playbook collection and making it easier to search and filter playbook collections and playbooks. You can add special characters and spaces in tags; however, the following special characters are not supported in tags: ', , , ", #, ?, and /.
    Click Create to create the new playbook collection.
  4. To add a playbook, click the collection in which you want to create the new playbook, and then click Add Playbook, which displays the Add New Playbook dialog:
    Adding a new Playbook
  5. In the Add New Playbook dialog, add the name of the playbook in the Name field and optionally in the Tags field, add keywords that you can use to reference the playbook, making it easier to search and filter playbooks. You can optionally in the Description field, add the description for the playbook.
    Important: Playbook names must be unique within a collection.
    The Active checkbox sets the state of the playbook as Active, or Inactive. By default, the Active checkbox is selected, i.e., new playbooks are created in the Active state.
    Click Create to add the new playbook.
    Note: The logging level of new playbooks are set as INFO, if you want detailed logging for the playbook, then you can open the playbook and set its mode to DEBUG.
  6. FortiSOAR displays the Playbook Designer for the newly added Playbook, with a placeholder trigger step and the name you have specified being displayed in the Name field at the top of the Designer. Now, you must select a playbook trigger from the Triggers section and enter the necessary variables for the selected trigger, and then click Save.
    Playbook Designer - First step
    For information on the various triggers, see the Triggers & Steps chapter .
    Note: Specific conditions that the playbook should meet before continuing can be called out by creating a Decision Step immediately after the trigger. While the playbook will still execute, the decision step (s) determines if the playbook continues through the following steps or is considered finished.
  7. Add playbook steps.
    Once you've selected a trigger, FortiSOAR displays the trigger step in the Playbook Designer with highlighted connector points as shown in the following image:
    Connecting a step to the trigger step
    Drag-and-drop a connector point to connect to another playbook step. FortiSOAR adds a placeholder step on the playbook designer page and opens the Steps tab which displays all the available playbook steps, select the playbook step that you need next, add the Step Name and the required variables and click Save.
    Adding steps
    Similarly, you can add further steps and create the desired flow for the playbook. A playbook ends when there are no additional steps to run. For more information on steps, see the Triggers & Steps chapter.
  8. Connect playbook steps or remove a connection between steps.
    It is straightforward to connect playbook steps as well as to remove the connection between playbook steps.
    To connect a playbook step, use the connection points that appear when you hover on a Playbook step. Select a connection point and drag and drop the arrow connector on the step you want to connect.
    Connecting Playbook steps
    To remove a connection between playbook steps, hover on the arrow connector between the steps, which then displays a cross (X) red color. Clicking X displays a Confirm dialog, click OK to remove the link between the playbook steps.
    Removing connection between playbook steps
  9. (Optional) To edit or remove an existing playbook step double-click on the step to reopen it and then you can edit the step or delete the step entirely by clicking Delete Step.
    Playbook steps include icons for the Info, Edit, Clone, and Delete actions enabling you to perform these actions in the step itself using the respective icons.
    Info, Edit, Clone, and Remove actions in playbook steps
    Clicking the Info icon displays additional information, if available, about the step.
    Clicking the Clone icon creates a copy of the current step and opens the step with the name as Copy of %Step Name%. All the properties of the current step are copied to the cloned step. You can edit the properties of the cloned step as required and then save the step.
    Clicking the Edit icon reopens the step, and you can edit the properties of the step and then save the step.
    Clicking the Delete icon deletes the step entirely.

Importing the BPMN Shareable Workflows as FortiSOAR Playbooks

FortiSOAR provides you with the ability to convert a BPMN Shareable Workflows to FortiSOAR playbooks. Business Process Model and Notation (BPMN) is a tool using which you can create flowcharts, and these flowcharts tend to be specific towards cybersecurity workflows. Therefore, this feature provides you with the advantage of importing your BPMN workflows and directly converting them into FortiSOAR playbooks, without the need to again create the same workflow in FortiSOAR.

The feature is introduced as a "BETA" feature with more enhancements being planned to be added in the subsequent releases to make the BPMN import more robust.

Import the BPMN Shareable Workflows into FortiSOAR as follows:

  1. Export your BPMN Shareable Workflows from your tool, such as Flowable, Camunda, or Signavio.
    BPMN workflows are exported in the XML format.
  2. To import the BPMN workflows into FortiSOAR:
    Note: FortiSOAR supports importing only a single BPMN workflow, i.e., you cannot import a collection of BPMN workflows.
    1. Log into FortiSOAR and click Automation > Playbooks in the left navigation bar.
    2. Click Import BPMN, which opens the Import BPMN dialog.
      Note: We are providing a "BETA" Version of this feature so that users can get a preview of this feature.
    3. In the Import BPMN dialog, do the following:
      1. From the BPMN Tool drop-down list, select the tool in which you have created your BPMN workflows.
        Note: FortiSOAR supports Flowable, Camunda, or Signavio.
      2. From the BPMN Output Format drop-down list, select the output format in which you want to convert your BPMN workflow.
        Note: FortiSOAR supports only XML as an output format.
      3. Drag and drop the BPMN XML file, or click the Import icon and browse to the XML file to import the BPMN XML file into FortiSOAR.
        If the XML of the BPMN workflow does contain errors, then a warning will be displayed in the Import BPMN dialog, which will contain the reason why the XML cannot be imported into FortiSOAR.
        If the XML of the BPMN workflow does not contain any mismatched elements or any other errors, then you will be able to import the workflow as a playbook in FortiSOAR.
        Import BPMN dialog
      4. To import the BPMN workflow file, click Import.
        This imports the workflow as a playbook in FortiSOAR with the same name as the workflow.
        Note: The name of the playbook must be unique, i.e., if you have two workflows with the same name that you want to import, you must either change the name of the playbook or click the Replace existing playbook checkbox to replace the existing playbook.
        Import BPMN with Replace existing playbook option
        FortiSOAR displays the imported workflow in the Playbook Designer as shown in the following image:
        Imported BPMN workflow in Playbook Designer
        Now you can edit the playbook as required in the playbook in FortiSOAR and easily create the automated workflow.

Translation of BPMN workflow steps into FortiSOAR steps in playbooks

The following table specifies which BPMN (Flowable in this case) workflow steps maps to which of the FortiSOAR steps in the playbooks:

Flowable (BPMN) step FortiSOAR steps Notes
SequenceFlows Routes Any SequenceFlows defined in your BPMN workflow get converted to a Decision step in FortiSOAR playbooks.
StartEvents Trigger steps Your BPMN workflow must mandatory have a “Start” event which is the starting point of the BPMN workflow. The Start event in the BPMN workflow get converted to a Manual Trigger in FortiSOAR playbooks.
Gateways Decision Step Your BPMN workflow must mandatorily have a “Flow Condition” input which must be referenced to the Gateway ID.
UserTasks Manual Tasks step Note: If the <userTask> is not created according to FortiSOAR Manual Task step requirements, then a generic manual task step is created in the FortiSOAR playbook instead of failing the playbook. After you import the workflow you can update the manual task step.
ServiceTasks Create Record step Or Update Record step A <serviceTask> in your BPMN workflow must have the following:
- A “Class” attribute to validate the model.
- The “Class” attribute must be specified as a module
- Addition of a “Class field” which contains either Create or Update.
ScriptTasks Connector step or as a Code Snippet step A <scriptTask> in your BPMN workflow must have the following:
- Name = {{ConnectorName}}
- scriptFormat = {{FortiSOAR Connector Action}}
- <script> => CDATA[ {{property mapping}} ]
Note: If the connector that you have defined in the <scriptTask> step is not installed in your FortiSOAR instance, then a generic connector step is created in the FortiSOAR playbook instead of failing the playbook. After you import the workflow you can update the connector step.
MailTasks SMTP step The mailTask is type of a <serviceTask> and it must be defined in your BPMN workflow as following:
<serviceTask>
Flowable:type = mail
HttpTasks FortiSOAR Utility Step (REST API call) The httpTask is type of a <serviceTask> and it must be defined in your BPMN workflow as following:
<serviceTask>
Flowable:type = http

Working with Playbooks

  1. Click Automation > Playbooks in the left navigation bar.
  2. On the Playbook Collections page, you can search, import, export, or delete a playbook collection.
    From release 7.2.0 onwards, you can view all system playbook collections by clicking the Show System Collections check box. Only users with a minimum of Update permissions on the Security module can view this checkbox. Clicking the Show System Collections checkbox displays the hidden playbook collections, both system fixtures as well as collections that contain data ingestion playbooks created by the data ingestion wizard, allowing you to view all the hidden playbook collections at once. For example, the Schedule Management playbooks in the following image is a system playbook collection:
    Show System Playbooks Collections checkboxIf you are a user without Security Update permissions, the Show System Collections checkbox will not be visible:
    Playbook Listing page
    Use the Search Collection field to search for playbook collections.
    You can import a playbook collection into FortiSOAR if it is in the appropriate JSON. To import a playbook collection into FortiSOAR, on the Playbook Collections page, click Import.
    On the Import Collections dialog, drag and drop the JSON file, or click the Import icon and browse to the JSON file to import the playbook collection into FortiSOAR and then click Import.
    Note: The name of the playbook collection being imported must be unique, else you will get a conflict while importing the playbook collection. However, if you want to replace an existing playbook collection, then click the Replace existing playbook collection checkbox.
    FortiSOAR also displays the list of global variables that would be imported along the playbook collections or playbooks on the Import Playbook dialog. These are the global variables that were part of the playbook that you had exported. You can review the imported global variables, and choose to modify them as per your requirements.
    If the JSON format is incorrect, FortiSOAR displays an error message and does not import the file.
    If the JSON format is correct, FortiSOAR imports the playbook collection and displays a success message.
    Note: Any tags associated with the playbook collection are upserted into the system when you import a playbook collection.
    To export a playbook collection, select the playbook collection and click Export. Any tags associated with a playbook collection are exported when you export a playbook collection.
    FortiSOAR exports the playbook collection in the JSON format.
    To delete a playbook collection, select the playbook collection and click Delete. Users with Delete permissions on the Playbooks module can delete playbook collections. From release 7.2.0 onwards, you can choose to permanently delete the playbook collection or move the playbook collection to the Recycle Bin (soft deletion). Once you click Delete, FortiSOAR displays the following confirmation dialog:
    Confirm Collection Deletion dialog
    On the confirmation dialog, select your deletion preference based on which the playbook collection is either permanently deleted or moved to the recycle bin. Clicking Move to Recycle Bin moves all the playbooks of that collection to the recycle bin. Similarly, when you restore any playbook from a playbook collection, the collection containing those playbooks is restored. For example, if you have a 'Demo' collection containing 3 playbooks, A, B, and C that you move to the recycle bin, and then restore B from the recycle bin, the Demo collection containing the B playbook gets restored. For more information on the Recycle Bin, see the "Administration Guide."
    You can click the More Options icon (More Options icon) to export records from the playbooks listing view in the csv or pdf format.
    Playbook - More Options Menu
    You can also reset the playbook record fields to the default fields specified for the playbook module, click the Reset Columns To Default option. You can include the Created By, Created On, Modified On, and Modified By fields in a playbook records for tracking purposes.
    To import a playbook on the <Playbooks Listing> page, click Import Playbook. The playbook must be in an appropriate JSON format. Any tags associated with the playbook are upserted into the system when you import a playbook.
  3. To perform operations on playbooks, click the playbook collection and open the <Playbooks Listing> page and then select playbooks. On the <Playbooks Listing> page, you can perform the following operations: Activate, Deactivate, Clone, Move, Export, Change Logging Level, and Delete.
    Playbook Listing Page - Playbook Operations
    On the <Playbooks Listing> page, you might see a message such as The count that you see on the playbook collection and the playbooks that you see..... as shown in the above image. This message is shown since RBAC is enforced on playbooks, and this means that you can only see a listing of those playbooks for which you (your team) are the owner. As shown in the above image, The Demo collection shows that 3 playbooks are part of the collection. However, the <Playbooks Listing> page only displays a single playbook, which means that the other playbook is a Private playbook with is owned by a team to which you are not assigned.
    You can also search for a playbook by typing keywords in the Search textbox.
    Follow the same process as specified for the Playbook Collection import and the same restrictions as applies to the Playbook Collection import applies to the Playbook import.
    To activate playbooks, select playbooks on the <Playbooks Listing> page and click Activate. To deactivate playbooks, select playbooks on the <Playbooks Listing> page and click Deactivate.
    To clone playbooks, select playbooks on the <Playbooks Listing> page and click Clone. You might clone playbooks if you want to reuse the playbook as a starting point for a new playbook. Cloning the playbook clones every step within the playbook. You can select more than one playbook to clone at a single time. FortiSOAR clones the playbook and places the cloned playbook with the name as Copy of %Playbook Name% (%New UUID%). Once you clone a playbook, you can edit it as per your requirements.
    To move playbooks to another existing collection, select playbooks on the <Playbooks Listing> page and click Move. FortiSOAR displays the Move Playbook dialog that contains the Move to collection section. Clicking Select in the Move to collection section displays the Collection dialog. From the Collection dialog, select the collection to which you want to move the playbooks and click Submit.
    To export playbooks, select playbooks on the <Playbooks Listing> page and click Export. FortiSOAR exports playbooks in the JSON format. Any tags associated with playbooks are exported when you export a playbook.
    To change the logging level for playbooks, select playbooks on the <Playbooks Listing> page and click Change Logging Levels, which displays the Playbook Execution Log Level dialog. From the Select Execution Log Level field, select DEBUG or INFO as the logging levels for the playbooks and click Apply. For more information on playbook logging levels, see the Setting the logging levels for playbooks topic.
    To delete playbooks, select playbooks and click Delete. Users with Delete permissions on the Playbooks module can delete playbooks. From release 7.2.0 onwards, you can choose to permanently delete the playbook or move the playbook to the Recycle Bin (soft deletion). Once you click Delete, FortiSOAR displays a confirmation dialog, on which you can choose from the following options Permanently Delete or Move to Recycle Bin.
  4. To edit a playbook, on the <Playbooks Listing> page, click the playbook that you want to edit.
    In the Playbook Designer, you can configure the following for the playbook:
    Change the state of the playbook by clicking the Is Active box, for example, change the state of the playbook from Active to Inactive.
    Change the Name of the playbook, by clicking the name box and updating the name. You can also add or update the Description of the playbook, or add or remove Tags from the playbook.
    Modify the trigger for the playbook, change or add steps or actions to the playbook.
    Use the Tools menu to enhance your playbook:
    Playbook Designer: Tools Menu
    To add parameters, use the Edit Parameters option.
    To add global variables, use the Global Variables option.
    To view the execution history of the playbook, use the Execution History option. For more information see the Debugging and Optimizing Playbooks chapter.
    To change the execution priority for a playbook, use the Execution Priority option. For more details, see the Changing the prioritization of playbook execution section.
    To apply a jinja template to a JSON input and then render the output, use the Jinja Editor option. You can thereby check the validity of the jinja and the output before you add the jinja to the playbook. For more information, see the Dynamic Values chapter.
  5. (Optional) Other actions that you can perform in the playbook designer are:
    Use the Export button to export the playbook in the JSON format. Use the Delete button to delete the playbook.
    Use the Trigger Playbook With Sample Data button to trigger the playbook from the playbook designer. For more details, see the Playbook Debugging - Triggering and testing playbooks from the Designer section.
    Use the Auto-Align - Vertical and Auto-Align - Horizontal buttons to align the playbook vertically or horizontally.
    Version 7.0.0 introduces the Undo/Redo feature, which is very useful while building a playbook when there is a lot of trial and back and forth to be done. Use the Undo button or use Ctrl+z(Windows)/Cmd+z (Mac) to reverse changes made in a playbook and use the Redo button or use Ctrl+y(Windows)/Cmd+shift+z(Mac) to reverse the steps that you have undone; therefore, you can use the Redo operation only after you have performed the Undo operation in a playbook. The playbook designer displays messages about the effect of the Undo/Redo operation in the bottom-right corner. When you perform bulk operations such as moving, cloning, or deleting a number of steps in one go, clicking Undo reverts the step modification. Similarly, if you have modified a step and saved it, clicking Undo, reverts the step modifications. Note that when editing inputs in the step argument form, the browser’s default change tracking is in effect; therefore, the Undo/Redo operations are applicable only after you save the step. Also, note that if you have made multiple changes in a small time period (around a second), then all these small changes are considered as a single operation.
  6. Once you have completed updating the playbook, click Save Playbook.

Tips for working in the playbook designer

Following are some tips that you can use to make it easier for you to work with playbooks and playbook steps in the playbook designer:

  • You can select a step by the CTRL+Mouse click operation. To select all the steps, press CTRL+A.
  • You can drag and drop multiple selected steps.
  • You can copy multiple selected steps by pressing CTRL+C or copy all the steps by pressing CTRL+A and then pressing CTRL+C. Ensure that you have clicked on your playbook canvas to bring it in focus before you copy the step(s).
    Note: The trigger step will not be copied.
  • You can paste the copied step(s) into a different playbook by using CTRL+V. Ensure that you have clicked on your playbook canvas to bring it in focus before you paste the step(s).
    Note: You can also select Paste from the Edit menu in your browser to paste the copied steps.
  • You can delete a step or multiple steps by selecting steps and pressing the backspace or the delete button.
  • You can use the Auto-Align - Vertical and Auto-Align - Horizontal buttons to align the playbook vertically or horizontally. You can use these buttons to make your playbook look neat and organized, which is especially useful for very large playbooks where playbook readability might be an issue.

Playbook Debugging - Triggering and testing playbooks from the Designer

You can trigger playbooks directly from the playbook designer making it easier for playbook developers to test and debug playbooks while building them. Now, playbook developers do not require to go now to the module, select the record, and then choose playbook and then trigger the playbook and then come back again to the playbook designer to make the changes; all this can now be directly done from the playbook designer.

Caution

Triggering a playbook from the designer starts the execution of the playbook, which can cause changes to your data leading to unwanted changes or loss of data. Therefore, it is important to review the playbook before it is triggered.

To trigger a playbook from the playbook designer, click the Trigger Playbook with Sample Data button. You can choose whether you want to use the Last Run Data as the sample data to trigger the playbook or you want to use Record Input/Custom.

Triggering playbooks from the playbook designer - Last Run Data option

If you have run the playbook earlier, you can choose the Last Run Data option, and then from the Choose a recent playbook execution drop-down list, select the playbook execution with whose environment you want to trigger the playbook and click Trigger Playbook. Once you trigger the playbook with sample data, the Executed Playbook Logs dialog opens and you can view the logs and results of your executed playbook and continue to test and build your playbook.

You can also choose the Record Input/Custom option, and if you have a playbook that has a Manual trigger, then from the Select Record drop-down list choose the record(s) using whose data, i.e., fields and values, you want to use to trigger the playbook. Note that the 30 recently-created records will be fetched.

Triggering playbooks from the playbook designer - Custom Sample Data option

To trigger a playbook, you provide input based on the type of trigger you have defined for the playbook. For example, the Select Record drop-down list will not be present in case of a "Manual Trigger" step that has the Does not require a record input to run option selected since in this case the playbook does not require the data of a record to trigger a playbook. Also, in the case of a "Manual Trigger" step that has the Run separately for each selected records option selected, and in which you have selected multiple records and triggered a playbook from the designer, you will observe that only a single playbook will be triggered on a single record to simulate the output. Similarly, in case of a Referenced trigger, you can provide parameter values and trigger the playbook using those parameters.

The playbook can also use the "Mock Output" defined in the steps while running the playbook if you choose to Enable mock output.

Changing the prioritization of playbook execution

You can change the prioritization of playbook execution based on the importance of that playbook, thereby enabling the higher priority playbooks to be executed first even if there are some normal priority playbooks already queued for execution. Earlier, the playbook execution queue was based on first in first out method, with round robin assignment of workers (processes), which meant that important playbooks might get queued after lower-priority playbooks.

For example, if you have set up data ingestion to run every minute, then possibly you would have many data ingestion playbooks queued up, and then if you also require to run an important playbook with a manual action, it would earlier be run only once the data ingestion task that was scheduled before it was completed. Now, you can change the prioritization of the manual input playbook to "High" enabling it to get executed on priority.

You can set the priority for playbook execution as High, Medium, or Low. The default priority is set as "Medium". Playbook execution prioritization works as follows:

  • If any worker is available for the task execution, it gets assigned a task from the "High" queue first and so on.
  • If all workers are occupied with lower priority tasks and any higher priority task comes up, the high priority task gets executed only when any worker is again available.
  • Low priority tasks do not get executed if there are high priority tasks.

To set a priority for playbook prioritization, open that playbook in the playbook designer. Click Tools > Execution Priority. In the Execution Priority dialog, you can set the playbook execution prioritization to High, Medium, or Low:

Setting the playbook execution priority

To list the number of messages (workflow count) in the 'celery' queue, use the following command:
rabbitmqctl list_queues -p fsr-cluster --no-table-headers --silent | grep -E "^\s*celery\s+" | awk '{print $2}'
When there is no queue, it will display 0 (default), and when the queue builds up, it will display the queue count number such as 10, 25, etc.

Notes:

  • All 'sync' reference playbooks automatically inherit the priority of their parent playbooks, thereby ignoring any preset priority.
  • If you update the execution priority of a scheduled playbook, then you require to edit and resave the schedules associated with that playbook.
  • If you want to schedule a data ingestion playbook, then you must set the priority of the data ingestion playbook before scheduling the same.

FortiSOAR also integrates with a GUI-based celery monitoring tool called Flower, using which you can monitor and administer celery cluster and playbook execution queues. You can start a Flower web server using the following process:

cd /opt/cyops-workflow/sealab

../.env/bin/flower -A sealab --port=5555

Note: Ensure that port that you are specifying in the URL, 5555 in the above sample, is opened in your firewall and can be accessed.

Live User implementation in Playbook Designer

The playbook designer implements Live Users, which means that the playbook designer displays users who are also currently working on the same playbook. Therefore, when you open a playbook and if there are other users who are working on the same playbook apart from you, then the playbook designer will display the users working on the playbook, as well as the number of sessions that are active for each user. Live Users also notifies users that are working on the same playbook, if any other user or session has saved modifications to the playbook, so that the user can refresh the playbook before working on the same, thereby ensuring that users work on the latest version of the playbook. Users can also save versions of their current modified state of the playbook, thereby providing users with the ability to merge their changes.

Live Users - Playbook Designer

Live Users has the following benefits:

  • Users are notified of other users or sessions that are active on the same playbook.
  • Users work on the latest version of the playbook, and they do not lose their updates made to the playbook.

Saving versions of your playbook

You can save versions of a playbook that you are creating or updating. Using versioning, you can save multiple versions of the same playbook. You can also revert your current playbook to a particular version, making working in playbooks more effective.

The maximum number of versions that can be taken, across all users working on a playbook is 20. If you or other users try to take more than 20 snapshots, a confirm dialog is displayed that prompts you to delete a version so that you can free space and save a new version, as shown in the following image:

Confirm dialog for deleting a snapshot

When you click Confirm, the Versions - <Name of Playbook> dialog is displayed. You can now choose the version(s) that you want to delete, click the Delete icon, and then click Confirm on the confirmation dialog and close the Versions - <Name of Playbook> dialog. This frees up space and you can now save a new version.

Versions Dialog

Using the Versions - <Name of Playbook> dialog, you can search for versions based on the notes you have added, and also filter versions by the Created By (user who has created the version), Saved On (time the version was saved) and action performed.

To take a snapshot and revert the playbook to a particular snapshot do the following:

  1. In the playbook in which you are working in the playbook designer, click Save Version.
  2. In the Save Version dialog, add a note that you want to associate with the version and click Save Version.
    It is recommended that you add meaningful notes for versions as these names will help you in identifying the snapshots when you want to revert to a particular version.
  3. To revert a version, click Save Version and then either click Revert to Last Saved or click View Saved Versions. Clicking Revert to Last Saved reverts the playbook to the last saved version of the playbook
    Clicking View Saved Versions displays the Versions - <Name of Playbook> dialog that allows you to choose the version of the playbook to which you want revert:
    Versions dialog
    In the Versions - <Name of Playbook> dialog, in the version row to which you want to revert, click Load.
    Once you click Load, that snapshot is loaded in the playbook designer, with a message: "You are working on a previously taken playbook snapshot...." as shown in the following image:
    Loading of a version in the playbook designer
  4. You can choose to view the playbook that is currently saved, by clicking the View Current Saved Playbook link, or you can click Mark as Current Saved Playbook to make this version the current saved version of the playbook and continue to work on the playbook.

Exporting versions of your playbook

You can choose to export playbook collections or playbooks with saved versions of the playbooks. This is extremely useful while developing playbooks, especially if you erroneously delete a step in the playbook or you want to go back to the previous state of the playbook. Retaining the versions of playbooks while exporting playbooks enables you to load a snapshot of a previously saved version of the playbook into an imported playbook

You can choose to export playbook collections or playbooks with saved versions of the playbooks as shown in the following image:

Exporting a playbook with versions

Clicking Yes, include versions on the above dialog will export playbooks or playbook collections with the saved versions of the playbook.

You can then import the playbook and then open that playbook in the playbook designer, you can see the previously saved versions of the playbook by clicking Save Version > View Saved Versions. This opens the Versions dialog as shown in the following image:

Save Version - View Saved Versions

You can load a snapshot of a previously saved version of playbook in the Versions dialog by selecting the snapshot that you want to load in the playbook designer and clicking Load. This will display a message such as "You are working.....playbook snapshot...." as shown in the following image:

Viewing a previous snapshot of a playbook

You can save this version of the playbook and continue to work on it or you can click View Current Saved Playbook to revert back to the state of the playbook when it was last saved.

Playbook recovery

FortiSOAR autosaves playbooks so that you can recover playbook drafts in cases where you accidentally close your browser or face any issues while working on a playbook. These unsaved (autosaved) drafts do not replace the current saved version of the playbook and only ensure that you do not lose any of your work done in the playbook, by providing you the ability to recover the drafts.

Playbook recovery in FortiSOAR is user-based, which ensures that users see their own unsaved drafts of the playbook. Since it is browser-based, it comes into effect as long as the same browser instance is used by the user. Also, playbook drafts might not be saved if you are working in the "Incognito" mode.

By default, FortiSOAR saves playbook drafts 15 seconds after the last change. However, you can ask your administrator to change this time across all playbooks by modifying the time, in seconds, on the Application Configuration tab in the System Configuration page. The minimum time that your administrator can set for saving playbook drafts is 5 seconds after the last change. You can also choose to disable (and later enable) playbooks recovery for all playbooks. For more information, see the System Configuration chapter in the "Administration Guide."

Note

If the browser data is cleared, then the autosaved drafts will get deleted.

To recover an unsaved draft of the playbook, reopen that playbook in the playbook designer you will be prompted to confirm whether you want to recover the draft of the playbook as shown in the following image:

Confirm recovery of autosaved version of Playbook

Once you click Confirm on the Confirm dialog, the autosaved version of the playbook is loaded in the playbook designer, and you can then choose to save this playbook using Save Playbook and make it the current working copy.

System Playbooks

FortiSOAR includes some system playbook collections that are used to automate tasks, such as the Schedule Management Playbooks collection can be used to schedule various tasks such as cleaning up playbook execution history, purging integration logs, etc. Or, you can use the Report Management Playbooks collection to manage generation of reports. For example, the Generate Report By Scheduler playbook generates reports based on schedules that you have specified. You can also reference system playbook from other playbooks.

The FortiSOAR UI includes links on the System Configuration page to the various playbook collections and templates, which are included by default when you install your FortiSOAR instance. Administrators can click the Settings (Setting icon) icon to open the System Configuration page and click the System Fixtures tab to access the system playbooks or fixtures. The System Fixtures page contains links to the system playbook collections and templates. Administrators can click these links to easily access all the system fixtures to understand their workings and make changes in them if required. For example, to access Schedule Management Playbooks, click the Schedule Management Playbooks link.

System Fixtures tab

Caution

You can modify system playbooks as per your requirements. However, incorrectly modifying any system playbook can affect FortiSOAR functionality.

For example, if you want to modify the default email signature, which is currently Regards, FortiSOAR Admin, for a system playbook, open the playbook and double-click on its Send Email step. In the Send Email step, in the Content field, modify the signature as per your requirements and click Save.

Tooltip

In the system playbook (or any playbook) that is sending an email, ensure that you have used the Server_fqhn global variable in the Send Email step.

When you are using a system playbook that sends an email, for example, when an alert is escalated to an incident, and an Incident Lead is assigned, then the system playbook sends an email to the Incident Lead specified. The email that is sent to the Incident Lead contains the link to the incident using the default hostname, which is the hostname that you had specified or that was present when you installed FortiSOAR. To ensure that the correct hostname is displayed in the email, you must update the appropriate hostname as per your FortiSOAR instance, in the playbook, using the Playbook Designer as follows:

  1. Open the Playbook Designer.
  2. Click Tools > Global Variables to display a list of global variables.
  3. In the Global Variables pane, search for the Server_fqhn global variable, then click the Edit icon in the Server_fqhn global variable, and in the Field Value field add the appropriate hostname value.
    Editing global variables in the Send Email steps
    You can optionally specify a default hostname value in the Default Value field.
  4. Click Submit.
    This adds the updated hostname for your incident and then when a system playbook sends an email the link contains the correct hostname.
Note Playbooks that contain a reference to the approvalHost global variable fail with the 'approvalHost variable undefined' error, since the approvalHost global variable is removed from release 7.2.0 onwards. To resolve this error, replace the approvalHost global variable in the playbook with the Server_fqhn global variable.

For information about all the system playbook collections and templates, which are included by default when you install your FortiSOAR instance, see the System Configuration topic in the "Administration Guide."

Introduction to Playbooks

Playbooks in FortiSOAR allow you to automate your security processes across external systems while respecting the business process required for your organization to function. Playbook templates can be customized to follow an organization's current procedures while leveraging the automation capabilities of FortiSOAR.

Tooltip

Playbooks are the key to empowering your organization with the full benefits of orchestration for both the human and machine side.

Playbooks can leverage a number of different FortiSOAR capabilities, such as inserting new data records, sending email notifications, and even referencing specified conditions to determine what path(s) to continue executing. Playbooks are highly configurable and provide consistent and thorough execution of IR response plans, enabling swift triage and containment of any potential cybersecurity threats.

The Playbook Engine runs asynchronously, meaning as an independent service, within the FortiSOAR application. This allows for better scalability and also frees the Application Engine to focus on request execution for better responsiveness to human users.

Overview of Playbook Collections

Use Playbook Collections to organize your playbooks. A playbook collection is similar to a folder structure in which you create and store playbooks that can be used for a particular strategy in your environment.

We recommend the following organizational scheme for storing your playbooks in Collections.

  • Each integration target should have its own Collection, e.g., Splunk
  • Actions should have their own Collections, such as Forensics, Enrichment, and Remediation, and further, the actions can leverage the integration playbooks
  • Response Plans should have their own Collection and should leverage the Actions in a sequence based on the standard categories of incidents

Overview of Playbooks

Playbooks are individual sequences of steps designed to accomplish a specific purpose. Playbooks are akin to a functional programming language, with capabilities to handle internal processes and external integrations.

Note

FortiSOAR supports RBAC for playbooks and therefore administrators require to assign roles with appropriate permissions to users who require to work with playbooks. For example, for users who require to run playbooks must be assigned the Execute permission on the Playbooks module.

The Playbook Designer supports Pan and Zoom tools. In case of large playbooks, you can use the Pan tool to scroll through your playbook, and you can use the Zoom tools to view the details of the playbook.

Playbooks are executed by default in the context of Playbook Appliance (PBA).

Tooltip

Ensure that when you are creating a playbook that you give the PBA all the necessary privileges on all the modules that will be consumed while executing the playbook. For example, if you want to extract indicators from an incident record using a playbook, then the playbook must have a minimum of Read permission on the Incident module and the Create permission on the Indicator module..

Permissions required to work with playbooks

  • To create Playbooks; you must be assigned a role with a minimum of Create, Read, and Update permission on the Playbooks module.
  • To modify steps and to view steps in-depth, you must be assigned a role with a minimum of Read and Update permission on the Playbooks module.
  • To view the Playbook Designer (you cannot view the steps in detail), you must be assigned a role with a minimum of Read permission on the Playbooks module.
  • To create and delete Playbooks, you must be assigned a role with a minimum of Create, Read, Update, and Delete permission on the Playbooks module.

Setting the logging levels for playbooks

From version 7.0.2 onwards, you can choose to set the logging levels for individual playbooks to either INFO (default) or DEBUG. Your administrator sets the global playbook logging levels; however, an administrator can also enable a setting that allows users to change the logging level for individual playbooks, which in turn overrides the global playbook logging levels. Set the playbook level logging to INFO for production instances and in scenarios where you want to use storage space efficiently; whereas use the DEBUG option only while designing or debugging playbooks since this option can quickly fill up the storage space.

To set the logging levels of a playbook, open the playbook in the playbook designer, and then click INFO or DEBUG (depending on the logging level set), which is present at the top of the Playbook Designer, as shown in the following image:
Playbook Designer: Top bar - Logging Level Mode

Clicking INFO or DEBUG displays the Playbook Execution Log Level dialog:
Playbook Execution Log Level Dialog
From the Select Execution Log Level field, select the logging level that you want to set for this playbook and click Apply. For example, if you select DEBUG, you will see that text at the top of the Playbook Designer changes to Running in DEBUG mode. Click Save Playbook to apply this change to the playbook.

For more information on playbook execution logs, see the Debugging and Optimizing Playbooks chapter.

Assigning ownership of playbooks

You can assign ownership to playbooks, i.e., if you want certain playbooks to be executed only by certain teams, then you can create a Private playbook and assign the playbook to only those teams.

By default, when you are creating a playbook, the playbook is created as a Public playbook, i.e., the playbook can be executed by all (if they have other appropriate rights). However, you can change this to Private by clicking the Private button that is present at the top of the Playbook Designer, as shown in the following image:

Playbook Designer: Top bar - Public Switch

To assign the playbook to a particular team, click the Teams icon (Teams icon). This opens the Assign Owners dialog. In the Assign Owners dialog, from the Owners drop-down list select the team that will own this playbook and click Assign.

Playbook Designer - Ownership Dialog

You can make multiple teams, owners of this playbook in a similar manner. If you want to remove ownership from a particular team, click the red cross that appears besides the team name.

Playbook Designer - Ownership Dialog: Removing teams

It is important to note that execute actions such as Escalate, Resolve, or any actions, which are displayed in the Execute drop-down list in records of modules such as Alerts, are shown based on ownership. For example, if you have created a Private playbook with a Manual Trigger or a Custom API Endpoint trigger on the Alerts module, and if you go to the alerts module and select the record, then Execute drop-down list will contain only those playbooks that belong to your team(s). In case of On Create or On Update triggers, RBAC is honored by matching the team defined in the playbook with the teams associated with the record.

Tooltip

When you export a playbook collection then all the playbooks within that collection become "Public" playbooks, even if some were marked as "Private playbooks, and the owners of the private playbooks become blank. Therefore, when you import these playbooks back into FortiSOAR, and you want the playbooks to be private, then open the playbook and click "Private" and reassign the owners. Exporting a single private playbook also marks it as public and its owners also become blank, and therefore, after importing this playbook into FortiSOAR, you will have to follow the same steps to make it "Private", if you want this playbook to be a "Private" playbook.

Creating Playbooks

  1. Click Automation > Playbooks in the left navigation bar.
  2. On the Playbook Collections page, click New Collection to define a new playbook collection in which to save the playbook you want to create, or, click an existing playbook collection and add the new playbook in that collection.
    Note: You cannot add a playbook directly on the Playbook Collections page, you require to add playbooks to a playbook collection.
  3. In the Add New Playbook Collection dialog, add the name of the collection in the Name field and optionally in the Description field, add the description for the playbook collection.
    You can optionally change the icon that represents the playbook collection, by clicking Change Image and dragging and dropping your icon to the Upload an Image dialog, or browsing to the icon on your system, selecting the icon and then clicking Save Image.
    You can optionally also add keywords in the Tags field that you can use to reference the playbook collection and making it easier to search and filter playbook collections and playbooks. You can add special characters and spaces in tags; however, the following special characters are not supported in tags: ', , , ", #, ?, and /.
    Click Create to create the new playbook collection.
  4. To add a playbook, click the collection in which you want to create the new playbook, and then click Add Playbook, which displays the Add New Playbook dialog:
    Adding a new Playbook
  5. In the Add New Playbook dialog, add the name of the playbook in the Name field and optionally in the Tags field, add keywords that you can use to reference the playbook, making it easier to search and filter playbooks. You can optionally in the Description field, add the description for the playbook.
    Important: Playbook names must be unique within a collection.
    The Active checkbox sets the state of the playbook as Active, or Inactive. By default, the Active checkbox is selected, i.e., new playbooks are created in the Active state.
    Click Create to add the new playbook.
    Note: The logging level of new playbooks are set as INFO, if you want detailed logging for the playbook, then you can open the playbook and set its mode to DEBUG.
  6. FortiSOAR displays the Playbook Designer for the newly added Playbook, with a placeholder trigger step and the name you have specified being displayed in the Name field at the top of the Designer. Now, you must select a playbook trigger from the Triggers section and enter the necessary variables for the selected trigger, and then click Save.
    Playbook Designer - First step
    For information on the various triggers, see the Triggers & Steps chapter .
    Note: Specific conditions that the playbook should meet before continuing can be called out by creating a Decision Step immediately after the trigger. While the playbook will still execute, the decision step (s) determines if the playbook continues through the following steps or is considered finished.
  7. Add playbook steps.
    Once you've selected a trigger, FortiSOAR displays the trigger step in the Playbook Designer with highlighted connector points as shown in the following image:
    Connecting a step to the trigger step
    Drag-and-drop a connector point to connect to another playbook step. FortiSOAR adds a placeholder step on the playbook designer page and opens the Steps tab which displays all the available playbook steps, select the playbook step that you need next, add the Step Name and the required variables and click Save.
    Adding steps
    Similarly, you can add further steps and create the desired flow for the playbook. A playbook ends when there are no additional steps to run. For more information on steps, see the Triggers & Steps chapter.
  8. Connect playbook steps or remove a connection between steps.
    It is straightforward to connect playbook steps as well as to remove the connection between playbook steps.
    To connect a playbook step, use the connection points that appear when you hover on a Playbook step. Select a connection point and drag and drop the arrow connector on the step you want to connect.
    Connecting Playbook steps
    To remove a connection between playbook steps, hover on the arrow connector between the steps, which then displays a cross (X) red color. Clicking X displays a Confirm dialog, click OK to remove the link between the playbook steps.
    Removing connection between playbook steps
  9. (Optional) To edit or remove an existing playbook step double-click on the step to reopen it and then you can edit the step or delete the step entirely by clicking Delete Step.
    Playbook steps include icons for the Info, Edit, Clone, and Delete actions enabling you to perform these actions in the step itself using the respective icons.
    Info, Edit, Clone, and Remove actions in playbook steps
    Clicking the Info icon displays additional information, if available, about the step.
    Clicking the Clone icon creates a copy of the current step and opens the step with the name as Copy of %Step Name%. All the properties of the current step are copied to the cloned step. You can edit the properties of the cloned step as required and then save the step.
    Clicking the Edit icon reopens the step, and you can edit the properties of the step and then save the step.
    Clicking the Delete icon deletes the step entirely.

Importing the BPMN Shareable Workflows as FortiSOAR Playbooks

FortiSOAR provides you with the ability to convert a BPMN Shareable Workflows to FortiSOAR playbooks. Business Process Model and Notation (BPMN) is a tool using which you can create flowcharts, and these flowcharts tend to be specific towards cybersecurity workflows. Therefore, this feature provides you with the advantage of importing your BPMN workflows and directly converting them into FortiSOAR playbooks, without the need to again create the same workflow in FortiSOAR.

The feature is introduced as a "BETA" feature with more enhancements being planned to be added in the subsequent releases to make the BPMN import more robust.

Import the BPMN Shareable Workflows into FortiSOAR as follows:

  1. Export your BPMN Shareable Workflows from your tool, such as Flowable, Camunda, or Signavio.
    BPMN workflows are exported in the XML format.
  2. To import the BPMN workflows into FortiSOAR:
    Note: FortiSOAR supports importing only a single BPMN workflow, i.e., you cannot import a collection of BPMN workflows.
    1. Log into FortiSOAR and click Automation > Playbooks in the left navigation bar.
    2. Click Import BPMN, which opens the Import BPMN dialog.
      Note: We are providing a "BETA" Version of this feature so that users can get a preview of this feature.
    3. In the Import BPMN dialog, do the following:
      1. From the BPMN Tool drop-down list, select the tool in which you have created your BPMN workflows.
        Note: FortiSOAR supports Flowable, Camunda, or Signavio.
      2. From the BPMN Output Format drop-down list, select the output format in which you want to convert your BPMN workflow.
        Note: FortiSOAR supports only XML as an output format.
      3. Drag and drop the BPMN XML file, or click the Import icon and browse to the XML file to import the BPMN XML file into FortiSOAR.
        If the XML of the BPMN workflow does contain errors, then a warning will be displayed in the Import BPMN dialog, which will contain the reason why the XML cannot be imported into FortiSOAR.
        If the XML of the BPMN workflow does not contain any mismatched elements or any other errors, then you will be able to import the workflow as a playbook in FortiSOAR.
        Import BPMN dialog
      4. To import the BPMN workflow file, click Import.
        This imports the workflow as a playbook in FortiSOAR with the same name as the workflow.
        Note: The name of the playbook must be unique, i.e., if you have two workflows with the same name that you want to import, you must either change the name of the playbook or click the Replace existing playbook checkbox to replace the existing playbook.
        Import BPMN with Replace existing playbook option
        FortiSOAR displays the imported workflow in the Playbook Designer as shown in the following image:
        Imported BPMN workflow in Playbook Designer
        Now you can edit the playbook as required in the playbook in FortiSOAR and easily create the automated workflow.

Translation of BPMN workflow steps into FortiSOAR steps in playbooks

The following table specifies which BPMN (Flowable in this case) workflow steps maps to which of the FortiSOAR steps in the playbooks:

Flowable (BPMN) step FortiSOAR steps Notes
SequenceFlows Routes Any SequenceFlows defined in your BPMN workflow get converted to a Decision step in FortiSOAR playbooks.
StartEvents Trigger steps Your BPMN workflow must mandatory have a “Start” event which is the starting point of the BPMN workflow. The Start event in the BPMN workflow get converted to a Manual Trigger in FortiSOAR playbooks.
Gateways Decision Step Your BPMN workflow must mandatorily have a “Flow Condition” input which must be referenced to the Gateway ID.
UserTasks Manual Tasks step Note: If the <userTask> is not created according to FortiSOAR Manual Task step requirements, then a generic manual task step is created in the FortiSOAR playbook instead of failing the playbook. After you import the workflow you can update the manual task step.
ServiceTasks Create Record step Or Update Record step A <serviceTask> in your BPMN workflow must have the following:
- A “Class” attribute to validate the model.
- The “Class” attribute must be specified as a module
- Addition of a “Class field” which contains either Create or Update.
ScriptTasks Connector step or as a Code Snippet step A <scriptTask> in your BPMN workflow must have the following:
- Name = {{ConnectorName}}
- scriptFormat = {{FortiSOAR Connector Action}}
- <script> => CDATA[ {{property mapping}} ]
Note: If the connector that you have defined in the <scriptTask> step is not installed in your FortiSOAR instance, then a generic connector step is created in the FortiSOAR playbook instead of failing the playbook. After you import the workflow you can update the connector step.
MailTasks SMTP step The mailTask is type of a <serviceTask> and it must be defined in your BPMN workflow as following:
<serviceTask>
Flowable:type = mail
HttpTasks FortiSOAR Utility Step (REST API call) The httpTask is type of a <serviceTask> and it must be defined in your BPMN workflow as following:
<serviceTask>
Flowable:type = http

Working with Playbooks

  1. Click Automation > Playbooks in the left navigation bar.
  2. On the Playbook Collections page, you can search, import, export, or delete a playbook collection.
    From release 7.2.0 onwards, you can view all system playbook collections by clicking the Show System Collections check box. Only users with a minimum of Update permissions on the Security module can view this checkbox. Clicking the Show System Collections checkbox displays the hidden playbook collections, both system fixtures as well as collections that contain data ingestion playbooks created by the data ingestion wizard, allowing you to view all the hidden playbook collections at once. For example, the Schedule Management playbooks in the following image is a system playbook collection:
    Show System Playbooks Collections checkboxIf you are a user without Security Update permissions, the Show System Collections checkbox will not be visible:
    Playbook Listing page
    Use the Search Collection field to search for playbook collections.
    You can import a playbook collection into FortiSOAR if it is in the appropriate JSON. To import a playbook collection into FortiSOAR, on the Playbook Collections page, click Import.
    On the Import Collections dialog, drag and drop the JSON file, or click the Import icon and browse to the JSON file to import the playbook collection into FortiSOAR and then click Import.
    Note: The name of the playbook collection being imported must be unique, else you will get a conflict while importing the playbook collection. However, if you want to replace an existing playbook collection, then click the Replace existing playbook collection checkbox.
    FortiSOAR also displays the list of global variables that would be imported along the playbook collections or playbooks on the Import Playbook dialog. These are the global variables that were part of the playbook that you had exported. You can review the imported global variables, and choose to modify them as per your requirements.
    If the JSON format is incorrect, FortiSOAR displays an error message and does not import the file.
    If the JSON format is correct, FortiSOAR imports the playbook collection and displays a success message.
    Note: Any tags associated with the playbook collection are upserted into the system when you import a playbook collection.
    To export a playbook collection, select the playbook collection and click Export. Any tags associated with a playbook collection are exported when you export a playbook collection.
    FortiSOAR exports the playbook collection in the JSON format.
    To delete a playbook collection, select the playbook collection and click Delete. Users with Delete permissions on the Playbooks module can delete playbook collections. From release 7.2.0 onwards, you can choose to permanently delete the playbook collection or move the playbook collection to the Recycle Bin (soft deletion). Once you click Delete, FortiSOAR displays the following confirmation dialog:
    Confirm Collection Deletion dialog
    On the confirmation dialog, select your deletion preference based on which the playbook collection is either permanently deleted or moved to the recycle bin. Clicking Move to Recycle Bin moves all the playbooks of that collection to the recycle bin. Similarly, when you restore any playbook from a playbook collection, the collection containing those playbooks is restored. For example, if you have a 'Demo' collection containing 3 playbooks, A, B, and C that you move to the recycle bin, and then restore B from the recycle bin, the Demo collection containing the B playbook gets restored. For more information on the Recycle Bin, see the "Administration Guide."
    You can click the More Options icon (More Options icon) to export records from the playbooks listing view in the csv or pdf format.
    Playbook - More Options Menu
    You can also reset the playbook record fields to the default fields specified for the playbook module, click the Reset Columns To Default option. You can include the Created By, Created On, Modified On, and Modified By fields in a playbook records for tracking purposes.
    To import a playbook on the <Playbooks Listing> page, click Import Playbook. The playbook must be in an appropriate JSON format. Any tags associated with the playbook are upserted into the system when you import a playbook.
  3. To perform operations on playbooks, click the playbook collection and open the <Playbooks Listing> page and then select playbooks. On the <Playbooks Listing> page, you can perform the following operations: Activate, Deactivate, Clone, Move, Export, Change Logging Level, and Delete.
    Playbook Listing Page - Playbook Operations
    On the <Playbooks Listing> page, you might see a message such as The count that you see on the playbook collection and the playbooks that you see..... as shown in the above image. This message is shown since RBAC is enforced on playbooks, and this means that you can only see a listing of those playbooks for which you (your team) are the owner. As shown in the above image, The Demo collection shows that 3 playbooks are part of the collection. However, the <Playbooks Listing> page only displays a single playbook, which means that the other playbook is a Private playbook with is owned by a team to which you are not assigned.
    You can also search for a playbook by typing keywords in the Search textbox.
    Follow the same process as specified for the Playbook Collection import and the same restrictions as applies to the Playbook Collection import applies to the Playbook import.
    To activate playbooks, select playbooks on the <Playbooks Listing> page and click Activate. To deactivate playbooks, select playbooks on the <Playbooks Listing> page and click Deactivate.
    To clone playbooks, select playbooks on the <Playbooks Listing> page and click Clone. You might clone playbooks if you want to reuse the playbook as a starting point for a new playbook. Cloning the playbook clones every step within the playbook. You can select more than one playbook to clone at a single time. FortiSOAR clones the playbook and places the cloned playbook with the name as Copy of %Playbook Name% (%New UUID%). Once you clone a playbook, you can edit it as per your requirements.
    To move playbooks to another existing collection, select playbooks on the <Playbooks Listing> page and click Move. FortiSOAR displays the Move Playbook dialog that contains the Move to collection section. Clicking Select in the Move to collection section displays the Collection dialog. From the Collection dialog, select the collection to which you want to move the playbooks and click Submit.
    To export playbooks, select playbooks on the <Playbooks Listing> page and click Export. FortiSOAR exports playbooks in the JSON format. Any tags associated with playbooks are exported when you export a playbook.
    To change the logging level for playbooks, select playbooks on the <Playbooks Listing> page and click Change Logging Levels, which displays the Playbook Execution Log Level dialog. From the Select Execution Log Level field, select DEBUG or INFO as the logging levels for the playbooks and click Apply. For more information on playbook logging levels, see the Setting the logging levels for playbooks topic.
    To delete playbooks, select playbooks and click Delete. Users with Delete permissions on the Playbooks module can delete playbooks. From release 7.2.0 onwards, you can choose to permanently delete the playbook or move the playbook to the Recycle Bin (soft deletion). Once you click Delete, FortiSOAR displays a confirmation dialog, on which you can choose from the following options Permanently Delete or Move to Recycle Bin.
  4. To edit a playbook, on the <Playbooks Listing> page, click the playbook that you want to edit.
    In the Playbook Designer, you can configure the following for the playbook:
    Change the state of the playbook by clicking the Is Active box, for example, change the state of the playbook from Active to Inactive.
    Change the Name of the playbook, by clicking the name box and updating the name. You can also add or update the Description of the playbook, or add or remove Tags from the playbook.
    Modify the trigger for the playbook, change or add steps or actions to the playbook.
    Use the Tools menu to enhance your playbook:
    Playbook Designer: Tools Menu
    To add parameters, use the Edit Parameters option.
    To add global variables, use the Global Variables option.
    To view the execution history of the playbook, use the Execution History option. For more information see the Debugging and Optimizing Playbooks chapter.
    To change the execution priority for a playbook, use the Execution Priority option. For more details, see the Changing the prioritization of playbook execution section.
    To apply a jinja template to a JSON input and then render the output, use the Jinja Editor option. You can thereby check the validity of the jinja and the output before you add the jinja to the playbook. For more information, see the Dynamic Values chapter.
  5. (Optional) Other actions that you can perform in the playbook designer are:
    Use the Export button to export the playbook in the JSON format. Use the Delete button to delete the playbook.
    Use the Trigger Playbook With Sample Data button to trigger the playbook from the playbook designer. For more details, see the Playbook Debugging - Triggering and testing playbooks from the Designer section.
    Use the Auto-Align - Vertical and Auto-Align - Horizontal buttons to align the playbook vertically or horizontally.
    Version 7.0.0 introduces the Undo/Redo feature, which is very useful while building a playbook when there is a lot of trial and back and forth to be done. Use the Undo button or use Ctrl+z(Windows)/Cmd+z (Mac) to reverse changes made in a playbook and use the Redo button or use Ctrl+y(Windows)/Cmd+shift+z(Mac) to reverse the steps that you have undone; therefore, you can use the Redo operation only after you have performed the Undo operation in a playbook. The playbook designer displays messages about the effect of the Undo/Redo operation in the bottom-right corner. When you perform bulk operations such as moving, cloning, or deleting a number of steps in one go, clicking Undo reverts the step modification. Similarly, if you have modified a step and saved it, clicking Undo, reverts the step modifications. Note that when editing inputs in the step argument form, the browser’s default change tracking is in effect; therefore, the Undo/Redo operations are applicable only after you save the step. Also, note that if you have made multiple changes in a small time period (around a second), then all these small changes are considered as a single operation.
  6. Once you have completed updating the playbook, click Save Playbook.

Tips for working in the playbook designer

Following are some tips that you can use to make it easier for you to work with playbooks and playbook steps in the playbook designer:

  • You can select a step by the CTRL+Mouse click operation. To select all the steps, press CTRL+A.
  • You can drag and drop multiple selected steps.
  • You can copy multiple selected steps by pressing CTRL+C or copy all the steps by pressing CTRL+A and then pressing CTRL+C. Ensure that you have clicked on your playbook canvas to bring it in focus before you copy the step(s).
    Note: The trigger step will not be copied.
  • You can paste the copied step(s) into a different playbook by using CTRL+V. Ensure that you have clicked on your playbook canvas to bring it in focus before you paste the step(s).
    Note: You can also select Paste from the Edit menu in your browser to paste the copied steps.
  • You can delete a step or multiple steps by selecting steps and pressing the backspace or the delete button.
  • You can use the Auto-Align - Vertical and Auto-Align - Horizontal buttons to align the playbook vertically or horizontally. You can use these buttons to make your playbook look neat and organized, which is especially useful for very large playbooks where playbook readability might be an issue.

Playbook Debugging - Triggering and testing playbooks from the Designer

You can trigger playbooks directly from the playbook designer making it easier for playbook developers to test and debug playbooks while building them. Now, playbook developers do not require to go now to the module, select the record, and then choose playbook and then trigger the playbook and then come back again to the playbook designer to make the changes; all this can now be directly done from the playbook designer.

Caution

Triggering a playbook from the designer starts the execution of the playbook, which can cause changes to your data leading to unwanted changes or loss of data. Therefore, it is important to review the playbook before it is triggered.

To trigger a playbook from the playbook designer, click the Trigger Playbook with Sample Data button. You can choose whether you want to use the Last Run Data as the sample data to trigger the playbook or you want to use Record Input/Custom.

Triggering playbooks from the playbook designer - Last Run Data option

If you have run the playbook earlier, you can choose the Last Run Data option, and then from the Choose a recent playbook execution drop-down list, select the playbook execution with whose environment you want to trigger the playbook and click Trigger Playbook. Once you trigger the playbook with sample data, the Executed Playbook Logs dialog opens and you can view the logs and results of your executed playbook and continue to test and build your playbook.

You can also choose the Record Input/Custom option, and if you have a playbook that has a Manual trigger, then from the Select Record drop-down list choose the record(s) using whose data, i.e., fields and values, you want to use to trigger the playbook. Note that the 30 recently-created records will be fetched.

Triggering playbooks from the playbook designer - Custom Sample Data option

To trigger a playbook, you provide input based on the type of trigger you have defined for the playbook. For example, the Select Record drop-down list will not be present in case of a "Manual Trigger" step that has the Does not require a record input to run option selected since in this case the playbook does not require the data of a record to trigger a playbook. Also, in the case of a "Manual Trigger" step that has the Run separately for each selected records option selected, and in which you have selected multiple records and triggered a playbook from the designer, you will observe that only a single playbook will be triggered on a single record to simulate the output. Similarly, in case of a Referenced trigger, you can provide parameter values and trigger the playbook using those parameters.

The playbook can also use the "Mock Output" defined in the steps while running the playbook if you choose to Enable mock output.

Changing the prioritization of playbook execution

You can change the prioritization of playbook execution based on the importance of that playbook, thereby enabling the higher priority playbooks to be executed first even if there are some normal priority playbooks already queued for execution. Earlier, the playbook execution queue was based on first in first out method, with round robin assignment of workers (processes), which meant that important playbooks might get queued after lower-priority playbooks.

For example, if you have set up data ingestion to run every minute, then possibly you would have many data ingestion playbooks queued up, and then if you also require to run an important playbook with a manual action, it would earlier be run only once the data ingestion task that was scheduled before it was completed. Now, you can change the prioritization of the manual input playbook to "High" enabling it to get executed on priority.

You can set the priority for playbook execution as High, Medium, or Low. The default priority is set as "Medium". Playbook execution prioritization works as follows:

  • If any worker is available for the task execution, it gets assigned a task from the "High" queue first and so on.
  • If all workers are occupied with lower priority tasks and any higher priority task comes up, the high priority task gets executed only when any worker is again available.
  • Low priority tasks do not get executed if there are high priority tasks.

To set a priority for playbook prioritization, open that playbook in the playbook designer. Click Tools > Execution Priority. In the Execution Priority dialog, you can set the playbook execution prioritization to High, Medium, or Low:

Setting the playbook execution priority

To list the number of messages (workflow count) in the 'celery' queue, use the following command:
rabbitmqctl list_queues -p fsr-cluster --no-table-headers --silent | grep -E "^\s*celery\s+" | awk '{print $2}'
When there is no queue, it will display 0 (default), and when the queue builds up, it will display the queue count number such as 10, 25, etc.

Notes:

  • All 'sync' reference playbooks automatically inherit the priority of their parent playbooks, thereby ignoring any preset priority.
  • If you update the execution priority of a scheduled playbook, then you require to edit and resave the schedules associated with that playbook.
  • If you want to schedule a data ingestion playbook, then you must set the priority of the data ingestion playbook before scheduling the same.

FortiSOAR also integrates with a GUI-based celery monitoring tool called Flower, using which you can monitor and administer celery cluster and playbook execution queues. You can start a Flower web server using the following process:

cd /opt/cyops-workflow/sealab

../.env/bin/flower -A sealab --port=5555

Note: Ensure that port that you are specifying in the URL, 5555 in the above sample, is opened in your firewall and can be accessed.

Live User implementation in Playbook Designer

The playbook designer implements Live Users, which means that the playbook designer displays users who are also currently working on the same playbook. Therefore, when you open a playbook and if there are other users who are working on the same playbook apart from you, then the playbook designer will display the users working on the playbook, as well as the number of sessions that are active for each user. Live Users also notifies users that are working on the same playbook, if any other user or session has saved modifications to the playbook, so that the user can refresh the playbook before working on the same, thereby ensuring that users work on the latest version of the playbook. Users can also save versions of their current modified state of the playbook, thereby providing users with the ability to merge their changes.

Live Users - Playbook Designer

Live Users has the following benefits:

  • Users are notified of other users or sessions that are active on the same playbook.
  • Users work on the latest version of the playbook, and they do not lose their updates made to the playbook.

Saving versions of your playbook

You can save versions of a playbook that you are creating or updating. Using versioning, you can save multiple versions of the same playbook. You can also revert your current playbook to a particular version, making working in playbooks more effective.

The maximum number of versions that can be taken, across all users working on a playbook is 20. If you or other users try to take more than 20 snapshots, a confirm dialog is displayed that prompts you to delete a version so that you can free space and save a new version, as shown in the following image:

Confirm dialog for deleting a snapshot

When you click Confirm, the Versions - <Name of Playbook> dialog is displayed. You can now choose the version(s) that you want to delete, click the Delete icon, and then click Confirm on the confirmation dialog and close the Versions - <Name of Playbook> dialog. This frees up space and you can now save a new version.

Versions Dialog

Using the Versions - <Name of Playbook> dialog, you can search for versions based on the notes you have added, and also filter versions by the Created By (user who has created the version), Saved On (time the version was saved) and action performed.

To take a snapshot and revert the playbook to a particular snapshot do the following:

  1. In the playbook in which you are working in the playbook designer, click Save Version.
  2. In the Save Version dialog, add a note that you want to associate with the version and click Save Version.
    It is recommended that you add meaningful notes for versions as these names will help you in identifying the snapshots when you want to revert to a particular version.
  3. To revert a version, click Save Version and then either click Revert to Last Saved or click View Saved Versions. Clicking Revert to Last Saved reverts the playbook to the last saved version of the playbook
    Clicking View Saved Versions displays the Versions - <Name of Playbook> dialog that allows you to choose the version of the playbook to which you want revert:
    Versions dialog
    In the Versions - <Name of Playbook> dialog, in the version row to which you want to revert, click Load.
    Once you click Load, that snapshot is loaded in the playbook designer, with a message: "You are working on a previously taken playbook snapshot...." as shown in the following image:
    Loading of a version in the playbook designer
  4. You can choose to view the playbook that is currently saved, by clicking the View Current Saved Playbook link, or you can click Mark as Current Saved Playbook to make this version the current saved version of the playbook and continue to work on the playbook.

Exporting versions of your playbook

You can choose to export playbook collections or playbooks with saved versions of the playbooks. This is extremely useful while developing playbooks, especially if you erroneously delete a step in the playbook or you want to go back to the previous state of the playbook. Retaining the versions of playbooks while exporting playbooks enables you to load a snapshot of a previously saved version of the playbook into an imported playbook

You can choose to export playbook collections or playbooks with saved versions of the playbooks as shown in the following image:

Exporting a playbook with versions

Clicking Yes, include versions on the above dialog will export playbooks or playbook collections with the saved versions of the playbook.

You can then import the playbook and then open that playbook in the playbook designer, you can see the previously saved versions of the playbook by clicking Save Version > View Saved Versions. This opens the Versions dialog as shown in the following image:

Save Version - View Saved Versions

You can load a snapshot of a previously saved version of playbook in the Versions dialog by selecting the snapshot that you want to load in the playbook designer and clicking Load. This will display a message such as "You are working.....playbook snapshot...." as shown in the following image:

Viewing a previous snapshot of a playbook

You can save this version of the playbook and continue to work on it or you can click View Current Saved Playbook to revert back to the state of the playbook when it was last saved.

Playbook recovery

FortiSOAR autosaves playbooks so that you can recover playbook drafts in cases where you accidentally close your browser or face any issues while working on a playbook. These unsaved (autosaved) drafts do not replace the current saved version of the playbook and only ensure that you do not lose any of your work done in the playbook, by providing you the ability to recover the drafts.

Playbook recovery in FortiSOAR is user-based, which ensures that users see their own unsaved drafts of the playbook. Since it is browser-based, it comes into effect as long as the same browser instance is used by the user. Also, playbook drafts might not be saved if you are working in the "Incognito" mode.

By default, FortiSOAR saves playbook drafts 15 seconds after the last change. However, you can ask your administrator to change this time across all playbooks by modifying the time, in seconds, on the Application Configuration tab in the System Configuration page. The minimum time that your administrator can set for saving playbook drafts is 5 seconds after the last change. You can also choose to disable (and later enable) playbooks recovery for all playbooks. For more information, see the System Configuration chapter in the "Administration Guide."

Note

If the browser data is cleared, then the autosaved drafts will get deleted.

To recover an unsaved draft of the playbook, reopen that playbook in the playbook designer you will be prompted to confirm whether you want to recover the draft of the playbook as shown in the following image:

Confirm recovery of autosaved version of Playbook

Once you click Confirm on the Confirm dialog, the autosaved version of the playbook is loaded in the playbook designer, and you can then choose to save this playbook using Save Playbook and make it the current working copy.

System Playbooks

FortiSOAR includes some system playbook collections that are used to automate tasks, such as the Schedule Management Playbooks collection can be used to schedule various tasks such as cleaning up playbook execution history, purging integration logs, etc. Or, you can use the Report Management Playbooks collection to manage generation of reports. For example, the Generate Report By Scheduler playbook generates reports based on schedules that you have specified. You can also reference system playbook from other playbooks.

The FortiSOAR UI includes links on the System Configuration page to the various playbook collections and templates, which are included by default when you install your FortiSOAR instance. Administrators can click the Settings (Setting icon) icon to open the System Configuration page and click the System Fixtures tab to access the system playbooks or fixtures. The System Fixtures page contains links to the system playbook collections and templates. Administrators can click these links to easily access all the system fixtures to understand their workings and make changes in them if required. For example, to access Schedule Management Playbooks, click the Schedule Management Playbooks link.

System Fixtures tab

Caution

You can modify system playbooks as per your requirements. However, incorrectly modifying any system playbook can affect FortiSOAR functionality.

For example, if you want to modify the default email signature, which is currently Regards, FortiSOAR Admin, for a system playbook, open the playbook and double-click on its Send Email step. In the Send Email step, in the Content field, modify the signature as per your requirements and click Save.

Tooltip

In the system playbook (or any playbook) that is sending an email, ensure that you have used the Server_fqhn global variable in the Send Email step.

When you are using a system playbook that sends an email, for example, when an alert is escalated to an incident, and an Incident Lead is assigned, then the system playbook sends an email to the Incident Lead specified. The email that is sent to the Incident Lead contains the link to the incident using the default hostname, which is the hostname that you had specified or that was present when you installed FortiSOAR. To ensure that the correct hostname is displayed in the email, you must update the appropriate hostname as per your FortiSOAR instance, in the playbook, using the Playbook Designer as follows:

  1. Open the Playbook Designer.
  2. Click Tools > Global Variables to display a list of global variables.
  3. In the Global Variables pane, search for the Server_fqhn global variable, then click the Edit icon in the Server_fqhn global variable, and in the Field Value field add the appropriate hostname value.
    Editing global variables in the Send Email steps
    You can optionally specify a default hostname value in the Default Value field.
  4. Click Submit.
    This adds the updated hostname for your incident and then when a system playbook sends an email the link contains the correct hostname.
Note Playbooks that contain a reference to the approvalHost global variable fail with the 'approvalHost variable undefined' error, since the approvalHost global variable is removed from release 7.2.0 onwards. To resolve this error, replace the approvalHost global variable in the playbook with the Server_fqhn global variable.

For information about all the system playbook collections and templates, which are included by default when you install your FortiSOAR instance, see the System Configuration topic in the "Administration Guide."