Skip to content

HTTP REST API for TAXII 2.0

Jump to bottom Edit New page
jordan2175 edited this page Nov 9, 2015 · 17 revisions

HTTP REST API Documentation

The TAXII REST API is an HTTP-based model for exchanging threat information and discovering a TAXII Server's capabilities. TAXII servers MUST use HTTPS. HTTP implementations, even if they conform to all other requirements, are not considered to be TAXII conformant.

TAXII Channels that are related in some way are all organized at a common root URL, called an API-Base. A TAXII Server MUST have at least one API-Base. A TAXII server may have multiple API-Bases. TAXII defines one well-known API-Base that all TAXII Servers MUST implement. TAXII imposes no rules on additional API-Bases. Additionally, all TAXII Servers MUST implement the well-known Discovery URL.

TAXII Discovery is done at the management root, which is not contained in an API Base.

DNS SRV

TAXII defines a DNS Service (SRV) record for automated discovery. A DNS SRV record identifies a server name and port for a particular service name (e.g,. _taxii2) under a particular domain (e.g., example.com). This section describes an example DNS SRV record and defines rules for generating the default API-Base and the discovery URL.

Per the DNS SRV RFC, TAXII defines the following label for TAXII 2.x: _taxii2. An example DNS SRV record follows:

_taxii2._tcp.example.com. 86400 IN SRV 0 5 443 taxii.example.com

Using <host> and <port> as variables to hold hostname and port number, the following rules are used to generate the discovery URL and the well-known API-Base

Well-known Discovery URL: https://<host>:<port>/t2/api_bases/

Well-known API Base: https://<host>:<port>/t2/default/

As a note, the Default indicator channel would be accessed at: https://<host>:<port>/t2/default/channels/indicator/

Discovery URL Scheme

The Discovery URL scheme is as follows:

  • HTTP GET https://<host>:<port>/t2/api_bases - Return a list of available API-Bases

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 extend TAXII for the purpose of API-Base creation, modification, and/or deletion.

API-Base URL Scheme

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/
  • [API-Base]/channels/<channel-name>/

API Methods

  • GET [API-Base]/channels/ - Returns a list of channels

  • GET [API-Base]/channels/<channel-name>/ - Returns info about a specific channel

  • POST <channel object JSON message> to [API-Base]/channels/ - Create a new channel

  • HTTP 201 - Message accepted, channel will be created

  • HTTP 400 - Invalid request, something wrong with your channel structure

  • HTTP 403 - Permission denied, you are not allowed to make new channels

  • HTTP 501 - Not implemented, this server has a fixed set of available channels

  • POST <taxii message(s)> to [API-Base]/channels/<channel-name>/ - Add TAXII message(s) to the channel

  • HTTP 202 - Message(s) accepted, message will be transmitted to the channel

  • HTTP 400 - Invalid request, something wrong with your message structure

  • HTTP 403 - Permission denied, you can not post to this channel

  • HTTP 501 - Not implemented (This is a read only channel)

  • GET [API-Base]/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.

  • HTTP 200 - Response fulfilled

  • HTTP 204 - No new data

  • HTTP 400 - Invalid request

  • HTTP 403 - Permission denied

  • HTTP 501 - Not implemented (This is a write-only channel)

Open Questions:

  1. If we permit POSTing multiple messages, how are different message dispositions handled? (e.g., message 1 was accepted, message 2 was re-written, and message 3 was rejected)
  2. How is content negotiated? At the channel level, at the message level? Something else?
  3. MSD Opinion: Should try to leverage HTTP Content-Types/MIME Types
  4. Should there be update and destroy (PUT and DELETE)? Renaming channels could be complicated and have weird side effects given the name is in the URL, but changing permissions for existing channels might be a requirement.
  5. We should think about long polling vs. other options
  6. https://developer.mozilla.org/en-US/docs/Web/API/EventSource
  7. Should the REST API include mechanisms for modifying permissions, or should that be an implementation-specific thing?
  8. Groups are no longer in the API. Does that work?
  9. Should getting messages be a GET? These responses shouldn't be cached, so maybe not.

Control Messages

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_ms> # 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:

  1. Should permissions be somehow provided/optional in the message?
  2. Is there a way to "invite" people to a channel?

Subscriptions

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:

  1. An authenticated client does an HTTP GET to a channel
  2. Server does a "get or create" action on the subscription
  3. If the subscription already existed, the server responds with queued messages (if any)
  4. If the subscription was created, the server waits for some new messages before returning

Other parameters:

  1. If a client does not reconnect within <timeout>, the subscription can be automatically discarded
  2. The number of messages queued for a particular subscription may be enforced, either by total message size or by number of outstanding messages.
  3. There is no subscription ID (at least in terms of client/server comms; the server can do whatever it wants to track subscriptions) - the subscription ID is implicit and is nominally a triple of user-id, channel URL, and selector.

Other features Under Discussion

  • Rate Limiting (maybe an X-Rate-Limit header?). We need to define what this means.
  • max_size - A way for a client to tell the server what the max size of a response they can handle is.
  • Corner case: What happens when one message exceeds the max_size? Does it get discarded? Sent anyway? Is an alert generated?
Add a custom footer
Add a custom sidebar
Clone this wiki locally