The Farsight Security Advanced Exchange Access (AXA) RESTful Interface adds a streaming HTTP interface on top of the AXA toolkit 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.


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


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.


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.


AXA REST requires HTTPS permitted outbound to

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

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

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

    $ axamd_client --server --list-channels ch255:

Additional documentation can be found on the Github repository for axamd_client in the README file.

SRA Internals

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


SRA requires the user to specify one or more SIE channels to stream. These are specified as 255.


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, or dns=*

Sample Usage


Example usage of the axamd_client:

Steam all messages from the SIE heartbeat channel 255

$ axamd_client --server --channel 255 --watches ch=255


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' \

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


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 or follow us on Twitter: @FarsightSecInc.