Phantom Function Exploration: extract_regex

Welcome to the Phantom Function blog collection’s inaugural post. In this series, Steve McMaster and Austin O’Neil are going to explore a number of useful custom functions we’ve built at Hurricane Labs in order to increase the accessibility of playbook development. The sky’s the limit when it comes to what you can do in Phantom, but often the limiting factor is whether the actions and functions exist in Phantom to do what you want and, if not, whether you have the Python skills necessary to create them.

We’re going to open the series with a particularly versatile function, aptly named extract_regex. This function does what you’d expect it to do–given a string and a regular expression, it returns the matches to you. It supports all of the features of the Python regular expression library, and it will return groups to you as both numbered groups and as named groups. 

To the code!

Let’s jump right into reviewing the code:

As you can see, there’s not a lot to this function. The function takes two inputs–input_text and regex–and outputs two data paths: groups and groupdict. 

We’re utilizing re.search rather than re.match as a convenience to anyone using the function; the difference is that re.match forces the pattern to match at the start of the input, whereas re.search can apply to any part of the input. Regex flags are supported using the standard Python syntax for them, which we’ll outline in our examples. The outputs are provided as a list in the groups data path, and as a dictionary in the groupdict data path. We expect that the groupdict data path will be used far more often, but both are available for any times where the list might be needed instead. Match groups can be accessed by other actions in the playbook by referencing groupdict.group_name, which you will see in some of our examples.

This function can be very useful in a number of situations where the text you need is embedded within a larger block of text. Some example scenarios include:

• Extracting a hostname or IP address from a URL
• Extracting a file name from a file path
• Extracting artifacts from an email container
• Passing values to a condition to take action only if a pattern is matched

Here are a few configuration examples showing how you might configure the function: