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:

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

  2. Extract the software from the archive

    $ tar xzvf 1.2.0.tar.gz

  3. Change directory

    $ cd axamd_client-debian-1.2.0/

  4. Install prerequisites

    $ sudo apt-get install python-setuptools

  5. Install the axamd_client package

    $ sudo python setup.py install

  6. Create and configure your .conf file

    $ vi ~/.axamd-client.conf

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

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

  8. 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 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.

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/20150923-mschiffm-axa-accounting/.

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 largest 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. Learn more about how we can empower your threat platform and security team with Farsight Security passive DNS solutions at www.farsightsecurity.com or follow us on Twitter: @FarsightSecInc.