Playbook Fridays: OneMillion API Component

Using this Playbook Component, incident responders and analysts can check if a given domain exists on any lists of the most frequently visited hostnames

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.

What?

This week, we are featuring a Playbook Component which finds the rank of a given host in a list of the one million, most visited hostnames. In this post, we are going to introduce why this component is useful, discuss why it is a Playbook Component rather than a Playbook, and show you how to use this component (if you have Playbooks enabled in your ThreatConnect instance, you can create a Playbook to use this component in less than five minutes).

Why?

If a Host Indicator is one of the top million, most visited domains, this usually merits further investigation. It could be that a host in the list is benign (perhaps it is a false positive or perhaps a malware sample calls back to a benign host to test its internet connection or get its IP address). It could alternatively mean that the host is malicious and simply getting a lot of traffic. Either way, it’s helpful to have this information. This Playbook Component, built on the OneMillion API (which is not maintained by ThreatConnect), allows incident responders and analysts to check if a given domain exists on any lists of the most frequently visited hostnames.

Why a component?

Before we talk about how to use this component, let’s address why this system was created as a Playbook Component rather than normal Playbook. The major benefit of components is that you can capture a common process you would like to repeat in multiple, diverse places. For example, if you are making a Playbook which requires you to get the length of a string, you could add apps to get the length of a string to that Playbook, but if you ever need to get the length of a string again, you will have to recreate what you have already done. Instead, if you are creating a generic function or one that you would like to use in multiple playbooks, consider creating a component. A component lets you perform an operation again and again without having to recreate anything (and by the way, there is a component to get the length of a string described here (this site is not maintained by ThreatConnect)). In the case of the OneMillion API Component, it was created as a component so that it is easy to plug into new and existing playbooks.

Using the component

So how do you use this component? In this section, we’ll walk through the installation of the component and will create a Playbook to use the component to show you how easy it is to use components to expand the functionality of a Playbook.

1. The first step is to install the component. You can download it from https://tc.hightower.space/post/playbook-components/onemillion-api-query/ (which is not maintained by ThreatConnect) or download the “Query OneMillion API.pbx” file from GitHub.
2. Once you have downloaded the component, you can import it into ThreatConnect like a Playbook by going to the “Playbooks” tab in ThreatConnect and clicking “New” > “Import” (on ThreatConnect versions before 5.7, you can click the “Import” button). Then import the Query OneMillion API.pbx file.
3. Turn it on and the component is ready to be used!
4. Now that we have installed and activated the “Query OneMillion API” component, we need to create a Playbook to use it. To do this, go back to the “Playbooks” tab in ThreatConnect and create a new Playbook. For this example, we are going to create a Playbook with a User Action trigger that will allow users to submit a host indicator in ThreatConnect to the OneMillion API and return the result with a single click.
5. To build this Playbook, select the “Trigger” tab in the pane on the left and select “UserAction”. This will add the trigger to the design canvas. Now, double click on the new trigger to edit it. Rename the trigger in the “User Action Name” field (this name will show up for users when viewing Host indicators in ThreatConnect). Select “Host” for the “Type” field, click through the next section, and save the trigger.
6. Now, click the “App” tab in the pane on the left and select the “Query OneMillion API” from the “Components” section. If it does not show up, this is probably the “Query OneMillion API” component you installed in step two is not turned on (as we did in step three). Assuming, you were able to find the “Query OneMillion API” component and add it to the design canvas, drag a line from the blue dot on the trigger to the component. Double click on the component to edit it. In the “Host” field, start typing “#” and a list of available options will show up. Select “trg.action.item” (this is the hostname which is captured by the User Action trigger); this means that the hostname from which the Playbook was triggered will be sent to the OneMillion API (if this doesn’t make sense, watch the gif above for a demo that will clarify how this system works). Save the “Query OneMillion API” component.
7. Now, draw a line between the blue dot on the “Query OneMillion API” component and the trigger. This allows us to send information back to the user via the trigger. Double click on the trigger to edit it. Click “Next” to move to the second stage (you should see a text area with the label “Body”). In the text area, start typing “#” (again, this shows you a list of available values you can send back to the user). Select “hostRank” and save the trigger.
8. Turn the Playbook on by clicking the “Active” toggle in the upper right-hand corner.
9. Now for the fun part: using the Playbook! Find or create a host indicator in your ThreatConnect instance. There should be a “Playbook Actions” card on the top-right side of the indicator’s page and it should list the name of the User Action trigger you provided in step five (if you didn’t change the name of the User Action trigger, it will probably show up as “UserAction Trigger 1“). When you click it, the Playbook will be executed and the rank of the host (if there is one) will be returned to the right of the trigger. You now have a Playbook which lets analysts query the OneMillion API!

If you have completed the steps above and would like to contribute your playbook with the trigger in it, there are instructions for contributing to our playbooks repository here: https://github.com/ThreatConnect-Inc/threatconnect-playbooks/wiki/Contributions-Workflow .

If you have any questions or run into any problems with this playbook component, please raise an issue in Github. As always, let us know if you have any questions!