37. Playbooks
This guide describes Lawliet 1.5.13.s (the current release). Screens, commands and procedures may change in later versions; the usage guide is updated with each release. Check the version your server runs under Settings > Platform or with ./lawliet version, and see the Releases page for what changed.
A playbook is an automatic response: "When an alert, a DLP incident or a hunt hit arrives, run these steps. Containment waits for a second signature." It opens a case, collects evidence, adds a review item or sends a notification on its own, and files containment (block, isolate, kill) as an approval request for a person to sign.
Permissions:
| Task | Permission | Four-eyes |
|---|---|---|
| See playbooks and their runs | View the review queue | - |
| Create, edit, enable, dry-run a playbook; ask again for a step's approval | Manage playbooks | no |
| A containment step | - | always, whatever the dual-control policy says |
37.1 How a playbook runs#
- Trigger: one of
| Trigger | Fires on | Filters |
|---|---|---|
| Detection alert | A detection rule raised an alert | Rule (one rule or Any rule), Minimum severity |
| DLP incident | An agent reported a DLP incident | Minimum severity, Only incidents the agent blocked |
| IOC hunt hit | A hunt found indicators on a host | Minimum hits |
- Steps ("Do, in order"):
| Step | What it does | Second signature |
|---|---|---|
| Open an investigation | A forensic case for the trigger, with the trigger as its first timeline event; with a priority | no |
| Collect live-response evidence | Asks the host's agent for the chosen collectors; opens a case first if none is open | no |
| Block the source address | Blocks the trigger's source address on the host | yes |
| Isolate the host | Cuts the host off the network except for Lawliet | yes |
| Kill the process | Kills the process the trigger names | yes |
| Add a review-queue item | An item in the shared work list, linked to the run; with a severity | no |
| Send a notification | To the configured webhook and mail recipients, and the console's bell; with a severity | no |
A step whose module is not licensed is skipped and says why.
Containment steps and their approval#
A containment step never runs by itself. It files an ordinary approval request in the name of the playbook's owner (whoever last saved or enabled it), with the exact command it will send. So:
- the owner's approver pairing applies, and the owner can never approve it;
- approvers see it in Approvals like any request typed in the console;
- once approved, it runs automatically; the owner must still hold Execute containment at that moment;
- the resulting action appears in Defense and can be undone there.
Steps after a waiting one do not wait for it: evidence is collected while an approver is found. Each step commits on its own.
37.2 The Playbooks page#
Path: Playbooks.
- Table: Playbook, Trigger, Steps, Owner, Runs, Last run, Enabled. "(example)" marks a shipped example; "(needs approval)" marks a playbook with containment steps. The Enabled tick box switches it on and off; Edit opens it.
- Runs: Run, Started, Status (running, waiting, completed, failed). Open a run to see each step: pending, done, waiting for approval, failed, skipped, with links to what it created.
37.3 Procedure: create a playbook#
Permission: Manage playbooks. Four-eyes: no (containment steps still need a signature each time they run).
Risk: a loose trigger (for example any alert of any severity) opens a case and sends a notification for every alert. Rollback: untick Enabled and save.
- Open Playbooks and press New playbook.
- Fill Name and Description.
- Under When, choose the Trigger and its filters.
- Under Do, in order, choose a step type and fill its options; press Add step for more. Reorder with Up / Down; Remove deletes a step. Containment steps are marked "needs a second signature".
- Leave Enabled off for now.
- Dry run: choose a Recent trigger (or A sample instead, with a Severity) and press Dry run. "What each step would do with a trigger. Nothing is created, sent or contained." Each step shows "would be done / skipped / waiting for approval / failed" with the reason.
- Press Save playbook.
- When the dry run looks right, edit it, tick Enabled and Save playbook.
What you see: the playbook in the table. When a matching trigger arrives, a run appears in Runs.
If it fails: the form shows the server's message. A dry run step "failed" with "the playbook's owner (<name>) does not hold execute_defense" means the owner cannot file containment; have someone with Execute containment save it.
37.4 Procedure: a containment step is waiting#
- Open the run. The step shows waiting for approval.
- An approver signs it in Approvals. The step runs and turns done.
- If nobody decided before the request expired, the step turns failed and offers Ask again to a user with Manage playbooks: "File the same request again, in your name. Someone else approves it." A rejected request is not offered again.
37.5 Procedure: change, switch off or retire a playbook#
Permission: Manage playbooks. Four-eyes: no. Rollback: switch it on again, or edit it back.
Whoever saves or enables a playbook becomes its Owner: its containment steps are filed in that person's name (37.1). Check the Owner column after a colleague edits it.
To switch it off or on:
- Open Playbooks.
- Untick Enabled on the playbook's row (Enable <name>). It stops reacting to new triggers at once; runs already started finish. Tick it to switch it on again.
To change it:
- Press Edit on the row. The editor opens with its trigger and steps.
- Change the trigger or steps, run a Dry run again (37.3 step 6), and press Save playbook.
To retire it: there is no delete button for a playbook in the console in this release. Untick Enabled; it stays in the list, with its runs, as a record.