Playbooks Glossary
  • 25 Mar 2024
  • 17 Minutes to read
  • Dark
    Light

Playbooks Glossary

  • Dark
    Light

Article Summary

Overview

This glossary consists of the terminology used within ThreatConnect’s Playbooks feature and its various screens. For a complete list of Playbook Apps available in ThreatConnect, visit the ThreatConnect Marketplace.

A

Active Mode - Active Mode is used when a Playbook has been completely designed and configured with no validation issues. When Playbooks are active, they are available for execution in an Organization. Playbooks may not be edited in Active Mode. However, you can view Trigger and App parameters in Active Mode by double-clicking on the element.

Activity Screen - The Playbooks Activity screen is a control panel on which Organization Administrators, Operations Administrators, and System Administrators can monitor Playbook Server and Worker execution metrics, priorities, and processes for their instance. From this screen, current, present, and past Worker activity and allocation to Servers can be viewed and Playbook executions can be killed.

App - An App is a tool that is used to act on data provided by a Trigger or another App within a Playbook. Currently, there are 15 App categories:

  • Collaboration & Messaging: Collaboration & Messaging Apps send a customizable message via a client (e.g., email, meeting invitation, SMS).
  • Component: Components are Apps that consist of modules of Playbook elements (Apps and Operators, with a single initial Trigger) that can be called from a Playbook.
  • Data Enrichment: Data Enrichment Apps automate the enrichment of Indicators through ThreatConnect or third-party enrichment tools.
  • Email Security: Email Security Apps automate email investigation and response actions based on senders, attachments, and folders.
  • Endpoint Detection & Response: Endpoint Detection & Response Apps add, update, and remove Indicators from alerting and blocking lists on endpoint security tools.
  • Identity & Access Management: Identity & Access Management Apps retrieve user information and update, activate, and block users.
  • Incident Response & Ticketing: Incident Response & Ticketing Apps create a ticket, record, or issue for the Trigger in a third-party system such as Jira™, ServiceNow®, or IBM Resilient Incident Response Platform® (Resilient).
  • IT Infrastructure: IT Infrastructure Apps investigate storage solutions and other infrastructures, such as Amazon Simple Storage Service (Amazon S3™) or Apache Kafka®, to identify Indicators and security alerts.
  • Malware Analysis: Malware Analysis Apps analyze a file artifact for maliciousness and automate actions to be taken on the resulting report data.  
  • Network Security: Network Security Apps add, update, and remove Indicators from alerting and blocking lists on network tools.
  • SIEM & Analytics: SIEM & Analytics Apps add, update, and remove Indicators from alerting and blocking lists on SIEM tools.
  • Threat Intelligence: Threat Intelligence Apps integrate with third-party products that typically use data in ThreatConnect. These integrations bring timely and relevant information into ThreatConnect so that users can make informed decisions.
  • ThreatConnect: ThreatConnect Apps perform a task in ThreatConnect.
  • Utility: Utility Apps perform data utility functions, like formatting dates, filtering regexes, and extracting data from a file of a given type (CSV, JSON, EML/MSG, RSS, or XPath).
  • Vulnerability Management: Vulnerability Management Apps search for, retrieve, and prioritize vulnerabilities.

App Builder - The App Builder is a Python development environment where you can create, edit, and release Playbook Apps directly in ThreatConnect.

App Logs - App logs are logs for an App that has been executed in a Playbook.

Apps Pane - The Apps pane of the Playbook Designer displays a list of the 13 App categories and the Apps in each category that can be added to a Playbook. See “App” for more information about the App categories.

App Builder Screen – The App Builder screen contains features and components that enable you to build a Playbook App and are customizable in the user interface.

Apps Screen –The Apps screen is displayed when you select App Builder from the Playbooks dropdown on the top navigation bar. It displays all App Builder projects in your Organization and has options for creating a new App, cloning an existing App, and importing an App from a saved file.

Audit Log Pane - The Audit Log pane of the Playbook Designer provides a detailed list of all changes made to a Playbook by users in an Organization.

B

Break Iterator Operator - See “Operator.”

C

Clone - The act of making a copy of an existing Playbook or Component. Playbooks and Components can be cloned as Playbooks, Components, and Workflow Playbooks. 

Component - A Component is an App that consists of modules of Playbook elements (Apps and Operators, with a single initial Trigger) that can be called from a Playbook in ThreatConnect. They make Playbook design more convenient when a group of elements is used repeatedly by allowing the elements to be packaged together and called as a single element.

Components Pane - The Components pane of the Playbook Designer displays all Components in an Organization that can be added to a Playbook.

D

DataStore - The DataStore is a feature that allows runtime and Playbook Apps to persist data using OpenSearch®. The DataStore is available to any Job, Spaces, or Playbook App requiring persistent storage.

DataStore Explorer - See “DataStore Pane.”

DataStore Pane - The DataStore pane of the Playbook Designer opens the DataStore Explorer, where you can interact with DataStore information indexes while working with the Playbook Designer.

DEBUG - The DEBUG log level records detailed diagnostic information about the execution of a Playbook or Playbook App.

Delay Operator - See “Operator.”

Design Mode - When the Playbook Designer is in Design Mode, existing Playbooks are made inactive (i.e., they cannot be executed) and can be modified and configured. When a new Playbook is created, the Playbook Designer opens automatically in Design Mode.

Display Documentation - Clicking the Display Documentation icon when configuring a Trigger, App, or Operator displays information about the selected Playbook element, including a description, input parameters, and output variables.

E

Environments Screen - The Playbooks Environments screen provides information to Organization Administrators, Operations Administrators, and System Administrators on the Environments available to their ThreatConnect instance and allows them to administrate the Environments from within their instance.

ERROR - The ERROR log level will record only serious issues, such as a failure of an important process within the execution of a Playbook or Playbook App. The Playbook or Playbook App will still be able to run, but the problem, such as a dropped database connection or the inability to access a file or service, will require remediation in the near future.

Execute - The act of running a Playbook. The results of a Playbook execution can be viewed in the Executions pane of the Playbook Designer while the Playbook is open, and full details of an execution can be viewed by clicking on it in the Executions pane to open its Execution screen.

Execution Details Pane - The Execution Details pane of the Execution screen contains cached data (i.e., inputs, outputs, App logs, and OS logs) on the execution for a Trigger, App, Operator, or Component used in the Playbook. It also contains details about a selected Trigger, App, Operator, or Component, including its name, type, session ID, execution status, start time, end time, elapsed time, log level, and status message.

Execution Details Tab - The Execution Details tab in Interactive Mode contains cached data (i.e., inputs, outputs, App logs, and OS logs) on the execution for a Trigger, App, Operator, or Component used in the Playbook.

Execution Graph Pane - The Execution Graph pane of the Execution screen displays the path that an execution took. Steps that were executed will be displayed in color, and the status, session ID, and execution time will be displayed above the corresponding Trigger, App, or Operator on the graph. Steps that were not executed will be grayed out.

Execution Screen - After a Playbook execution is selected from the Executions pane of the Playbook Designer, its Execution screen will open in the Playbook Designer. The Execution screen displays details about an execution, including its session ID, status, start time, completion time (if it was a fully successful execution), the job server on which it was executed, the Worker on which it was executed, the Playbook name, and the log level used during the execution. In addition, an Executions Details pane and Execution Graph pane will be displayed at the lower left and lower right on the Execution screen, respectively. For more information, see “Execution Details Pane” and “Execution Graph Pane,” respectively.

Executions Pane - The Executions pane of the Playbook Designer displays a table with a row for each execution of a Playbook. Details provided in the table include the execution’s session ID and the date and time at which the execution occurred.

G

Global Variables - Global variables are ad-hoc user-defined variables that are created at the Playbook level. These variables can be set, updated, and referenced anywhere in the Playbook, even inside nested Components and Iterators. They provide an easy way to track settings, counts, and other important information throughout a Playbook’s execution.

I

If / Else Operator - See “Operator.”

Inactive - See “Design Mode.”

INFO - The INFO log level will record normal behavior and milestones for the execution of a Playbook or Playbook App, such as the start or exit of an App or the submission of an Indicator to a SIEM.

Input Parameters - Input parameters are values that are passed to an App or Operator used in a Playbook.

Interactive Mode - When the Playbook Designer is in Interactive Mode, you can interactively test an App in-line and collaborate with other users on the Playbook.

Iterator Operator - See “Operator.”

J

 Job Server - See “Playbook Server.”

K

 Kill - The act of stopping an active Playbook execution.

L

Label - A label is a keyword used to classify a Playbook or Component. Labels that have been applied to a Playbook or Component can be viewed in the Labels column of the Playbooks screen and the Summary pane of the Playbook Designer.

Log Level - A Playbook’s log level determines the amount of information logged when a Playbook is executed. Log levels cascade; in other words, any log level will capture details at its own level and at all less granular log levels. Available log levels, from least to most granular, are ERROR, WARN, INFO, DEBUG, and TRACE.

M

Mailbox Trigger - See “Trigger.” 

Major Version - See “Versioning.”

Merge Operator - See “Operator.”

Metadata Pane - The Metadata pane of the Playbook Designer displays all global variables accessible to any Trigger, App, Operator, or Component within a Playbook.

Minor Version - See “Versioning.”

Multi-Environment Orchestration - Multi-environment orchestration allows users that have an Environment Server behind a firewall to use their instance to communicate with that server and run Playbook Apps and Services inside their firewall.

MultipleIndicator Trigger - The MultipleIndicator Trigger enables you to select more than one Indicator type for a single Trigger so that any of the selected Indicator types will cause the Trigger to initiate the Playbook’s actions. The Indicator type that actually caused the Trigger to initiate is provided as one of the output variables (#trg.tc.type).

O

Operator -  Operators are logic-based links between Triggers and Apps. Currently, there are five Operators:

  • Break Iterator - The Break Iterator Operator is used in the iteration loop of the Iterator Operator to define a break condition for the loop or break from the loop directly after an App failure. 
  • Delay Operator - The Delay Operator lets you specify an amount of time to wait before executing additional operations in the Playbook. It is useful when using a third-party service that you know may take several seconds or minutes to return a response.
  • If / Else - The If / Else Operator compares two variables to perform logical operations on the data. It can be used to determine whether an Indicator's threat rating is over a certain threshold, to see if a string of text exists in information returned by an integration, etc.
  • Iterator - The Iterator Operator iterates through items in an input array or set of arrays, applies any logic available with Playbooks to each item, and returns the output to the Playbook.
  • Merge - The Merge Operator enables upstream Apps to merge an operation into a single path, allowing a Playbook to guarantee an outcome in cases of path failures. The first path to hit a Merge Operator will force a continuation of the Playbook even if the other paths have not been completed.

Operators Pane - The Operators pane of the Playbook Designer displays the five Operators that can be added to a Playbook.

OS Logs - OS logs are logs generated on the server side of a Playbook execution.

Output Variables - Output variables are values that Triggers, Apps, or Operators can send to other Triggers, Apps, and Operators.

P

Pathways - The various routes between Triggers, Apps, and Operators that a Playbook execution can take.

Playbook Designer - The Playbook Designer is the configuration screen that is displayed after creating or opening a Playbook. It is the screen where you build and activate a Playbook, create and operate Run Profiles, access a Playbook’s version history, create global variables, view execution details and logs, and access administrative functions and settings for the Playbook.

Playbook File - A file that you can use to import a Playbook into ThreatConnect. The current file format is .pbxz, and the legacy file format is .pbx.

Playbook IP Filter - The Playbook IP Filter specifies IP addresses and IP address ranges that can send requests to WebHook Triggers.

Playbook Server - A Playbook Server, also known as a Job Server, is a ThreatConnect instance that is dedicated to the execution of Playbooks. Playbook Servers can be designated as Public or Private. For more information, see “Public Playbook Server” and “Private Playbook Server,” respectively.

Playbook Services - Playbook Service Apps are microservices that constantly run in the background. Currently, there are two types of Services available in ThreatConnect.

  • Custom Trigger Service - This type of Trigger creates Push-type events to handle a custom protocol or raw-port access or that Pull on a configured interval.
  • Webhook Trigger Service - This type of Trigger creates Push-type events that have complex data requiring normalization, filtering, or a better UX. This Trigger Service is essentially a custom WebHook Trigger.

Playbook Template - Playbook Templates are Playbooks provided by ThreatConnect to illustrate best-in-class use cases for Playbooks to help educate users in how to construct more complex Playbooks. Templates are available on the Playbooks Templates screen.

Playbook Worker - A Playbook Worker is an embedded process in a Playbook Server responsible for executing orchestration logic in a queue. A Worker can execute only one Playbook at a time, and multiple Workers can exist inside a Playbook Server.

Playbooks – The Playbooks feature allows you to automate cyberdefense tasks via a drag-and-drop interface. The interface uses Triggers (e.g., a new IP address Indicator, a phishing email sent to an inbox) to pass data to Apps, which perform a variety of functions, including data enrichment, malware analysis, and blocking actions. Once enabled, Playbooks run in real time and provide users with detailed logs of each execution. Playbooks may also be saved for use as Components (i.e., modules) within other Playbooks.

Playbooks Metrics - Playbooks Metrics are available on dashboard Metric cards and provide a graphical representation of three metrics calculated by the Playbooks Return on Investment (ROI) feature for all selected Playbooks: Playbook Execution Count, Playbook Financial Savings, and Playbook Hours Saved.

Playbooks Queue – The Playbooks queue contains all Playbooks currently waiting for execution. A Playbook’s priority level is used to influence the Playbook’s position in the queue. See “Priority Level” for more information.

Playbooks ROI - See “Return on Investment (ROI).”

Playbooks Screen - The Playbooks screen lists all Playbooks, including Playbook Components, available on your ThreatConnect instance. From this screen, you can perform a variety of actions, including creating new Playbooks, searching for and opening existing Playbooks, importing and exporting Playbooks, cloning existing Playbooks, and deleting Playbooks.

Priority Level - A Playbook’s priority level is used to influence a Playbook’s position in the Playbooks queue. Available priority levels include High, Medium, and Low, with Medium being the default priority level assigned to a Playbook. When all Playbooks in the queue have the same priority level, they will go through the queue on a first-in, first-out (FIFO) basis. When a Playbook of higher priority enters the queue, its execution will take precedence over any lower-priority Playbooks waiting in the queue, regardless of existing queue order. When multiple Playbooks of a given priority level are in the queue, they will execute on a FIFO basis within their priority level.

Private Playbook Server - Private Playbook Servers enable ThreatConnect Organizations to assign a Playbook to a dedicated instance for resource allocation or quality-of-service needs.

Public Playbook Server - Public Playbook Servers are designated to a pool and can be used to scale horizontally for any Organization.

R

Return on Investment (ROI) - The Playbooks Return on Investment (ROI) feature allows you to view and visualize the return on investment for the Playbooks executed in your Organization—that is, how much money and time each execution of a given Playbook has saved you (versus doing all of the tasks in the Playbook manually, without orchestration) over various periods of time.

ROI Metrics - Metrics on Playbook Return on Investment (ROI) are available on dashboard Metric cards, in the Summary pane of the Playbook Designer, and on the Playbooks screen by clicking the graph icon in the ROI column.

Run Profile – A Run Profile represents a data type or event needed to execute a Playbook without requiring you to navigate away from the Playbook Designer.

Run Profiles Pane - The Run Profiles pane of the Playbook Designer allows you to create and manage Run Profiles available to use with a Playbook in an Organization.

S

Services Screen – The Playbooks Services screen shows all Services that are installed in your ThreatConnect instance. See “Playbook Services” for more information.

Session ID - The unique identification number for each Playbook execution.

Share Token - A token that can be used to import a shared Playbook into any ThreatConnect instance.

Sharing Server - A server on which a shared Playbook is shared.

Summary Pane - The Summary pane of the Playbook Designer displays Playbook metadata, including a Playbook’s name, description, labels applied to the Playbook, and ROI metrics for the Playbook.

T

Templates Screen - The Playbooks Templates screen displays a table containing all Templates available to you, along with any associated labels and the date when the Template was last updated.

Timer Trigger - See “Trigger.”

TRACE - The TRACE log level records very detailed diagnostic information about the execution of a Playbook or Playbook App. This log level provides the most granular information and is used to capture every possible detail about the Playbook or Playbook App’s behavior.

Trigger - Playbook Triggers are tools that initiate the actions defined within a Playbook. In order to be activated, a Playbook must have one, and only one, Trigger. Currently, there are five Trigger categories:

  • External Triggers - External Triggers are actions that occur outside of the ThreatConnect platform. Currently, there are five External Trigger types:
    • Mailbox Trigger - The Mailbox Trigger is an External Trigger that lets you create a mailbox to send information to a Playbook. The Trigger will fire whenever an email is received in the inbox you create.
    • Timer Trigger - The Timer Trigger is an External Trigger that lets you trigger a Playbook on a set schedule (e.g., once a day; on the fifteenth of the month).
    • UserAction Trigger - The UserAction Trigger is an External Trigger that lets you run Playbooks on demand from the Details screen of Indicators, Groups, Tracks, or Victims. This Trigger is contextually aware and user driven, and it allows a customized response (HTML or plain text).
    • WebHook Trigger - The WebHook Trigger is an External Trigger that creates an HTTPS endpoint that can process nearly any piece of information that can be sent via HTTP.
    • Custom Trigger - A Custom Trigger is a type of Service Trigger that is not linked to a remote HTTP request. Instead, it is dependent on an external Trigger source to determine whether the Playbook executes, as defined by the App in its configuration. See “Playbook Services” for more information.
  • Group Triggers - Group Triggers correspond to all of the defined Groups on your ThreatConnect instance.
  • Indicator Triggers - Indicator Triggers correspond to all of the defined Indicators on your ThreatConnect instance.
  • Other Triggers - Other Triggers correspond to the Case, Track, and Victim objects.
  • Service Triggers - Service Triggers are microservices that constantly run in the background.

Triggers Pane - The Triggers pane of the Playbook Designer displays all available Triggers that can be added to a Playbook.

U

UserAction Trigger - See “Trigger.”

V

Validations Pane - The Validations pane of the Playbook Designer provides real-time information about issues preventing the execution of a Playbook.

Variable Explorer Tab - The Variable Explorer tab in Interactive Mode allows you to observe the state of each Trigger, App, Operator, and Component in a Playbook as a self-contained element.

Versioning - Versioning in Playbooks allows you to maintain and manage versions of your Playbooks and Components. Every time a Playbook or Component is activated, a new minor version is autosaved. Users can create and comment on major versions, as well as split off older versions to create new Playbooks and Components.

Versions Pane - The Versions pane of the Playbook Designer allows you to view saved versions and version history of a Playbook.

W

WARN - The WARN log level will record unexpected and unusual, but not necessarily serious, problems in the execution of a Playbook or Playbook App, such as an attempt to invoke a service that resulted in failures before a successful connection on an automatic retry. It is unknown whether the issue will persist or recur. Warnings should be investigated, but are typically not urgent.

WebHook Trigger - See “Trigger.”

Worker - See “Playbook Worker.”

Workflow Playbook - A Workflow Playbook is a special type of Playbook that uses a Workflow Trigger, which passes input from within the Workflow process to the rest of the Playbook, which then performs its defined function and returns its output to the Workflow process. Workflow Playbooks are called by automated Tasks. They can also be run ad hoc on a Workflow Artifact in a Case.

Workflow Trigger - See “Workflow Playbook.”


ThreatConnect® is a registered trademark of ThreatConnect, Inc.
Amazon S3™ is a trademark of Amazon Technologies, Inc.
Apache Kafka® is a registered trademark of The Apache Software Foundation.
IBM Resilient Incident Response Platform® is a registered trademark of IBM Corporation.
Jira™ is a trademark of Atlassian Corporation Plc.
OpenSearch® is a registered trademark of Amazon Web Services.
ServiceNow® is a registered trademark of ServiceNow, Inc.

20116-01 v.02.F


Was this article helpful?