Building Apps - Quick Start

The following steps are written for development on a OSX or Linux system. Development on a Windows system is supported and should follow similar steps. Prior to proceeding Python must be installed and if preferred a Python virtual environment should be configured. For local testing a Redis server also must be installed and running. The steps to install Python, Redis, and configure a virtual environment are outside the scope of this document.

This quickstart guide will walk through each step to create a working App. It will initialize a fully functioning App. Adding custom code/logic is not covered in this quickstart guide.

Important

This guide assumes that the workstation and ThreatConnect instance have the same version of Python installed. Writing Apps that support multiple versions of Python is supported but not covered in the quickstart guide.

Initializing an App

pip install tcex
mkdir TCPB_-_JsonPretty
cd TCPB_-_JsonPretty
tcinit --action create --template playbook_utility

Note

The prefix of TCPB_-_ (ThreatConnect PlayBook) is optional. However, it’s a helpful naming convention to distinguish PlayBook Apps from Job Apps.

After running the tcinit command the App directory/file structure will be autogenerated. The playbook_utility template is a working App so there is no need to change any of the files.

Note

When ready to create custom App logic the run() method of app.py file would be updated with appropriate changes. An changes to App inputs/args would be made to the install.json and args.py file. The param[].name field of the install.json must match the name of the args the App is expecting (e.g., “api_key” name in install.json would pass the “–api_key” arg to the App).

See also

Building Apps - Templates
Documentation for using App Templates.
App Structure
Documentation for App files and folders structure.

Building the “lib” Directory

At a minimum all Apps require the tcex Python package. If other Python packages are required the package name should be added to the requirements.txt file in the project directory. For this quickstart guide no additional packages are required.

tclib

After running the tclib command a “lib_<Python version>” (e.g., lib_3.6.7) directory will be in the project directory. This directory will contain all Python packages defined in requirements.txt and any sub-dependencies.

Important

This version of the lib directory should closely match the version of Python on the ThreatConnect server. Difference in micro versions (e.g., Python version 3.6.5 / lib_3.6.7) are acceptable.

See also

App Dependencies
Documentation for building App dependencies.

Packaging an App

tcpackage

The tcpackage command will package all relevant files in the project directory into a “.tcx” file that can be uploaded to the ThreatConnect Platform. By default the package will be created in the target directory in the project directory.

Important

The tclib command must be successfully ran before packaging an App. Otherwise the App will be missing any dependencies and may not function properly.

See also

App Packaging
Documentation for packaging of an App.