References - Playbook Output Variable Naming Schema

Owned by John Hall (Unlicensed)
Feb 20, 2020

Overview

This document is intended for the technical audience building an integration with the ThreatConnect Platform. This document is most applicable to someone building an On-Demand Enrichment integration and provides specific instructions for how name output variables.

Follow the steps in this document in the order provided in order to implement this configuration within your integration.

Variable Naming Schema

Playbook Components and Apps must make use of an appropriate variable naming schema in order to remain consistent across the various implementations in the ThreatConnect Platform. This is an important factor to ensure a fluid process for Playbook authors.

The naming schema is broken-up into these parts:

<App Slug>.<Data Type>[.<Sub Type 1>][.<Sub Type 2>].<Descriptor>[.<Content Type>]

Name parts enclosed in brackets [] are optional. All other fields are required. Avoid the use of camelcase and make use of the underscore (_) in place of spaces to improve readability. The table below defines the schema for output variable names:

Name Part

Required

Description

App Slug

Yes

A concise, lowercase name for your App
(Example: tc for ThreatConnect, sl for SecuLast).

Data Type

Yes

The type of data included in this output variable
(Example: indicators, results, response, document).

NOTE: The data type response should be used for data that comes directly from the response of the remote source. The data type results should be used for data that comes from processing the response.

Sub Type 1

No

An optional sub-type for the data
(Example: address, host).

Sub Type 2

No

An optional sub-type for the data
(Example: tags).

Descriptor

Yes

A description of the data included in the output variable
(Example: count, groups, message, code, <number>)

Content Type

No

A description of the content of the data
(Example: csv, json, zip, pdf)

Name Examples

  • sl.results.count

  • sl.results.address.count

  • sl.results.address.0

  • sl.results.address.tags.count

  • sl.document.address.report.pdf

  • sl.indicators.address.groups.csv

  • sl.response.host_scan.message

  • sl.response.json.raw

Single vs Multiple Outputs

For Components or Apps that accept multiple inputs (such as a StringArray), follow these guidelines in structuring your outputs:

  • If you accept a StringArray input, you should always return a StringArray output if there is any chance that you will return more than one result (even if you are only returning one result).

  • If there is a high likelihood that you will return a single output on a regular basis, you may optionally add a convenience String variable named in this way to return the first result only:

    • Output StringArray: sl.results.dates

    • Output String (convenience): sl.results.dates.0

  • It is discouraged to reuse the same variable name for multiple types. For example, if you could return a different output based on an input parameter, these should be split into separate names:

    • Discouraged Example:

      • sl.results.scan.data (String or Binary)

    • Encouraged Example:

      • sl.results.scan.data_string

      • sl.results.scan.data_binary