Posted
Playbooks for the Non-Programmer using what else, Star Wars
ThreatConnect developed the Playbooks capability to help analysts automate time consuming and repetitive tasks so they can focus on what is most important. And in many cases, to ensure the analysis process can occur consistently and in real time, without human intervention.
We’ve written lots of Playbook Friday posts. None, though, have explained how to do it if you’re unfamiliar with how to create a Playbook in the first place. It’s a strength of ThreatConnect’s Playbooks feature set that for most use cases, you don’t have to be a programmer. You can do things like parse JSON, as we show in this post, without dipping into Python. So, for those of you who might need the first step – or a refresher – read on…
Overview of APIs
An API (Application Programming Interface) is an interface provided by software services to developers that allows them to perform tasks and retrieve information. In simpler terms, an API is used by other software and a UI (User Interface) is used by humans. By using an API you have a way to automate things that users are doing manually, therefore introducing some time saving.
Retrieving data from an API
We’re going to use the example of retrieving data from the publicly available Star Wars API (of course!). This API provides various data relating to the first seven Star Wars movies.
Building our Playbook
- Choose the data you want to retrieve
After reviewing the API documentation, we decide that we want to retrieve a list of film titles.
Star Wars API Documentation – Films. To retrieve a list of the films and their data, we have to make a call to https://swapi.dev/api/films/. When we do this, we receive a JSON formatted response. This is a human readable format that organizes information in two ways:
- lists (or arrays);
- dictionaries (or key-value pairs).
For more information on the JSON format and how it is used to structure data, see: REST API Tutorial: Introduction to JSON
When we request the films from the API, we get a list of different films, each described in the following format:
In the above format a title key and release_date which we’ll use to display the name of each film in our Playbook as a campaign in the ThreatConnect UI.
- Querying the API in our Playbook
To query the API, we use the following steps in our Playbook:
- HTTPLink Trigger – This is used as the item that starts the Playbook
- HTTP Client – We will provide this with the URL of the StarWars API above
We will also loop the result back from the HTTP Client to the Trigger so that we can see the results.
When we execute this Playbook, the following is returned from the API – the raw JSON – looks like this:
This JSON response is difficult to read when returned from the API. Remember, this wasn’t designed for a human to read or interact with so we have a few different ways to make this useable for now. The first option is a Chrome Extension – https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en which will show a button to click in your browser to make this readable:
Another option is to paste it into a JSON formatter website such as https://jsonformatter.org/
- Copy the JSON text
- Paste the JSON into the main editor window
Click the formatter icon at the top left. 
3. Find the data you want to retrieve
We want to retrieve title of each movie. From the API response, we can see that:
- there is a dictionary with a key called results;
- the value of results is an array of films;
- each film is its own dictionary or object; and
- the name of the movie is stored under the title key in that dictionary.
For example:
{
“count”: 7,
“next”: null,
“previous”: null,
“results”: [
{
“title”: “A New Hope”,
“episode_id”: 4,
…
}
We want to retrieve the title and release date for each film by using JMESPath to filter out the result set that we want.
To do this piece we’ll need to use JMESPath or JSONPath. You can use either to do this but JMESPath is preferred over JSONPath and will be the one we use for this demonstration. Navigate in your browser to https://jmespath.org/ and paste in your JSON Content.
Since we know from the formatted output that the data we want is in the “results” dictionary, we put that into JMESPath’s website:
So far so good; but not exactly what we are going for yet. We filter down further to just the titles and release date. Because this is a dictionary and we don’t want to pull out a single item, but instead want every item in the dictionary, we have to put an empty open and close bracket [ ] to our query before we can filter further, like the below:
We can now target “title” like the below by specifying our query as “results[].title” and the release date with “results[].release_date”.
4. Capture the data in Playbooks
Great! We have the titles and release date! Now let’s modify our Playbook to capture this information. To do this, you’ll need to add the Playbook app “JMESPath” into your Playbook:
Then in the “JSON Data” area, pass in the HTTP Content:
Then in the “JMES Path StringArray Expression” area input the query and assign it a “variable” or Key name such as “titles” and “release_dates”:
5. Saving the data
Now let’s save our extracted data as Campaigns!
This part is pretty simple. Add the step “Create ThreatConnect Campaign” and then there are two required fields, notated with “*” those are: “Campaign Name” and “First Seen”.
Use “titles” and “release_dates” for each respectively.
6. Viewing the data
After a successful execution of the Playbook, you should now see the Campaigns (aka “titles”) and their “creation date” inside of the Browse page in the source defined in the “Create ThreatConnect Campaign” step.
Congratulations! You’re on your way to creating all the Playbooks!
