Adaptable Incident Response With Splunk Phantom Modular Workbooks

Splunk Phantom is a security orchestration, automation and response (SOAR) technology that lets customers automate repetitive security tasks, accelerate alert triage, and improve SOC efficiency. Case management features are also built into Phantom, including “workbooks,”  that allow you to codify your security standard operating procedures into reusable templates. Phantom supports custom and industry-standard workbooks (like NIST 800-53) that can help divide tasks into phases, assign responsibilities to team members, and document your work. 

However, no single end-to-end workbook can be a “one size fits all” for every investigation of a particular security incident. For instance, one phishing workbook cannot be expected to capture every possible permutation of tasks for every phishing investigation. Some real-time task modification may be required to adapt to unforeseen circumstances. 

That’s why “modular workbooks” are available in Phantom, allowing you to effortlessly adapt your security operations workflow. Rather than creating all-encompassing end-to-end workbooks that strictly define every single task, modular workbooks allow you to create task modules and combine them in different ways to complete your investigation process. This not only enables more dynamic run-time assignment, but makes workbooks more adaptable and scalable across a variety of use cases. 

Modular workbook development is a design pattern for increasing the flexibility of Phantom workbooks by implementing a modular approach to their design, and then leveraging playbooks and custom functions (new in Phantom 4.9) to describe Standard Operating Procedures (SOPs) in a dynamic way.


Let's start the discussion by looking at an example. The screenshot below shows a Phantom workbook that may be used for a scenario where a user's device was stolen.

As you can see, the workbook outlines the appropriate response steps. This is an adequate first step, but over time you might come to realize there are other possibilities beyond just bricking the device.  

For example, what happens if we can't brick the device because it wasn't encrypted? What if the device has sensitive information on it?

We've come up with the following workflow to more fully represent the "stolen device" use-case:


From this flow chart, it should be clear that some actions should only be performed under certain circumstances. How do we represent this in a workbook? One way is to build out condition phrasing in our workbooks, like the following screenshot.

Here we can see that one could represent the logic by having “phases” represent outer conditions (e.g. "ENCRYPTED DEVICES", "UNENCRYPTED DEVICES").

But this doesn't scale particularly well for sub-conditions, so we represent those as 'IF' conditions within the text of the phase's tasks (e.g. 'IF SENSITIVE DATA:'). 

The problem with this design pattern is that it leaves decisions up to analysts about what they should be doing rather than simply defining the tasks that they must be doing (based on the reality of the event, as opposed to theoretical possibilities).

So, how can we better capture SOPs with branching conditions like those described above? With modular workbooks!

The work described below has a few moving parts that I'll outline here:

  1. Workbooks are decomposed to their constituent parts
  2. A custom function is used to dynamically add workbooks to an event
  3. Playbooks are used as controllers for dynamic workbook creation

Workbook Decomposition

What I mean by “workbook decomposition” is that phases/tasks that may be reused in multiple workbooks (e.g. "Secure Account") should be isolated into their own workbook. Why? Because this allows for a single source of truth for a particular set of actions. In the case of “Secure Account,” we might use that in phishing investigations, stolen devices, terminations, compromised credentials, etc. We don't want to represent all the things that comprise "Secure Account" in multiple workbooks. Instead we'd like to have a single workbook that can be composed into the larger contexts of those other use cases. When a change is needed to the "Secure Account" process, it can be implemented in the modular workbook once, and will be correct in all future workbooks that utilize it. 

A modular workbook for "Secure Account" might look like the following screenshot. Note: I adopted a naming convention of "m_" for workbooks that are "modules" and should be composed together to solve a complex problem. 

In the above example, we have a few steps:

  1. Generate a secure password
  2. Set account to this new password
  3. Revoke tokens (e.g. devices with log-lived OAuth2 or similar tokens)
  4. Text the user to call the service desk

This is a modular workbook that by itself is the codified, living standard of our company's policy with regard to securing an account. It is described one time, and then used anywhere the description is needed — giving us a single source of truth.

We will similarly have other modular workbooks. For example:

  • m_SecureAccount (described above)
  • m_BrickComputer (deleting the encryption keys so the device can never be decrypted)
  • m_ContactLegal  (In the event of a violation or risk of the type that legal must be involved, the process to do so correctly)
  • m_FilePoliceReport
  • m_FileInsuranceClaim
  • m_ProvisionDevice  (e.g. Opening a ticket with procurement to get a new laptop)

Some of these may be used in other cases which, of course, is the whole point. We build modular workbooks and use them like building blocks to create a larger structure.

Custom Functions

To achieve our goal here, we need but a single custom function. As a brief refresher, custom functions were introduced in Phantom 4.9 and provide many features and benefits over the legacy custom code blocks, most importantly for us: reusability. You can find more detailed information about those here. For this discussion, I will assume that you have some familiarity with them.

The function I am using looks like this:

With this custom function in place, we are now ready to start building controller playbooks.

Controller Playbooks

How do we get the information about the status of the device (e.g. Is it encrypted? Did it contain sensitive information?)? This depends on your workflow and the upstream data available to Phantom. In my experience, a stolen/missing device is more frequently reported via a panicked phone call from an airport. In those situations, maybe the best approach is to have the playbook simply prompt for those answers.

It is possible that those answers could be provided from an upstream system — maybe the user called the service desk first, or maybe there is some automation that Phantom can run to determine some or all of the answers (e.g. if a BitLocker key exists for the device). I will not describe those steps here as they are substantially similar (although if there is interest, I may write another blog to cover some of those concepts).

Finally, we could design our playbooks to do both: prompt if data isn't available and act upon it if it is.

For a prompt-based playbook that represents the flow-chart above, we have this:

You can see the playbook closely matches the original flow chart describing our behavior.

In this case, when the playbook runs, it will immediately add the m_SecureAccount modular workbook and prompt the analyst for information so other modules are added as appropriate. In broad strokes, this is how you can use custom functions and the modular workbook design pattern to flesh out your SOPs in a way that is more dynamic and flexible than static workbooks.

Check out our Tech Talk: Adaptable Incident Response with Splunk Phantom Modular Workbooks, to see this functionality in action. Please feel free to reach out with any questions or comments in our Slack community, on Splunk Answers, or email me directly.

Sam Hays
Posted by

Sam Hays

For the last 20 years, I have been responsible for engineering projects across Security, IAM, Automation & Development, and Infrastructure design and implementation. During my tenure at Splunk I have spent time with our user community, product management, and engineering teams. Today I work as a Senior Software Engineer focused on the some of our internal and user-facing technologies.