Integrations - Documentation and Media

Owned by John Hall (Unlicensed)
Last updated: Nov 18, 2020
2 min read

Overview

This document explains the expectations around Documentation and Media that should be met when completing an integration with the ThreatConnect Platform.

User Documentation

In order to increase the usability of your integration, we request that you supply User Documentation. The target audience for this documentation is typically ThreatConnect users, Platform administrators, and internal ThreatConnect resources. Each integration must have accompanying documentation addressing these points:

  1. A description of the integration along with at least one high-level use case.

  2. A change log for future updates based on the version of the integration being released.

  3. A list of requirements in order to use the integration. This should specifically include:

    1. Any requirements for subscription/service-level within the third-party platform.

    2. Any requirements within the ThreatConnect Platform (dedicated/on-prem instance, etc).

  4. A set of instructions on how to install and/or implement the integration.

  5. A set of instructions on how to configure the integration including instructions for the ThreatConnect Platform if required for particular setups (custom attributes or indicator types).

  6. A set of instructions on how to use the integration including screenshots and at least one practical example.

  7. Instructions on how to contact you for support/assistance with the integration.

    1. This may be used by customers or by ThreatConnect resources to report any issues.

    2. You can refer to a portal or other site that provides information on this.

For Playbook Apps, the built-in Help Note and App Note (in the project Metadata) should be used to provide context to your integration and each parameter. These details can be summarized in your User Documentation along with a reference to these other fields.

For Playbook Components, the built-in Description should be used to provide context to your integration. These details can be summarized in your User Documentation along with a reference to the Component description.

Based on delivery (see https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/4587531), documentation must be provided in one of these formats:

  • Any In-Platform Integration Technology: A PDF (preferred) or README.md (Markdown) file published with the package.

  • Non-ThreatConnect Technology: A public-facing knowledge base or blog article on the Partner’s website.

Integration documentation must be available to ThreatConnect at any time to gather information. This documentation should remain public-facing, if possible. Additionally, this documentation must remain up-to-date and is the responsibility of the Partner. You are encouraged to include screenshots in your documentation for easier reading.

In-Platform Installation Instructions

Installing in-platform integrations in ThreatConnect should rely on the ThreatConnect-provided instructions. For your user-facing documentation, you can use the quotes in the sections below based on the technology in use.

Runtime or Playbook Apps

For installation instructions, refer to the ThreatConnect System Administration Guide (Install an App). For more information, contact your ThreatConnect Customer Success representatives.

Playbook Components or Templates

To install this Playbook Component or Template, visit the Playbooks tab within the ThreatConnect Platform. Select New > Import and locate the PBX file you wish to add to your system. Follow the on-screen instructions to complete the import.

Integration Video

For all integrations other than the Threat Intelligence Feed, you may supply brief video of your integration for use by ThreatConnect internally. This provides an easy way to disseminate high-level information about your integration. Please see this document: https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/603815937 for guidance.