Posted
Proper naming conventions, using Descriptions and Labels, and more!
This is the first of a multi-part series of posts on Playbooks best practices. There’s a lot of material to cover, and it would be too much for a single post. In Part 1, I’m sticking to the basics – how to use proper naming conventions and how to best use Descriptions and Labels. In the next post, I’ll go more in-depth with things like efficiency tricks and error handling methods.
Recently, I’ve been surveying Playbooks written not only in ThreatConnect, but in various other orchestration platforms, and I have made a few observations that (I think) are worth sharing. I’ve noticed that a lot of Playbooks appear to have been developed in a haphazard manner – with minimal testing, and then activated without them being cleaned up in order to ready them for production.
It’s typical that Playbooks are created through trial and error. And, most likely, the progression of a workflow is modeled from a human process brain dump, which is a perfectly acceptable approach. However, once the Playbook is working, it is still not finished. The next step is to refine the workflow and find efficiencies where human tasks don’t translate directly to Apps (some can be combined in a single App, while others may take multiple Apps). This “refinement” is a critical step to successfully create a production-ready Playbook.
Bottom line, Playbooks should be treated as production-ready automation and orchestration workflows.
With that, let’s dive a bit deeper into some Best Practices!
What’s In A Name?
Your Playbooks should be named in a way that anyone could read the title and have at least a basic understanding of what the Playbook does.
- IP_VT = Bad
- Enrich IP Address with VirusTotal = Good
Not only should you be properly naming your Playbook, but also any triggers and apps used within the Playbook itself. When you introduce an App onto the Playbook Canvas, ThreatConnect will always append a number to it.
In the example above, you can see that we’ve got a pretty ambiguously designed Playbook with no properly named triggers or apps. This can get confusing when you start to build Playbooks that may have 5+ copies of the same app performing different tasks. This will make debugging a nightmare. Save yourself the hassle and give each app a name that clearly describes the task it’s performing.
Below is a screenshot of the same Playbook, but with more intuitive app names. As you can see, it’s much easier to understand what may be going on here, so anyone on the team will be able to get up to speed on the team’s processes at an accelerated pace.
Describing Your Playbooks For Fun And Profit
We strongly recommend using the Description field to full document your Playbook. Producing a Playbook that doesn’t have a Description is actually a detriment to the process and a big oversight. No one wants uncommented code!
An example of a subpar Playbook description (besides a blank one) would be something like:
“VirusTotal Enrichment”.
Although technically accurate, it doesn’t necessarily tell the whole story.
Think about using something like this:
“This Playbook takes a given IP address IOC, enriches it data from VirusTotal’s Enterprise API, and stores the context as additional attributes. Additionally, the Playbook searches for, parses out and stores any related IOCs in ThreatConnect for further analysis.”
Put simply:
- Descriptions should include things like a summary, required dependencies, helpful links, and perhaps some sample data, etc.
- Summaries should include an excerpt on what the Playbook does and how the user will benefit from deploying it. Additionally, it’s very helpful to include any sample use cases that you may have.
Listing any required information and dependencies is also a really great idea as it’s going to help the user decide early on if they’ll even be able to deploy that particular Playbook. If your Playbook uses a paid API endpoint for a particular enrichment service or enterprise security product that requires an API key, definitely note that upfront. This prevents users who don’t subscribe to that product or service from wasting their time (some 3rd party products offer free versions of their service which can be confusing for a lot of people).
If you’re a generous Playbook developer (hint, hint), you can include additional info such as links to third party product information, API documentation, sample data, etc (if applicable). This info isn’t necessarily required and is more of a “nice to have”, but it really rounds out the Playbook and produces a fully finished product that can be more easily consumed by other users.
Don’t Label Me, Bro
Kidding. Label everything!
Labels, as the name implies, can be thought of as tags or keywords. We recommend strongly that you use Labels to organize your Playbooks.
What does the Playbook do? Does it send a binary to VirusTotal’s automated malware analysis solution? Try using the following Labels:
- Malware, Sandbox
Another great use case for Labels is to indicate where a Playbook stands in the development and implementation process. Some basic examples of labels for this are:
- In Design, In Development
- Pre-Production, UAT, Testing
- Production
One thing you’ll want to do is make sure to check and see if said Label already exists (when typing the label, if you get an autocomplete dropdown, use it).
If you have any questions or feedback, feel free to contact us. Also, don’t forget to explore our repository of Playbooks, Playbook Components, and Playbook Apps.