Skip to main content
DomainTools Announces Predictive Threat Feeds - Powering Preemptive Exposure Management
Tag title

SRA and AXA RESTful Interface User Guide

Published on: 
December 9, 2022
On This Page
TOC Element
Share:

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 theSecurity Information Exchange (SIE) over HTTP using a RESTful API.

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

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 specificoperating 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 compatiblewith various modern operating systems.

Hardware

Minimum hardware requirements to get started with Domain Sentry are asfollows:

  • 1 CPU
  • 1 GB Memory
  • 1 GB Disk

Note: Depending on the amount of data you end up processing, you mayneed 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 FarsightSecurity 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 theRESTful 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 systemwith 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:
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 SIEover 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 ormore DNS watches. These tell the server what to filter and send to theclient. These are specified as ip={/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 browseror 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 srafor 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.

HTTP Response CodeMeaningDiscussion200Successful operation400Invalid parametersClient specified invalid channel, watch, or anomaly parameters401Missing or invalid X-API-Key402Out of RAD PointsClient tried to load a RAD module that would result in a negative balance403Not authorized for resourceClient tried to access a channel, watch, or anomaly without proper permission404Nonexistent resourceClient tried to access a channel, watch, or anomaly that doesn't exist500Internal Server ErrorSomething egregious happened server-side

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 itanomalies is list of maps. map MUST contain module, may contain list of watches, mappingof 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 currentcounter statistics relevant to your current session. For more details onthese packet counts, reference Farsight's Advanced Exchange AccessInternals: Understanding Accounting.

Limitations

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