Creating Cognitive Playbooks

The core of DarkLight’s functionality is through the reasoning components, called Cognitive, or Programmable Reasoning Object (PRO) Playbooks. The purpose of these are to make inferences on sets of data whether contextual, working, or both. Each Playbook encodes the logical thought process used by an analyst and uses the power of ontologies to add data-typing and reasoning to incoming events.

Playbooks are created using the built-in PRO Playbooks perspective, which uses the following views:

  • PRO Playbook Manager - lists all Playbooks in the workspace and lets you open one for editing.
  • Playbook Editor - the edit window for a Playbook, showing how steps connect together.
  • Step Editor - the edit window for the selected step from an open Playbook.
  • Inventory - when a sample file has been loaded into an open Playbook, this shows the contents of the data package for each step as it flows through the Playbooks.

Watch this two-minute movie for a quick overview on how to create, open, edit, and organize playbooks.

  1. Click the New Playbook button in the PRO Playbook Manager
  2. The PRO Playbook Editor will open with the name "Untitled" pre-filled. Click on the name to change it
  3. Click Save PRO Playbook in the bottom-left corner of the window to save your changes to the PRO Playbook Manager
  • Click the Create New Folder icon and give the new empty folder a name.
  • Drag one or more playbooks (use standard Shift and Control/Option modifier keys to select multiple) into the folder
    • Control/Option-drag a playbook to drag an alias of the playbook into a folder
    • Playbooks can exist in more than one folder at a time. These are not copies of the playbook. Any change to one will change any other references.
  • Right-click a folder or click a folder and use the triangle menu for more options like sorting, removing from folders, and expanding/collapsing all items
  • Remove from Folder is only available when a playbook is in more than one location. Removing a playbook from one folder does not effect the other references to it.
  • Delete will delete the playbook itself, which means all references to it in other folders will be deleted as well.
  • Folders can also be dragged onto other folders
  • The icon of the folder shows the status of the playbooks inside it, with errors and warnings taking priority
  • The checkbox shows the state of the items inside it, either checked, unchecked, or both.
    • Clicking the checkbox checks all playbook and folder checkboxes inside it.

PRO Playbooks are made up of multiple steps which can be assembled in many different ways to achieve the goals of the playbook. As the data package flows through the steps of the playbook, it uses the logic inside the individual steps to know which step(s) to go to next. Each step answers a TRUE + / FALSE - question and sends the package to the step or steps attached to the corresponding side of the step. Note that unlike strict decision trees, the output of a step can also be BOTH v represented by the icon in the center of the step.

Adding the First Step

With a playbook open, click on the Add to Step IF TRUE button in the menubar of the Playbook Editor. A "Create Step" dialog will open that shows all of the available steps, separated into categories. All playbooks must start with one or more of the steps in the Input category.

  • Ingest refers to one of the Data Feeds that brings data into DarkLight.
  • Playbook is used when starting a sub-playbook that will be called by another playbook.
  • Schedule refers to a Data Feed of type "Schedule" with a configured cron pattern
  • Subscribe is used by playbooks that receive data from another playbook that has Reified and Broadcast the package.

Connecting Steps Together

When a step is highlighted in a playbook, its configuration is shown in the Step Editor view. The name of the step can be customized, and a description can be entered in the box below the name.

At the bottom of the Step Editor are two boxes that have Add a Step buttons. Use these to add a new step to either the TRUE or FALSE side of the step. New steps can also be added by using the + and - buttons at the top of the Playbook Editor. For example, the Ingest step does not have a False side, so you'd add the next step to the true side. A Filter step, however, will either match true or false, and the package will travel out the corresponding side.

Invalid Link
The top of the Create Step list includes a section highlighted in yellow. These are steps that are already in your playbook. Only the steps that are children or siblings of the current step are shown, to prevent an endless loop.
Invalid Link
If you want the package to continue on to the next step regardless of the outcome (for example, a Query Database step where you don't know if there will be a result), connect the next step in the chain to both the TRUE and FALSE sides.

To remove a link from one step to another, click on the parent step to load it into the Step Editor, and then click the red x at the bottom of the step editor view next to the step you want to remove the link from. Any steps that are no longer linked to other steps will sort to the top-right corner of the playbook.

Copy and Paste Steps

If you have a configured step that you would like to use in another playbook, you can select one or more steps, copy them to your system clipboard, and paste them into another playbook. Links between steps will remain connected as they were. If you select a step before you paste, the copied steps will be attached to the TRUE output of the selected step. If you do not select a step before you paste, the copied steps will appear in the top-right of the playbook flowchart.

  1. Select one or more steps by clicking on a single step, or dragging a box around multiple steps. Highlighted steps turn light blue.
  2. Click the Copy icon in the menubar, or choose Copy Step(s) from the drop-down menu.
  3. In the target playbook, select one step you would like the copied steps attached to. (This step is optional)
  4. Click the Paste icon in the menubar, or choose Paste Step(s) from the drop-down menu.

The copied content is JSON

Nerdy Note: When you copy a step, all of its configuration settings are stored in the JSON that the playbook uses when it saves its configuration. This means that a copied step can be transferred as text to another system and pasted into a different version of DarkLight. It also means that the configuration of the step can be manually edited in text before pasting (but we don't recommend you do that).

See Also:

  • help/about_pros
  • Last modified: 2019/07/16 17:56