This guide is intended to guide you through the process of contributing playbooks to our content, after they were created through the user interface.
- For general guidelines on how to create playbooks, visit our Creating Playbooks article.
- Playbooks can be be divided into 2 categories depending on their usage. Technically, they are the same, but usage-wise, there are some differences. "Parent" playbooks are playbooks that run as the main playbook of an incident. The other type is "sub-playbooks", which are just playbooks that are being called by another playbook.
Examples of parent playbooks can be
Phishing Investigation - Generic v2, or
Endpoint Malware Investigation - Genericbecause an incident starts with them. Examples of sub-playbooks are
IP Enrichment - Generic v2or
Retrieve File From Endpoint - Generic, because they are steps we take as part of the bigger investigation. What one needs to consider is that since sub-playbooks are used as part of a bigger investigation, they should have inputs and outputs. Make sure that data you want to get from a sub-playbook, is defined in the outputs of it, so it can be used outside of that playbook. Since sub-playbooks are building blocks that will preferably be usable in other playbooks and use-cases, you should define generic inputs for them as explained in our context standards article.
- Test playbooks can be used for testing integration commands individually (checking that they work and return the right inputs/outputs), but in the sense of playbooks - test playbooks should test a certain scenario of the investigation. For example, the test of
Phishing Investigation - Generic v2creates an incident and attaches and email, and then makes sure that the URL contained in the email was found malicious (as it should be).
Your playbooks contain playbook and task descriptions by now and they should be able to run smoothly.
In order to contribute your newly created playbooks, they have to be exported via the "Export" button in playbook view mode:
The playbook will be exported as a YML file. Use demisto-sdk command
demisto-sdk format -t playbook -s <path to playbook yml>against the YML file. The command will modify some fields in the file to normalize it with the rest of the playbooks in our content, and will output a file with the prefix
playbook-in the filename. That is the file you have to use from now on.
If your playbook has a test playbook, copy the ID of the test playbook and declare it as the test playbook of your playbook, like so:
Add your test in the
conf.jsonfile, located in
content\Tests\conf.json. You should add an entry that specifies the integrations needed for your test playbook, as well as specify a timeout in seconds if your test is taking a long time to complete and fails due to timeout (usually not needed). Also, specify the minimum version for your test here (fromversion: 5.0.0).
For layouts, you will also need to create a changelog file:
if a changelog file already exists, just add your release-notes to the "Unreleased" part of the file.
- Remember to include all files relevant to your use-case in the PR. That includes scripts, incident fields, layouts, incident types (if any were created and are used), integrations, playbooks and test playbooks.
- Your playbooks will only be reviewed after finalizing the code-review stage.
- We will review your playbooks and comment for any needed changes.
We value your time and willingness to contribute. Thank you for contributing to our content!