Playbooks

In ThreatConnect, you can use Playbooks to automate your cyberdefense tasks and custom processes. Each Playbook contains a single Trigger and one or more Apps and Operators that determine the Playbook’s logic and the actions that the Playbook will perform once executed.

Endpoint: /api/v3/playbooks

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields that may be included in responses returned from the /v3/playbooks endpoint, which is a read-only endpoint:

OPTIONS /v3/playbooks?show=readonly

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/playbooks endpoint:

OPTIONS /v3/playbooks/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/playbooks endpoint:

OPTIONS /v3/playbooks/tql

Hint

See the “Retrieve a Specific Playbook” section for example use cases of the tql query parameter.

Schemas

Response Body

The default response returned from a successful GET request to the /v3/playbooks endpoint includes one or more objects with the following fields:

id: <Integer> The Playbook’s ID number.
groupXid: <String> The Playbook’s XID.
name: <String> The Playbook’s name.
description: <String> The Playbook’s description. This field is included in the response body only if a description has been provided for the Playbook.
webLink: <String> The Playbook’s URL. This URL includes the Playbook’s ID number.
groupWebLink: <String> The Playbook’s URL. This URL Includes the Playbook’s XID.
version: <String> The Playbook’s current version number.
comment: <String> The comment associated with the Playbook’s current version number.
lastInteractiveSession: <String> The XID associated with the most recent interactive session for the Playbook. This field is included in the response body only if the Playbook has been used in Interactive Mode.
type: <String> The Playbook’s type. Possible values include Playbook (for standard Playbooks), Component (for Playbook Components), and Workflow (for Workflow Playbooks).
triggerType: <String> The type of Trigger that the Playbook uses. This field is included in the response body only if a Trigger has been added to the Playbook.
endpoint: <String> The endpoint for the Playbook’s Trigger. This field is included in the response body only for Playbooks that use a Mailbox or WebHook Trigger.
active: <Boolean> Specifies whether the Playbook is active.
basicAuthEnabled: <Boolean> Specifies whether basic authentication is turned on for the Playbook’s Trigger.
logLevel: <String> The Playbook’s log level.
updated: <DateTime> The date and time when the Playbook was last updated.
labels: <String Array> The label(s) applied to the Playbook. This field is included in the response body only if one or more labels have been applied to the Playbook.
priority: <Integer> The Playbook’s priority. Possible values include 3 (for Low), 6 (for Medium, which is the default priority), and 7 (for High).
scheduleCronFormat: <String> The schedule of the Playbook’s Timer Trigger defined as a cron expression. This field is included in the response body only for Playbooks that use a Timer Trigger.
status: <String> The Playbook’s status.
zoom: <Float> The current zoom level for the Playbook in the Playbook Designer.
panX: <Float> The number of units that the Playbook has been moved horizontally in the Playbook Designer.
panY: <Float> The number of units that the Playbook has been moved vertically in the Playbook Designer.
roiDollarsPerHour: <Integer> The dollars per hour that will be saved with each execution of the Playbook.
roiMinutes: <Integer> The amount of an analyst’s time, in minutes, that will be saved with each execution of the Playbook.
apiUser: <String> The name of the user under which the Playbook will execute.
enableNotifications: <Boolean> Specifies whether failure notifications are turned on for the Playbook.
notifyEmailList: <String> The email address(es) to which failure notifications will be sent. This field is included in the response body only if failure notifications are turned on for the Playbook and one or more email addresses to which notifications will be sent have been specified.
notifyIncludeLogFiles: <Boolean> Specifies whether to include log files in the failure notifications.
notifyEmailCount: <Integer> The number of failure notifications that have been sent for the Playbook.
ownerName: <String> The Organization in which the Playbook exists.

Example

{
    "id": <int>,
    "groupXid": "<string>",
    "name": "<string>",
    "description": "<string>",
    "webLink": "<string>",
    "groupWebLink": "<string>",
    "version": "<string>",
    "comment": "<string>",
    "lastInteractiveSession": "<string>",
    "type": "<string>",
    "triggerType": "<string>",
    "active": <boolean>,
    "basicAuthEnabled": <boolean>,
    "logLevel": "<string>",
    "updated": "<datetime>",
    "labels": [
        "<string>"
    ],
    "priority": <int>,
    "status": "<string>",
    "zoom": <float>,
    "panX": <float>,
    "panY": <float>,
    "roiDollarsPerHour": <int>,
    "roiMinutes": <int>,
    "apiUser": "<string>",
    "enableNotifications": <boolean>,
    "notifyEmailList": "<string>",
    "notifyIncludeLogFiles": <boolean>,
    "notifyEmailCount": <int>,
    "ownerName": "<string>"
}

Retrieve Playbooks

Retrieve All Playbooks

Send the following request to retrieve data for all Playbooks in your Organization:

Request

GET /v3/playbooks

Response

{
    "data": [
        {
            "id": 10,
            "groupXid": "Jisp3U1A",
            "name": "Vulnerability Content Pack - Manual Vulnerability Enrichment from NIST NVD",
            "description": "This playbook goes out to NVD NIST via a User Action Trigger to search for a CVE and bring back the Summary, CVSS Score, CVSS Severity and Metrics Matrix, and the References associated with the CVE. It will also associate and add the Technical Blogs and Reports by CVE tag to the Vulnerability object.",
            "webLink": "https://app.threatconnect.com/#/playbooks/designer/12345",
            "groupWebLink": "https://app.threatconnect.com/#/playbooks/designer/Jisp3U1A",
            "version": "1.172",
            "comment": "Auto-Saved on Thu Oct 26 15:52:48 UTC 2023",
            "type": "Playbook",
            "triggerType": "UserAction",
            "active": true,
            "basicAuthEnabled": false,
            "logLevel": "WARN",
            "updated": "2023-10-26T15:46:16Z",
            "labels": [
                "NVD CVE Use Case ",
                "Vulnerability Content Pack"
            ],
            "priority": 7,
            "status": "Active",
            "zoom": 1.1471,
            "panX": -94.0,
            "panY": 930.0,
            "roiDollarsPerHour": 75,
            "roiMinutes": 10,
            "apiUser": "John Smith",
            "enableNotifications": true,
            "notifyEmailList": "[email protected]",
            "notifyIncludeLogFiles": false,
            "notifyEmailCount": 0,
            "ownerName": "Demo Organization"
        },
        {
            "id": 9,
            "groupXid": "23llBiwt",
            "name": "Vulnerability Use Case - Vulnerability Enrichment Manual User Action R1",
            "webLink": "https://app.threatconnect.com/#/playbooks/designer/12344",
            "groupWebLink": "https://app.threatconnect.com/#/playbooks/designer/23llBiwt",
            "version": "1.27",
            "comment": "Auto-Saved on Thu Oct 26 15:49:52 UTC 2023",
            "type": "Component",
            "triggerType": "PipeConfig",
            "active": true,
            "basicAuthEnabled": false,
            "logLevel": "WARN",
            "updated": "2023-10-26T15:46:13Z",
            "labels": [
                "NVD CVE Use Case "
            ],
            "priority": 6,
            "status": "Active",
            "zoom": 0.8,
            "panX": -129.0,
            "panY": 273.0,
            "roiDollarsPerHour": 75,
            "roiMinutes": 10,
            "apiUser": "John Smith",
            "enableNotifications": false,
            "notifyIncludeLogFiles": false,
            "notifyEmailCount": 0,
            "ownerName": "Demo Organization"
        },
        {...}
    ],
    "status": "Success"
}

Hint

To include details about a Playbook’s most recent execution in the API response, append ?fields=lastExecution to the end of the request URL.

Retrieve a Specific Playbook

The following requests demonstrate how to use TQL to retrieve data for a specific Playbook.

Filter by ID Number

In the following example, the API request will retrieve data only for the Playbook whose ID number is 12345:

Request (Decoded URL)

GET /v3/playbooks?tql=id = 12345

Request (Encoded URL)

GET /v3/playbooks?tql=id%20%3D%2012345

Filter by XID

In the following example, the API request will retrieve data only for the Playbook whose XID is GiTVUWaN:

Request (Decoded URL)

GET /v3/playbooks?tql=groupXid = "GiTVUWaN"

Request (Encoded URL)

GET /v3/playbooks?tql=groupXid%20%3D%20%22GiTVUWaN%22

Filter by Name

In the following example, the API request will retrieve data only for the Playbook whose name is Send IR Results to SIEM:

Request (Decoded URL)

GET /v3/playbooks?tql=name = "Send IR Results to SIEM"

Request (Encoded URL)

GET /v3/playbooks?tql=name%20%3D%20%22Send%20IR%20Results%20to%20SIEM%22