Playbook Module

Module of a Playbook

A module is a pre-built automation function that you can add to your playbook. Modules can perform actions such as formatting output, parsing a string, checking IP addresses, or downloading emails. For example, a module could check IP addresses against an abuse IP database.

A module is defined within a step. Each step consists of a single pre-built automation (module or integration). A module can have child steps, but the actions in a child step are configurable only if the parent module has a defined automation.

Add a Module to a Playbook

To add a module:

1. Create or edit your playbook in Advanced Mode.
2. Start the module setup in either of the following ways:
   • If you are adding a module to an existing step, click Add Automation within the step.
   • If you are creating a module directly, click + for the parent step on the map and select Add Module.
3. Locate the module you would like to add in any of the following ways:

• Scroll through the list.
• Start entering the name in the search area to see matching modules.
• Expand the module list in the left menu and select a module type to filter the list by that type.

4. Click + to select and set up the module.

5. Specify the fields for the module. The particular fields depend on the type of module.
6. Click Insert to save and add the module to your playbook.

Edit a Module

1. Click the header of the step on the map to display the details.
2. Click Edit.
3. Modify any of the settings.
4. Click Save.

Add Integration in a Module

Playbooks allow you to add an integration while adding or editing a module.

1. Click + on any node to add a module. See Add a Module to a Playbook.
2. Click + on the module > Module Definition > Edit.

The editing page opens up.

3. Click + on the node and choose Add Integration.

Delete an Automation in a Module

You cannot edit an existing module, but you can delete a module without deleting the step.

1. Click the automation name in the step.
2. Click OK to confirm the deletion.

Delete a Module

1. Click the header of the step on the map to display the details.
2. Click Edit.
3. Click Remove Automation and click OK to confirm.

Deconstruct a Module

Deconstructing a module removes the module wrapper and leaves all the steps in place. Use the deconstruct action in the following cases:

• if you no longer want to group steps in a particular module.
• If you want to change the steps in a module. In this case, you must deconstruct the module and then create a new one.

To deconstruct a module, click it to display the settings, and then select Actions > Deconstruct. The module is deconstructed and all the steps to the bottom right of the module automatically shift to make space for the deconstructed steps.

Create a New Module for Automation

A module is a pre-built automation function that you can add to your playbook to perform a specific action such as formatting output, parsing a string, checking IP addresses, or downloading emails.

The currently available modules are accessible from the module library by selecting Automations > Modules from the top menu bar. To select a module from the library and add it to a playbook, follow the instructions in Add a module to a playbook.

This topic describes how you can create your own modules and add them to the module library.

Creating a new module consists of the following actions:

1. Start with a playbook that includes the logic that you want to incorporate into the module. You can start with an existing playbook or a new playbook that you have created for this purpose.
2. Identify the steps to include in the module.
3. Provide a name, description, and other basic information to identify the module.
4. Generalize the logic in the module by parameterizing any values that users might want to vary. For example, you might have an existing playbook that computes a weighted average of 50 items. In the module definition, you would parameterize ‘50’ so the module can be used to compute a weighted average of any number of items.
5. Save the module and add it to the module library.

An Example Playbook

To show how to go from a playbook to a module, we’ll use an example playbook that does phishing analysis. The playbook you start with might be completely different. This example is intended to provide guidance on working with your own playbook.

The example process begins with a pre-defined playbook that does a specific check for URLs that could cause problems if someone clicked on them in an email. The playbook extracts the domain names from the URLs and compares it with a known domain name.

The playbook includes steps a-e.

The first step uses a query to generate data for the example. The data that is generated from the query includes two fake URLs and one real URL.

The next step uses regex to extract the part of the URL that is the hostname.

The next step extracts the domain from the hostname.

The next step uses a Levenshtein function to calculate the ‘distance’ between the known (correct) domain and the domain in the results table.

• If there is no difference between the domains, then there is no problem.
• If the difference is significant, it is also not a problem for this check because the user would have observed that the domain names are very different.
• The problem occurs when there is a difference that is small and possibly subtle. The entries of most interest in the results table are the first two, which are close to amazon.com, but not an exact match with the expected domain.

The last step uses the distance to compute an lhub_score.

This example source playbook shows all the individual steps that result in the calculation of the lhub_score for the phishing emails.

Most users will be interested only in the calculation, not in all the steps that contributed to it. They will also want a generalized version that can take other URLs as inputs and use different values to relate the Levenshtein distances to the lhub_scores.

The module creation process gives you control over what you include in the module and what you choose to parameterize.
The remainder of this topic provides detailed steps on creating a module from a playbook, with references to the phishing analysis example. You can apply these steps to other playbooks.

Create a Module

1. In Advanced Mode, create your playbook or open a playbook from the Playbooks list.
2. Verify that a date range is selected. The date range is needed to validate that the module works correctly.
3. In the top icon bar, click Module.

Use your cursor to select all the steps you want to add to the module. For the phishing analysis example, selecting steps b - e will take the original input and report the results of the lhub_score calculation.

The module editor opens. The first step (with the blue header) is a synthetic input step that represents the data flowing into the module from the playbook that it is part of. This step is not editable.

5. Configure the following on the Settings tab to identify the module:
   Enter a unique ID for the module.
   Enter a descriptive name.
   (optional) Enter a text description.
   Enter a comma-separated list of categories. These are used to filter the modules shown in the Module library.
   Include the person to be listed as the author of the module.
   Select Published to Shared Module Library to make the module available to you and other users in the module library. We recommend that you do this for all modules.

6. Click the Parameters tab to specify the values you want to parameterize. You may want to select different steps in the playbook to view the associated queries and identify elements to parameterize. When you have identified an element to parameterize, configure the following on the Parameters tab and click Apply.
   In the Flow Value field, enter the value that you want to parameterize.
   In the ID field, enter the variable name that you want to use to substitute for the playbook value.
   Enter a descriptive name to identify the step.
   Enter a data type. The type can be text, number, step or column. If the data type is Column, you must also select the table that the column comes from.
   For input data types you can then specify the input type, which can be text or a password.
   Alternatively for column data type, choose the parent step parameter that should be referenced to populate column names when using the module in a playbook.

In the phishing analysis example, one of the steps in the input playbook includes bankofamerica.com as a playbook value. To generalize this to allow module users to specify another domain, a parameter was defined as follows:
Flow value = amazon.com
Id = reference_domain. (This setting allows you to generalize the domain by substituting %%%reference_domain%%% for amazon.com in any query in the module.)
Name = Reference Domain Name (enter a name to identify the parameter)
Description = (optional)
Data Type = Text (in this case the playbook value is a text value)
Input Type = Text (input type is either text or password)

You can now copy the parameter string from the parameter definition and paste it into the query for the relevant step.

After creating the parameter, add it to the relevant LQL in the module. Copy the string for the parameter name and paste in into the LQL to replace an string in the query.

The query is now parameterized for reuse. To verify, click Update Table.

In this example, a parameter with ID ‘url_column_name’ query becomes ‘%%%url_column_name%%%’.

To simplify use of the parameter in the subsequent steps, you can normalize the parameter (to ‘url’ in this example).

Add additional parameters for any other playbook values that you want to generalize.

The final step in the module can also be parameterized. In the example, the edit distance for scoring is set manually. This can be parameterized as shown here.

7. When you are finished setting up the module, click Save on the Settings tab. This action saves the module, closes the editor, and shows the module as a single step in the original playbook.

Use a Module

After you create a module and add it to the module library, it is now available for use.

1. Select Automations > Modules from the top menu bar.
2. Find the module you want to use and click +.

3. The setup page lets you add a title, name, and description for the module step and node, and it displays the event type.

4. The module parameters are also listed, so you can add the values you want to use for this instance of the module.

5. Click Insert to add the module to your playbook.

Edit Module Definition

To edit the module definition after adding a module to a playbook, click + for the module and select Module Definition > Edit.

Edit Module Parameter Values

To change any parameter values for a module, click the module in the playbook designer, and then click Edit.

Change any of the values and click Save.

📘

Module Versioning

Modules are versioned by the system. Right now we don't expose any control into custom module versions. Yet behind the scene, when you edit a custom module, the version of the module is incremented. In most cases, the minor version of the module is incremented. And the latest version will be used in all playbooks that use the module. However, if the change is not a backward compatible change, the major version will be incremented. Backward incompatible edits includes: (1) adding parameters; (2) changing the types of existing parameters.

Existing uses of that module will continue to use the older major version they were created with but will use the latest minor version that is available. This means that if you are using the same module in a few playbooks, and update one with a new parameter, the other playbooks will continue to use the older version. To upgrade to the latest version, edit the module in the playbook. This will present you with the new parameters. Once you provide all the new parameters, you upgrade the playbook to use the latest version of the module.

We have plans to make versioning clearer to the playbook authors in the UI.

Modules and Integrations

Integrations can be used in modules like other steps. Right now they can't be added in the module editing view, they have to be part of the initial steps selected.

A user adding a module with an integration will still need to select the connection for the integration but they will not be asked to enter in any of the other parameters for the integration action. Instead the values originally entered in the integration are used.

If you want to expose some of these parameters to a module user you can create them as module parameters, then use the parameter string in the integration configuration. This can be done with strings or columns.

Update or Replace a Module

Playbooks provide the ability to update or replace a module in multiple playbooks. Following are the options provided:

• Module (Replace With)
• Update (Module Definition)
• Update to this in other playbooks (Module Definition)
• Replace with this in other playbooks (Module Definition)

Module

Playbooks allow you to replace a module with another module in multiple playbooks by remapping the parameters if all parameters are the same.

To replace a module:

1. Go to My Library > Playbooks.
2. Open a playbook in Advanced Mode.
3. To the existing module in the playbook, click + on the Module node > Replace With > Module.

The Automation Library opens up.

Search or browse for the module to be replaced. Click + on the module to enter the module parameters.

Click Replace. A Successfully replaced module message appears on the top-right corner.

Update

Playbooks allow module update to the latest available version. In the module node, you can either click on the arrow indicating to update to the latest version or click on the + > Module Definition > Update.

The Module Parameters form opens up to update the version. Enter the details for the new version and click Save.

A Module Updated Successfully message appears on the top-right corner.

Update to this in Other Playbooks

This option allows you to update the module in other playbooks. This option is useful when the user has multiple playbooks and has the same module in all the playbooks, the user can update the module to a higher version at once by selecting this option.

1. Click + on the module > Module Definition > Update to this other playbooks.

A confirmation window opens up to upgrade the module in other playbooks.

Select the required instances or select all instances and click Update.

Replace with this in Other Playbooks

This option allows you to replace the module in other playbooks. This option is useful if the user wants to replace the current module in all other playbooks.

Click + on the module > Module Definition > Replace with this in other playbooks.

A pop-up window opens up to choose the module to be replaced.

Select the module from the drop-down list and click Next.
The drop-down displays a list of modules that are on the Automations > Modules page.

A confirmation window opens up to replace the selected module and its associated instances with the current module.

Select the required instances or select all instances and click Replace.

After you click Replace, a successful message appears that the modules are replaced.