TAXII™ Version 2.0
Committee Specification Draft 01 /
Public Review Draft 01
03 May 2017
Specification URIs
This version:
http://docs.oasis-open.org/cti/taxii/v2.0/csprd01/taxii-v2.0-csprd01.docx (Authoritative)
http://docs.oasis-open.org/cti/taxii/v2.0/csprd01/taxii-v2.0-csprd01.html
http://docs.oasis-open.org/cti/taxii/v2.0/csprd01/taxii-v2.0-csprd01.pdf
Previous version:
N/A
Latest version:
http://docs.oasis-open.org/cti/taxii/v2.0/taxii-v2.0.docx (Authoritative)
http://docs.oasis-open.org/cti/taxii/v2.0/taxii-v2.0.html
http://docs.oasis-open.org/cti/taxii/v2.0/taxii-v2.0.pdf
Technical Committee:
OASIS Cyber Threat Intelligence (CTI) TC
Chair:
Richard Struse (Richard.Struse@hq.dhs.gov), DHS Office of Cybersecurity and Communications (CS&C)
Editors:
John Wunder (jwunder@mitre.org), MITRE Corporation
Mark Davidson (Mark.Davidson@nc4.com), NC4
Bret Jordan (bret_jordan@symantec.com), Symantec Corp.
This specification replaces or supersedes:
This specification is related to:
Abstract:
Trusted Automated eXchange of Intelligence Information (TAXII™) is an application layer protocol for the communication of cyber threat information in a simple and scalable manner. This specification defines the TAXII RESTful API and its resources along with the requirements for TAXII Client and Server implementations.
Status:
This document was last revised or approved by the OASIS Cyber Threat Intelligence (CTI) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=cti#technical.
TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/cti/.
This Committee Specification Public Review Draft is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/cti/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Citation format:
When referencing this specification the following citation format should be used:
[TAXII-v2.0]
TAXII™ Version 2.0. Edited by John Wunder, Mark Davidson, and Bret Jordan. 03 May 2017. OASIS Committee Specification Draft 01 / Public Review Draft 01. http://docs.oasis-open.org/cti/taxii/v2.0/csprd01/taxii-v2.0-csprd01.html. Latest version: http://docs.oasis-open.org/cti/taxii/v2.0/taxii-v2.0.html.
Notices
Copyright © OASIS Open 2017. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Portions copyright © United States Government 2012-2017. All Rights Reserved.
STIX™, CYBOX™, AND TAXII™ (STANDARD OR STANDARDS) AND THEIR COMPONENT PARTS ARE PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THESE STANDARDS OR ANY OF THEIR COMPONENT PARTS WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE STANDARDS OR THEIR COMPONENT PARTS WILL BE ERROR FREE, OR ANY WARRANTY THAT THE DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE STANDARDS OR THEIR COMPONENT PARTS. IN NO EVENT SHALL THE UNITED STATES GOVERNMENT OR ITS CONTRACTORS OR SUBCONTRACTORS BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY CONNECTED WITH THESE STANDARDS OR THEIR COMPONENT PARTS OR ANY PROVIDED DOCUMENTATION, WHETHER OR NOT BASED UPON WARRANTY, CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE STANDARDS, THEIR COMPONENT PARTS, AND ANY PROVIDED DOCUMENTATION. THE UNITED STATES GOVERNMENT DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THE STANDARDS OR THEIR COMPONENT PARTS ATTRIBUTABLE TO ANY THIRD PARTY, IF PRESENT IN THE STANDARDS OR THEIR COMPONENT PARTS AND DISTRIBUTES IT OR THEM "AS IS."
Table of Contents
1.4.8 Authentication and Authorization
3.4.1 Object and Collection Ranges
3.4.3 Endpoints Supporting Pagination
3.5.1 Supported Fields for Match
4 TAXII™ API - Server Information
8.1.2 TAXII™ 2.0 Collections Server
8.1.3 TAXII™ 2.0 Channels Server
8.2.1 TAXII Server Core Requirements
8.2.2 HTTPS and Authentication Server Requirements.
8.3.1 Client Certificate Verification
8.4.2 TAXII™ 2.0 Collections Client
8.4.3 TAXII™ 2.0 Channels Client
8.5.1 HTTPS and Authentication Client Requirements.
8.5.2 Server Certificate Verification
TAXII™ is an application layer protocol for the communication of cyber threat information in a simple and scalable manner. This specification defines the TAXII RESTful API and its resources along with the requirements for TAXII Client and Server implementations.
1.0.1 IPR Policy
This Committee Specification Public Review Draft is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/cti/ipr.php).
1.1 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
All text is normative except for examples, the overview (section 1.4), and any text marked non-normative.
1.2 Normative References
[HTTP Auth] IANA, “Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry”, March 2017, [Online]. Available: https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml
[ISO10646] “ISO/IEC 10646:2014 Information technology -- Universal Coded Character Set (UCS)”, 2014. [Online]. Available: http://standards.iso.org/ittf/PubliclyAvailableStandards/c063182_ISO_IEC_10646_2014.zip
[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, http://www.rfc-editor.org/info/rfc20.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, http://www.rfc-editor.org/info/rfc2119.
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, February 2000, http://www.rfc-editor.org/info/rfc2782.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, http://www.rfc-editor.org/info/rfc3339.
[RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, "DNS Security Introduction and Requirements", RFC 4033, DOI 10.17487/RFC4033, March 2005, http://www.rfc-editor.org/info/rfc4033.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005, http://www.rfc-editor.org/info/rfc4122.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, http://www.rfc-editor.org/info/rfc5246.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, http://www.rfc-editor.org/info/rfc5280.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011, http://www.rfc-editor.org/info/rfc6125.
[RFC6818] Yee, P., "Updates to the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 6818, DOI 10.17487/RFC6818, January 2013, http://www.rfc-editor.org/info/rfc6818.
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, http://www.rfc-editor.org/info/rfc7230.
[RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, http://www.rfc-editor.org/info/rfc7231.
[RFC7233] Fielding, R., Ed., Y. Lafon, Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 10.17487/RFC7233, June 2014, http://www.rfc-editor.org/info/rfc7233.
[RFC7235] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 10.17487/RFC7235, June 2014, http://www.rfc-editor.org/info/rfc7235.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, http://www.rfc-editor.org/info/rfc7540.
[RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, DOI 10.17487/RFC7617, September 2015, http://www.rfc-editor.org/info/rfc7617.
[RFC7671] Dukhovni, V. and W. Hardaker, "The DNS-Based Authentication of Named Entities (DANE) Protocol: Updates and Operational Guidance", RFC 7671, DOI 10.17487/RFC7671, October 2015, http://www.rfc-editor.org/info/rfc7671.
[TLS1.3] E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.3 draft-ietf-tls-tls13-18", RFC draft, [Online]. Available: https://tools/ietf.org/html/draft-ietf-tis-tis13-18.
1.3 Document Conventions
1.3.1 Naming Conventions
All type names, property names and literals are in lowercase. Words in property names are separated with an underscore (_), while words in type names and string enumerations are separated with a dash (-). All type names, property names, object names, and vocabulary terms are between three and 250 characters long.
1.3.2 Font Colors and Style
The following color, font and font style conventions are used in this document:
● The Consolas font is used for all type names, property names and literals.
○ resource and type names are in red with a light red background – collection
○ property names are in bold style – description
○ parameter names in URLs are stylized with angled brackets - <api-root>
○ literals (values) are in blue with a blue background – complete
● All examples in this document are expressed in JSON. They are in Consolas 9-point font, with straight quotes, black text and a light grey background, and 2-space indentation.
● Parts of the example may be omitted for conciseness and clarity. These omitted parts are denoted with ellipses (...).
1.4 Overview
Trusted Automated Exchange of Intelligence Information (TAXII) is an application layer protocol used to exchange cyber threat intelligence (CTI) over HTTPS. TAXII enables organizations to share CTI by defining an API that aligns with common sharing models. Specifically, TAXII defines two primary services, Collections and Channels, to support a variety of commonly-used sharing models. Collections allow a producer to host a set of CTI data that can be requested by consumers. Channels allow producers to push data to many consumers; and allow consumers to receive data from many producers. Collections and Channels can be organized by grouping them into an API Root to support the needs of a particular trust group or to organize them in some other way. Note: This version of the TAXII specification reserves the keywords required for Channels but does not specify Channel services. Channels and their services will be defined in a subsequent version of this specification.
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.
1.4.1 Discovery
This specification defines two discovery methods. The first is a network level discovery that uses a DNS SRV record [RFC2782]. This DNS SRV record can be used to advertise the location of a TAXII Server within a network (e.g., so that TAXII-enabled security infrastructure can automatically locate an organization's internal TAXII Server) or to the general Internet. See section 3.9 for complete information on advertising TAXII Servers in DNS.
The second discovery method is a Discovery Endpoint (this specification uses the term Endpoint to identify a URL and an HTTP method with a defined request and response) that enables authorized clients to obtain information about a TAXII Server and get a list of API Roots. See section 4.1 for complete information on the Discovery Endpoint.
1.4.2 API Roots
API Roots are logical groupings of TAXII Channels, Collections, and related functionality. A TAXII server instance can support one or more API Roots. API Roots can be thought of as instances of the TAXII API available at different URLs, where each API Root is the "root" URL of that particular instance of the TAXII API. Organizing the Channels and Collections into API Roots allows for a division of content and access control by trust group or any other logical grouping. For example, a single TAXII Server could host multiple API Roots - one API Root for Channels and Collections used by Sharing Group A and another API Root for Channels and Collections used by Sharing Group B.
Each API Root contains a set of Endpoints that a TAXII Client contacts in order to interact with the TAXII Server. This interaction can take several forms:
● Server Discovery, as described above, can be used to learn about the API Roots hosted by a TAXII Server.
● Each API Root might support zero or more Collections. Interactions with Collections include discovering the type of CTI contained in that Collection, pushing new CTI to that Collection, and/or retrieving CTI from that Collection. Each piece of CTI content in a Collection is referred to as an Object.
● Each API Root might host zero or more Channels.
● Each API Root also allows TAXII Clients to check on the Status of certain types of requests to the TAXII Server. For example, if a TAXII Client submitted new CTI, a Status request can allow the Client to check on whether the new CTI was accepted.
Figure 1.1 summarizes the relationships between the components of an API Root.
Figure 1.1
1.4.3 Endpoints
An Endpoint consists of a specific URL and HTTP Method on a TAXII Server that a TAXII Client can contact to engage in one, specific type of TAXII exchange. For example, each Collection on a TAXII Server has an Endpoint that can be used to get information about it; TAXII Clients can contact the Collection’s Endpoint to request a description of that Collection. A separate Endpoint is used for the TAXII Client to collect a manifest of that Collection’s Content. Yet another Endpoint is used to get objects from the Collection and, at the same URL, a POST can be used to add objects to the collection. The Endpoints supported by a TAXII Server are summarized in section 3.1 and fully defined in sections 4, 5, and 6.
1.4.4 Collections
A TAXII Collection is an interface to a logical repository of CTI objects provided by a TAXII Server and is used by TAXII Clients to send information to the TAXII Server or request information from the TAXII Server. A TAXII Server can host multiple Collections per API Root, and Collections are used to exchange information in a request–response manner.
Figure 1.2 below illustrates how Collection based communications are used when a single TAXII Client makes a request to a TAXII Server and the TAXII Server fulfills that request with information available to the TAXII Server (nominally from a database).
1.4.5 Channels
A TAXII Channel is maintained by a TAXII Server and enables TAXII Clients to exchange information with other TAXII Clients in a publish-subscribe model. TAXII Clients can publish messages to Channels and subscribe to Channels to receive published messages. A TAXII Server may host multiple Channels per API Root.
Figure 1.3 below illustrates how Channel communications are used when a single authorized TAXII Client sends a message to the TAXII Server, and that TAXII Server then distributes the message to all authorized TAXII Clients that are connected to the Channel.
Figure 1.2 Figure 1.3
|
|
1.4.6 Transport
The TAXII protocol defined in this specification uses HTTPS (HTTP over TLS) as the transport for all communications.
1.4.7 Content Negotiation
This specification uses HTTP content negotiation [RFC7231]. The STIX 2.0 and TAXII 2.0 media types are defined in the following table.
|
Media Type |
Description |
|
application/vnd.oasis.taxii+json |
Any version of TAXII in JSON |
|
application/vnd.oasis.taxii+json; version=2.0 |
TAXII version 2.0 in JSON |
|
application/vnd.oasis.stix+json |
Any version of STIX in JSON |
|
application/vnd.oasis.stix+json; version=2.0 |
STIX version 2.0 in JSON |
1.4.8 Authentication and Authorization
Access control to an instance of the TAXII API is expected to be specific to the sharing community, vendor, or product and is not defined by this specification.
Authentication and Authorization in TAXII is implemented as defined in [RFC7235], using the Authorization and WWW-Authenticate HTTP headers respectively.
HTTP Basic authentication, as defined in [RFC7617] is the mandatory to implement authentication scheme in TAXII. As specified in sections 8.2.2 and 8.5.1, TAXII Servers and Clients are required to implement support for HTTP Basic, though other authentication schemes can also be supported. Implementers can allow operators to disable the use of HTTP Basic in their operations.
If the TAXII Server receives a request for any Endpoint that requires authentication, regardless of HTTP method, and either an acceptable Authorization header that grants the client access to that object is not sent with the request or the TAXII Server does not determine via alternate means that the client is authorized to access the resource, the TAXII Server responds with a HTTP 401 (Unauthorized) status code and a WWW-Authenticate HTTP header.
The WWW-Authenticate header contains one or more challenges, which define which authentication schemes are supported by the TAXII Server. The format of the WWW-Authenticate HTTP header and any challenges are defined in [RFC7235]. To ensure compatibility, it is recommended that any authentication schemes used in challenges be registered in the IANA Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry [HTTP Auth].
A TAXII Server may omit objects, information, or optional fields from any response if the authenticated client is not authorized to receive them, so long as that omission does not violate this specification.
1.4.9 STIX and Other Content
TAXII is designed with STIX in mind and support for exchanging STIX 2.0 [STIX™ Version 2.0. Part 1: STIX Core Concepts] content is mandatory to implement. Additional content types are permitted, but specific requirements for STIX are present throughout the document. See section 3.7 for more details.
This section defines the names and permitted values of common types used throughout this specification. These types are referenced by the “Type” column in other sections. This table does not, however, define the meaning of any fields using these types. These types may be further restricted elsewhere in the document.
|
Type |
Description |
|
api-root |
An API Root Resource, see section 4.2.1. |
|
boolean |
A boolean is a value of either true or false. Properties with this type MUST have a literal (unquoted) value of true or false. |
|
bundle |
A STIX Bundle, see section 5 of STIX™ Version 2.0. Part 1: STIX Core Concepts. |
|
collection |
A Collection Resource, see section 5.2.1. |
|
collections |
A Collections Resource, see section 5.1.1. |
|
dictionary |
A dictionary is a JSON object that captures an arbitrary set of key/value pairs. |
|
discovery |
A Discovery Resource, see section 4.1.1. |
|
error |
An Error Message, see section 3.6.1. |
|
identifier |
An identifier is an RFC 4122-compliant Version 4 UUID. The UUID MUST be generated according to the algorithm(s) defined in RFC 4122, section 4.4 (Version 4 UUID) [RFC4122]. |
|
integer |
The integer data type represents a whole number. Unless otherwise specified, all integers MUST be capable of being represented as a signed 64-bit value. Additional restrictions MAY be placed on the type where it is used. |
|
list |
The list type defines a sequence of values ordered based on how they appear in the list. The phrasing “list of type <type>” is used to indicate that all values within the list MUST conform to the specified type. For instance, list of type integer means that all values of the list must be of the integer type.
This specification does not specify the maximum number of allowed values in a list, however every instance of a list MUST have at least one value. Specific TAXII resource properties may define more restrictive upper and/or lower bounds for the length of the list.
Empty lists are prohibited in TAXII and MUST NOT be used as a substitute for omitting optional properties. If the property is required, the list MUST be present and MUST have at least one value.
The JSON MTI serialization uses the JSON array type [RFC7159], which is an ordered list of zero or more values. |
|
manifest |
A Manifest Resource, see section 5.6.1. |
|
object |
An Object Resource, see section 3.7. |
|
status |
A Status Resource, see section 4.3.1. |
|
string |
The string data type represents a finite-length string of valid characters from the Unicode coded character set [ISO10646] that are encoded in UTF-8. Unicode incorporates ASCII [RFC0020] and the characters of many other international character sets. |
|
timestamp |
The timestamp type defines how timestamps are represented in TAXII and is represented in serialization as a string.
● The timestamp field MUST be a valid RFC 3339-formatted timestamp [RFC3339] using the format YYYY-MM-DDTHH:mm:ss.[s+]Z where the “s+” represents 1 or more sub-second values. The brackets denote that sub-second precision is optional, and that if no digits are provided, the decimal place MUST NOT be present. ● The timestamp MUST be represented in the UTC timezone and MUST use the “Z” designation to indicate this. |
The TAXII API is described as sets of Endpoints. Each Endpoint is identified by the URL that it is accessible at and the HTTP method that is used to make the request. For example, the "Get Collections" Endpoint is requested by issuing a GET to `<api-root>/collections/`. Each Endpoint identifies its URL, which parameters it accepts (including both path parameters and standard parameters), which features it supports (e.g. filtering, pagination), and which content types it defines on request and response. It also identifies common error conditions and provides guidance on how to use the Endpoint.
This section defines behavior that applies across Endpoints, such as normative requirements to support each Endpoint, sorting, pagination, filtering, and error handling.
3.1 Endpoints
Sections 4, 5 and 6 define the set of TAXII Endpoints used in the TAXII API. The following normative requirements apply to each Endpoint:
● All TAXII requests MUST include a media range in the Accept header. Requests for TAXII or STIX content MUST use the values from section 1.4.7 and SHOULD include the version parameter.
● All TAXII responses MUST include the appropriate media type and version parameter in the Content-Type header as defined for that Endpoint.
● TAXII responses SHOULD be the highest version of content (e.g., TAXII, STIX) that the server supports if the version parameter in the Accept header is omitted during content negotiation.
● TAXII responses with an HTTP success code (200 series) that permit a response body MUST include the appropriate response body for the specified content type as identified in the definition of that Endpoint.
● TAXII responses with an HTTP error code (400-series and 500-series status codes, defined by sections 6.5 and 6.6 of [RFC7231]) that permit a response body (i.e. are not in response to a HEAD request) MUST contain an error message (see section 3.6.1) in the response body.
● Requests with media types in the Accept and/or Content-Type headers that are defined for that Endpoint MUST NOT result in an HTTP 406 (Not Acceptable) or HTTP 415 (Unacceptable Media Type) response.
● Requests with media types in the Accept and/or Content-Type headers that are not defined for that Endpoint MAY be satisfied with the appropriate content or MAY result in an HTTP 406 (Not Acceptable) or HTTP 415 (Unacceptable Media Type) response.
● TAXII responses from Endpoints that support pagination and include items as a requested range unit MUST comply with the normative requirements in section 3.4 and MUST respond with an appropriate 200, 206, or 416 response per the HTTP specification [RFC7233].
● TAXII responses to Endpoints that support filtering MUST filter results per the requirements in section 3.5.
The following table provides a summary of the Endpoints (URLs and HTTP Methods) defined by TAXII and the Resources they operate on.
|
URL |
Methods |
Resource Type (section 2) |
|
Core Concepts (section 4) |
|
|
|
/taxii/ |
GET |
discovery |
|
<api-root> |
GET |
api |
|
<api-root>/status/<status-id>/ |
GET |
status |
|
Collections (section 5) |
|
|
|
<api-root>/collections/ |
GET |
collections |
|
<api-root>/collections/<id>/ |
GET |
collection |
|
<api-root>/collections/<id>/objects/ |
GET, POST |
object* |
|
<api-root>/collections/<id>/objects/<object-id>/ |
GET |
object* |
|
<api-root>/collections/<id>/manifest/ |
GET |
manifest |
|
Channels (section 6) |
|
|
|
<TBD in a future version> |
|
|
* The actual format of objects is dependent on HTTP Content negotiation, as discussed in section 1.4.7
3.2 HTTP Headers
This section summarizes the HTTP headers and defines custom headers used by this specification.
|
Type |
Description |
|
Standard Headers |
|
|
Accept |
The Accept header is used by HTTP Requests to specify which Content-Types are acceptable in response. STIX and TAXII define media types that can be used in the Accept header in section 1.4.7. See section 5.3.2 of [RFC7231]. |
|
Accept-Ranges |
The Accept-Ranges header is used by HTTP Responses to specify its acceptance of range requests for a resource. See section 2.3 of [RFC7233]. |
|
Authorization |
The Authorization header is used by HTTP Requests to specify authentication credentials. See section 4.2 of [RFC7235]. |
|
Content-Range |
The Content-Range header is used by HTTP to identify which subrange(s) of a resource are contained in an HTTP 206 (Partial Content) response. See section 4.2 of [RFC7233]. |
|
Content-Type |
The Content-Type header is used by HTTP to identify the format of HTTP Requests and HTTP Responses. STIX and TAXII define media types that can be used in the Content-Type header in section 1.4.7. See section 3.1.1.5 of [RFC7231]. |
|
Range |
The Range header is used by HTTP to request a subrange of a resource. TAXII uses the Range header, and related headers, to perform pagination. See section 3.1 of [RFC7233]. |
|
WWW-Authenticate |
The WWW-Authenticate header is used by HTTP Responses to indicate that authentication is required and to specify the authentication schemes and parameters that are supported. See section 4.1 of [RFC7235]. |
|
Custom Headers |
|
|
X-TAXII-Date-Added-First |
The X-TAXII-Date-Added-First header is an extension header. It indicates the date_added timestamp of the first object of the response.
The value of this header MUST be a timestamp. All HTTP 200 and 206 responses to the following Endpoints MUST include the X-TAXII-Date-Added-First header: ● GET <api-root>/collections/objects/ ● GET <api-root>/collections/manifest/ |
|
X-TAXII-Date-Added-Last |
The X-TAXII-Date-Added-Last header is an extension header. It indicates the date_added timestamp of the last object of the response.
The value of this header MUST be a timestamp. All HTTP 200 and 206 responses to the following Endpoints MUST include the X-TAXII-Date-Added-Last header: ● GET <api-root>/collections/objects/ ● GET <api-root>/collections/manifest/ |
3.3 Sorting
For the Collection and Manifest Endpoints, objects MUST be sorted in ascending order by the date the object first appeared in the TAXII Collection (i.e., the added date). The most recently added object is last in the list.
For the Object Search Endpoint, objects MUST be sorted in ascending order by the date the object first appeared in object search (i.e., the added date). If an object would appear multiple times (for instance, a single object was added to different Collections at different times), subsequent appearances of that object MUST be omitted from the result.
For the Collections Endpoint, Collections MUST be sorted and MAY be sorted in any order. Pagination requires a consistent sort order, and therefore multiple responses from the same endpoint need to be sorted in a consistent manner. Sort order MUST be consistent across responses.
3.4 Pagination
Pagination is a feature that is used to break up result sets over multiple request/response pairs. TAXII uses HTTP's Range and Content-Range headers, and defines the items range unit, to perform pagination as defined in section 2 of [RFC7233]. items is the mandatory to implement range unit for TAXII. Other range units MAY be implemented by clients and servers.
3.4.1 Object and Collection Ranges
The items range unit is defined for expressing subranges of a resource [HTTP 7233]. For the Endpoints that return object, items represents objects. For the Endpoints that return collections, items represents Collections.
The first items value in the Range and Content-Range headers gives the first item in a range. The last items value in the Range and Content-Range headers gives the last item in the range; that is, items ranges specified are inclusive. items are zero-indexed; that is, the first item is object zero. A Content-Range header will have a third value that identifies the size of the available dataset.
For example:
● If the Range header contains "items 10-49", "10" represents the first item requested; and "49" represents the last item requested.
● if the Content-Range header contains "items 10-49/500", "10" represents the first object in the response; "49" represents the last object in the response; and "500" represents the total number of items available.
All items values MUST be:
● a non-negative integer
● zero indexed (i.e., the first object is object "0")
3.4.2 Requirements
The following requirements only apply to items based range requests (aka pagination).
● The Accept-Ranges header allows a server to indicate that it supports range requests for the target resource [RFC7233] as well as which range units are supported.
● For resources where items-based pagination is supported, and where the Accept-Ranges header is present, the Accept-Ranges header MUST contain items as an acceptable range. The Accept-Ranges header MAY contain other acceptable ranges, if the server supports them.
● Requests MAY use the Range header to request a subset of data that would otherwise be returned.
● As defined in the HTTP specification, HTTP 206 (Partial Content) [RFC7233] responses include a Content-Range header, even if the entire resource is contained in the response.
● As defined in the HTTP specification, if the requested Range cannot be satisfied, an HTTP 416 (Requested Range Not Satisfiable) [RFC7233] response is used.
○ For example, if a range requests items 500-600, but only 0-100 are available, an HTTP 416 (Requested Range Not Satisfiable) is used.
● An HTTP 206 (Partial Content) response with a Content-Range header MAY be returned even if the original request did not have a Range header.
○ Note that this is a deviation from the HTTP specification, which indicates that HTTP 206 responses are only permitted when the Range header is present in the request.
● Responses to requests with a Range header SHOULD contain only the requested range and MAY include a range smaller than what was requested.
● TAXII follows standard HTTP rules for the Content-Range and Range headers, with the exception of allowing a 206 response to a request without a Range header:
○ The 206 (Partial Content) status code indicates that the server is successfully fulfilling a range request for the target resource see section 4.1 of [RFC7233]
○ If a single part is being transferred, the server generating the 206 response MUST generate a Content-Range header field, describing what range of the selected representation is enclosed, and a payload consisting of the range. See section 4.2 of [RFC7233].
NOTE: The total number of items available in a result may change with each request for a new page in the paginated result set. This can happen if items have been added or deleted between subsequent requests.
3.4.3 Endpoints Supporting Pagination
The following URL Endpoints support Pagination.
● GET <api-root>/collections/ - see section 5.1.
● GET <api-root>/collections/<name>/objects/ - see section 5.3.
● GET <api-root>/collections/<name>/manifest/ - see section 5.6.
Examples
Client makes a request with no Range header and server returns all results, no pagination.
|
GET Request GET .../collections/my-collection/objects/?added_after=2016-02-01T00:00:01.000Z HTTP/1.1 Accept: application/vnd.oasis.stix+json; version=2.0
Get Response HTTP/1.1 200 Ok Content-Type: application/vnd.oasis.stix+json; version=2.0 |
Client makes a request for items 0-49 (50 items) and the server responds with 0-49.
|
GET Request GET .../collections/my-collection/objects/?added_after=2016-02-01T00:00:01.000Z HTTP/1.1 Range: items 0-49 Accept: application/vnd.oasis.stix+json; version=2.0
GET Response HTTP/1.1 206 Partial Content Content-Type: application/vnd.oasis.stix+json; version=2.0 X-TAXII-Date-Added-First=2016-02-21T05:01:01.000Z X-TAXII-Date-Added-Last=2016-02-21T12:01:01.000Z Content-Range: items 0-49/500 |
Client makes a request for items 0-999 (1000 items) and the server responds with 0-49 (50 items).
|
GET Request GET .../collections/my-collection/objects/?added_after=2016-02-01T00:00:01.000Z HTTP/1.1 Range: items 0-999 Accept: application/vnd.oasis.stix+json; version=2.0
GET Response HTTP/1.1 206 Partial Content Content-Type: application/vnd.oasis.stix+json; version=2.0 X-TAXII-Date-Added-First=2016-02-21T05:01:01.000Z X-TAXII-Date-Added-Last=2016-02-21T12:01:01.000Z Content-Range: items 0-49/500 |
Client makes a request with no Range header and server responds with pagination. This example shows the first and second requests in this series. Note: the client needs to add the "Range" header to the second request.
|
GET Request 1 GET .../collections/my-collection/objects/?added_after=2016-02-01T00:00:01.000Z HTTP/1.1 Accept: application/vnd.oasis.stix+json; version=2.0
GET Response 1 HTTP/1.1 206 Partial Content Content-Type: application/vnd.oasis.stix+json; version=2.0 X-TAXII-Date-Added-First=2016-02-21T05:01:01.000Z X-TAXII-Date-Added-Last=2016-02-21T12:01:01.000Z Content-Range: items 0-99/500
GET Request 2 GET .../collections/my-collection/objects/?added_after=2016-02-01T00:00:01.000Z HTTP/1.1 Range: items 100-199 Accept: application/vnd.oasis.stix+json; version=2.0
GET Response 2 HTTP/1.1 206 Partial Content Content-Type: application/vnd.oasis.stix+json; version=2.0 X-TAXII-Date-Added-First=2016-02-21T05:01:01.000Z X-TAXII-Date-Added-Last=2016-02-21T12:01:01.000Z Content-Range: items 100-199/500 |
3.5 Filtering
This section defines the URL parameters used for matching and filtering content. A TAXII Client may request specific content from a TAXII Server by specifying a set of filters included in the request to the server. The match parameter specifies what to include in the response from the TAXII Server. If no match parameter is specified then the TAXII Client is requesting all content be returned for that Endpoint.
|
URL Parameters |
Description |
|
added_after |
A timestamp that filters objects to only include those added to the Channel or Collection after the specified timestamp. The value of this parameter is a timestamp.
The added_after parameter is not in any way related to dates or times in a STIX object or any other CTI object.
Note: The HTTP Date header can be used to identify and correct any time skew between client and server. |
|
match[<field>] |
The match parameter defines filtering on the specified <field>. The list of fields that must be supported is defined per Endpoint as defined in sections 4, 5, and 6. The match parameter can be specified any number of times, where each match instance specifies an additional filter to be applied to the resulting data. Said another way, all match fields are ANDed together. All <field> parameters are defined in this table. Requests MAY use a <field> not defined in this specification, and servers MAY ignore fields they do not understand.
Each <field> MUST NOT occur more than once in a request.
Each match MAY contain one or more values. Multiple values are separated by a comma (U+002C COMMA, “,”) without any spaces. If multiple values are present, the match is treated as a logical OR. For instance, ?match[type]=incident,ttp specifies a filter for objects that are of type incident OR ttp.
Examples ?match[type]=incident,ttp,actor
?match[type]=incident&match[version]=2016-01-01T01:01:01.000Z |
3.5.1 Supported Fields for Match
|
Match Field |
Description |
|
id |
The identifier of the object(s) that are being requested. When searching for a STIX Object, this is a STIX ID.
|
|
type |
The type of the object(s) that
are being requested. Only the types listed in this parameter are permitted in
the response.
|
|
version |
The version of the object(s) that are being requested. If no version parameter is provided, the server MUST return the latest version of the object.
Valid values for the version parameter are: ● last - requests the latest version of an object. This is the default parameter value. ● first - requests the earliest version of an object ● all - requests all versions of an object ● <value> - requests a specific version of an object. ○ For STIX objects this requests objects whose modified time matches exactly the provided value. This value MUST follow the rules for timestamp as defined in [STIX™ Version 2.0. Part 1: STIX Core Concepts]. ○ For example: "2016-01-01T01:01:01.000Z" tells the server to give you the exact STIX object with a modified time of "2016-01-01T01:01:01.000Z". ○ For non-STIX objects this value MAY be any string that represents the version of that object type. If the target format does not support object versions, this parameter MUST be ignored. |
3.6 Errors
TAXII primarily relies on the standard HTTP error semantics (400-series and 500-series status codes, defined by sections 6.5 and 6.6 of [RFC7231]) to allow TAXII Servers to indicate when an error has occurred. For example, an HTTP 404 (Not Found) status code in response to a request to get information about a Collection means that the Collection could not be found. The tables defining the Endpoints in sections 4 and 5 identify common errors and which response should be used, but are not exhaustive and do not describe all possible errors.
In addition to this, TAXII defines an error message structure that is provided in the response body when an error status is being returned. It does not, however, define any error codes or error conditions beyond those defined by HTTP.
3.6.1 Error Message
Message Name: error
The error message is provided by TAXII Servers in the response body when returning an HTTP error status and contains more information describing the error, including a human-readable title and description, an error_code and error_id, and a details structure to capture further structured information about the error. All of the fields are application-specific and clients shouldn't assume consistent meaning across TAXII Servers even if the codes, IDs, or titles are the same.
|
Property Name |
Type |
Description |
|
title (required) |
string |
A human readable plain text title for this error. |
|
description (optional) |
string |
A human readable plain text description that gives details about the error or problem that was encountered by the application. |
|
error_id (optional) |
string |
An identifier for this particular error instance. A TAXII Server might choose to assign each error occurrence it's own identifier in order to facilitate debugging. |
|
error_code (optional) |
string |
The error code for this error type. A TAXII Server might choose to assign a common error code to all errors of the same type. Error codes are application-specific and not intended to be meaningful across different TAXII Servers. |
|
http_status (optional) |
string |
The HTTP status code applicable to this error. |
|
external_details (optional) |
string |
A URL that points to additional details. For example, this could be a URL pointing to a knowledge base article describing the error code. Absence of this field indicates that there are no additional details. |
|
details (optional) |
dictionary |
The details property captures additional server-specific details about the error. The keys and values are determined by the TAXII Server and MAY be any valid JSON object structure. |
Examples
{
"title": "Error condition XYZ",
"description": "This error is caused when the application tries to access data...",
"error_id": "1234",
"error_code": "581234",
"http_status": "409",
"external_details": "http://example.com/ticketnumber1/errorid-1234",
"details": {
"somekey1": "somevalue",
"somekey2": "some other value"
}
}
3.7 Object Resource
Resource Name: object
This resource type is negotiated based on the media type. This specification does not define any form of content wrapper for objects. Instead, objects are the direct payload of HTTP messages.
When returning STIX 2 content (the Content-Type header contains application/vnd.oasis.stix+json; version=2.0) in a TAXII response, the root object MUST be a STIX bundle per section 5 of STIX™ Version 2.0. Part 1: STIX Core Concepts. For example:
● A single indicator in response to a request for an indicator by ID is enclosed in a bundle.
● A list of campaigns returned from a Collection is enclosed in a bundle.
● An empty response with no STIX objects results in an empty bundle.
Definitions for media types other than STIX can be found in their respective specifications.
Examples
{
"type": "bundle",
...,
"indicators": [
{
"type": "indicator",
"id": "indicator--252c7c11-daf2-42bd-843b-be65edca9f61",
...,
}
]
}
3.8 Property Names
● All property names and string literals MUST be exactly the same, including case, as the names listed in the property tables in this specification.
○ For example, the discovery resource has a property called api_roots and it must result in the JSON key name api_roots.
● Properties marked required in the property tables MUST be present in the JSON serialization of that resource.
3.9 DNS SRV Names
Organizations that choose to implement a DNS SRV record in their DNS server to advertise the location of their TAXII Server MUST use the service name taxii.
Examples
The following example is for a DNS SRV record advertising a TAXII Server for the domain “example.com” located at taxii-hub-1.example.com:443:
_taxii._tcp.example.com. 86400 IN SRV 0 5 443 taxii-hub-1.example.com
The following table provides a summary of the Server Information Endpoints (URLs and HTTP Methods) defined by TAXII and the Resources they operate on.
|
URL |
Methods |
Resource Type |
|
/taxii/ |
GET |
discovery |
|
<api-root>/ |
GET |
api-root |
|
<api-root>/status/<status-id>/ |
GET |
status |
4.1 Server Discovery
This Endpoint provides general information about a TAXII Server, including the advertised API Roots. It's a common entry point for TAXII Clients into the data and services provided by a TAXII Server. For example, clients auto-discovering TAXII Servers via the DNS SRV record defined in section 1.4.1 will be able to automatically retrieve a discovery response for that server by requesting the /taxii/ path on that domain.
Discovery API responses MAY advertise any TAXII API Root (included those hosted on other servers).
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/taxii/ |
||
|
Parameters |
N/A |
||
|
Pagination |
No |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: discovery |
||
|
Common Error Codes |
404 - No discovery information could be found or the requester does not have access to get discovery information.
401, 403 - The client either needs to authenticate or does not have access to get discovery information |
||
4.1.1 Discovery Resource
Resource Name: discovery
The discovery resource contains information about the TAXII Server, such as a human-readable title, description, and contact information, as well as a list of API Roots that it is advertising. It also has an indication of which API Root it considers the default, or the one to use in the absence of other information/user choice.
|
Property Name |
Type |
Description |
|
title (required) |
string |
A human readable plain text name used to identify this server. |
|
description (optional) |
string |
A human readable plain text description for this server. |
|
contact (optional) |
string |
The human readable plain text contact information for this server and/or the administrator of this server. |
|
default (optional) |
string |
The default API Root that a TAXII Client MAY use. Absence of this field indicates that there is no default API Root. The default API Root MUST be an item in api_roots. |
|
api_roots (optional) |
list of type string |
A list of URLs that identify known API Roots. This list MAY be filtered on a per-client basis. |
Examples
URLs
https://taxii.example.com:443/taxii/
https://someserver.example.net/taxii/
|
GET Request GET /taxii/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "title": "Some TAXII Server", "description": "This TAXII Server contains a listing of...", "contact": "string containing contact information", "default": "https://example.com/api2/", "api_roots": [ "https://example.com/api1/", "https://example.com/api2/", "https://example.net/trustgroup1/" ] } |
4.2 Get API Root Information
This Endpoint provides general information about an API Root, which can be used to help users and clients decide whether and how they want to interact with it. Multiple API Roots MAY be hosted on a single TAXII Server. Often, an API Root represents a single trust group.
● Each API Root MUST have a unique URL.
● Each API Root MAY have different authentication and authorization schemes.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collections |
||
|
Pagination |
No |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: api-root |
||
|
Common Error Codes |
404 - No API Root could be found or the requester does not have access to get API Root information.
401, 403 - The client either needs to authenticate or does not have access to get API Root information. |
||
4.2.1 API Root Resource
Resource Name: api-root
The api-root resource contains general information about the API Root, such as a human-readable title and description, the TAXII versions it supports, and the maximum size of the content body it will accept in a PUT or POST (max_content_length).
|
Property Name |
Type |
Description |
|
title (required) |
string |
A human readable plain text name used to identify this API instance. |
|
description (optional) |
string |
A human readable plain text description for this API Root. |
|
versions (required) |
list of type string |
The list of TAXII versions that this API Root is compatible with. A value of taxii-2.0 MUST be included in this list to indicate conformance with this specification. |
|
max_content_length (required) |
integer |
The maximum size of the request body in octets (8-bit bytes) that the server can support. This applies to requests only and is determined by the server. Requests with total body length values smaller than this value MUST NOT result in an HTTP 413 (Request Entity Too Large) response. |
Examples
URLs
https://example.com/api1/
https://example.com/api2/
https://example.org/trustgroup1/
|
GET Request GET /api1/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version-2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "title": "Malware Research Group", "description": "A trust group setup for malware researchers", "versions": ["taxii-2.0"], "max_content_length": 9765625 } |
4.3 Get Status
This Endpoint provides information about the status of a previous request. In TAXII 2.0, the only request that can be monitored is one to add objects to a Collection (see section 5.4). It is typically used by TAXII Clients to monitor a request that they made in order to take action when it is complete.
TAXII Servers SHOULD provide status messages at this Endpoint while the request is in progress until at least 24 hours after it has been marked completed.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/status/<status-id>/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collections <status-id> - the identifier of the status message being requested |
||
|
Pagination |
No |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: status |
||
|
Common Error Codes |
404 - No status could be found or the requester does not have access to get status information.
401, 403 - The client either needs to authenticate or does not have access to get status information |
||
4.3.1 Status Resource
Resource Name: status
The status resource represents information about a request to add objects to a Collection. It contains information about the status of the request, such as whether or not it's completed (status) and the status of individual objects within the request (i.e. whether they are still pending, completed and failed, or completed and succeeded).
The status resource is returned in two places: as a response to the initial request (see section 5.4) and in response to a get status request (see section 4.3), which can be made after the initial request to continuously monitor its status.
The list of objects that are still pending and the list of
objects that have been added are both lists of strings containing the identifier
of the object (e.g., for STIX objects, their id).
The list of objects that failed to be added is a simple type so that both the id and a message indicating why it
failed can be provided.
|
Property Name |
Type |
Description |
|
id (required) |
string |
The identifier of this Status resource. |
|
status (required) |
string |
The overall status of a previous POST request where an HTTP 202 (Accept) was returned. The value of this property MUST be one of complete or pending. A value of complete indicates that this resource will not be updated further and MAY be removed in the future. A status of pending indicates that this resource MAY update in the future. |
|
request_timestamp (optional) |
timestamp |
The datetime of the request that this status resource is monitoring. |
|
total_count (required) |
integer |
The total number of objects that were in the request. For a STIX bundle this would be the number of objects in the bundle. |
|
success_count (required) |
integer |
The number of objects that were successfully created. |
|
successes (optional) |
list of type string |
A list of object IDs that were successfully processed. For STIX objects the STIX ID MUST be used here. For object types that do not have their own identifier, the server MAY use any value as the id. |
|
failure_count (required) |
integer |
The number of objects that failed to be created. |
|
failures (optional) |
list of type status-failure |
A list of objects that were not successfully processed. |
|
pending_count (required) |
integer |
The number of objects that have yet to be processed. |
|
pendings (optional) |
list of type string |
A list of objects for objects that have yet to be processed. For STIX objects the STIX ID MUST be used here. For object types that do not have their own identifier, the server MAY use any value as the id. |
Type Name: status-failure
This type represents an object that was not added to the Collection. It contains the id of the object and a message describing why it couldn't be added.
|
Property Name |
Type |
Description |
|
id (required) |
string |
The identifier of the object that failed to be created. For STIX objects the id MUST be the STIX Object id. For object types that do not have their own identifier, the server MAY use any value as the id. |
|
message (optional) |
string |
A message indicating why the object failed to be created. |
Examples
URLs
https://example.com/api1/status/2d086da7-4bdc-4f91-900e-d77486753710/
https://example.com/api2/status/88dc8293-827e-44f0-a592-4b5302fbe9d3/
https://example.org/trustgroup1/status/5d26743b-4ade-4b7d-8fea-f68119d4f909/
|
GET Request GET /api1/status/2d086da7-4bdc-4f91-900e-d77486753710/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "id": "2d086da7-4bdc-4f91-900e-d77486753710", "status": "pending", "request_url": "https://example.com/api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/objects", "request_timestamp": "2016-11-02T12:34:34.12345Z", "total_objects": 4, "success_count": 1, "successes": [ "indicator--c410e480-e42b-47d1-9476-85307c12bcbf" ], "failure_count": 1, "failures": [ { "id": "malware--664fa29d-bf65-4f28-a667-bdb76f29ec98", "message": "Unable to process object" } ], "pending_count": 2, "pendings": [ "indicator--252c7c11-daf2-42bd-843b-be65edca9f61", "relationship--045585ad-a22f-4333-af33-bfd503a683b5" ] } |
A TAXII Collection is a logical grouping of threat intelligence that enables the exchange of information between a TAXII Client and a TAXII Server in a request-response manner. Collections are hosted in the context of an API Root. Each API Root MAY have zero or more Collections. As with other TAXII Endpoints, the ability of TAXII Clients to read from and write to Collections can be restricted depending on their permissions level.
This sections defines the TAXII API Collection Endpoints (URLs and methods), valid media types, and responses.
The following table provides a summary of the Endpoints (URLs and HTTP Methods) defined by TAXII and the Resources they operate on.
|
URL |
Methods |
Resource Type |
|
<api-root>/collections/ |
GET |
collections |
|
<api-root>/collections/<name>/ |
GET |
collection |
|
<api-root>/collections/<name>/objects/ |
GET, POST |
object |
|
<api-root>/collections/<name>/objects/<object-id>/ |
GET |
object |
|
<api-root>/collections/<name>/manifest/ |
GET |
manifest |
5.1 Get Collections
This Endpoint provides information about the Collections hosted under this API Root. This is similar to the response to get a Collection (see section 5.2), but rather than providing information about one Collection it provides information about all of the Collections. Most importantly, it provides the Collection's id, which is used to request objects or manifest entries from the Collection.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/collections/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collections |
||
|
Pagination |
Yes |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: collections |
||
|
Common Error Codes |
404 - The Collections resource does not exist or the client does not have access to the Collections resource.
401, 403 - The client either needs to authenticate or does not have access to get Collection information. |
||
5.1.1 Collections Resource
Resource Name: collections
The collections resource is a simple wrapper around a list of collection resources.
|
Property Name |
Type |
Description |
|
collections (optional) |
list of type collection |
A list of Collections. If there are no Collections in the list, this key MUST be omitted and the response is an empty object. The collection resource is defined in section 5.2.1. |
Examples
|
GET Request GET /api1/collections/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "collections": [ { "id": "91a7b528-80eb-42ed-a74d-c6fbd5a26116", "title": "High Value Indicator Collection", "description": "This data collection is for collecting high value IOCs", "can_read": true, "can_write": false, "media_types": [ "application/vnd.oasis.stix+json; version=2.0" ] }, { "id": "52892447-4d7e-4f70-b94d-d7f22742ff63", "title": "Indicators from the past 24-hours", "description": "This data collection is for collecting current IOCs", "can_read": true, "can_write": false, "media_types": [ "application/vnd.oasis.stix+json; version=2.0" ] } ] } |
5.2 Get a Collection
This Endpoint provides general information about a Collection, which can be used to help users and clients decide whether and how they want to interact with it. For example, it will tell clients what it's called and what permissions they have to it.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/collections/<id>/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collection <id> - the identifier of the Collection being requested |
||
|
Pagination |
No |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: collection |
||
|
Common Error Codes |
404 - The Collection could not be found or the requester does not have access to get Collection information.
401, 403 - The client either needs to authenticate or does not have access to get Collection information |
||
5.2.1 Collection Resource
Resource Name: collection
The collection resource contains general information about a Collection, such as its id, a human-readable title and description, an optional list of supported media_types (representing the media type of objects can be requested from or added to it), and whether the TAXII Client, as authenticated, can get objects from the Collection and/or add objects to it.
|
Property Name |
Type |
Description |
|
id (required) |
identifier |
The id property universally and uniquely identifies this Collection. It is used in the Get Collection Endpoint (see section 5.2) as the <id> parameter to retrieve the Collection. |
|
title (required) |
string |
A human readable plain text title used to identify this Collection. |
|
description (optional) |
string |
A human readable plain text description for this Collection. |
|
can_read (required) |
boolean |
Indicates if the requester can read (i.e., GET) objects from this Collection. |
|
can_write (required) |
boolean |
Indicates if the the requester can write (i.e., POST) objects to this Collection. |
|
media_types (optional) |
list of type string |
A list of supported media types for Objects in this Collection. Absence of this field is equivalent to a single-value list containing application/vnd.oasis.stix+json. |
Examples
|
GET Request GET /api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "id": "91a7b528-80eb-42ed-a74d-c6fbd5a26116", "title": "High Value Indicator Collection", "description": "This data collection is for collecting high value IOCs", "can_read": true, "can_write": false, "media_types": [ "application/vnd.oasis.stix+json; version=2.0" ] } |
5.3 Get Objects
This Endpoint retrieves objects from a Collection. Clients can search for objects in the Collection, retrieve all objects in a Collection, or paginate through objects in the Collection.
To support searching the Collection, the Endpoint supports filtering as defined in section 3.5. Clients can provide one or more filter parameters to get objects with a specific ID, of a specific type, or with a specific version. Future versions of TAXII will add more advanced filtering capabilities.
To support requesting a large number of objects, the Endpoint supports pagination as defined in section 3.4. Clients can optionally provide their desired number of items per page and which page they want and servers will return that result set. Servers can also override client-provided pagination parameters, including requiring pagination when it isn't requested. As such, all clients should be aware that responses to this Endpoint may be paginated and be prepared to properly handle that.
When requesting STIX 2.0 content, the content will always be delivered in a STIX bundle (even if there's only zero or one objects, in which case the bundle will be empty or only contain one object). Other content types can be requested by using a different Accept header, however the specific representation of other content types is not defined.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/collections/<id>/objects/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collection <id> - the identifier of the Collection from which objects are being requested |
||
|
Pagination |
Yes |
||
|
Filtering |
Yes - id, type, version |
||
|
Valid Request Type |
Accept: application/vnd.oasis.stix+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.stix+json; version=2.0 Body: bundle
Requests for other content types are permitted and may result in other response bodies. |
||
|
Common Error Codes |
404 - The Objects resource does not exist or the client does not have access to the Objects resource.
401, 403 - The client either needs to authenticate or does not have access to get objects in the Collection. |
||
Examples
|
GET Request GET /api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/objects/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.stix+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.stix+json; version=2.0
{ "type": "bundle", ... "objects": [ { "type": "indicator", ... } ] } |
5.4 Add Objects
This Endpoint adds objects to a Collection.
Successful responses to this Endpoint will contain a status resource describing the status of the request. The status resource contains an id, which can be used to make requests to the get status Endpoint (see section 4.3), a status flag to indicate whether the request is completed or still being processed, and information about the status of the particular objects in the request.
If the request is marked pending in the status field, the client SHOULD periodically poll the get status Endpoint to get an updated status until such a time that the status property returns a value of complete. At that point, the request can be considered complete.
When adding STIX 2.0 content, clients MUST deliver all objects in a STIX bundle. Other content types MAY be added (if the Collection supports it) by using a different Content-Type header, however the specific representation of other content types is not defined.
|
Properties |
|
|
|
|
Supported Method |
POST |
||
|
URL |
/<api-root>/Collections/<id>/objects/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collection <id> - the identifier of the Collection to which objects are being added |
||
|
Pagination |
No |
||
|
Filtering |
No |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 Content-Type: application/vnd.oasis.stix+json; version=2.0 Body: bundle
POSTs containing other Content-Types are permitted and may have a different body. |
||
|
Successful Response |
Status: 202 (Accepted) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: status |
||
|
Common Error Codes |
422 - The object type or version is not supported or could not be processed. This can happen, for example, when sending a version of STIX that this TAXII Server does not support and cannot process, when sending a malformed body, or other unprocessable content.
401, 403 - The client either needs to authenticate or does not have access to get Collection information |
||
Examples
|
POST Request POST /api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/objects/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0 Content-Type: application/vnd.oasis.stix+json; version=2.0
{ "type": "bundle", ... "objects": [ { "type": "indicator", "id": "indicator--c410e480-e42b-47d1-9476-85307c12bcbf", ... } ] }
POST Response HTTP/1.1 202 Accepted Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "id": "2d086da7-4bdc-4f91-900e-d77486753710", "status": "pending", "request_url": "https://example.com/api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/objects", "request_timestamp": "2016-11-02T12:34:34.12345Z", "total_count": 4, "success_count": 1, "successes": [ "indicator--c410e480-e42b-47d1-9476-85307c12bcbf" ], "failure_count": 0, "pending_count": 3 } |
5.5 Get an Object
This Endpoint gets an object from a Collection by its id. It can be thought of as a search where the match[id] parameter is set to the <object-id> in the path. For STIX 2.0 objects, the <object-id> MUST be the STIX id.
To support getting a particular version of an object, this Endpoint supports filtering as defined in section 3.5. The only valid match parameter is version.
When requesting STIX 2.0 content, the content will always be delivered in a STIX bundle (even if there's only zero or one objects, in which case the bundle will be empty or only contain one object). Other content types MAY be requested by using a different Accept header, however the specific representation of other content types is not defined.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/collections/<id>/objects/<object-id>/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collection <id> - the identifier of the Collection being requested <object-id> - the ID of the object being requested |
||
|
Pagination |
No |
||
|
Filtering |
Yes - version |
||
|
Valid Request Type |
Accept: application/vnd.oasis.stix+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.stix+json; version=2.0 Body: bundle
Requests for other content types are permitted and may result in other response bodies. |
||
|
Common Error Codes |
404 - The object could not be found or the requester does not have access to get the object.
401, 403 - The client either needs to authenticate or does not have access to get the object. |
||
Examples
|
GET Request GET /api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/object/indicator--252c7c11-daf2-42bd-843b-be65edca9f61/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.stix+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.stix+json; version=2.0
{ "type": "bundle", ..., "indicators": [ { "type": "indicator", "id": "indicator--252c7c11-daf2-42bd-843b-be65edca9f61", ..., } ] } |
5.6 Get Object Manifests
This Endpoint retrieves a manifest about objects from a Collection. It supports filtering and pagination identical to the get objects Endpoint (see section 5.3) but rather than returning the object itself it returns metadata about the object. It can be used to retrieve metadata to decide whether it's worth retrieving the actual objects.
This Endpoint supports filtering, which is applied against the source object rather than the manifest entry for an object. Thus, searching the manifest for a type of indicator will return the manifest entries for objects with a type of indicator, even though the manifest doesn't have a type field.
|
Properties |
|
|
|
|
Supported Method |
GET |
||
|
URL |
/<api-root>/collections/<id>/manifest/ |
||
|
Parameters |
<api-root> - the base URL of the API Root containing the Collection <id> - the identifier of the Collection being requested |
||
|
Pagination |
Yes |
||
|
Filtering |
Yes - id, type, version
Filtering is based on properties of the objects that the manifest entries represent. For example, filtering by type=indicator will return manifest entries for objects with a type of indicator. |
||
|
Valid Request Type |
Accept: application/vnd.oasis.taxii+json; version=2.0 |
||
|
Successful Response |
Status: 200 (OK) Content-Type: application/vnd.oasis.taxii+json; version=2.0 Body: manifest |
||
|
Common Error Codes |
404 - The Manifest resource does not exist or the client does not have access to the Manifest resource.
401, 403 - The client either needs to authenticate or does not have access to get manifests for objects in the Collection. |
||
5.6.1 Manifest Resource
Resource Name: manifest
The manifest resource is a simple wrapper around a list of manifest-entry items.
|
Property Name |
Type |
Description |
|
objects (optional) |
list of type manifest-entry |
The list of manifest entries for objects returned by the request. If there are no manifest-entry items in the list, this key MUST be omitted and the response is an empty object. |
Type Name: manifest-entry
The manifest-entry type captures metadata about a single object, indicated by the id property. The metadata includes information such as when the object was added to the Collection, what versions of the object are available, and what media types the object is available in.
|
Property Name |
Type |
Description |
|
id (required) |
identifier |
The identifier of the object that this manifest entry describes. |
|
date_added (optional) |
timestamp |
The date and time this object was added to the server. |
|
versions (optional) |
list of type string |
A list of available versions, sorted in order from most recent version to least recent version.
For example versions[0] contains the newest version and versions[len-1] contains the oldest version.
For objects in STIX format, the STIX modified field is the version. |
|
media_types (optional) |
list of type string |
The media types that this object can be requested in. |
Examples
|
GET Request GET /api1/collections/91a7b528-80eb-42ed-a74d-c6fbd5a26116/manifest/ HTTP/1.1 Host: example.com Accept: application/vnd.oasis.taxii+json; version=2.0
GET Response HTTP/1.1 200 OK Content-Type: application/vnd.oasis.taxii+json; version=2.0
{ "objects": [ { "id": "indicator--29aba82c-5393-42a8-9edb-6a2cb1df070b", "date_added": "2016-11-01T03:04:05Z", "versions": ["2016-11-03T12:30:59.000Z","2016-12-03T12:30:59.000Z"], "media_types": ["application/vnd.oasis.stix+json; version=2.0"] }, { "id": "indicator--ef0b28e1-308c-4a30-8770-9b4851b260a5", "date_added": "2016-11-01T10:29:05Z", "versions": ["2016-11-03T12:30:59.000Z"], "media_types": ["application/vnd.oasis.stix+json; version=2.0"] } ] } |
RESERVED
This section defines how to extent TAXII in an interoperable manner.
7.1 Custom Properties
It is understood that there will be cases where certain information exchanges can be improved by adding properties that are not specified nor reserved in this document; these properties are called Custom Properties. This section provides guidance and requirements for how TAXII Servers and Clients should use and interpret Custom Properties in order to extend TAXII in an interoperable manner.
Note: The presence of Custom Properties may introduce variability of behavior depending on whether or not the TAXII Server or Client understands the Custom Properties. A reasonable strategy to minimize unwanted variations in behavior is to provide well defined and consistent rules for processing Custom Properties to any TAXII Server or Client that would be reasonably expected to parse them.
7.1.1 Requirements
● A TAXII resource MAY have any number of Custom Properties.
● Custom Property names MUST be in ASCII and are limited to characters a-z (lowercase ASCII) and underscore (_).
● Custom Property names SHOULD start with “x_” followed by a source unique identifier (like a domain name), an underscore and then the name. For example: x_examplecom_customfield.
● Custom Property names SHOULD be no longer than 30 ASCII characters in length.
● Custom Property names MUST have a minimum length of 3 ASCII characters.
● Custom Property names MUST be no longer than 256 ASCII characters in length.
● Custom Property names that are not prefixed with “x_” may be used in a future version of the specification for a different meaning. If compatibility with future versions of this specification is required, the “x_” prefix MUST be used.
● Custom Property names SHOULD be unique when produced by the same source and SHOULD use a consistent namespace prefix (e.g., a domain name).
● Custom Properties SHOULD only be used when there are no existing properties defined by the TAXII specification that fulfill that need.
TAXII Servers that receive a TAXII Resource with one or more Custom Properties it does not understand MAY respond in one of two ways:
1. Either refuse to process the content further and respond to the message with an HTTP 422 (Unprocessable Entity) status code,
2. or silently ignore non-understood properties and continue processing the message.
TAXII Clients that receive a TAXII Resource with one or more Custom Properties it does not understand MAY silently ignore non-understood properties and continue processing the message.
The reporting and logging of errors originating from the processing of Custom Properties depends on the TAXII Server and Client implementations and is therefore not covered in this specification.
Examples
{
...,
"x_acmeinc_scoring": {
"impact": "high",
"probability": "low"
},
...
}
8.1 TAXII™ Servers
This section describes the types of TAXII Servers that can be implemented and which normative requirements those types of servers must conform to.
8.1.1 TAXII™ 2.0 Server
A "TAXII 2.0 Server" is any software that conforms to the following normative requirements:
1. It MUST support all requirements for a TAXII Collections Server as defined in section 8.1.2.
8.1.2 TAXII™ 2.0 Collections Server
A "TAXII 2.0 Collections Server" is any software that conforms to the following normative requirements:
1. It MUST support all requirements as defined in section 3, section 4 and section 5.
2. It MUST include all required properties within TAXII Resources, as defined in section 4 and section 5.
3. It MUST support all features listed in section 8.2, Mandatory Server Features.
4. It MAY support any features listed in section 8.3, Optional Server Features. Software supporting an optional feature MUST comply with the normative requirements of that feature.
8.1.3 TAXII™ 2.0 Channels Server
RESERVED
8.2 Mandatory Server Features
This sections defines the mandatory features that all TAXII Servers must implement.
8.2.1 TAXII Server Core Requirements
1. It MUST define the URL of the Discovery API to be /taxii/ and it MUST be located at the root of the server, e.g., https://example.com/taxii/
2. It MUST support at least one API Root.
3. It MAY support multiple API Roots.
4. It MAY implement other HTTP Methods, Content Types, and/or URLs beyond those defined in this specification.
5. It MUST be capable of sending HTTP responses for features that it supports whose content is valid TAXII as defined in sections 3, 4, 5, and 6 or STIX as defined in [STIX™ Version 2.0. Part 1: STIX Core Concepts].
6. All properties MUST conform to the data type and normative requirements for that property.
8.2.2 HTTPS and Authentication Server Requirements
1. It MUST accept TAXII 2.0 requests using HTTPS [RFC7230].
2. It MUST accept connections using TLS version 1.2 [RFC5246] and SHOULD accept connections using TLS version 1.3 [TLS1.3] or higher
3. It SHOULD NOT accept any TLS 1.2 connections that use any of the cipher suites that are listed in the cipher suite black list in Appendix A of [RFC7540].
4. It MUST implement the HTTP Basic authentication scheme per [RFC 7617].
5. It MAY permit configurations that enable and/or disable all authentication schemes, including HTTP Basic authentication.
6. It MAY implement additional authentication and authorization schemes beyond HTTP Basic, see section 1.4.8.
7. It MAY restrict access to clients by omitting specific objects, information, or optional fields from any TAXII response.
8. It MAY permit operators to disable all authentication.
9. It MAY choose to not respond to (a.k.a. silently ignore) unauthorized requests.
8.3 Optional Server Features
This sections defines the optional features that a TAXII Server MAY implement.
8.3.1 Client Certificate Verification
TAXII 2.0 servers MAY choose to verify a client’s certificate and use it for authentication. TAXII Servers supporting client certificate verification and authentication MUST follow the normative requirements listed in this section.
● The default strategy for TAXII Servers authenticating and verifying certificates SHOULD be PKIX as defined in [RFC5280], [RFC6818], [RFC6125] et al.
● It MAY support other certificate verification policies such as Certificate Pinning.
8.4 TAXII™ Clients
This section describes the types of TAXII Clients that can be implemented and which normative requirements those types of clients must conform to.
8.4.1 TAXII™ 2.0 Client
A "TAXII 2.0 Client" is any software that conforms to the following normative requirements:
1. It MUST support all requirements for a TAXII Collections Client as defined in section 8.4.2.
8.4.2 TAXII™ 2.0 Collections Client
A "TAXII 2.0 Collections Client" is any software that exchanges CTI data with a TAXII 2.0 Collections Server or a TAXII 2.0 Server. A TAXII 2.0 Collections Client conforms to the following normative requirements:
1. It SHOULD be capable of looking up and using the TAXII SRV record from DNS.
2. It MUST support parsing all properties for resources defined in section 4 and section 5.
3. It MUST support all features listed in section 8.5, Mandatory Client Features.
8.4.3 TAXII™ 2.0 Channels Client
RESERVED
8.5 Mandatory Client Features
This section defines the mandatory features that all TAXII Clients MUST support.
8.5.1 HTTPS and Authentication Client Requirements
1. It MUST initiate TAXII 2.0 requests to a TAXII 2.0 Server using HTTPS [RFC7230].
2. It MUST support TLS 1.2 and SHOULD use TLS version 1.3 [TLS1.3] or higher
3. It SHOULD NOT use TLS 1.2 with any of the cipher suites that are listed in the cipher suite blacklist in Appendix A of [RFC7540].
4. It MUST implement the HTTP Basic authentication scheme as a client per [RFC 7617].
5. It MAY implement additional authentication and authorization schemes beyond HTTP Basic, see section 1.4.8.
8.5.2 Server Certificate Verification
● The default strategy for TAXII Clients authenticating and verifying the server's TLS certificate SHOULD be PKIX as defined in [RFC5280], [RFC6818], [RFC6125] et al.
● TAXII Clients MAY support other certification verification policies such as:
○ Certificate Pinning: A single or limited set of either hard-coded or physically distributed pinned certificate authorities or end-entity certificates.
○ DANE: DNS-based Authentication of Named Entities [RFC7671]. Systems implementing DANE SHOULD also implement DNSSEC [RFC4033].
○ Note that Self-Signed Certificates (like other certificates which cannot be verified by PKIX) MAY be supported via Certificate Pinning and/or DANE as noted above.
API Root - A grouping of TAXII Channels, Collections, and related functionality.
Channel - A publish-subscribe communications method where messages are exchanged.
CTI - Cyber Threat Intelligence
Collection - A logical group of CTI objects.
Endpoint - A combination of a URL and HTTP method with defined behavior in TAXII.
STIX - Structured Threat Information Expression (STIX™) is a language and serialization format used to exchange cyber threat intelligence (CTI).
STIX Content - STIX documents, including STIX Objects, grouped as STIX Bundles.
STIX Object - A STIX Domain Object (SDO) or STIX Relationship Object (SRO).
TAXII - Trusted Automated eXchange of Intelligence Information (TAXII™) is an application layer protocol for the communication of cyber threat intelligence (CTI).
TAXII Client - A software package that connects to a TAXII Server and supports the exchange of CTI.
TAXII Server - A software package that supports the exchange of CTI.
TAXII Subcommittee Chairs:
Bret Jordan, Symantec Corp.
Mark Davidson, NC4
Special Thanks:
Substantial contributions to this specification from the following individuals are gratefully acknowledged:
Terry MacDonald, Cosive
Jane Ginn, Cyber Threat Intelligence Network, Inc. (CTIN)
Richard Struse, DHS Office of Cybersecurity and Communications
Sergey Polzunov, EclecticIQ
Iain Brown, GDS
Eric Burger, Georgetown University
Jason Keirstead, IBM
Allan Thomson, LookingGlass Cyber
Rich Piazza, MITRE Corporation
Charles Schmidt, MITRE Corporation
John Wunder, MITRE Corporation
Mark Davidson, NC4
John-Mark Gurney, New Context Services, Inc.
Dave Cridland, Surevine
Bret Jordan, Symantec Corp.
Participants:
The following individuals were members of the OASIS CTI Technical Committee during the creation of this specification and their contributions are gratefully acknowledged:
David Crawford, Aetna
Marcos Orallo, Airbus Group SAS
Roman Fiedler, AIT Austrian Institute of Technology
Florian Skopik, AIT Austrian Institute of Technology
Russell Spitler, AlienVault
Ryan Clough, Anomali
Nicholas Hayden, Anomali
Wei Huang, Anomali
Angela Nichols, Anomali
Hugh Njemanze, Anomali
Katie Pelusi, Anomali
Dean Thompson, Australia and New Zealand Banking Group (ANZ Bank)
Alexander Foley, Bank of America
Sounil Yu, Bank of America
Vicky Laurens, Bank of Montreal
Humphrey Christian, Bay Dynamics
Ryan Stolte, Bay Dynamics
Alexandre Dulaunoy, CIRCL
Andras Iklody, CIRCL
Rapha‘l Vinot, CIRCL
Sarah Kelley, CIS
Syam Appala, Cisco Systems
Ted Bedwell, Cisco Systems
David McGrew, Cisco Systems
Mark-David McLaughlin, Cisco Systems
Pavan Reddy, Cisco Systems
Omar Santos, Cisco Systems
Jyoti Verma, Cisco Systems
Doug DePeppe, Cyber Threat Intelligence Network, Inc. (CTIN)
Jane Ginn, Cyber Threat Intelligence Network, Inc. (CTIN)
Ben Othman, Cyber Threat Intelligence Network, Inc. (CTIN)
Jeff Odom, Dell
Sreejith Padmajadevi, Dell
Ravi Sharda, Dell
Will Urbanski, Dell
Sean Sobieraj, DHS Office of Cybersecurity and Communications (CS&C)
Richard Struse, DHS Office of Cybersecurity and Communications (CS&C)
Marlon Taylor, DHS Office of Cybersecurity and Communications (CS&C)
Jens Aabol, Difi-Agency for Public Management and eGovernment
Wouter Bolsterlee, EclecticIQ
Marko Dragoljevic, EclecticIQ
Oliver Gheorghe, EclecticIQ
Joep Gommers, EclecticIQ
Sergey Polzunov, EclecticIQ
Rutger Prins, EclecticIQ
Andrei S”rghi, EclecticIQ
Raymon van der Velde, EclecticIQ
Ben Sooter, Electric Power Research Institute (EPRI)
Chris Ricard, Financial Services Information Sharing and Analysis Center (FS-ISAC)
Phillip Boles, FireEye, Inc.
Prasad Gaikwad, FireEye, Inc.
Rajeev Jha, FireEye, Inc.
Anuj Kumar, FireEye, Inc.
Shyamal Pandya, FireEye, Inc.
Paul Patrick, FireEye, Inc.
Scott Shreve, FireEye, Inc.
Jon Warren, FireEye, Inc.
Remko Weterings, FireEye, Inc.
Gavin Chow, Fortinet Inc.
Steve Fossen, Fortinet Inc.
Kenichi Terashita, Fortinet Inc.
Ryusuke Masuoka, Fujitsu Limited
Daisuke Murabayashi, Fujitsu Limited
Derek Northrope, Fujitsu Limited
Jonathan Algar, GDS
Iain Brown, GDS
Adam Cooper, GDS
Mike McLellan, GDS
Tyrone Nembhard, GDS
Chris O'Brien, GDS
James Penman, GDS
Howard Staple, GDS
Chris Taylor, GDS
Laurie Thomson, GDS
Alastair Treharne, GDS
Julian White, GDS
Bethany Yates, GDS
Robert van Engelen, Genivia
Eric Burger, Georgetown University
Allison Miller, Google Inc.
Mark Risher, Google Inc.
Yoshihide Kawada, Hitachi, Ltd.
Jun Nakanishi, Hitachi, Ltd.
Kazuo Noguchi, Hitachi, Ltd.
Akihito Sawada, Hitachi, Ltd.
Yutaka Takami, Hitachi, Ltd.
Masato Terada, Hitachi, Ltd.
Peter Allor, IBM
Eldan Ben-Haim, IBM
Allen Hadden, IBM
Sandra Hernandez, IBM
Jason Keirstead, IBM
John Morris, IBM
Laura Rusu, IBM
Ron Williams, IBM
Paul Martini, iboss, Inc.
Jerome Athias, Individual
Peter Brown, Individual
Joerg Eschweiler, Individual
Stefan Hagen, Individual
Elysa Jones, Individual
Sanjiv Kalkar, Individual
Terry MacDonald, Individual
Alex Pinto, Individual
Tim Casey, Intel Corporation
Kent Landfield, Intel Corporation
Karin Marr, Johns Hopkins University Applied Physics Laboratory
Julie Modlin, Johns Hopkins University Applied Physics Laboratory
Mark Moss, Johns Hopkins University Applied Physics Laboratory
Mark Munoz, Johns Hopkins University Applied Physics Laboratory
Nathan Reller, Johns Hopkins University Applied Physics Laboratory
Pamela Smith, Johns Hopkins University Applied Physics Laboratory
David Laurance, JPMorgan Chase Bank, N.A.
Russell Culpepper, Kaiser Permanente
Beth Pumo, Kaiser Permanente
Michael Slavick, Kaiser Permanente
Trey Darley, Kingfisher Operations, sprl
Gus Creedon, Logistics Management Institute
Wesley Brown, LookingGlass
Jamison Day, LookingGlass
Kinshuk Pahare, LookingGlass
Allan Thomson, LookingGlass
Ian Truslove, LookingGlass
Chris Wood, LookingGlass
Greg Back, Mitre Corporation
Jonathan Baker, Mitre Corporation
Sean Barnum, Mitre Corporation
Desiree Beck, Mitre Corporation
Michael Chisholm, Mitre Corporation
Nicole Gong, Mitre Corporation
Ivan Kirillov, Mitre Corporation
Michael Kouremetis, Mitre Corporation
Chris Lenk, Mitre Corporation
Richard Piazza, Mitre Corporation
Larry Rodrigues, Mitre Corporation
Jon Salwen, Mitre Corporation
Charles Schmidt, Mitre Corporation
Alex Tweed, Mitre Corporation
Emmanuelle Vargas-Gonzalez, Mitre Corporation
John Wunder, Mitre Corporation
James Cabral, MTG Management Consultants, LLC.
Scott Algeier, National Council of ISACs (NCI)
Denise Anderson, National Council of ISACs (NCI)
Josh Poster, National Council of ISACs (NCI)
Mike Boyle, National Security Agency
Joe Brule, National Security Agency
Jessica Fitzgerald-McKay, National Security Agency
David Kemp, National Security Agency
Shaun McCullough, National Security Agency
John Anderson, NC4
Michael Butt, NC4
Mark Davidson, NC4
Daniel Dye, NC4
Angelo Mendonca, NC4
Michael Pepin, NC4
Natalie Suarez, NC4
Benjamin Yates, NC4
Daichi Hasumi, NEC Corporation
Takahiro Kakumaru, NEC Corporation
Lauri Korts-P_rn, NEC Corporation
John-Mark Gurney, New Context Services, Inc.
Christian Hunt, New Context Services, Inc.
Daniel Riedel, New Context Services, Inc.
Andrew Storms, New Context Services, Inc.
Stephen Banghart, NIST
David Darnell, North American Energy Standards Board
Cory Casanave, Object Management Group
Aharon Chernin, Perch
Dave Eilken, Perch
Sourabh Satish, Phantom
Josh Larkins, PhishMe Inc.
John Tolbert, Queralt Inc.
Ted Julian, Resilient Systems, Inc..
Igor Baikalov, Securonix
Joseph Brand, Semper Fortis Solutions
Duncan Sparrell, sFractal Consulting LLC
Thomas Schreck, Siemens AG
Rob Roel, Southern California Edison
Dave Cridland, Surevine Ltd.
Bret Jordan, Symantec Corp.
Curtis Kostrosky, Symantec Corp.
Juha Haaga, Synopsys
Masood Nasir, TELUS
Greg Reaume, TELUS
Alan Steer, TELUS
Crystal Hayes, The Boeing Company
Wade Baker, ThreatConnect, Inc.
Cole Iliff, ThreatConnect, Inc.
Andrew Pendergast, ThreatConnect, Inc.
Ben Schmoker, ThreatConnect, Inc.
Jason Spies, ThreatConnect, Inc.
Ryan Trost, ThreatQuotient, Inc.
Patrick Coughlin, TruSTAR Technology
Chris Roblee, TruSTAR Technology
Mark Angel, U.S. Bank
Brian Fay, U.S. Bank
Joseph Frazier, U.S. Bank
Mark Heidrick, U.S. Bank
Mona Magathan, U.S. Bank
Yevgen Sautin, U.S. Bank
Richard Shok, U.S. Bank
James Bohling, US Department of Defense (DoD)
Eoghan Casey, US Department of Defense (DoD)
Gary Katz, US Department of Defense (DoD)
Jeffrey Mates, US Department of Defense (DoD)
Evette Maynard-Noel, US Department of Homeland Security
Robert Coderre, VeriSign
Kyle Maxwell, VeriSign
Eric Osterweil, VeriSign
Patrick Maroney, Wapack Labs LLC
Anthony Rutkowski, Yanna Technologies LLC
|
Revision |
Date |
Editor |
Changes Made |
|
01 |
2017-04-24 |
Bret Jordan, Mark Davidson, John Wunder |
Initial Version |