Accessing the STIX/TAXII Integration.

Overview

  • Structured Threat Information Expression (STIX™) is a structured language for describing cyber threat information so it can be shared, stored, and analyzed in a consistent manner that facilitates automation.

  • Trusted Automated eXchange of Indicator Information (TAXII™) is a transport mechanism used to exchange STIX data.

ThreatSTOP provides a STIX/TAXII service, supporting two types of integration:

  • Retrieve IOCs contained in targets for data enrichment, for example in your SIEM software (Splunk, QRadar, ArcSight, LogRhythm…)
  • Retrieve and updating your user-defined lists of IP and Domain names

The STIX/TAXII service supports

  • TAXII HTTP Protocol Binding Specification 1.0
  • STIX XML 1.1.1

Access to this feature

  • Access to this feature must be enabled in your product plan. Please contact your ThreatSTOP representative if your current plan doesn’t include it.
  • When using the feature to update or retrieve User-Defined Lists, the API token must have the corresponding permission, set in the API Keys page of the Admin Portal.
  • When using the feature to retrieve ThreatSTOP targets, any valid API token can be used.

Accessing Services

Authentication

Authentication is performed using a ThreatSTOP API key tied to this service and your account. Once the feature is enabled, you will be able to obtain the required API key by navigating to the SIEM Integration page on the Portal. The API is provided in the STIX and TAXII section.

Service overview

Service URLs:

  • http://taxii.threatstop.com:9000/services/poll-*
  • http://taxii.threatstop.com:9000/services/push-*

  • API key must be included in the request using the Authorization header.
    Authorization:Bearer <API KEY>
    

If your client doesn’t support passing the token using a header, you can also fallback to basic Authentication. Set the username to the API Key, and use any password.

Tools

The STIX/TAXII service should work with any client implementing the supported versions. Examples will be provided using Cabby , a Python-based implementation.

Cabby options:

  • The response can be limited by using the -l argument
  • You can save poll output to a file by using the –dest-dir argument. Received objects will be saved one per file.

Error codes

The service will return the following error codes

  • HTTP Error (status code 404) : Invalid URL provided.
  • NOT_FOUND: ITEM=something; The collection requested was not found - Invalid UDL / target provided. If using Cabby, check the value passed to the -c option.
  • UNAUTHORIZED: Invalid or missing API key, or access to the STIX service is not enabled.
  • FAILURE: There was a failure while executing the message handler - Internal service error or invalid data provided.

User-defined Lists

Domains

To retrieve the domain list contained in a User-defined Domain List, use the poll-udl service:

taxii-poll --path https://taxii.threatstop.com:9000/services/poll-udl --header 'Authorization:Bearer <REST_API_KEY>' -c standard:DOMAIN_LIST_NAME

Sample response

2017-10-19 01:52:59,646 INFO: Polling using data binding: ALL
2017-10-19 01:52:59,648 INFO: Sending Poll_Request to http://taxii.threatstop.com:9000/services/poll-udl
<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ttp="http://stix.mitre.org/TTP-1" xmlns:example="http://example.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:stixCommon="http://stix.mitre.org/common-1" xmlns:DomainNameObj="http://cybox.mitre.org/objects#DomainNameObject-1" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-f719cae8-009a-4f01-836f-7562d4e63502" version="1.2">
   <stix:Indicators>
       <stix:Indicator id="example:indicator-ff23c383-7719-4847-b81f-af2f83ec06a7" timestamp="2017-10-18T22:52:59.839232+00:00" xsi:type="indicator:IndicatorType">
           <indicator:Title>User defined list</indicator:Title>
           <indicator:Type xsi:type="stixVocabs:IndicatorTypeVocab-1.1">URL Watchlist</indicator:Type>
           <indicator:Observable id="example:Observable-882ceb2c-dec1-43a3-a2a5-2e911ed36bfa">
               <cybox:Object id="example:DomainName-672ccaa9-3186-4e3c-bf6b-875507b1999f">
                   <cybox:Properties xsi:type="DomainNameObj:DomainNameObjectType">
                       <DomainNameObj:Value>example.com</DomainNameObj:Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
           <indicator:Indicated_TTP>
               <stixCommon:TTP idref="example:ttp-b5c527a6-5802-41d8-8a49-cf4e8e07b187" xsi:type="ttp:TTPType"/>
           </indicator:Indicated_TTP>
       </stix:Indicator>
   </stix:Indicators>
   <stix:TTPs>
       <stix:TTP id="example:ttp-b5c527a6-5802-41d8-8a49-cf4e8e07b187" timestamp="2017-10-18T22:52:59.839180+00:00" xsi:type="ttp:TTPType">
           <ttp:Title>User defined list</ttp:Title>
       </stix:TTP>
   </stix:TTPs>
</stix:STIX_Package>

<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ttp="http://stix.mitre.org/TTP-1" xmlns:example="http://example.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:stixCommon="http://stix.mitre.org/common-1" xmlns:DomainNameObj="http://cybox.mitre.org/objects#DomainNameObject-1" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-916abffe-d128-4683-a401-22ea6b0a4087" version="1.2">
   <stix:Indicators>
       <stix:Indicator id="example:indicator-a6853fd9-a08f-4a53-a2ad-9d0b7908fa02" timestamp="2017-10-18T22:52:59.840845+00:00" xsi:type="indicator:IndicatorType">
           <indicator:Title>User defined list</indicator:Title>
           <indicator:Type xsi:type="stixVocabs:IndicatorTypeVocab-1.1">URL Watchlist</indicator:Type>
           <indicator:Observable id="example:Observable-957abb1c-c3c7-49be-b2d9-92dcb55b6e6d">
               <cybox:Object id="example:DomainName-af2d6677-6a98-4e93-b96b-0bd1352ce40d">
                   <cybox:Properties xsi:type="DomainNameObj:DomainNameObjectType">
                       <DomainNameObj:Value>sub.example.com</DomainNameObj:Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
           <indicator:Indicated_TTP>
               <stixCommon:TTP idref="example:ttp-6d09c881-36b7-4be7-a6b0-aad866b310e6" xsi:type="ttp:TTPType"/>
           </indicator:Indicated_TTP>
       </stix:Indicator>
   </stix:Indicators>
   <stix:TTPs>
       <stix:TTP id="example:ttp-6d09c881-36b7-4be7-a6b0-aad866b310e6" timestamp="2017-10-18T22:52:59.840769+00:00" xsi:type="ttp:TTPType">
           <ttp:Title>User defined list</ttp:Title>
       </stix:TTP>
   </stix:TTPs>
</stix:STIX_Package>

2017-10-19 01:52:59,851 INFO: 2 blocks polled

IP addresses

To retrieve the list of IP addresses contained in a User-defined List, use the poll-uil service:

taxii-poll --path https://taxii.threatstop.com:9000/services/poll-uil --header 'Authorization:Bearer REST_API_KEY' -c standard:IP_LIST_NAME

Sample response:

2017-10-19 02:03:35,483 INFO: Polling using data binding: ALL
2017-10-19 02:03:35,485 INFO: Sending Poll_Request to http://taxii.threatstop.com:9000/services/poll-uil
<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ttp="http://stix.mitre.org/TTP-1" xmlns:example="http://example.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1" xmlns:stixCommon="http://stix.mitre.org/common-1" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:AddressObj="http://cybox.mitre.org/objects#AddressObject-2" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-577c78f6-f52e-4219-8cd4-31587e09ae7f" version="1.2">
   <stix:Indicators>
       <stix:Indicator id="example:indicator-0dea8139-56d0-45d6-90a4-b0319b549066" timestamp="2017-10-18T23:03:35.853267+00:00" xsi:type="indicator:IndicatorType">
           <indicator:Title>User defined list</indicator:Title>
           <indicator:Type xsi:type="stixVocabs:IndicatorTypeVocab-1.1">IP Watchlist</indicator:Type>
           <indicator:Observable id="example:Observable-01a9718d-4133-47f4-a419-21c2dc57c7ff">
               <cybox:Object id="example:Address-8f454a30-f043-453b-a981-5f9721b898c5">
                   <cybox:Properties xsi:type="AddressObj:AddressObjectType" category="ipv4-addr">
                       <AddressObj:Address_Value condition="Equals">223.4.152.227/32</AddressObj:Address_Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
           <indicator:Indicated_TTP>
               <stixCommon:TTP idref="example:ttp-291285ae-4dfb-44dc-b258-1f96ca49b55a" xsi:type="ttp:TTPType"/>
           </indicator:Indicated_TTP>
       </stix:Indicator>
   </stix:Indicators>
   <stix:TTPs>
       <stix:TTP id="example:ttp-291285ae-4dfb-44dc-b258-1f96ca49b55a" timestamp="2017-10-18T23:03:35.853164+00:00" xsi:type="ttp:TTPType">
           <ttp:Title>User defined list</ttp:Title>
       </stix:TTP>
   </stix:TTPs>
</stix:STIX_Package>

<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ttp="http://stix.mitre.org/TTP-1" xmlns:example="http://example.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1" xmlns:stixCommon="http://stix.mitre.org/common-1" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:AddressObj="http://cybox.mitre.org/objects#AddressObject-2" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-90661992-7492-4fbe-ad41-dd1b70368f10" version="1.2">
   <stix:Indicators>
       <stix:Indicator id="example:indicator-67ee3fc8-82e4-492a-adf5-e25ab8c2a63c" timestamp="2017-10-18T23:03:35.855565+00:00" xsi:type="indicator:IndicatorType">
           <indicator:Title>User defined list</indicator:Title>
           <indicator:Type xsi:type="stixVocabs:IndicatorTypeVocab-1.1">IP Watchlist</indicator:Type>
           <indicator:Observable id="example:Observable-5a210b41-fcc9-455f-a0d0-94be9845bcde">
               <cybox:Object id="example:Address-9ade80f3-c7e2-4566-8bf4-59b564dd39a6">
                   <cybox:Properties xsi:type="AddressObj:AddressObjectType" category="ipv4-addr">
                       <AddressObj:Address_Value condition="Equals">193.23.181.44/32</AddressObj:Address_Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
           <indicator:Indicated_TTP>
               <stixCommon:TTP idref="example:ttp-41abdca3-537d-4b60-9e06-22d8378a9725" xsi:type="ttp:TTPType"/>
           </indicator:Indicated_TTP>
       </stix:Indicator>
   </stix:Indicators>
   <stix:TTPs>
       <stix:TTP id="example:ttp-41abdca3-537d-4b60-9e06-22d8378a9725" timestamp="2017-10-18T23:03:35.855444+00:00" xsi:type="ttp:TTPType">
           <ttp:Title>User defined list</ttp:Title>
       </stix:TTP>
   </stix:TTPs>
</stix:STIX_Package>

2017-10-19 02:03:36,577 INFO: 2 blocks polled

Importing IOCs in user-defined lists

To import IOCs in a User-Defined List, use the push-udl (domains) and push-uil (IPs) services. The STIX data must match the response output described above.

taxii-push --path https://taxii.threatstop.com:9000/services/push-udl --header 'Authorization:Bearer REST_API_KEY' --dest standard:DOMAIN_LIST_NAME -f PATH_TO_FILE_WITH_STIX_PACKAGE
taxii-push --path https://taxii.threatstop.com:9000/services/push-uil --header 'Authorization:Bearer REST_API_KEY' --dest standard:IP_LIST_NAME -f PATH_TO_FILE_WITH_STIX_PACKAGE

Targets

  • Use the poll-target service to retrieve the IoCs currently present in a target list.
    taxii-poll --path https://taxii.threatstop.com:9000/services/poll-target --header 'Authorization:Bearer REST_API_KEY' -c standard:TARGET_NAME [-l LIMIT]
    

Sample response:

2017-10-19 02:10:39,196 INFO: Polling using data binding: ALL
2017-10-19 02:10:39,198 INFO: Sending Poll_Request to http://localhost:9001/services/poll-target
<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:example="http://example.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:AddressObj="http://cybox.mitre.org/objects#AddressObject-2" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-56b75289-d25c-4315-a788-bffe6ae5006b" version="1.2">
   <stix:STIX_Header>
       <stix:Title>Target Package header</stix:Title>
   </stix:STIX_Header>
   <stix:Indicators>
       <stix:Indicator id="example:indicator-d0134909-be51-42a7-85aa-6bee77b68f96" timestamp="2017-10-19T02:10:07" xsi:type="indicator:IndicatorType">
           <indicator:Observable id="example:Observable-84427c2e-589c-44e3-a582-6e95afc6fe4c">
               <cybox:Object id="example:Address-e778be7e-bec1-4140-8b77-bb07c63d5ded">
                   <cybox:Properties xsi:type="AddressObj:AddressObjectType" category="ipv4-addr">
                       <AddressObj:Address_Value condition="Equals">2.16.217.128/25</AddressObj:Address_Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
       </stix:Indicator>
   </stix:Indicators>
</stix:STIX_Package>

<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:example="http://example.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:AddressObj="http://cybox.mitre.org/objects#AddressObject-2" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-183ca966-358a-4062-8346-384ab70671a3" version="1.2">
   <stix:STIX_Header>
       <stix:Title>Target Package header</stix:Title>
   </stix:STIX_Header>
   <stix:Indicators>
       <stix:Indicator id="example:indicator-90e0dc65-fc92-4801-b2bf-54bcd7face42" timestamp="2017-10-19T02:10:07" xsi:type="indicator:IndicatorType">
           <indicator:Observable id="example:Observable-81257853-9166-42e1-aa86-2c9e0ed6bdc8">
               <cybox:Object id="example:Address-e92d99bc-9da8-471a-ad34-206b8aa00f69">
                   <cybox:Properties xsi:type="AddressObj:AddressObjectType" category="ipv4-addr">
                       <AddressObj:Address_Value condition="Equals">2.60.0.0/14</AddressObj:Address_Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
       </stix:Indicator>
   </stix:Indicators>
</stix:STIX_Package>

<stix:STIX_Package xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cyboxCommon="http://cybox.mitre.org/common-2" xmlns:example="http://example.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stix="http://stix.mitre.org/stix-1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:indicator="http://stix.mitre.org/Indicator-2" xmlns:cybox="http://cybox.mitre.org/cybox-2" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:AddressObj="http://cybox.mitre.org/objects#AddressObject-2" xmlns:taxii="http://taxii.mitre.org/messages/taxii_xml_binding-1" xmlns:taxii_11="http://taxii.mitre.org/messages/taxii_xml_binding-1.1" xmlns:tdq="http://taxii.mitre.org/query/taxii_default_query-1" id="example:Package-a7c875f9-e09a-44ad-8a64-a0651a838f5f" version="1.2">
   <stix:STIX_Header>
       <stix:Title>Target Package header</stix:Title>
   </stix:STIX_Header>
   <stix:Indicators>
       <stix:Indicator id="example:indicator-0b07d79a-ecd2-4aa0-9e7b-e452da65c120" timestamp="2017-10-19T02:10:07" xsi:type="indicator:IndicatorType">
           <indicator:Observable id="example:Observable-22ce0c90-c7e5-4321-9e1b-f35ef43349de">
               <cybox:Object id="example:Address-afecc252-0e0d-4837-86a2-b8a430327166">
                   <cybox:Properties xsi:type="AddressObj:AddressObjectType" category="ipv4-addr">
                       <AddressObj:Address_Value condition="Equals">2.92.0.0/14</AddressObj:Address_Value>
                   </cybox:Properties>
               </cybox:Object>
           </indicator:Observable>
       </stix:Indicator>
   </stix:Indicators>
</stix:STIX_Package>

2017-10-19 02:10:40,666 INFO: 3 blocks polled        

Additional Resources

  • STIX/TAXII home page: https://stixproject.github.io/
  • Samples: https://stix.mitre.org/language/version1.1.1/samples.html
  • TAXII client: https://cabby.readthedocs.io/en/stable/
  • Utilities: https://stixproject.github.io/documentation/utilities/