Quick Start

Installation

Python 2.7+ is a prerequisite for using the ThreatConnect Python SDK. Typically, Python comes pre-installed on Linux/OS X/Unix systems, so additional steps to install Python are usually not required. To ensure you have python installed and to check the version, type python --version into the command line/command prompt.

The ThreatConnect Python SDK can be installed using python pip as shown below:

pip install threatconnect

Note

If you get a Permission denied error, you may have to install the threatconnect package with escalated privileges: sudo pip install threatconnect.

Warning

If you are using Python 2, you will also need to install the enum34 package using: pip install enum34.

Configuration

Any script using the ThreatConnect Python SDK needs access to a configuration file which is laid out as follows:

[threatconnect]

# note -- do not use any quotes...

#
# api access id - ENTER API ACCESS ID
#
api_access_id = 12345678900987654321

#
# api org - ENTER API DEFAULT ORG
#
api_default_org = Test Owner

#
# api secret key - ENTER API SECRET KEY
#
api_secret_key = aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz!@#$%^&*()-=

#
# api base url - ENTER API BASE URL (e.g. https://api.threatconnect.com)
#
api_base_url = https://api.threatconnect.com

Update the configuration file as follows:

  1. Replace the api_access_id and api_secret_key with your credentials.

  2. Update the api_default_org with your organization’s name as it appears in ThreatConnect.

  3. Change the api_base_url as needed (see the note below if you are using the ThreatConnect sandbox).

Note

If you are working with the ThreatConnect sandbox, the api_base_url should be: https://sandbox.threatconnect.com/api/.

What hath God wrought! (a.k.a. Hello World)

Assuming that you have installed the ThreatConnect Python SDK and have created a configuration file with the correct information, we are now ready to test the SDK. To test the SDK:

  1. Create a folder in a convenient location on your computer.

  2. Copy the configuration file from the previous, Configuration step into the new folder and name it tc.conf.

  3. Copy and paste the following code into a file and save it in the new folder with the name tc_test.py. This code will print all of the owners in ThreatConnect which you have permission to see.

try:
    import ConfigParser
except:
    import configparser as ConfigParser
import sys

from threatconnect import ThreatConnect

config = ConfigParser.RawConfigParser()
config.read('./tc.conf')

try:
    api_access_id = config.get('threatconnect', 'api_access_id')
    api_secret_key = config.get('threatconnect', 'api_secret_key')
    api_default_org = config.get('threatconnect', 'api_default_org')
    api_base_url = config.get('threatconnect', 'api_base_url')
except ConfigParser.NoOptionError:
    print('Could not read configuration file.')
    sys.exit(1)

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Owners object
owners = tc.owners()

try:
    # retrieve the Owners
    owners.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Owners
for owner in owners:
    print(owner.id)
    print(owner.name)
    print(owner.type)
    print('')

  1. In the command line/command prompt, run python tc_test.py. This should print the ID number, name, and type of the owners which you have permission to see.

Standard Script Heading

Every script that communicates to the ThreatConnect Python SDK should begin with the same, basic code:

try:
    import ConfigParser
except:
    import configparser as ConfigParser
import sys

from threatconnect import ThreatConnect

config = ConfigParser.RawConfigParser()
config.read('./tc.conf')

try:
    api_access_id = config.get('threatconnect', 'api_access_id')
    api_secret_key = config.get('threatconnect', 'api_secret_key')
    api_default_org = config.get('threatconnect', 'api_default_org')
    api_base_url = config.get('threatconnect', 'api_base_url')
except ConfigParser.NoOptionError:
    print('Could not read configuration file.')
    sys.exit(1)

For the sake of brevity, the configuration code above will be summarized with ... in all of code snippets in this documentation. In other words, any time you see ... in a code snippet, it can be replaced with the code above.

Next Steps

From here, find a topic that interests you and dig in! If you don’t know where to start, retrieving indicators is a good place to start.

Hint

There are some good examples using this SDK here: https://github.com/ThreatConnect-Inc/threatconnect-python/tree/master/examples

Hint

When using this documentation, it will be helpful to have a basic understanding of the ThreatConnect Data Model.