Playbook


What is Playbook?

Playbook is a new entity for a package. It is a new way to write queries and return data after execution. It is useful for building usecases for incident response, etc.

Features of Playbook

  • Each playbook will hold one query (multiple query functions).
  • Playbooks can be used for executing queries which are one time executable.
  • Playbooks work in a manner similar to Workbooks except that they do not need to be scheduled using cron.
  • Playbooks can be used to simply execute a task in the form of a query or return data after execution

Understanding how to use Playbook

Creating and viewing Playbook

Playbook can be added inside a package by clicking the + sign on the top right corner as shown below:

resultset of the fetch query function

Details to be added while creating a Playbook:

resultset of the fetch query function

Here,

  • Name: Name of the playbook is a mandatory field. The maximum length for the playbook name is 30 characters and minimum is 5 characters. Name cannot start with a number or special character. Special characters and white spaces are not allowed to be used for the name of a playbook.

  • Description: Description of the playbook is an optional field. The maximum length for the playbook description is 500 characters.

  • Tag: Tag of the playbook is an optional field. The minimum length for a playbook tag is 3 characters and the maximum length for a tag is 10 characters. Multiple tags can be added. Special characters are not allowed to be used for the name of a playbook.

  • Status: Status of the playbook is a mandatory field. It appears in the form of a dropdown menu. The values that can be selected are Inactive, Executable, Returnable and Deleted. The default value is Executable which also means that the Playbook is in Active state by default.The different types of Playbook status are listed below:
    • Deleted: Deleted status will not excute the Playbook
    • Executable: Executable status will enable only execution of the playbook. By default the status is active
    • Inactive: Inaactive status will not excute the Playbook
    • Returnable: Returnable status will return the result of the execution
  • API Callable: API Callable is a mandatory field. It is used to call the playbook from an external API. It has two options: Active and Inactive which are shown by means of a slider. The default value is Active.

  • Query Details: Query details is the mandatory part of a playbook and this enables for the execution of the desired task through a playbook by means of a query. The sections in Query Details are:
    • Query: The query can be a parameterized query or without parameters. There is functionality of validation for parameters in a parameterized query.
    • Parameters: Parameters are to be entered only for a parameterized query. Parameterized query can be created by clicking the check box on the top right corner as it appears in the below image:
resultset of the fetch query function

The parameters can be added and validated as shown below:

resultset of the fetch query function

Note: That the Playbook name cannot be edited after playbook has been added to a package. This is because the playbook name gives rise to a playbook slug which is not editable. It is possible to edit the Status of a playbook except in the case of the playbook being DELETED in which case the entity will not be listed in a package or being INACTIVE.

resultset of the fetch query function

Playbook can be found and viewed inside the package as shown in the image:

resultset of the fetch query function

The playbook can be deleted in the following way:

  • Click on the garbage bin icon the list of entities inside a package.
  • A playbook can be executed depending upon its Status.
  • If the Status is INACTIVE or DELETED, the playbook cannot be executed.
  • If the Status is EXECUTABLE, then the playbook is executed by clicking the RUN icon on the right inside a package and does not return any result on the console.

NOTE: The Playbook name test_playbook123 is used here for demonstration purpose.

resultset of the fetch query function

If the Status is RETURNABLE, then the playbook is executed by clicking the RUN icon on the right inside a package and returns the result on the console.

resultset of the fetch query function

Types of DQL directives in Playbook

Playbooks are used with following DQL directives.

_call directive

_return directive