TAXII Server

Updated 2 weeks ago by Elvis Hovor

Trusted Automated Exchange of Intelligence Information (TAXII) is an application layer protocol used to exchange cyber threat intelligence (CTI) over HTTPS. It enables organizations to share CTI by defining an API that aligns with common sharing models. TAXII is specifically designed to support the exchange of CTI represented in STIX. As such, the examples and some features in the specification are intended to align with STIX. This does not mean TAXII cannot be used to share data in other formats; it is designed for STIX, but is not limited to STIX. This document provides a description of the service that provides access to TruSTAR IOCs in STIX and TAXII format.

TruSTAR TAXII Server Features

  • Allows users to download indicators from the Station application's enclaves of their choice in STIX format.
  • Users can run discovery service to identify all available services with the TruSTAR TAXII Server.
  • Can specify "from" & "to" times to download indicators from a specific time window.

TruSTAR TAXII Server Notes / FAQ:

  • Whitelisted indicators. Indicators the user has whitelisted in the Station application will be present in the TAXII server's responses to indicator-download actions (poll requests). If the user wants to filter whitelisted indicators out of the TAXII server's responses, the user must do that in code after receiving the response from the TAXII server. When connecting Logrythm or other applications' built-in TAXII clients to the TruSTAR TAXII server, know that those applications will import IOCs that you've whitelisted. To avoid this, the user will need to manually delete those indicators in the Station web-app.
  • Submitting reports/indicators. TruSTAR's TAXII server is not configured to allow users to send reports or indicators into their enclaves in Station. The TAXII server was designed to enable users to download the indicators that already exist in their enclaves. Reports can be submitted programmatically using TruSTAR's "submit report" REST API endpoint directly (documentation here: https://docs.trustar.co/api/v13/reports/submit_report.html ), or using the TruSTAR Python SDK's "submit_report()" method (documentation here: https://docs.trustar.co/sdk/TruStar/
  • Customizing download enclaves. TruSTAR's TAXII server will serve IOCs from all enclaves that the user account tied to the API credentials used in the poll request has access to. To download IOCs only from specific enclaves, TruSTAR recommends that the users create a new Station User Account and give that user account "view" access only to the enclaves from which the user would like to download IOCs via the TAXII server. Think of this as a "service account". Use a "team" or "group" email address for this user account's username, not an address tied to a specific human in the organization, becuase that user account will only have access to only a few enclaves, and it will only have "view" access (read-only) to those enclaves, and a human user who logs into the web u/i will usually need/want view access to all enclaves that person's company has access to.
  • Maintaining relationship between indicators and the enclaves they came from. If the user needs to download indicators from multiple enclaves AND know which enclave each IOC came from, TruSTAR recommends the user create several "service" accounts (described in the "Customizing download enclaves" bullet), give each service account "view" access to a single enclave, then make poll requests to the TAXII server with one account at a time to download indicators only from the enclave that that account has access to.
  • Time window. The "--time" argument is optional for poll requests made to the TruSTAR TAXII server. Think of this as a "from" time - if it's supplied in a poll request, the server's response will include all IOCs from the enclaves that the user account has access to whose "Last Seen" attribute falls between the time submitted to the "--time" argument and present moment. The TruSTAR TAXII server cannot deliver only IOCs that were last seen in a historical time window - the server does not accept any form of a "to" time in the poll request; the "to" time is always present moment.

Requirements

The details below summarizes the prerequisites and requirements needed for users to connect to the TruSTAR TAXII Server

TAXII client running TAXII version 1.1

TAXII client with ability to connect to a TAXII server running TAXII software version 1.1

TAXII client with access to connect to TruSTAR TAXII server supported services (Discovery, Collection-Management and Collection Polling)

TAXII client should be able to accept STIX 1.2 formatted packages

Easy Configuration - Using a TAXII client GUI

Users do not need download install files to connect to the TruSTAR TAXII server. Most TAXII client meeting the requirements above can access the TAXII server.

Users with access to the TAXII client that can run on a graphical user interface can connect to the discovery service or the collection management service to find all the collections that are available for download.

As an example users who have Log Rhythm Threat Intelligence Services can leverage the TAXII client to connect to TruSTAR's TAXII service. More details on connecting to TruSTARs TAXII server using LogRhythm TIS can be found here.

General Guidelines

  1. Select to add a STIX/TAXII Provider button.
  2. Sample TAXII client setup page
  3. Fill out the Information below where applicable
    • TAXII Collection Endpoint: https://taxii.trustar.co/services/collection-management
    • Username: This is your API Authentication Key available on TruSTAR station. Click here to get it: https://station.trustar.co/settings/api
    • Password: This is your API Secret available on TruSTAR station. Click here to get it: https://station.trustar.co/settings/api
    • Certificate Authentication: Leave unchecked and ignore Certificate Password and Certificate Path.
  4. Threat Provider Name: Use any name your of choice.
  5. You should see a list of available collections

    #

    Collection Name

    Description

    1

    collection-indicator-IP

    Collection of all IP addresses.

    2

    collection-indicator-url

    Collection of all URL’s.

    3

    collection-indicator-MD5

    Collection of all MD5 hashes.

    4

    collection-indicator-SHA1

    Collection of all SHA1 hashes.

    5

    collection-indicator-SHA256

    Collection of all SHA256 hashes.

    6

    collection-indicator-EMAIL_ADDRESS

    Collection of all email addresses.

    7

    collection-indicator-REGISTRY_KEY

    Collection of all registry keys.

  6.  The TruSTAR TAXII service provides a subset of IOCs from the Station platform through the collections described below. Please note that each collection will return from the Station platform all IOCs that were submitted in the last 24 hours to any of the enclaves the user (whose API credentials are being used) has access to.

Manual Configuration & Testing

TAXII Services Supported 

Currently we support the following TAXII services

#

TAXII Service

Description

1

Poll

Used by a TAXII Client to request information from a TAXII Server.

URL: https://taxii.trustar.co/services/poll

2

Collection-Management

Used by a TAXII Client to request information about available Data Collections or request a subscription.

URL: https://taxii.trustar.co/services/collection-management

3

Discovery

Used by a TAXII Client to discover available TAXII Services.

URL: https://taxii.trustar.co/services/discovery

Configuration

You will need a TAXII client to connect to TruSTAR’s TAXII server. There are a number of open source clients available - we recommend using the Libtaxii repository available here: https://github.com/TAXIIProject/libtaxii or cabby also available here: https://github.com/EclecticIQ/cabby
TruSTAR TAXII Server Parameters

Description

Libtaxii parameter

Value

URL to connect

-u, --url

Always use: https://taxii.trustar.co/services/

Username

--username

Use your TruSTAR API Key. Available here: https://station.trustar.co/settings/api

Example: >>>......--username aca05832-f1a0-0184-8f67-5741fffe7a14......

Password

--pass

User your TruSTAR API Secret. Available here: https://station.trustar.co/settings/api

Example: >>>......--pass Tzw4FLIX0rW338i7jYU3UgU0......

Collection to use

--collection

See next section

Example: >>>.....--collection collection-indicator-IP.......

Time

--time

Allows the user to specify a "from" time; the TAXII server will return all IOCs from the enclaves your API credentials have View (or higher) access to whose "timeUpdated" attribute is between the time you specify in this parameter and the present moment.

Proxy

--proxy

Specify a proxy

Example: >>>.....--proxy http://myproxy.example.com:80........

 Collections Available

The TruSTAR TAXII service provides a subset of IOCs from the platform through the collections described below. Please note that each collection will return data from the TruSTAR platform for previous 24 hours.

#

Collection Name

Description

1

collection-indicator-IP

Collection of all IP addresses.

2

collection-indicator-url

Collection of all URL’s.

3

collection-indicator-MD5

Collection of all MD5 hashes.

4

collection-indicator-SHA1

Collection of all SHA1 hashes.

5

collection-indicator-SHA256

Collection of all SHA256 hashes.

6

collection-indicator-EMAIL_ADDRESS

Collection of all email addresses.

7

collection-indicator-REGISTRY_KEY

Collection of all registry keys.

Libtaxii Client Calls 

Discovery
python discovery_client.py -u https://taxii.trustar.co/services/discovery --username <API Credential> --pass <API key>
Sample Response
Request:

Message Type: Discovery_Request
Message ID: 377306701207002283

Response:

Message Type: Discovery_Response
Message ID: 6034388875283072057; In Response To: 377306701207002283
=== Service Instance ===
Service Type: POLL
Service Version: urn:taxii.mitre.org:services:1.1
Protocol Binding: urn:taxii.mitre.org:protocol:https:1.0
Service Address: https://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
Available: True
Message: Trustar indicator Poll Service description
=== Service Instance ===
Service Type: DISCOVERY
Service Version: urn:taxii.mitre.org:services:1.1
Protocol Binding: urn:taxii.mitre.org:protocol:https:1.0
Service Address: https://taxii.trustar.co/services/discovery
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
Available: True
Message: Trustar Discovery Service description
=== Service Instance ===
Service Type: COLLECTION_MANAGEMENT
Service Version: urn:taxii.mitre.org:services:1.1
Protocol Binding: urn:taxii.mitre.org:protocol:https:1.0
Service Address: https://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
Available: True
Message: Trustar Collection Management Service description

Poll a Specific Collection
python poll_client.py -u https://taxii.trustar.co/services/poll --collection collection-indicator-IP --username <API Credential> --pass <API key>
Sample Response
Request:

Message Type: Poll_Request
Message ID: 3641663190328146359
Collection Name: collection-indicator-IP
Excl. Begin TS Label: None
Incl. End TS Label: None
=== Poll_Parameters ===
Response type: FULL

Response:

Message Type: Poll_Response
Message ID: 3685762672097258501; In Response To: 3641663190328146359
Collection Name: collection-indicator-IP
More: False
Result ID: None
Result Part Num: 1
=== Content Block ===
Content Binding: urn:stix.mitre.org:xml:1.1>IP
Content length: 78959
(Content not printed for brevity)
Timestamp Label: 2019-03-12 23:12:34.222823+00:00
Message: None
Padding: None

File created: collection-indicator-IP_STIX11_t2019_03_12T23_12_34_222823_00_00.xml
Collection Management
python poll_client.py -u https://taxii.trustar.co/services/collection-management --username <API Credential> --pass <API key>
Sample Response
Request:

Message Type: Collection_Information_Request
Message ID: 2357215507238313583

Response:

Message Type: Collection_Information_Response
Message ID: 4748931395125127784; In Response To: 2357215507238313583
Contains 9 Collection Informations
=== Data Collection Information ===
Collection Name: collection-indicator-url
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-IP
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-MD5
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-SHA1
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-SHA256
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-SOFTWARE
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-EMAIL_ADDRESS
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-REGISTRY_KEY
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

=== Data Collection Information ===
Collection Name: collection-indicator-CIDR_BLOCK
Collection Type: DATA_SET
Available: True
Collection Description: None
Supported Content: All
=== Polling Service Instance ===
Poll Protocol: urn:taxii.mitre.org:protocol:http:1.0
Poll Address: http://taxii.trustar.co/services/poll
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
=== Subscription Service ===
Protocol Binding: urn:taxii.mitre.org:protocol:http:1.0
Address: http://taxii.trustar.co/services/collection-management
Message Binding: urn:taxii.mitre.org:message:xml:1.0
Message Binding: urn:taxii.mitre.org:message:xml:1.1
==================================

Optional Parameters
python poll_client.py -u https://taxii.trustar.co/services/poll -- collection collection-indicator-IP --time <Time_in_UTC :00:00:000> --username <API Credential> --pass <API key> --key <MyKey.key> --username<api_key> --proxy <http://myproxy.example.com:80> --xml-output 

FAQ

  • How far back can i download data from my TruSTAR enclaves using the TAXII server
    • By default you can get the last 24 hours of data from TruSTAR if no time parameter is specified. However users can specify how far back to download data from the TruSTAR TAXII server by specifying the time as part of their query. Refer to optional parameters above.
  • Where can I download the public TAXII documentation?

Troubleshooting

Please reach out to support@trustar.co for any additional questions.


How Did We Do?