Building Apps: Templates (tcinit)
Summary
The tcinit CLI tool provides a simple interface to begin a new project from a template and to keep Framework files updated. There are several templates that support specific-use cases. Most templates are working Apps that can easily be modified to the developer’s use case.
Usage
To get the latest usage and template choices for tcinit, run tcinit -h.
usage: tcinit [-h] [--branch BRANCH] [--layout] [--migrate] [--update]
[--template {external,external_ingress,job,job_batch,playbook,playbook_actions,playbook_utility,service_api,service_trigger,service_webhook}]
optional arguments:
-h, --help show this help message and exit
--branch BRANCH Git branch.
--layout Create a layout.json file.
--migrate Enable this flag to migrate an existing App.
--update Enable this flag to update an existing App.
--template {external,external_ingress,job,job_batch,playbook,playbook_actions,playbook_utility,service_api,service_trigger,service_webhook}
Choose an appropriate App template for the current
project.
The "tcinit" command it intended to enable quick development of ThreatConnect Exchange Apps.
Job App Templates:
job - This template provides the structure for a Job App without any App
logic.
job_batch - This template provides a working example of downloading remote threat
intel (md5 hash indicators) and writing the data in the ThreatConnect
Platform using the tcex batch module.
Playbook App Templates:
playbook - This template provides the structure for a Playbook App without any
App logic.
playbook_actions - This template provides an example of "actions" in a Playbook
App. Using the "actions" feature a single Playbook App can have
multiple actions to perform different operations on the provided data.
playbook_utility - This template provides a basic example of a utility App that takes
an input, analyzes or modifies the data, and writes the results as
output.
External App Templates:
external - This template provides the structure for a External App without any
App logic.
external_ingress - This template provides a working example of downloading remote threat
intel (md5 hash indicators) and writing the data in the ThreatConnect
Platform using the tcex batch module.
Service App Templates:
service_api - This template provides the structure for a API Service App.
service_trigger - This template provides the structure for a Trigger Service App.
service_webhook - This template provides the structure for a Webhook Trigger Service App.
Common Usage
To initialize a new App, run this command from the project directory:
tcinit --template playbook_utility
To update an existing App, run the command below from the project directory. The update action will download all Frameworks files to ensure that these files are the latest with any bug fixes or updates. It is best practice to run the update action whenever an App is being updated for new features or bug fixes.
tcinit --update
Job App Templates
The run() method is the default method that is called when an App is executed. For simple Apps, the core logic of the App can be written in this method. For more advanced Apps, additional methods can be added to the app.py file, if required.
Job (job)
This basic template provides the structure for a Job App without any logic. This template is intended for advanced users that only require the App structure.
app.py
Job Batch (job_batch)
This template provides a working example of how to download remote-threat intel (md5 hash Indicators) and write the data in the ThreatConnect platform using the TcEx Batch Module. The URL is defined in the init() method for convenience. In the run() method, the Batch module is instantiated. Next, the data is retrieved from the remote URL and written to the Batch module. Finally, the Batch Job is submitted to ThreatConnect for processing.
app.py
Playbook App Templates
Playbook (playbook)
This template provides the structure for a Playbook App without any logic. This template is intended for advanced users that only require the App structure.
app.py
Playbook Actions (playbook_actions)
This template provides a working example of actions in a Playbook App. Using the Actions feature, a single Playbook can have multiple actions to perform different operations on the provided data. Python decorators are heavily used in this template to provide a clean interface to process inputs for an App.
See also
decoratorsInline documentation of App decorators
app.py
Playbook Utility (playbook_utility)
This template provides a working example of a utility App that takes an input, analyzes or modifies the data, and writes the results as output.
app.py
External App Templates
The TcEx Framework provides methods to build an App to run in the ThreatConnect Exchange environment. However, the TcEx Frameworks also supports writing Apps that run external to the ThreatConnect Exchange environment. Two init params are supported during the initialization of TcEx. The first option, TcEx(config_file='app_config.json), takes a JSON file as input for the App configuration file. The second option, TcEx(config=app_config_dict), takes a dictionary of configuration data. Either param will load the data and make it accessible via the self.args namespace.
The run() method is the default method that is called when an App is executed. For simple Apps, the core logic of the App can be written in this method. For more advanced Apps, additional methods can be added to the app.py file, if required.
Example Config data
{
"api_access_id": "API_ACCESS_ID",
"api_default_org": "API_DEFAULT_ORG",
"api_secret_key": "API_SECRET_KEY",
"tc_api_path": "TC_API_PATH",
"tc_log_level": "debug",
"tc_log_path": "log",
"tc_owner": "MyOwner",
"tc_proxy_host": "TC_PROXY_HOST",
"tc_proxy_password": "TC_PROXY_PASSWORD",
"tc_proxy_port": "TC_PROXY_PORT",
"tc_proxy_tc": false,
"tc_proxy_username": "TC_PROXY_USERNAME"
}
In the example above the proxy configuration is only required if using a proxy server in the environment.
External (external)
This basic template provides the structure for an External App without any logic. This template is intended for advanced users that only require the App structure.
app.py
External Ingress (external_ingress)
This template provides a working example of how to download remote-threat intel (md5 hash Indicators) and write the data in the ThreatConnect platform using the TcEx Batch Module. The URL is defined in the init() method for convenience. In the run() method, the Batch module is instantiated. Next, the data is retrieved from the remote URL and written to the Batch module. Finally, the Batch Job is submitted to ThreatConnect for processing.