Overview

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 https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/148963329 or https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/4522021 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.

Example Playbook

You will find the example Playbook referenced in this document here on GitHub.

Planning Your Report Data

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.

Report Data Example

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

Planning Your Report Template

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).

Report Template Example

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.

Implementing the Template using Playbooks

Once you’ve established a report template, you’ll want to prepare things for use in a Playbook:

1. Copy your existing template over to a new file (report_template_actual.html in our example instance).

2. 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%.

   1. 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.

3. 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):

1. 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.

   1. In the example we’ve put together, we get our example data from parsing a JSON blob into a few items:

      1. report_title - String

      2. file_hashes - StringArray

      3. names - StringArray

      4. abstracts - StringArray

2. We’ll use the ThreatConnect Set Variable app to generate multiple variables to hold the different elements of your report_template_actual.html file.

   1. In the example we’ve put together, we’re using template_header, template_body, and template_footer as variables.

   2. 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.

3. 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.

   1. 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).

   2. This is the step where we define the name of the variable to replace for each piece of data also.

   3. 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).

4. We can generate the report header using a single Find and Replace app as we only have one dynamic item there.

5. 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.

6. 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.

   1. 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.

   2. We take the previous operation’s output and append the template_footer (which contains no dynamic content and therefore is used directly).

7. 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.

8. 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.

   1. 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.

   2. 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.

   3. Supply the binary report data into the Report Data field.

   4. 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.

   5. Remember to apply any Attributes, Tags, or Associations that make this report useful (see https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/301006858 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.