This document provides information on a potential approach that can be used to generate in-platform HTML reports within the ThreatConnect Playbooks system (though this approach could be used within a Playbooks App as well). This document is primarily applicable to someone implementing a Integrations - Low-Volume Alerts Processing Description or Integrations - On-Demand Enrichment Description integration.
While enriching information and driving processes is useful within the ThreatConnect Platform, it is sometimes also desirable to have a report available that provides additional context or information that may be delivered to users outside of the generating organization. For this reason, we’ve provided guidance here on how to formulate an HTML report in-platform via the Playbooks system.
This guidance assumes that you’ve already properly parsed the pieces of information that you desire. There’s also an assumption that you wish to compile a report that contains multiple elements of the same kind.
This guidance assumes that you’ve already properly parsed the pieces of information that you desire. There’s also an assumption that you wish to compile a report that contains multiple elements of the same kind.
You will find the example Playbook referenced in this document here on GitHub.
Before getting started on any logic, you should take time to define what information you want to show. You should ensure that the Playbook Apps you intend to use for this process are capable of providing the information you want to display and that it is in an acceptable format.
For the purposes of an example, we’ll be using a small collection of data for our in-platform reporting:
File Hash
Description
Abstract Statement
You should work through a design process to establish the template. This is done outside of the ThreatConnect Platform and typically just consists of creating an HTML5 document. Here are some design considerations:
Keep your design simple to keep the actual HTML payload size low.
Plan to avoid using embedded images. Linked images will work properly but the content must be hosted outside of the ThreatConnect Platform in most instances.
Plan on using an embedded style-sheet for simplicity.
Plan on using simplistic styling to keep the payload size low.
Plan to split your template into three parts: header, body, and footer (optional)
NOTE: This doesn’t refer to the HTML elements but rather the way the template is used. All static content before (header) and after (footer) and then dynamic content (body).
You will typically construct your report template together as a single HTML document and then split it when you put it into practice (to ensure that it is congruent and works properly).
The full HTML template document is attached to this article. You can download it from below:
This example has many of the elements mentioned above for your convenience. See the comments that denote the split between the Header, Body, and Footer for the template.
Once you’ve established a report template, you’ll want to prepare things for use in a Playbook:
Copy your existing template over to a new file (report_template_actual.html in our example instance).
Insert variable placeholders for things that you plan to update dynamically. A simple syntax you can follow for this that shouldn’t interfere with anything else is %VARIABLE_NAME%
.
NOTE: It’s not extremely import what syntax you follow here as you’ll be doing a simple find/replace. For this reason, you just need to make sure your strategy allows you to have replaceable, unique values.
Remove any additional instances of things you had in the original template (such as multiple body elements to represent additional data for viewing purposes).
For convenience, we’ve provided the file we’ve created using the process above that allows you to compare with the template above:
The next step is that we must begin integrating this data into a Playbook. Follow the steps below (which basically walk you through the entire example Playbook):
There is a maximum of 4000 characters allowed within a Playbook input parameter. Because we will use Playbook input parameter to store the template components, you’ll need to break-up your data items into exactly 4000 character chunks if a particular section (such as the header) extends beyond this limit.
There is a maximum of 4000 characters allowed within a Playbook input parameter. Because we will use Playbook input parameter to store the template components, you’ll need to break-up your data items into exactly 4000 character chunks if a particular section (such as the header) extends beyond this limit.
Ensure that you have your data in a ready-to-go format for this process. You should at least have StringArrays of equal length that can be used to generate the dynamic portions of your report.
In the example we’ve put together, we get our example data from parsing a JSON blob into a few items:
report_title
- String
file_hashes
- StringArray
names
- StringArray
abstracts
- StringArray
We’ll use the ThreatConnect Set Variable
app to generate multiple variables to hold the different elements of your report_template_actual.html
file.
In the example we’ve put together, we’re using template_header
, template_body
, and template_footer
as variables.
If you have large amounts of data, you can break them into multiple variables and then marry them back together as a single variable for convenience.
We use an Iterator to loop over the 3 StringArray items and provide the single value from each array for each instance of the loop.
Within this loop, we call the Find and Replace
app for each dynamic item we need to replace. In our instance, we have 3 dynamic items. Our input text for the first item is the template_body
variable. For the remaining items, it will be the output of the preceding Find and Replace
app (to accumulate our changes).
This is the step where we define the name of the variable to replace for each piece of data also.
Also as part of the definition of the Iterator, we capture an output String of the final Find and Replace
app’s output for each instance of the loop (which generates a StringArray).
We can generate the report header using a single Find and Replace
app as we only have one dynamic item there.
We can flatten all of the report items together using the Join Array
app with an HTML comment as the delimiter. This produces a String that we can now use in the final report data.
We use the String Operations
app with the Append
operation to join our various report elements together into a single String. In our instance, we have to do this twice because we have 3 elements.
We take the Find and Replace
output for the template_header
and use it as the input for the first item. We append the flattened report items.
We take the previous operation’s output and append the template_footer
(which contains no dynamic content and therefore is used directly).
At this point, we now have a useful String populated with our HTML report. However, the Platform expects this data as a Binary value instead of a string. We use the Binary Operations
app with the action Convert from String
to convert this appropriately.
Finally, the output from the Binary Operations
value is used in the Create ThreatConnect Report
app to store a copy of the file in the Platform.
You will want to create a unique name for the Report Name
field if you are looking to generate a report regarding transient events. In our example, we used the gbl.timestamp.iso
variable to establish a unique title.
You will need to supply a filename for the report. If you intend for people to regularly download the reports, do them a favor and make sure the name of the file is unique-per-report. The gbl.timestamp.epoch
is an easy item to use in the filename for a unique name.
Supply the binary report data into the Report Data field.
The Owner field will be configured upon use for the Playbook so it isn’t necessary to try to set this to a particular value.
Remember to apply any Attributes, Tags, or Associations that make this report useful (see References - Threat Intelligence Data Mapping for thoughts).
Your logic flow is now complete and you should now be able to generate a report in-platform. If you plan on incorporating this report logic into multiple Playbooks, it’s very much appropriate for you to consider using a Playbook Component for this purpose. This will allow you to create re-usable logic for reporting. In addition, this reporting could be expanded to include multiple sets of dynamic data for sections and other tasks.