Dynamic Values

Overview

Use Dynamic Values to generate Jinja dynamically within the Playbook Designer. To make your playbook dynamic use Jinja templates to define various conditions within steps in a playbook. However, you must have some knowledge of Jinja (see Jinja Documentation) and must understand the workflow of the playbook steps in the JSON format to create Jinja templates.

Using the Jinja editor, you can apply a Jinja template to a JSON input and then render the output, thereby checking the validity of the Jinja and the output before you add the Jinja to the Playbook.

Using Dynamic Values, you can dynamically add Jinja to steps within a Playbook. Click a step, within the playbook that takes Jinja as an input and Dynamic Values is displayed. Choose from the options presented to add Jinja to the step.

FortiSOAR simplifies the process of building playbooks without requiring to have Jinja or Python knowledge. Use the "Expressions" tab on Dynamic Values to build playbooks with medium-level complexity without any programming knowledge, with the option to use Jinja or Code Snippets to build playbooks that are very complex. For more information, see Expressions Usage.

Jinja Editor

Use the Jinja editor to apply a Jinja template to a JSON input and then render the output. You can thereby check the validity of the Jinja and the output before you add the Jinja to the Playbook.

To open the Jinja Editor, in the Playbook Designer, click Tools > Jinja Editor.

The Jinja Editor has three areas: Template, JSON, and Output.

• Jinja Template: Use the Jinja Template area to specify the Jinja in curly brackets.
• JSON: Use the JSON area to specify the JSON input. JSON is always in the format of "Key":"Value" pair. If there are syntax errors in the JSON you have written, the Jinja editor displays a "Bad String" prompt. You can also specify nested key-value pairs.
  Once you have entered the Jinja and JSON, click Render to display the output.
• Output: The Output area displays the output that would be generated by the combination of the entered Jinja and the JSON.
  
  When an object is returned as the result, then the Jinja Editor will display the output as an object instead of a text area.

If the playbook has at any time been run in the 'DEBUG' mode (see the Setting the logging levels for playbooks topic in the Introduction to Playbooks chapter for information on changing the modes), then you also see a Choose A Recent Playbook Execution drop-down list, which lists the latest 30 executions for that playbook. You can also choose a playbook execution from that drop-down list and click Load Env JSON to view the environment JSON for that execution of the selected playbook. This helps in debugging playbooks:

You can also filter the list of executions by module, status, and record ID (if the playbook has been triggered on a particular record). Use the Trigger Module drop-down list and the Status drop-down list to filter the playbook executions by module and status, respectively. From release 7.3.0 onwards, you can filter the playbook executions for a particular record by entering the ID of the record in the Record ID field, allowing you to retrieve playbook logs based on that particular record. Click Apply to apply the filters, and click Clear to remove the filters:

Notes for filtering playbook executions:

• The Jinja Editor displays the latest 30 filtered playbook executions only.
• If the playbook trigger step has set its Execution Behavior to Does not require a record input to run, then such a playbook execution cannot be searched by using a record ID, and therefore the Record ID field is not available. For more information on playbook triggers, see the Triggers & Steps chapter.
• If the playbook trigger is set to 'Referenced' or 'Custom API Endpoint', then such playbook executions can be filtered by their 'Status' only.

Dynamic Values Usage

Dynamic Values is used within the Playbook Designer. Use the Dynamic Values directly within steps of your playbook to dynamically add Jinja to those steps. Click a step within the playbook that takes Jinja as an input and Dynamic Values is displayed. Choose from the options presented to add Jinja to the step.

Dynamic Values is visible for input fields such as text fields, rich text, date/time fields, picklists, checkboxes, etc. You can use the Dynamic Values button to toggle fields, such as drop-down lists and checkboxes, and add custom jinja expressions for fields such as picklists, Lookups, File selectors, rich text, text fields, etc. Clicking the Dynamic Values button also displays the Dynamic Values dialog, using which also you can add expressions to these fields. The ability to add Jinja expressions to these fields enables you to customize your playbooks further.

In version 7.0.0, FortiSOAR has updated the arrow library due to which the timestamp attribute has been changed into int_timestamp for DateTime jinja expressions. Therefore, new playbooks must use the int_timestamp for any DateTime jinja expressions. For more information, see the Dynamic Variables chapter.

You can also use Dynamic Values within a Text field type that has a subtype of either Rich Text (Markdown), which is the default, or Rich Text (HTML). Earlier, the Dynamic Values dialog would not be displayed for a Rich Text type field. To display Dynamic Values within a Rich Text type field, click the Dynamic Values () icon in the formatting toolbar as shown in the following image:

Dynamic Values provides you with the following Jinja options within a step:

• Input
• Step Results
• Variables
• Global Variables
• IRI Lookup

Before you delete or modify any global variable or variable(s) ensure that you have removed or updated the variable in the Playbook to ensure that the change does not affect the functionality of the playbook.

Use the “Expressions” tab on Dynamic Values to build playbooks based on your requirements and without programming knowledge. For more information, see Expressions Usage.

Input

Use the Input option to add various types of data, variables, and parameters that you can use in your current step.

The Input option provides you various type of parameters that you can use in your current step:

• Parameters that you have defined using Tools > Edit Parameters in the playbook designer appears when you click Input > Parameters.
• Trigger step data has been added as part of the Inputs so that you can use the variables and data from the module on which trigger has been added. Data of the trigger step appears when you click Input > Records.
• Data of the trigger step, in case of Custom API Endpoint Trigger, appears when you click Input > Parameters > api_body.
• Variables that you have defined in the Manual Trigger step appears when you click Input > Variables.

While importing playbooks that were created using an older version of FortiSOAR, before you use the "Input" option in any step, ensure that you open and save the trigger step and then save the playbook.

Step Results

The Step Results option enables you to use the output of the steps that have been executed, in the current step. Dynamic Values also displays the output of the current step in Variables and Message options in playbook steps, so that you can add or store the output of the current step directly in the step itself. For more information about playbook steps, see the Triggers & Steps chapter.

Dynamic Values displays the output of Step Results for the current step in the format vars.result.keyname. Dynamic Values displays the output of Step Results for the previous or already executed steps in the format vars.steps.stepname.keyname.

To use the output of the steps that have been executed, click the step in which you want to the use the executed steps' output, which then displays Dynamic Values. Select the Step Results option. Dynamic Values displays the output schema, with all its attributes, of the output of all the steps that have been executed. You can then use the output schema and attributes of any of the executed steps as an input to the current step based on the logic or functionality of the current step.

You can also use an array element in an executed steps' output:

If you select an array element for the executed steps' output, then you must specify the position of the element (index [i]) in the Jinja that is generated. The index value of an array starts from zero [0]. For example, if you want to fetch the name property from the Find_all_Open_Alerts [] array from the executed steps' output, then the Jinja that is generated is as follows: {{vars.steps.Find_all_Open_Alerts[0].name}}.

Therefore, before you run the playbook and require to fetch any element other than the first element in the array, you must provide the position of the element. For example, if you want to fetch the name property of the 4th element of the Find_all_Open_Alerts [] array then your Jinja must be written as {{vars.steps.Find_all_Open_Alerts[3].name}}.

If there is no step output available or if you are at the first step in the Playbook or if the step is not connected to another step, then the Jinja generator displays the following message: Either there is no previous step or the previous step output is not known. If there is no previous step then connect another step to the current step to view the previous step output.

Variables

Variables are variables that can be used only in the playbook in which it is defined. Therefore, the scope of a variable is local. To create a Variable, in the Playbook Designer, click the Set Variable step and add the Name and Value for the Variable and then click Save.

You can define multiple set variables in a playbook and then in this case you will see multiple Variables in the steps.

You use the Variable like you would use a Global Variables, except that variables can be used only in the remaining steps of the playbook in which they have been defined or in any child playbook, regardless of how many levels deep the child playbooks are called.

If there are no variables defined, the Jinja generator displays the following message: There are no Variables declared in this playbook or the current step is not connected to any step. You can create Variables by adding 'Set Variable' step.

Global Variables

Global variables (called macros in earlier version), are variables that can be used across playbooks. You can declare a global variable once and then use it across all playbooks, instead of having to redefine the variable every time in each playbook. You can create global variables only in the Playbook Designer. FortiSOAR includes some pre-defined global variables.

To create a global variable, in the Playbook Designer, click Tools > Global Variable. Click New Global Variable and enter appropriate content in the Variable Name and Field Value fields for the variable and click Submit to create a global variable. You can optionally also add the default value for the variable in the Default Value field.

Variable Names must always begin with a character when you are creating global variables and the name can contain only alphabets and numerals. Special characters and spaces are not allowed.

To ensure that the correct hostname is displayed in links contained in emails sent by System Playbooks, you must update the Server_fqhn global variable in Global Variables. Click the Edit icon in the Server_fqhn global variable, and in the Field Value field add the appropriate hostname value, and then click Submit. If you have not specified the hostname in global variables, then the hostname that you had specified or that was present when you installed FortiSOAR will be the default hostname and this will be added in the email. In this case, ensure that you have used the Server_fqhn global variable in the Send Email step in the playbook that is sending the email.

Example of using a global variable: In the Set Variable step, you need to set a name and value. When you click the Value field, Dynamic Values is displayed. Click Global Variables in Dynamic Values, and you will see a list of global variables that have been created. Click the global variable that you require, for example current date. This adds the Jinja value of the global variable in the Value field:

IRI Lookup

All foreign key references use International Resource Identifiers (IRIs) to reference records within the system. IRIs are generated automatically when FortiSOAR inserts records. FortiSOAR uses IRI values in multiple places for referencing picklists, playbooks, attachments, etc. Use the IRI Lookup option to efficiently use the IRI values of picklists, attachments, or playbooks configured in your system.

To use the IRI lookup, click the step in which you want to insert an IRI value, which then displays Dynamic Values. Select the IRI Lookup option and from the Choose Entity Type drop-down menu, choose the entity, either a Picklist, Attachment, or Playbook. For example, if you choose Picklist, then from the Provide Entity To Lookup IRI for drop-down menu, select the Picklist whose IRI value you want to add to the step. In our example, we want to add the IRI value for the picklist that retrieves the types of alerts. Therefore, from the Provide Entity To Lookup IRI for drop-down menu, select AlertType, and then in the Click to Add IRI Value section, select the alert type that you want to add, for example, Phishing, as shown in the following image:

Once you click Phishing, the IRI value (jinja) of 'Phishing' alert type is added to the playbook in the Jinja format, which is {{("picklistName"|picklist("itemvalue of picklist"))["@id"]}}.

Expressions Usage

Use the "Expressions" tab in Dynamic Values to build playbooks based on your requirements and without programming knowledge, and add various operations and expressions to playbooks. The Expressions tab contains easy-to-understand operations that cover most aspects of playbook development. The operations are grouped logically as per their functionality, for example, if you want to convert datetime into a specific format or to a different time zone then these operations will be listed in the Date Time Operations list. Similarly, if you want to replace text in a string with a regex, then these operations will be listed in the Regex Operations list. You can search for operations using the search textbox in the Expressions tab. Each operation has an information icon that you can hover over to view more information about that particular operation.

An example of using an expression would be requiring to extract artifacts from the source data of an alert that has been created in FortiSOAR from a SIEM and update that record with the extracted artifacts. You can use Utility Operation > Extract artifacts from a string operation to extract artifacts from the source data.

To use the Extract artifacts from a string operation, in the "Update Record" step, click the Indicators field, which displays Dynamic Values. Click the Expressions tab and then click the Utility Operations list:

Click the Extract artifacts from a string operation, which in turn displays a Inputs text box. From the Choose Field list, you can select Source Data of the alert by clicking Input > Records > modules > Alerts and clicking the Source Data field:

This adds the corresponding Jinja value in the Input string field:

Click Save to add the corresponding Jinja expressions in the Indicators field:

Click Save to save the Update Record step and then save the playbook. Now, when you run this playbook for an alert that contains source data, this step will extract artifacts from the source data and update the indicators associated with the alert record with the extracted artifacts.

Whenever FortiSOAR is upgraded, the files located in the /opt/cyops-workflow/sealab/expression_builder/expressions folder will be overridden based on enhancements or additions made to the expressions. Therefore, you should make changes to the expressions in the so it is advised to the user that they should make the changes to expression in the files located in the /opt/cyops-workflow/sealab/expression_builder/custom folder.

Adding your own expressions

You can also create your own expressions and add it to the "Expressions" tab in Dynamic Values. You can either use existing Jinja2 filters (https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html) or create your own new function and add it to the "Expressions" tab in Dynamic Values.

Adding existing Jinja2 filters to the "Expressions" tab

You can add existing Jinja2 filters that are currently not part of "Expressions" tab. An example of this can be the {{ path | win_splitdrive }} filter, which separates the Windows drive letter from the rest of a file path. To add this filter to the "Expressions" tab, do the following:

1. SSH to your FortiSOAR VM and login as a root user.
2. Navigate to the /opt/cyops-workflow/sealab/expression_builder/custom folder.
3. Edit the my_expressions.json file and add the {{ path | win_splitdrive }} filter as follows:

   {
     "name": "my_expressions",
     "title": "My Expressions",
     "description": "",
     "operations": [
       {
         "name": "Seperate Windows Drive Letter",
         "jexp": "{{params.path}} | win_splitdrive",
         "description": "",
         "params": [
           {
             "name": "path",
             "title": "File Path",
             "type": "text",
             "value": "",
             "editable": true,
             "required": true
           }
         ]
       }
     ]
   }
   

4. Save the my_expressions.json file.
   Note: The jexp parameter displays the final expression that will be added to the field in the playbook.
5. Restart the uwsgi and celeryd services using the following commands:
   # systemctl restart uwsgi
# systemctl restart celeryd

Once you have restarted the uwsgi and celeryd services, logon to FortiSOAR and open a playbook to view the "Expressions" tab in Dynamic Values. You will see "My Expressions" added at the end of the "Expressions" list:

Click Separate Windows Drive Letter to display the inputs to be gathered from the user and enter the file path from which you want to separate the windows drive letter:

Click Save to display the final expression that will be added to the field in the playbook:

Creating a new function and then adding it to the "Expressions" tab

You can also create a new function and either use it as a filter or add it to the "Expressions" tab in Dynamic Values.

To add a new function that displays a sum of two numbers, do the following:

1. SSH to your FortiSOAR VM and login as a root user.
2. Navigate to the /opt/cyops-workflow/sealab/expression_builder/custom folder.
3. Edit the custom_functions.py file as follows:

   vi custom_functions.py
   
   def sum(a,b):
       return (a+b)
   
   func_map = {
      'sum': sum
   }
   

4. Save the custom_functions.py file.
5. Restart the uwsgi and celeryd services using the following commands:
   # systemctl restart uwsgi
# systemctl restart celeryd
6. Now, you can use the sum filter as required or you can add it to the "Expressions" tab in Dynamic Values, using the method described in the earlier section.