Skip to main content

Cyware Orchestrate

  • Cyware Orchestrate
  • How To Articles
  • My First Playbook - A Step-by-Step Tutorial

My First Playbook - A Step-by-Step Tutorial

The goal of this tutorial is to guide beginners through the exciting journey of using Orchestrate playbooks. The instructions and examples provided here will allow you to have a hands-on learning experience of building playbooks, starting from the absolute basics.

Follow the steps below to get started with building playbooks.

Hello World Playbook

This topic includes step-by-step instructions to build a basic Hello World playbook and run the playbook to view the response. By the end of this activity, you will:

  • Have an understanding of how to create a basic playbook

  • Have an understanding of how to run and view the playbook output

Before you Start

Make sure you have the necessary permissions to view, create/update, and run playbooks.

Steps

To create the Hello World playbook, do the following:

  1. Go to Main Menu > Manage Playbooks and click New Playbook (plus icon) in the top-right corner.

  2. Name your playbook. For example, Hello World Playbook. You can then start building your workflow on the playbook canvas.

  3. Drag and drop a custom node as shown in the below graphic.

    Drag_Drop_Custom_Node.gif

  4. Modify the custom code to display Hello World text. Below is an example.

    def script_function():
    # Write your custom code here
    return 'Hello World'

  5. Scroll down the custom node window and click Describe this Node to provide a name for the custom node. For example, Display Hello World.

  6. Click Save drop down and select Save & Run to run the playbook. The playbook editor will inform you that the start node and your first node are disconnected. Now, connect your start node and first node as shown in the below graphic.

    Connect_start_and_custom.gif

  7. The playbook requests input data. Proceed to click Run Playbook from the bottom as no input is required for the playbook to run.

  8. Click Refresh in the top-right corner to view the live playbook run logs.

  9. After the playbook finishes executing, you can check the playbook output by clicking on the Display Hello World custom node. The graphic below shows the steps to run the playbook and view results.

    run_a_playbook.gif

Install Apps and Configure App Instances

Now that you are familiar with creating basic playbooks you can start building your first SOAR playbook. To be able to build your first SOAR playbook, you must know how to install apps from the Appstore and configure instances for the apps to communicate to their endpoints. This topic includes step-by-step instructions to install apps from the Appstore and configure app instances for the app installed apps. By the end of this activity, you will:

  • Have an understanding of app instances

  • Have an understanding of how to configure app instances to apps

What is an app instance?

Apps use instances to communicate with app endpoints. These instances include the base URL of the app endpoints and authentication credentials. An app can have multiple instances and users can choose an instance from the configured list to execute playbook actions.

Before you Start

  • Make sure you have the necessary permissions to view and create/update app instances.

  • Create an account in AbuseIPDB by signing up from https://www.abuseipdb.com/

Steps to Generate AbuseIPDB API Credentials

To generate API credentials from AbuseIPDB, do the following.

  1. Go to https://www.abuseipdb.com/ and log in using your account.

  2. Select the API tab and click Create Key.

  3. Give a name for the API. For example, Orchestrate Integration.

  4. Click Create. The window will show the API key for the account. We will use this key to create an AbuseIPDB app instance in Orchestrate.

    Note

    Copy and save the key in a safe location as you may not be able to retrieve this key after closing this window.

Steps to create app instance

In this example, we will generate an instance for the AbuseIPDB app.

  1. Go to Main Menu > Apps and click Appstore.

  2. Search for AbuseIPDB and click Install. Select a required version of the app and click Install.

  3. Once the app is installed, you can access the app from the My Apps section.

  4. Click the AbuseIPDB app card to view all the app-related details.

  5. Select the Instances tab.

  6. Click the plus icon to create a new instance of the app.

  7. Configure the following details for the instance:

    • Instance Name: Enter a name. For example, IP Enrichment - Abuse IPDB.

    • Instance Expiration: Click the calendar icon and select an expiration time for the instance. After this time, the instance expires. admins will receive an email notification for all instances that are nearing expiry.

    • Make as default instance: Toggle on this option to make this instance your default instance.

      Note

      On successful creation of the first instance for an app, the instance is automatically considered as Default Instance.

    • Agent Compatible: This field is available only if the app is marked as Agent Compatible. If an app is configured as agent compatible, then while adding an instance for that app, you have the option to mark that instance as agent compatible. Simply toggle the Agent Compatible option. On enabling, you can select the agents available on that server from the dropdown list.

    • API Token: Paste the API key you generated from the AbuseIPDB website in the previous section.

    • App version: Select the version of the app to run this instance.

  8. Click Create.

My First SOAR Playbook

Let’s get you started by creating a simple playbook that performs enrichment of a specified IP address and emails the report to you. The outline of the playbook design is described below:

my_first_soar_playbook.svg
Prerequisites

  1. Ensure you have permission to View Playbook, Create/Update Playbook, and Run Playbooks.

  2. Create an instance for the AbuseIPBD connector. If you already have a working instance for the AbuseIPDB app, you can skip this step. To create an app instance, see Add Instances.

  3. Create an instance for the Cyware Email Services connector. If you already have a working instance for the Cyware Email Services connector, you can skip this step. To create an app instance, see Add Instances.

Playbook Basic Details

  1. Go to Main Menu > Manage Playbooks and click New Playbook (plus icon) in the top-right corner.

  2. Name your playbook. You can then start building your workflow on the playbook canvas.

  3. Click Save.

Note

You have successfully created a draft playbook with basic details. At this point, you cannot execute the playbook as the playbook does not have any actions configured. Let's go ahead and build the playbook workflow.

Step 1: Configure your first Node

  1. From the node list on the left panel, drag and drop an input node as shown in the below screenshot. This input node will take an IP address as input from users.

    Drag_and_Drop_Input_Node.gif

  2. Change the field title to IP Address.

  3. Change the field identifier to ip_address.

  4. Change the field type to Text.

  5. Select Mandatory Parameter as the playbook will execute based on the IP address value provided by the user.

  6. Now click Save and the playbook editor will show a warning message. The playbook editor will inform you that the start node and your first node are disconnected. Now, connect your start node and first node as shown in the screenshot below.

    Connect_Input_Node.gif

Note

You have successfully created a playbook workflow by creating your first node.

Step 2: Configure an Action Node

  1. Drag and drop an action node as shown in the below screenshot. Select Search by apps and search for AbuseIPDB and select Get IP Address Reputation Details action.

    Drag_and_Drop_App_Node.gif

  2. The app action selects the default instance of AbuseIPDB to execute this action. You can change the instance if required. To know more about App Instances, see Work with App Instances.

  3. Click Setup Input Data. To proceed with this action, you need to retrieve the IP address from the input node that you have set as the first node. To do this, you can utilize dynamic path expressions to access and use data from a previous node. Enter the following values in the respective fields.

    Field

    Value

    Description

    IP Address

    ${_1::io::ip_address}

    The provided dynamic path expression retrieves the ip_address value from node number 1.

  4. Click Save. Remember to connect the action node from the previous node as shown below.

    Connect_App_Node_with_Input_Node.gif

Note

You have successfully configured your first action node.

Step 3: Email the Report

  1. Drag and drop an action node as shown in the below screenshot. Select Search by apps and search for Cyware Email Service and select Send Email action.

    Email_App_Node_Create.gif

  2. The app action selects the default instance of Cyware Email Service to execute this action. You can change the instance if required. To know more about App Instances, see Work with App Instances.

  3. Click Setup Input Data and fill in the required fields described below.

    Field

    Value

    Description

    Sender Email ID

    johndoe@orgname.com

    Denotes the sender's email address for the email report.

    Sender Name

    John Doe

    Denotes the sender’s name for the email report.

    Subject

    IP Enrichment Report

    Denotes the email subject.

    Body

    Hi, <br> After enriching the given IP address on AbuseIPDB the following JSON analysis was retrieved. <br> JSON - <br> ${_2::result::__instance__::data}

    Note: Replace __instanace__ with the instance name used for the AbuseIPDB action. For example, ${_2::result::default::data}

    Denotes the Email Subject

    Recipient ID

    $LIST[jack.doe@orgname.com, rick.doe@orgname.com]

    Denotes the list of recipients. You can add multiple values as a comma-separated list.

    Note: Remember to configure your email as a recipient to test the playbook.

  4. Remember to connect the action node from the previous node as shown below.

    Email_Node_connection.gif

  5. Click Save.

Note

You have successfully configured your first playbook. You can run your playbook to retrieve the report of a suspicious IP address and send the report as an email to the required recipients.

Test your First Playbook

  1. From the playbook editor, click on Save drop down and select Save & Exit. Now the playbook will switch to view mode.

  2. Click Run Playbook from the top-right corner. The playbook requests for input data. Proceed to click Run Playbook from the bottom as you will be providing the IP address input after the playbook starts running.

  3. Click Refresh in the top-right corner to view the live playbook run logs. Here you can provide the IP address as input for enrichment.

  4. After the playbook finishes executing, you can check the results from your email inbox.