Overview

This document is intended for a technical audience and provides a detailed description of an External TAXII Download with the ThreatConnect Platform. The general purpose of this integration is to allow an external system to engage the ThreatConnect Platform’s TAXII server to download indicator data from one or more collections.

Integration Attributes

• Data Directionality: Outbound - Data maintained in the ThreatConnect Platform is downloaded by way of collections via the ThreatConnect Platform’s TAXII server.

• ThreatConnect Technologies:

  • TAXII Server (1.1) - A built-in component available via the API endpoint (but using separate credentials) providing data in STIX 1.1.1 format.

• Execution:

  • Determined by the third-party application.

Example Integration Diagram

The diagram below provides a simple success-based example of this integration scenario.

Diagram Explanation

1. The TAXII client is initiated in the third-party (external) application.

2. (Optional) The TAXII client sends a TAXII Discovery Request to the ThreatConnect TAXII Server.

3. (Optional) The ThreatConnect TAXII Server responds with the list of available services (DISCOVERY, COLLECTION_MANAGEMENT, and POLL).

4. (Optional) The TAXII client sends a TAXII Collection Management Request to the ThreatConnect TAXII Server.

5. (Optional) The ThreatConnect TAXII Server responds with a list of the available collection (one per ThreatConnect data owner).

6. The TAXII client sends a TAXII Poll Request to the ThreatConnect TAXII Server for a single collection.

7. The ThreatConnect TAXII Server responds with a payload of Indicators available from that collection based on the timeframe specified.

8. The third-party (external) application saves these indicators for use and the TAXII client is terminated.

Integration Key Points

• Development Environment

  • This integration is developed completely externally in most instances.

• Architecture

  • Limitations - This integration type has limitations over the preferred Integrations - External REST Description type. Some of these limitations include:

    • Only a subset of the information from our Platform is available:

      • Supported Indicators - Host (type Domain Watchlist), Address (type IP Watchlist - IPv4 and IPv6), URL (type URL Watchlist), and File (type File Watchlist - MD5, SHA1, or SHA256 hashes)

      • No Groups are supported

    • Tags, most Attributes, ThreatAssess Confidence, and ThreatAssess Rating are unavailable.

    • Relationship context between Indicators is lost because Groups are unavailable.

    • Filtering beyond Collection (based on begin and end dates) must be done in the third-party application and requires download of the full payload requested.

    • The maximum number of hours you can Poll is 24 (by default). This is a configurable setting within the ThreatConnect Platform but you should anticipate the default configuration.

    • Creating a download-only integration reduces the value of the integration to end-users that may desire bi-directional functionality. In particular, SIEM integration cases are common for contributing Observations (accumulations of the number of sightings) for Indicators.

• Configuration

  • You should accept an input parameter of the URL to the ThreatConnect instance that should be polled. The URL that you accept should follow the guidance provided in the Overview section of this document.

    • Note: The authentication and other items mentioned in that document are not applicable to TAXII integrations. Only the base URL calculation guidance in the Overview section is applicable.

    • Note: You should never assume or “hard code” the value of the ThreatConnect URL into your integration.

  • Collections represent the various data owners within the ThreatConnect Platform. You should permit the selection of the desired Collections as it is typical that only a subset of data is desired for a given purpose.

  • You will be required to specify both an Exclusive Begin Date and Inclusive End Date with your Poll requests. The default configuration is to allow a maximum of 24 hours for polling though this can be changed by a ThreatConnect System Administrator.

• Data Mapping

  • Threat Rating and Confidence are typically set according to the ThreatConnect best-practices.

  • It is preferred that you use the TC_V2 parser (configured as part of the TAXII user) when possible. When using the TC_V2 parser, you should be prepared to parse the additional fields that we offer in this parser. The following additional fields are offered in these STIX Package fields:

    • indicator:description - <type> <value>|[desc: <desc>]|[src: <src>]|rating: <rating>|threatassess: <threatAssessScore>|falsepositives: <falsepositive_count>|owner: <owner>

      • <type> is an Indicator type of Host, Address, URL, or File. See our data model for more information.

      • <value> is the value of the Indicator based on the type.

      • <desc> is an optional field based on the attribute Description.

      • <src> is an optional field based on the attribute Source.

      • <rating> is the threat rating of this Indicator (float).

      • <threatAssessScore> is the ThreatAssess Score (analytics) that we generate for this Indicator across all data owners.

      • <falsepositive_count> is the number of false positives reported against this Indicator across all data owners.

      • <owner> is the data owner that returned this Indicator.

  • Only the following additional information is available for supported Indicators using the TC_V2 parser:

    • Observable - indicatorObservable/cybox:Object/cybox:Properties

    • Observations - indicator:Sightings (sightings_count property)

    • Confidence - indicator:Confidence/stixCommon:Value

    • Web Link - indicator:Producer/stixCommon:References/stixCommon:Reference

    • Date Added - indicator:Producer/stixCommon:Time/cyboxCommon:Produced_Time

    • TLP Security Label indicator:Handling/marking:Marking/marking:Marking_Structure (color property)

  • Data should be shown in a way that relates an Indicator to the Collection (data owner) that provided it. It is possible that a user in your Platform may desire to see the results for an Indicator search from multiple data owners.

• Miscellaneous

  • Identification values within STIX Packages are temporary and for the single transmission only. They are not persistent within the ThreatConnect Platform

• Distribution

  • This integration will be distributed by the partner using a method appropriate for the partner’s solution.

Getting Started

Once you’ve reviewed the guidelines above, see this article for information on how the TAXII server is configured in the ThreatConnect Platform.

Python 3 Code Example

For your convenience, we offer an example of connecting to the ThreatConnect TAXII Server using Python 3 here: References - Python 3 TAXII Client Example