Introduction

The Farsight Security Advanced Exchange Access (AXA) RESTful Interface adds a streaming HTTP interface on top of the AXA toolkit https://github.com/farsightsec/axa to enable developers of web-based applications to interface with Farsight Security’s SIE Remote Access (SRA) and Realtime Anomaly Detector (RAD) servers.

The SRA module facilitates the real time streaming of data from the Security Information Exchange (SIE) over HTTP using a RESTful API.

Access is controlled via an API key that is passed as the X-API-Key HTTP header.

Audience

This user guide is written for:

1. Programmers who want to write applications that interact with the Python module or the RESTful API
2. System Engineers comfortable using command line tools

Requirements

Operating System

The Farsight Security AXA RESTful Interface does not have any specific operating system requirements as it is delivered over a RESTful API. Farsight Security provides a convenience command line interface (CLI) tool that doubles as a Python 2.7 extension module which is compatible with various modern operating systems.

Hardware

Minimum hardware requirements to get started with Domain Sentry are as follows:

• 1 CPU
• 1 GB Memory
• 1 GB Disk

Note: Depending on the amount of data you end up processing, you may need to increase the resources accordingly.

Network

AXA REST requires HTTPS permitted outbound to axamd.sie-remote.net.

Service Entitlement

Subscribers must have purchased a service entitlement from Farsight Security and have been provisioned an API key.

Delivery Options

The SRA module is delivered by Farsight Security AXA RESTful Interface. Farsight Security has created some additional tools that utilize the RESTful API:

1. Python Package axamd_client a Python module and CLI tool created as a reference implementation and demonstration tool
2. REST API - the core mechanism to deliver the SRA module

Python Package: axamd_client

axamd_client is a reference implementation leveraging the AXA RESTful API. It is both a fully functional CLI tool and a Python 2.7 extension module. The primary purpose is of the CLI tool is to offer simplified access to SRA. Messages are emitted as newline-delimited JSON blobs which can be fed into any JSON-aware tools (such as jq https://stedolan.github.io/jq) for further processing.

Installation Instructions

These instructions assume a currently supported *inx operating system with Python 2.7.x installed.

1. Download the software from the axamd_client GitHub Page

$ wget https://github.com/farsightsec/axamd_client/archive/debian/1.2.0.tar.gz

1. Extract the software from the archive

$ tar xzvf 1.2.0.tar.gz

1. Change directory

$ cd axamd_client-debian-1.2.0/

1. Install prerequisites

$ sudo apt-get install python-setuptools

1. Install the axamd_client package

$ sudo python setup.py install

1. Create and configure your .conf file

$ vi ~/.axamd-client.conf

1. Copy and paste the following and specify your API key

apikey: <Farsight Security provided api key>
server: https://axamd.sie-remote.net

1. Test the client by running with the --list-channels option. You should see (at least) ch255 listed

$ axamd_client --server https://axamd.sie-remote.net/ --list-channels
ch255:
      10.32.255.255/8430 10.32.255.255/9430

Additional documentation can be found on the Github repository for axamd_client https://github.com/farsightsec/axamd_client in the README https://github.com/farsightsec/axamd_client/blob/master/README.md file.

SRA Internals

The SRA module facilitates the real time streaming of data from the SIE over HTTP using a RESTful API.

Channels

SRA requires the user to specify one or more SIE channels to stream. These are specified as an integer, for example 255.

Watches

SRA requires the user to specify one or more IP watches and/or one or more DNS watches. These tell the server what to filter and send to the client. These are specified as ip=<address>{/CIDR} or -dns=example.com, or dns=*.example.com.

Example: --watches ip=192.253.0.0/16 dns=\*.example.com

The AXAMD Protocol

AXAMD is a server program that sits in front of SRA and RAD servers inside the Farsight Security, Inc cloud and serves requests from client browsers and custom programs over a RESTful API. The overall architecture is shown in Figure 1. AXAMD speaks REST to web-enabled clients and the binary AXA protocol to the SRA and RAD servers.

AXAMD is a stateful proxy enabling authorized users access SRA and RAD using a web browser or custom REST client.

AXAMD can be accessed via https://axamd.sie-remote.net.

REST API

The following details the REST API provided by AXAMD.

Server Type Specification

The server type will be specified as a URL path element, after the version. It will be sra for requests made to an SRA server and rad for requests made to a RAD server.

Authentication

Authentication is done via X-API-Key headers (as per DNSDB).

Content Negotiation

The client will specify the content type it wants via an Accept-Encoding request header. The following content-types will be made available:

• axa-json: This is the default. Watch hit metadata will be emitted along with the base64 encoded NMSG or IP packet that caused the watch hit.
• nmsg-presentation: Presentation format of NMSG that caused the watch hit (see nmsgtool -).
• nmsg-json: JSON representation of NMSG that caused the watch hit.
• nmsg-binary: Binary NMSG only that caused the watch hit (requires the addition of an input_http module to nmsg for the last one).

HTTP Response Codes

The following HTTP responses codes can be returned from API requests.

Get Channel List

Returns JSON map of available channels, their statuses, and their descriptions

GET https://axamd.sie-remote.net/v1/sra/channels

Get Anomaly List

Returns JSON map of available RAD modules, their statuses, supported watch types, options

GET /v1/sra/anomalies

Post Data

POST /v1/sra/stream {
channels: [], watches: [str], anomalies: [{‘module’: str, ‘watches': [str],
    ‘options’: {str: str}}], rate_limit: int,
}

Channels is a list of channel names that should be enabled watch format has no tag on it anomalies is list of maps. map MUST contain module, may contain list of watches, mapping of option names to values rate_limit is optional.

Server auto assigns tags to watches and anomaly watches based on list indexes.

Sample Usage

axamd_client

Example usage of the axamd_client:

Steam all messages from the SIE heartbeat channel 255

$ axamd_client --server https://axamd.sie-remote.net/ --channel 255 --watches ch=255

REST API

Example usage of the REST API:

Steam all messages from the SIE heartbeat channel 255

curl --data '{ "channels": [255], "watches": ["ch=255"] }' \
    --header 'X-API-Key: abcdefgh-abcd-abcd-abcd-abcdefghijkl' \
    https://axamd.sie-remote.net/v1/sra/stream

Accounting Messages

By default, axamd will return AXA accounting messages containing current counter statistics relevant to your current session. For more details on these packet counts, reference Farsight’s Advanced Exchange Access Internals: Understanding Accounting https://www.farsightsecurity.com/blog/txt-record/axa-accounting-20150924/.

Limitations

The Farsight Security AXA RESTful Interface is not a recommended solution for SIE channels with an average data rate over 1 Mbps.

About Farsight Security

Farsight Security, Inc. is the world’s leading provider of historical and real-time DNS intelligence solutions. We enable security teams to qualify, enrich, and correlate all sources of threat data and ultimately save time when it is most critical - during an attack or investigation. Our solutions provide enterprise, government, and security industry personnel and platforms with unmatched global visibility, context, and response. Farsight Security is headquartered in San Mateo, California, USA. To learn more about how we can empower your security, threat, and intelligence platforms and security organization with Farsight Security passive DNS (pDNS) and threat intelligence solutions, please visit us at www.farsightsecurity.com or follow us on Twitter at @FarsightSecInc.