The TAXII SC has a general consensus that TAXII should have a REST API. There are many factors to consider when designing a REST API. This page documents the current state of the proposed REST API and documents open questions where they are known.
This page is written as normative text so that it can be used as the basis for a specification. This phrasing should not deter readers from raising questions.
This page defines the REST API and some other related items (e.g., Authentication, DNS SRV).
DNS Service (SRV) records are used for advertising network services via DNS. This section defines a service name for TAXII so that TAXII implementations that conform to this specification can be advertised in DNS. This section also defines rules for using the TAXII DNS SRV record to determine the Discovery URL and the Default API Base.
The service name for this version of TAXII is: taxii2. Future versions of TAXII may define alternate service names.
An example DNS SRV record, advertising a TAXII server located at taxii.example.com:443:
_taxii2._tcp.example.com. 86400 IN SRV 0 5 443 taxii.example.com
Discovery URL:
The Discovery URL is created from the TAXII DNS SRV record using the following production:
Discovery URL: https:// + hostname + : + port + /taxii2/api-bases/
Example Discovery URL: https://taxii.example.com:443/taxii2/api-bases/
Default API Base:
The Default API Base is created from the TAXII DNS SRV record using the following production:
Default API Base: https:// + hostname + : + port + /taxii2/default/
Example Default API Base: https://taxii.example.com:443/taxii2/default/
Ref: https://www.ietf.org/rfc/rfc2782.txt
The current proposal that seem to have acceptance is HTTPS + HTTP Basic + JWT (JSON Web Tokens).
Open Questions:
This specification defines requirements for using HTTPS; this specification does not define requirements for using HTTP. TAXII Clients and Servers MUST use HTTPS. While the additional use of HTTP is recognized as a straightforward and perhaps trivial to implement, and while Clients and Servers may choose to use HTTP, those uses are not considered conformant with this specification. ONLY the use of HTTPS is considered conformant with this specification.
Open Questions:
This specifications defines HTTP X-Headers that are used for TAXII.
Header Name: X-Max-Size
Use: The X-Max-Size MAY be used in HTTP Requests. The X-Max-Size header MUST NOT be used in HTTP Responses.
Meaning: The X-Max-Size header identifies the maxmimum response size in decimal number of OCTETs (aka bytes) that the client
is capable of receiving. The Content-Length of the response MUST NOT be larger than the X-Max-Size value, if specified.
Allowable Values: The mimimum allowable value is 9437184 (9mb). There is no maximum allowable value.
Default Value: If the X-Max-Size header is not specified in the HTTP Request, the value should be treated as the minimum allowable value.
Open Questions:
Not sure exactly what this means yet, other than it’s ben asked for and is a way to get clients to make slower requests. Need more detail on this one.
Note that in this version of TAXII, the creation, modification, and deletion of API-Bases is not specified; only the listing of available API-Bases is specified. Implementers are free to implement (or not) create/modify/delete functionality in any way they wish.
An API-Base is any valid HTTPS URL (e.g., https://subdomain.example.com:12345/whatever/)
From the API-Base, the following URLs are valid:
[API-Base]/channels/<channel-name>/[API-Base]/channels/In this section, each URL is specified, along with a set of possible responses.
GET [API-Base]/channels/ - Returns a list of channels
GET [API-Base]/channels/<channel-name>/ - Returns info about a specific channel
POST <channel object> to [API-Base]/channels/ - Create a new channel
POST <taxii message(s)> to /channels/<channel-name>/ - Add TAXII message(s) to the channel
GET /channels/<channel-name>/[?param1=val1...] - Get or Create a subscription and get TAXII messages from the channel with the specified filter. For more on subscriptions, see below.
Open Questions:
Channel Create Object
{
"name": "<channel-name>",
"description": "<channel-description>", # Optional user-friendly description of what is on the channel
"permitted_messages": ['msg1', 'msg2'], # Empty list denotes ALL messages are permitted (?)
"content_type": "<content type>" # Content type of the channel (MIME types? text/x-stix, text/x-openioc? ),
"ttl":<TTL_in_seconds> # TTL of any content in this channel before it is purged from your view. IE, how often you must poll to guarantee to not miss any messages.
}
Open questions:
Subscriptions are currently proposed as an implementation of the PubSub subscription model - a client requests messages from a channel that meet a particular filter. A subscription is uniquely identified by a user-id, API-Base + channel name, and the selector (e.g., GET parameters).
Subscription lifecycle:
Other parameters: