Skip to main content
Lantern Home

 

Splunk Lantern

Using a documentation-as-code approach to playbook development

  1. Last updated
  2. Save as PDF

Documentation of any security tooling is a critical yet time-consuming factor, and Splunk SOAR especially can create a heavy documentation burden. Playbooks, apps, custom functions, and other configuration items need to be documented in detail to ensure the solution is maintained and functional. 

Fortunately, Splunk SOAR natively supports a documentation-as-code approach for playbook development to minimize much of this effort, allowing for the documentation to automatically be populated as the playbook is developed.

How to adopt a documentation-as-code approach with Splunk SOAR 

The main factor to be mindful of when establishing processes for your SOAR documentation is that all SOAR playbooks are natively stored in a Git-based repository. This allows you to not only achieve strong version control of your playbooks, but to also bake-in your documentation in the process.

In order to realize this within SOAR, there are a few different features within SOAR that need to be utilized:

  • Names: function name
  • Descriptions: code comments
  • Notes: block tooltip

Each of these is covered in more detail below, and shown in the color-coded screenshot.

Block Name (blocked off in pink in the screenshot)

The 'custom name' attribute should always be populated with a detailed and logical format that identified the function of the block. This will provide SOAR with a function name at a code level, that should be set properly as the first part of a documentation-as-code approach. Note that this is not enforced, as SOAR will provide a generic 'action block 1' name as a default value.

Reviewing the below screenshot, we can see the function has been uniquely named through the custom name attribute, which is reflected in the code editor below as the underlying function name.

Block Description / code comment (blocked off in orange in the screenshot)

This is the most critical attribute to update. It provides in-line code comments that can be viewed both in the Visual Playbook Editor (VPE) and in the source control/code repository when viewing the raw playbook code. A detailed description of what the block does, what its dependencies are, the inputs and outputs, and any other supporting information should be placed here.

Reviewing the example screenshot we can see a detailed description has been added, which is automatically reflected in the code comments below. 

Notes / block tooltip (blocked off in purple in the screenshot)

This is the final component, and could be considered optional but should always be used when playbook complexity is high or when multiple developers are working on a single playbook. This attribute allows you to add a tooltip that can be hovered over within the VPE to gain more context as the function of a block. 

This is particularly useful for placeholder information when debugging, or when information about specifics of block input/output need to be shared with other developers. Another good approach is to include a concise summary of the block actions, as seen in the screenshot below, which has the notes attribute populated, and the tooltip expanded by hovering the mouse over it.

soar-documentation-as-code.png

Summary

If you adhere to this methodology for all playbooks you develop, the time spent creating and maintaining documentation drops to virtually zero as all of this is completed in real time as the playbook is developed.

As SOAR uses a Visual Playbook Editor (VPE), the playbook can be structured in a logical flow that can be easily exported as a screenshot to supplement any other additional documentation requirements.

Additional resources

This article is one of many in a series on using SOAR automation to improve your SOC processes. Check out the additional playbook guidance or some of the links below to continue getting more value out of Splunk SOAR. 

  • Written by Richard Hampshire, Security Architect at Splunk and Matthew Bennett, Managing Director at Hyperion3