Playbook is a web application available for installation on Manager nodes. Playbook allows you to create a Detection Playbook, which itself consists of individual Plays. These Plays are fully self-contained and describe the different aspects around a particular detection strategy.

The key components of a Play are:

  1. Objective & Context - what exactly are we trying to detect and why?
  2. What are the follow-up actions required to validate and/or remediate when results are seen?
  3. The actual query needed to implement the Play’s objective. In our case, the ElastAlert / Elasticsearch configuration.

Any results from a Play (low, medium, high, critical severity) are available to view within Hunt or Kibana. High or critical severity results from a Play will generate an Alert within TheHive.

The final piece to Playbook is automation. Once a Play is made active, the following happens:

Getting Started

You can access Playbook by logging into Security Onion Console (SOC) and clicking the Playbook link. You will see over 500 plays already created that have been imported from the Sigma Community repostory of rules at

Creating a new Play

Plays are based on Sigma rules - from

Sigma is a generic and open signature format that allows you to describe relevant log events in a straightforward manner. The rule format is very flexible, easy to write and applicable to any type of log file. The main purpose of this project is to provide a structured form in which researchers or analysts can describe their once developed detection methods and make them shareable with others.

To create a new play, click on the Sigma Editor menu link. Either Load a sample Sigma rule or paste one into the Sigma field and click Convert. This will convert the Sigma into a query that you can use in Hunt or Kibana to confirm that it will work for your target log.

Refer to Log Sources & Field Names for details around what field names to use in the Sigma etc.

Once you are ready to create the Play, click Create Play From Sigma. If the Play creation is successful, you will be redirected to the newly created Play - it will have a status of Draft.

The lifecycle of a Play is as follows:
  1. Draft (Initial state)
  2. Active (In Production)
  3. Inactive (Temporarily moved out of production)
  4. Archived (Play has been superseded/retired)

A Play can also have the status of Disabled, which means that it is broken in some way and should not be made Active.

Editing a Play

Click on Edit to edit a Play. There will only be a few fields that you can modify - to make edits to the others (Title, Description, etc), you will need to edit the Sigma inside the Sigma field. Keep in mind that the Sigma is YAML formatted, so if you have major edits to make it is recommended to lint it and/or Convert it through the Sigma Editor to confirm that it is formatted correctly. Be sure to remove the prepended and postpended Playbook-specific syntax highlighting before linting/converting - {{collapse(View Sigma) <pre><code class="yaml"> and </code></pre>}}.

Once you save your changes, Playbook will update the rest of the fields to match your edits, including regenerating the Elastalert rule if needed.

Putting a Play into Production

When you are ready to start alerting on your Play, change the Status of the play to Active. This will create TheHive case template & the ElastAlert config. Any edits made to the Play in Playbook will automatically update the ElastAlert configuration and TheHive case template.

The Elastalert rules are located under /opt/so/rules/elastalert/playbook/<PlayID>.yml. Elastalert rules created by Playbook will run every 3 minutes, with a buffer_time of 15 minutes.

Performance testing is still ongoing; initial testing has shown that on a lightly-used Standalone install with 16GB of RAM (4GB allocated to the Elasticsearch Heap), 300 Plays can be active without issues.

Viewing Playbook Alerts

When results from your Plays are found (ie alerts), they are available to view within Alerts.

User Accounts

By default, once a user has authenticated through SOC they can access Playbook without having to login again to the app itself. This anonymous access has the permissions of the analyst role. If you need your team to login with individual user accounts, you can disable this anonymous access and create new user accounts and add them to the analyst group which will give them all the relevant permissions.

If you need administrator access to Playbook, you can login as admin with the randomized password found via sudo salt-call pillar.get secrets. However, the Playbook UI is designed to be used with a user that has an analyst role. Using an admin account will be very confusing to newcomers to Playbook, since many of the fields will now be shown/editable and it will look much more cluttered.

Misc Notes

Every 5 minutes, so-playbook-sync runs. This script queries Playbook for all active plays, and then checks to make sure that there is an ElastAlert config and TheHive case template for each play. It also runs through the same process for inactive plays.

Log Sources & Field Names

Sigma support currently extends to the following log sources in Security Onion:

The pre-loaded Plays depend on Sysmon and Windows Eventlogs shipped with winlogbeat or osquery.

For best compability, use the following Sigma Taxonmy:

The current Security Onion Sigmac field mappings can be found here:

Adding Additional Rulesets

As previously mentioned, the pre-loaded Plays come from the community Sigma repository ( The default config is to only pull in the Windows rules. The rest of the rules from the community repository can be pulled in by editing a pillar value under /opt/so/saltstack/local/pillar/global.sls

  • windows

Add one or more of the following:


These are based on the top level directories from the Sigma community repository rule’s folder.

Next, restart SOCtopus (so-soctopus-restart) and have Playbook pull in the new rules with so-playbook-ruleupdate - this can take a few minutes to complete if pulling in a large amount of new rules.

Diagnostic Logging

Playbook logs can be found in /opt/so/log/playbook/.