...

1. Ensure that you’ve installed and are using a Python 3.6 interpreter. This is important to ensure that you match the oldest version of Python used in the ThreatConnect Platform. Python 3.6.8 is recommended.

2. Install the latest version of the tcex module:

   Code Block
   pip3 install 'tcex[development]'

3. Create a project directory on your system.

   1. NOTE: If you’re using an IDE, do not initialize this directory with your IDE until after you’ve initialized it with the appropriate template in the next step. Otherwise, you’ll receive an error that the directory is not empty.

4. Change directories into the project directory and prepare a template:

   Code Block
   tcinit --template job_batch

5. Modify the code in app.py. Specifically, your code belongs in the App.run() method.

6. Ensure that your other project configuration files are up-to-date:

   1. install.json - See this link for reference on this file. Most default values can remain. Key points:

      1. Ensure that your displayName is configured properly per our guidelines.

      2. Ensure that each of your input parameters are defined properly.

   2. tcex.json - Key points:

      1. Ensure that the package > app_name is version of your package name without spaces. Use the _ to substitute for spaces.

      2. For TcEx v1: The package > app_version field will be appended to the package name and doesn’t actually reflect the version embedded in the project.

      3. Any files you add to the project for development but that should not be shipped in the deliverable should be added to the package > excludes array.

   3. args.py - Key Points:

      1. Each argument you add to your app should be included here. You do not need to add any of the pre-defined arguments such as tc_log_level.

   4. requirements.txt - Key Points:

      1. Each package you require for any portion of your app should be specified here.

7. Prepare the project libraries from the project directory:

   Code Block
   tclib

8. Prepare a run profile/script to test your code. Use the following parameters for your profile/script:

   1. Execute the run.py with the working directory of your project.

   2. Use the following arguments:

      1. --tc_api_path - Set this to https://<instance URL>/api

         1. If you’re using the PartnerStage environment, this would be https://partnerstage.threatconnect.com/api.

         2. If you’re using the ThreatConnect Public Cloud (you access the UI using https://app.threatconnect.com), this would be https://api.threatconnect.com/.

      2. --api_access_id - Set this to your API Access ID

      3. --api_secret_key - Set this to your API Secret Key

         1. If you run this from a bash or zsh command-line, you must single-quote your API Secret Key or it will not work properly (you will get an API 400 response code saying it can’t find the indicator types).

         2. If you run this in PyCharm using a run profile, you must double-quote your API Secret Key or it may produce unexpected results inside the interpreter.

      4. --tc_log_path - Set this to . to generate the app.log in your working directory

         1. Specify another directory if you desire. All of the exceptions will be captured in this log and will not be printed to the screen.

      5. --tc_log_level - Set this to DEBUG for your testing purposes

      6. --tc_owner - Set this to the name of your Source in PartnerStage. This is typically going to be <Organization> Source as the name. If your company name is SecuLast, this would be SecuLast Source.

         1. This value is only for testing purposes. In the Production environment, you’ll accept a configurable name here in your project (configuration provided in the template).

9. Execute testing against your project to ensure that your code works properly against the description in your Solution Design as well as the guidelines for your integration type.

10. Ensure that your project is stored in your code repository.

11. Package the application using ‘tcpackage’. The output will be in ./target by default (a .tcx file).

TCEX Sample Project

Creating a brand new ThreatConnect Job can be overwhelming at first glance and so the Technology Partners Team has created a sample project for reference.

Sample Project Link: https://github.com/ThreatConnect-Inc/threatconnect-jobs/tree/master/apps/Malc0de%20Threat%20Intelligence

The sample project has a .tcx file which will contain the integration itself and a .pdf which is the user guide.

The .tcx file is really just a zip file with out special extension. Uncompress it with your preferred zip tool. Inside the .tcx file you will see the following files:

__main__.py
app_lib.py (Applib class)
app.py (This is the file where most of the app code will reside)
args.py (Arguments to be passed to the app)
install.json (JSON file that configures the app for the ThreatConnect platform)
job_app.py (JobApp class)
lib_3.6.8 
lib_latest
Malc0de_Threat_Intelligence_Feed.json (Feed deployer job file which is used to deploy the app through feed deployer)
README.md
requirements.txt (Python library requirements)
run.py (Run file for the app)

app.py

This sample project will showcase how to utilize many of the common features of the batch module. The main file that most of the code for an integration usually resides in is app.py. The app.py file shown in the sample project will display how to implement certain features of the batch module as shown below:

Setting the owner of indicators/groups:

• app.py line 284

Setting indicator threat rating and confidence:

• app.py line 288-289

Logging to the app log file using different log levels:

• app.py line 294,309

Setting an exit message and how to exit the app:

• app.py line 317-318

Getting the current UTC iso8601 time:

• app.py line 336-338

Generating a unique XID:

• app.py line 340

Creating a group:

• app.py line 341

Adding an attribute to a group:

• app.py line 342-347

Submitting all indicators/groups to the platform using batch:

• app.py line 363-364

Batch Error handling example:

• app.py line 362-395

Creating an indicator:

• app.py line 411

Adding attributes to an indicator :

• app.py line 427

Associating indicators to a threat group:

• app.py line 431