Summary of ThreatConnect apps and api

tc_api.md

Deployment models

• A local script can leverage the ThreatConnect API to make changes on behalf of a user's API key
• Code written in Java or Python can be deployed as an App to a ThreatConnect instance (useful for recurring server-side jobs)
• Code written in JavaScript can be deployed as a Spaces App ThreatConnect instance and (useful for client-side GUI tools)

Supported SDK Languages

Python library - Available in pip as ‘threatconnect’ - Can be used to build server-side apps for the platform

Java - Available in maven as `threatconnect-sdk. Can be used to build server-side apps for the platform

JavaScript - Not available in bower, npm or CDN Can be used to build visualization apps for the platform

Getting an API key

Sign up for an API key here

• The API uses your “Access ID” and “Secret Key” to authenticate requests and check permissions
• This key is linked to your user account
• Your user account is part of an Owner
• Your key is limited to viewing and modifying data for Owners that you have read/write privileges for

The public ThreatConnect API is: https://api.threatconnect.com/v2/

HTTP Methods

Endpoints follow a typical CRUD model for HTTP request types

• Use GET requests to ask for data
• Use POST requests to create/modify data
• Use DELETE requests to remove data

Example: Get a list of owners you can access by making a GET request for https://api.threatconnect.com/v2/owners

Authentication

Each request must include an HTTP Header Signature as an authentication token This is derived from your “Access ID”, “Secret Key”, and a time-based nonce The Python client library will handle authentication in client-side scripts An HTTP 401 error is returned if the request is not authenticated

Parsing an API Response

Endpoints return data in JSON by default

To return data in XML, include an HTTP header of Accept: application/xml

Responses typically include these fields:

• Status , a string
• “Success” for HTTP 20x response
• “Failure” for HTTP 40x response (includes message string with failure reason)
• resultCount, an integer Total number of results for the query
• data , a JSON dictionary Contains query-specific fields i.e. {“host” [ {“id” :1337} , {“id”: 42} ] }

Queries for indicators typically include

• webLink, a URL resolving to its information page
• ownerName, a string for its Owner
• dateAdded and lastModified, a DateTime string
• rating, an integer between 0 and 5
• confidence, a float between 0 and 100

Certain fields imply a subjective score for the indicator

Querying for specific data

Requests to most endpoints will accept query filters, as in:

• Owner, a string as in “Acme Corp” - Results will be limited to data owned by this Owner, as in “all data in Anti-Spam List”. If omitted, the server will either return a 403 error or return all data that the requesting API key has access to
• filter, a string with a comparison expression - Results will be limited to data matching the expression. Operators in the expression should be URL-encoded (i.e. ‘<’ as ‘%3E’) Pagination fields
• resultStart, an integer (set to zero by default) - Results will start at the given result index. Result index for a given entry is not guaranteed to be identical across queries
• resultLimit, an integer (set to 100 by default) - Results will be limited to this number. Maximum value is 500

Wrapping API queries using client libraries

Unofficial shell script - Useful for handling authentication and manual queries

Additional Resources

• RESTful APIs
• HTTP/CuRL
• JSON