Add New Playbook

1. Click on the [Playbook] main tab.

2. Click on the button.

3. In the [Add New Playbook] popup window, enter the “Name” of the Playbook, and a corresponding “Description”.

4. Click [OK].

Create Playbook

To create a Playbook:

1. Click on the [Playbook] main tab.

2. Doubleclick your new Playbook.

The [Node] panel will appear on the right side of the screen.

3. Click and hold a Node from the [Node] panel on the right side of the window, and drag it to the Playbook Field.

Nodes

Nodes are individual components that perform specific tasks, such as device communication, data processing, or conditional logic. They can be visually connected to create complex operational sequences called Playbooks.

Once a Node is in the Playbook Field, click the button in the top right corner of the node to change the descriptive Alias of the Node.

Node List

The [Node] panel is on the right side of the screen. These are the different components that can be composed together to create a Playbook.

Node Types by Position

Nodes are classified into “Start”, “Middle”, and “Terminal” based on their input/output terminals:

Start Nodes (Initiate processes)

• Device Search: Selects devices from inventory
• Compliance Remediation: Triggers on policy violations
• Incident: Starts with alert policy triggers
• Schedule: Time-based activation

Middle Nodes (Process data/decisions)

• And: Requires multiple input conditions
• Execute Script: Run a Python script configured here on your Script Executor Container and output the results
• Execute Existing Script: Run a Python script already saved on your Script Executor Container and output the results
• Regex Match: Filters text outputs and can set variables from Java 8 regex style capture groups
• Run Code: Executes a series of commands on your device
• Run Code With Automatic Retry: Run a series of commands on your device a number of times or until it is successful
• Ruleset: Run a ruleset against the output of a node
• Merge by Device: Combines inputs based on the device each is associated to
• Sleep: Adds timed delays (1ms-2h)
• SSH Exec: Runs CLI commands
• Load Configuration: Load a previously backed up configuration file, often for use in verification nodes later in the Playbook
• Backup Device: Run a device backup
• Set Variables: Set or update variables on inputs for use as replacements later in the Playbook
• To CSV: Serialize inputs to text formatted as comma separated values
• To Json: Serialize data to text formatted as JSON
• Update Fields: Update a Device’s custom fields, variables can be placed into fields by writing the variable name wrapped in {curly brackets}
• Upload File: Send a file to your devices

Terminal Nodes (Final outputs)

• Email: Send an email with a configurable summary of actions performed in the playbook
• Chat Webhook: Sends a message to Teams/Slack/Mattermost/Webex/Line using a pre-configured Webhook integration
• Raise Compliance Violation: Sends Compliance Violation notifications

i Note:

There have been recent changes to the Nodes side panel:

• The icon for the [Regex Match], Node has been updated:

• A new node, [Merge by Device], has been added:

• A new node, [Load Configuration], has been added:

• A new node, [Raise Compliance Violation], has been added:

Node Search

You can search for Nodes that you want to add by name, or filter the Nodes that are visible in the Nodes list by using the Nodes Search function at the top of the right sidepanel.

Add Node

To add a Node:

1. Click the [Playbook] main tab.

2. Doubleclick the Playbook to which the Node will be added.

3. Click and drag a Node from the Node list in the righthand panel, to the Playbook Field.

Select Device

To select a device:

1. Click the [Playbook] main tab.

2. Create or open a Playbook.

3. Add a “Device Search” Node to you workflow from the Node list on the right side of the window.

4. On the “Device Search” Node, click [Device Selection].

There are three options in the [Device Selection] window:

Selecting “Search” allows you to narrow your search using multiple criteria.

Run Code

To run code on a device:

1. Add a “Run Code” Node to your workflow from the Node list on the right side of the window.

2. Click the [Code Editor] button.

3. Enter a cli command for the devices you have selected.

Raise Compliance Violation

The [Raise Compliance Violation] Node sends Compliance Violation notifications to users via four methods:

• Email
• Webhook to Teams/Slack/Webex/Line/PagerDuty/Google Chat
• Both email and Webhook
• Notifications in ThirdEye’s [Inventory] main tab > Editor [Compliance] tab.

To view the details of the Violation in ThirdEye’s [Compliance] tab:

1. Click the [Inventory] main tab.

2. Doubleclick the device to open the its Editor window at the bottom of the screen.

3. Click the Editor’s [Compliance] tab.

The source of the Violation severity icon, Compliance Violation, Compliance Policy Name, and Violation message are displayed in the left sidepanel of the Editor.

For more information about the Violation, you can click the [Playbook] main tab to check the Violation History.

The History is located in the right sidepanel.

Connect Nodes

You can connect Nodes to create Playbook.

To connect nodes, click and drag from an output port (right side) of one Node, to an input port (left side) of another node.

Press [Backspace] on your keyboard to remove unwanted connections.

Nodes may also be connected by holding shift and dragging one close to another, a preview line will show where the connection will be made once you let go of the Node. The Node you’re dragging will only ever connect to the first handle, however you can move this node up or down to select the handle you want to connect to on the other Node.

Remove Nodes or Connection

To remove a node, or a connection, select the desired item, and click on [Backspace] on your keyboard.

Running a Playbook

1. Open the [Playbook] main tab.

2. Doubleclick the Playbook you want to run.

3. Click the [Run] button in the menu bar at the top of the window.

The Run button may be disabled based on your permissions and the Playbook’s approval status. Playbooks are subject to the [Approval Function]. Approvals for Playbooks may be managed within both the Playbooks and Jobs Tabs. The same permissions for Jobs are applicable to Playbooks.

View the Approvals log for a Playbook:

1. Click the [Playbook] main tab.

2. Doubleclick the Playbook you want to review.

3. Click the [Job Approvals Log] button to the right of the Nodes panel.

Viewing the Output of a Playbook Run

If you’ve just run a Playbook, you’ll be brought to the Output screen automatically.

To view the output of a previously run Playbook:

1. Click the [Playbook] main tab.

2. Click the Playbook you want to see a previous output for.

3. Browse the History panel on the right side of the screen.

4. If the execution you’re interested in is not present, search terms may be added to help find it.

Previous executions may also be searched in the [Job History] section of the [Jobs] main tab.

The Playbook Output screen

The Output screen is divided into two main sections. The upper section provides a display of the Playbook exactly as it was when it was executed. Nodes that have created outputs while executing will have their output handles highlighted in green. You can click on a Node, or a Node’s output handle in order to navigate the bottom panel to that Node’s output.

The bottom panel provides tabular data for each of a Node’s output. At its top is a selector to choose which Node’s output you wish to see. If the selected Node has one or more outputs, a series of tabs will be displayed which can be used to view individual outputs in a table. When selecting a Node in this panel, the top panel will fly to the newly selected node to help locate it in the Playbook.

Inside of this tabular data, individual rows may be selected, if the row has more information associated to it, a panel will open with that data. For example, the output of a Run Code node will have the output of the commands executed on the device hidden until a row is selected.

Sometimes you may want to see all interactions the Playbook performed against a specific device. In this case click the table icon in the top left of the bottom panel.

From here there’s a search bar in the top left to find the device you’re interested in, and the panel will display a timeline of every output of every node related to that device. Since this might get farily long, clicking on any node’s name left of the line will filter down the display to node outputs that caused or were caused by that specific output. Clicking it again will remove that filter. Clicking the [device] button in the top right will return you to the tabular output display.

Using Replacement Values

Many nodes will emit metadata alongside their main result. For a Run Code node this may be device or status. These will all be visible in the table for the Node’s output after starting the Playbook. If a field supports substitution, you may reference a value by surrounding its name with {curly braces} A number of nodes support templated substitution for these values:

• Regex Match: The Regular Expression and Compare Against inputs both support substitution.
• Run Code: Commands support substitution.
• Run Code With Automatic Retry: Commands support substitution.
• SSH Exec: Command supports substitution.
• Set Variables: Variable Values support substitution.
• Update Fields: Field Values support substitution.
• Upload File: Commands to pull file from server support substitution.
• Raise Compliance Violation: Message supports substitution.

If you want to extract a piece of information into it’s own piece of metadata to be output as a column from a node, the easiest way to do so it to use the Regex Match Node. It supports Java style regular expressions and named match groups will be pulled into a value with that name.

e.g. to pull a Cisco device’s uptime into a value named uptime you can pass the output of show version to a Regex Match node with the Regular Expression:

lab-router uptime is (?<uptime>[\w ,]+)

And Compare Against set to its default of {result}, then this Regular Expression is not designed to match the entire Compare Against value, so let’s enable Partial Match to indicate that we want it to count as a match if the Expression is at least present.

Once this is configured, the output of the Regex Match will include any matched uptimes in a new uptime column, which can be used in subsequent nodes as {uptime}

We can also chain these to capture more specific information by changing Compare Against, for example, if you want to check for switches reset recently, you could check for an uptime that does not match the regex day:

Connect the uptime Regex Match Node to a new Regex Match Node and set the Regular Expression to :

day

Set Compare Against to {uptime}, and again make sure Partial Match is enabled.

Then we can inspect the output of nonMatches or connect handle of this new node to an Email, Webhook, Raise Compliance Violation, or Set Variables node with a message like ‘Device reset recently: {uptime}’ to recieve the results in another way.

Keyboard Shortcuts

In the following shortcuts, Mod will refer to Control on Windows, or Command on Mac

Node creation shortcuts are performed by holding a key and left clicking on the Playbook field where you want the new node.

Import Playbook

To import a Playbook:

1. Click the [Playbook] main tab.

2. Click the button in the menu bar at the top of the window.

3. Doubleclick the Playbook .json file you want to import.

4. The Playbook file will appear in the [Playbook] interface.

Export Playbook

To export a Playbook:

1. Click the [Playbook] main tab.

2. Doubleclick the [Playbook] you want to export.

3. Click the click the [Export] button in the menu bar at the top of the window.

4. Download the Playbook as a .json file.

5. Click the [Close Playbook] button in the menu bar at the top of the window.

Playbook Categories

The Playbook Category Feature introduces organizational improvements for Playbook management.

With Playbook Categories you can:

• Create and edit custom categories
• label using colored tags in Playbook lists
• Create multiple categories within one playbook

Create Playbook Category

To create a Playbook Category:

1. Click the [Playbook] main tab.

2. Click the button next to the “Playbook” main tab title to open the [Categories] window.

3. Click the button to open the [Add Category] window.

4. Click the button to select a .svg image for the Category.

5. Enter a name for the Category.

6. Click [OK] > [Close].

Edit Playbook Category

1. Click the button next to the “Playbook” main tab title to open the [Categories] window.

2. Click the category name in the [Categories] window.

3. Click the button to open the [Edit Category] window.

4. Click [OK] after editing.

Delete Playbook Category

1. Click the button next to the “Playbook” main tab title to open the [Categories] window.

2. Click the category name in the [Categories] window.

3. Click the button to open the [Remove Category] window.

4. Click [Yes].

Compliance Remediations

Playbooks may be executed automatically in response to Compliance Rule Violations.

1. Click the [Compliance] > [Rule Sets] tabs.

2. Doubleclick the Rule Set you wish to add a Remediation Playbook to in order to open it in the Editor at the bottom of the page.

3. Click the “Remediation job or playbook” button in the lower right of the page.

Example:

Incident Actions

Playbooks may be executed automatically as a part of an Alert Policy.

1. Click the [Monitors] > [Alert Policies] tabs.

2. Add a “Alert Policy Name”, or select an existing Alert Policy.

3. Click [New Action].

You have the option to click [Send to Playbook].

Once added, select “Playbook to Run”, “Frequency” and “Perform the action when…”.

Example:

Incident example:

Script Executor Container

Some workflows may be easier to implement using a more traditional programming language. So to enable these workflows, we provide a Docker image at:

harbor.logicvein.com/lvi/lvi-script-sandbox:latest

This image comes with Python preinstalled, and exposes an API over SSH (Port: 2022) that allows for executing scripts in a more sandboxed environment. Once the image is pulled, it can be run with:

docker run -d \
  --name lvi-script-sandbox \
  --read-only \
  --tmpfs /tmp:size=1G \
  --cap-add=SYS_ADMIN \
  --security-opt no-new-privileges \
  - v ./scripts:/shared:ro \
  - v ./packages:/packages \
  lvi/lvi-script-sandbox:latest

The /shared volume is intended to allow for accessing files from the host, for example if you have a library of scripts you wish to use.

The /packages volume will be used to store pip installed packages.

Environment Variables

The following environment variables may be defined to override defaults:

• WORKSPACE_TIMEOUT: The maximum lifetime for created workspaces. Once this timeout is reached, the workspace’s directory will be deleted. The value must be of the form <number><unit> where unit can be s for seconds, m for minutes, or h for hours. Default: 60m.
  • One workspace will be created per Playbook run, the whole run will share one namespace regardless of how many script nodes are present.
• SCRIPT_TIMEOUT: The maximum execution time for each script. If a script exceeds this timeout, it will be terminated. The value must be of the form <number><unit> where unit can be s for seconds, m for minutes, h for hours. Default: 120s.

Test it out

You can connect to it from a terminal with the command:

ssh -p 2022 root@localhost shell

The default password will be sandbox. You should be able to log in and run some commands within the sandboxed environment.

Configuration

To set up a custom password to use as an API Key to connect from ThirdEye, run the following command:

ssh -p 2022 root@localhost passwd

And provide a new password when prompted.

If you need to have your scripts perform API calls against the ThirdEye server, you may set an API Key, by running the container with the following options:

docker run -d \
  --name lvi-script-sandbox \
  --tmpfs /tmp:size=1G \
  --cap-add=SYS_ADMIN \
  --security-opt no-new-privileges \
  lvi/lvi-script-sandbox:latest

And then run:

ssh -p 2022 root@localhost setkey <new_key>

Packages

If you have mounted the /packages directory to a volume, the pip command will support the following: install uninstall and list. These packages will be available for all sessions and script executions.

ssh -p 2022 root@localhost pip install human-regex

Enabling the Execute Script Nodes

The server settings has a [Script Executor] option where you may Enable the Executor, provide a Hostname, Port, and the Password set earlier. Once the Executor is enabled, you will be able to access the Execute Script and Execute Existing Script Playbook Nodes.

Scripting

Input

Each input to the Execute Script Nodes will individually invoke python. Invocations will be performed concurrently with no ordering or timing guarantee. The input for each Python script invocation will be inside a file named in.json and will be structured as follows:

• device - Device-specific data
• globals - Values from previous nodes
• metadata - Execution metadata

device (object)

Represents a managed network device and its associated metadata.

Properties

backupStatus enum

• SUCCESS
• FAILURE
• INVALID_CREDENTIAL

complianceState enum

• 0 = compliant
• 1 = unsaved changes
• 2 = policy violations

severity enum

• 1 = DEBUG
• 2 = INFORMATIONAL
• 3 = NOTICE
• 4 = WARNING
• 5 = ERROR
• 6 = CRITICAL
• 7 = ALERT
• 8 = EMERGENCY

globals (object)

Output values from the input connection.

• All columns are included
• Structure is dynamic
• Values will be pairs of type = string or list, value = value. If the type is list, the value will contain an array of strings.

metadata (object)

Execution metadata for the playbook.

Properties

Example:

In practice, this will look like the following, fields have been omitted from device for brevity:

{
    "device": {
        "ipAddress": "10.0.0.1",
        "hostname": "",
        "adapterId": "Cisco::IOS",
        "deviceType": "Switch",
        "network": "Default",
        "serialNumber": "FOC1721W1SR"
    },
    "globals": {
        "status": { "type": "string", "value": "OK"},
        "err_message": { "type": "string", "value": ""},
        "result": {"type": "string", "value": "show version\nCisco IOS Software, C1900 Software (C1900-UNIVERSALK9-M), Version 15.4(3)M5, RELEASE SOFTWARE (fc1)\nTechnical Support: http://www.cisco.com/techsupport\nCopyright (c) 1986-2016 by Cisco Systems, Inc.\nCompiled Tue 09-Feb-16 02:36 by prod_rel_team\n..."}
    },
    "metadata": {
        "author": "admin",
        "execution_id": 8622,
        "execution_url": "https://10.0.0.1/#action=playbook&executionId=736&scriptId=854618fa-7d14-48a1-b06d-d4c8874333b4&versionId=411",
        "executor": "admin",
        "job_id": 133,
        "node": "Nurturing_Nexus",
        "origin": "10.0.0.1",
        "playbook": "Script Runner",
        "started_at": 1774858794829
    }
}

Output

If you have a simple string output you wish to use in downstream nodes, you can just print it out to standard out as is. The output will use that value as its result.

If you wish to introduce variables, or emit multiple outputs for a single input, you can print JSON to standard out, following the Schema:

Properties

output (object)

Single output container sent to the output handle.

Properties

globals

outputs (array)

Array of output objects sent to the eachOutput handle, where each item shares the same shape as output.

error

Represents execution error details:

Examples:

A minimal example script that outputs one value:

import base64
import json

data = {
    "output": {
        "raw": base64.b64encode(b"Hello").decode("utf-8"),
        "globals": {
            "foo": "bar"
        }
    }
}

print(json.dumps(data))

Multiple outputs:

import time
import base64
import json

data = {
    "outputs": [
        {
            "raw": base64.b64encode(b"Hello").decode("utf-8"),
            "globals": {
                "foo": "bar"
            }
        },
        {
            "raw": base64.b64encode(b"Hello").decode("utf-8"),
            "globals": {
                "foo": "bar"
            }
        },
    ]
}

print(json.dumps(data))

And example of a failure, the error key takes priority over outputs, so if error is present, the node will be treated as having failed regardless of any output key presence:

import json

data = {
    "error": {
        "message": "this was bad",
        "code": "15",
    },
}

print(json.dumps(data))