.. _building_apps_quickstart: --------------------------- Building Apps: Quick Start --------------------------- The following steps are written for development on a macOS® or Linux® system. Development on a Windows® system is supported and should follow similar steps. Before 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 needed to install Python, Redis, and a virtual environment are outside the scope of this document. This guide walks through the steps necessary to create and initialize a fully functioning App. Adding custom code or logic is not covered in this guide. .. note:: This quick start guide covers building an App with TcEx 2.x. A quick start guide for building an App with TcEx 3.x is available at `https://threatconnect.readme.io/docs/building-apps-quickstart `_. .. Important:: This guide assumes that the workstation and ThreatConnect instance have the same version of Python installed. Writing Apps that supports multiple versions of Python is supported but not covered in this guide. Initializing an App ------------------- .. code-block:: bash 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 is a helpful naming convention to distinguish Playbook Apps from other types of Apps. After running the ``tcinit`` command, the App directory and 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 is updated with appropriate changes. And changes to App **inputs/args** are made to the **install.json** and **args.py** file. The ``param[].name`` field of the **install.json** file must match the name of the args (arguments) the App is expecting (e.g., "api_key" name in install.json would pass the "self.args.api_key" arg to the App). .. seealso:: :ref:`Building Apps: Templates ` Documentation for using App templates. :ref:`App Files and Folders 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 guide, no additional packages are required. .. code-block:: bash tclib After running the ``tclib`` command, a "lib_" (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. Differences in micro-versions (e.g., Python version 3.6.5 vs. lib_3.6.7) are usually acceptable. .. seealso:: :ref:`App dependencies ` Documentation for building App dependencies. Packaging an App ---------------- .. code-block:: bash 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 of the project directory. .. IMPORTANT:: The ``tclib`` command must be successfully run before packaging an App. Otherwise the App will be missing any dependencies and may not function properly. .. seealso:: :ref:`App Packaging ` Documentation for packaging of an App macOS® is a registered trademark of Apple, Inc. Linux® is a registered trademark of Linus Torvalds. Python® is a registered trademark of the Python Software Foundation. Redis® is a registered trademark of Redis Ltd. Windows® is a registered trademark of the Microsoft Corporation.