axa
1.2.1
Farsight Security Advanced Exchange Access (AXA)
|
The purpose of Farsight's Advanced Exchange Access (AXA) toolkit is to bring the capabilities of the Farsight Security Information Exchange (SIE) right to the subscriber's network edge rather than requiring a direct connection to the SIE.
The Farsight AXA toolkit contains tools and C-based library code used to connect to Farsight's SRA (SIE Remote Access) and RAD (Realtime Anomaly Detector) servers.
SRA and RAD services are delivered via Farsight's AXA protocol which allows session initiators to control a number of parameters including:
The following tools are provided to Farsight customers that subscribe to one or more SIE channels:
sratool
: A command line tool used to connect to an SRA server, send AXA protocol messages and stream responses.radtool
: A command line tool used to connect to a RAD server, set anomaly watches, and stream responses.sratunnel
: SRA Tunnel. A tool that copies remote SIE data to the local network.radtunnel
: RAD Tunnel. A tool that copies RAD data to the local network.libaxa
: C API middleware for the AXA protocol including connection and encapsulation/decapsulationThe sratool
program is the reference implementation of the AXA protocol. It is intended primarily as a protocol demonstration and debugging interface, although it can also perform some of the same functions as sratunnel
.
The sratunnel
source code is intended as a working example of calling libaxa
to set up an SRA session, turn on an SIE channel, set a single and simple filter, receive remote data over AXA, and decapsulate that data. SRA application developers can use the sratunnel
source code as a template for other SRA applications, or get a quicker start by running the sratunnel
program which will make the remote data available locally, and then use `pcap` (for SIE channel 14) or `nmsg` (for all other SIE channels) as they would on an analysis server directly connected to SIE itself. An example of how to do this is included later in this document.
The radtool
and radtunnel
programs are used to stream RAD watch hits from a remote RAD server to the local network. They actually share code bases with their "sra-" counterparts and the program logic is such that it detects its filename and invokes itself in RAD mode.
Of note, SRA can perform filtering. This feature is highly desirable due to the very high volume of data carried by SIE which can burst to hundreds of megabits per second in a single channel. On the flip side, when using SRA to access low volume channels, entire channels can be selected for remote distribution. However, when remotely accessing high volume SIE channels, the subscriber usually specifies a list of IP addresses and DNS names of interest, so that the SRA server can filter out everything else, and send to the subscriber only a subset of that channel's SIE data.
Also of note, AXA is a deliberately lossy protocol. If a subscriber requests more data than the network can carry, data overruns will occur. When this happens, "loss markers" are transmitted reliably within the AXA stream to inform the subscriber. At this point, the subscriber's possible mitigation strategies include:
The distributed AXA package constitutes the authoritative documentation of the AXA protocol. Farsight advises SRA subscribers needing custom functionality not provided in sratool
, sratunnel
, radtool
, or radtunnel
to utilize the libaxa
library for session management and data decapsulation rather than crafting hand drawn logic to perform these functions.
A later version of the AXA software will include Python language bindings.
For specific details on sratool
, radtool
, sratunnel
, and radtunnel
, please see the respective man pages included in the distribution.
AXA can built manually or, on Debian systems, installed by using pre-built packages.
The AXA suite has the following external dependencies:
--without-libxs
)Optional dependency:
After satisfying the above, build with something like:
./autogen.sh
followed by ./configure
and make
To generate the API documentation (including an HTMLized version of this document): ./make doc
. The html documentation will be in html
and can be rendered in any modern browser. Something like $ open html/index.html
should get you started.
Finally, to give the AXA suite a home, sudo make install
.
On Debian systems, the following packages should be installed:
pkg-config
libpcap0.8-dev
zlib1g-dev
libbsd-dev
libedit-dev
libprotobuf-c0-dev (>= 1.0.1)
protobuf-c-compiler
libwdns-dev (>= 0.6.0)
libnmsg-dev (>= 0.9.1)
nmsg-msg-module-sie-dev (>= 1.0.0)
The binary packages of AXA and its dependencies are available from a Debian package repository maintained by Farsight Security. These packages should be used instead of building from source on Debian-based systems.
On a clean Debian install, the following brings in everything "external" that is needed and then install all of thw AXA tools and libaxa
:
After SRA and/or RAD session parameters have been established, SIE data is encrypted and streamed to the SRA subscriber using either an SSH transport (similar to applications like rsync or git or using TLS).
While both transports offer comparable encryption and compression, Farsight recommends using TLS in preference to SSH. On most systems, TLS performance should be faster as it doesn't have to deal with piping data to or from the SSH server process.
Before either method can be used, you first need to generate new authentication keys and submit the public half to Farsight Security.
As of the time of this writing, the SRA and RAD servers answer at the following addresses via the SSH transport:
sra-service@sra.sie-remote.net
rad-service@rad.sie-remote.net
Incoming SRA or RAD connections are handled on TCP port 22 by the SSH server.
To setup SSH access for SRA and/or RAD, you need to do the following:
ssh-keygen
: $ ssh-keygen -t rsa -b 4096 Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): /home/user/.ssh/farsight-axa-id_rsa ...
~/.ssh/config
file to specify the private half of the SSH key pair for the SRA and RAD servers: Host sra.sie-remote.net rad.sie-remote.net IdentityFile ~/.ssh/farsight-axa-id_rsa
~/.ssh/farsight-axa-id_rsa.pub
) to your Farsight Security account manager. DO NOT EVER SHARE YOUR PRIVATE KEY (~/.ssh/farsight-axa-id_rsa
). This is the private half of your generated key pair that you should keep safe. As soon as your account is provisioned you will receive notification from Farsight Security.As of the time of this writing, the SRA and RAD servers answer at the following addresses via the TLS transport:
The TCP port numbers 1021 and 1022 are IANA "[RFC3692](https://tools.ietf.org/html/rfc3692)-style Experiment 1" port numbers and were chosen in consideration of that document.
To setup TLS access for SRA and/or RAD, you need to do the following:
# axa_make_cert -u username Create /usr/local/etc/axa/certs? y Generating a 2048 bit RSA private key ............+++ .............+++ writing new private key to 'username.key' -----
# chown user. /usr/local/etc/axa/certs/username.key
# axa_server_cert -s sra.sie-remote.net,1021 Obtained certificate for "farsight" with SHA1 Fingerprint=2D:0C:92:23:B9:6F:70:E7:F3:E3:7A:2B:D6:F5:D4:CA:1F:F8:CE:71 Install it in /usr/local/etc/axa/certs/farsight.pem? yes
username.pem
) to your Farsight Security account manager. DO NOT EVER SHARE YOUR PRIVATE KEY (username.key
). This is the private half of your generate key pair that you should keep safe. As soon as your account is provisioned you will receive notification from Farsight Security.The following are a few examples of how to use sratool
, sratunnel
and radtool
. For the interactive tools sratool
and radtool
, all user commands are prefaced with sra>
or rad>
prompts.
Here's a simple example using sratool
to grab the first five packets seen on SIE channel 212 (Newly Observed Domains):
sra> connect ssh:sra-service@sra-eft.sie-remote.net
: we connected to an SRA server using the SSH transport. SSH used its keyring to prove the user's identity, so there was no 'password:' prompt. The HELLO
response from the remote end tells us its version number and the protocol level.sra> count 5
: we asked our sratool
client to stop after five messages are output.sra> channel 212 on
: we then asked the remote end to listen to SIE channel 212 which was OK
'd by the server indicating that we are provisioned for this channel according to our authentication and authorization level.sra> 1 watch ch=212
: we then asked to watch all content on channel 212 (with no rate limiting or filtering), which is a common choice for 212 since its volume is low.Next, we introduce in-line connections and show rate limiting of SIE channel 204 (filtered passive DNS RRsets):
we put our first
sratoolsubcommand on the command line of
sratool` itself. This is a shortcut that allows the first subcommand to come from the command line, while subsequent subdomains wil come from the control terminal.sra> count 5
: we again asked for a limit of five total recordssra> limit 1 5
: this time we asked the remote end to limit our output to one message per second and report every 5 seconds.sra> channel 204 on
: as before, switch on channel 204sra> 1 watch ch=204
: as before, watch channel 204MISSED
: We then saw one message from channel 204, followed immediately by a loss marker showing that 2299 messages could not be sent to us because of our rate limit. Note that loses due to rate limits are counted independently from losses due to congestion. After four more messages containing channel 204 data, our packet count limit was reached. We received one more rate limit report before terminating sratool
.Here we introduce sratunnel
and send some packets to a local endpoint and view them with nmsgtool
and watch packet flow via tcpdump
.
First we invoke sratunnel
:
Next let's have a look what this looks like using tcpdump
:
Indeed, traffic is flowing and we can use nmsgtool
to receive and decapsulate the data. Here we invoke it to capture and display three payloads:
tcpdump -n -c 3 -i lo udp port 5000
: we then used the tcpdump command to show that packets were being received on the local socket.nmsgtool -V SIE -T newdomain -l 127.0.0.1/5000 -c 3
: We ran nmsgtool
, specifying our input with the -V
, -T
, and -l
options since the nmsgtool
shortcut for channel notation (-C
) only works for directly connected SIE clients. nmsgtool
displayed three messages and exited. We then killed the background sratunnel
process, concluding the demo.Next, radtool
is used to watch for specified IP addresses in SIE channels. In the example below, the ip14-80
anomaly module, which looks for IP packets in SIE channels 14 (Darknet) and 80 (Conficker Sinkhole) is used. Traffic appearing in either of these feeds is often considered anomalous and worthy of deeper investigation.
rad> connect ssh:rad-service@rad-eft.sie-remote.net
: we connected to a RAD server using the SSH transport. SSH used its keyring to prove the user's identity, so there was no 'password:' prompt. The HELLO
response from the remote end tells us its version number and the protocol level.rad> count 5
: we asked our radtool
client to stop after five messages are output.rad> 1 watch ip=0.0.0.0/1
: set a watch for all IP packets matching the specified CIDR mask.rad> 1 watch ip=128.0.0.0/1
: set a watch for all IP packets matching the specified CIDR mask. In combination with the previous watch, all IP packets should be matched. In practice, a user would specify IP watches specific to addresses in his or her organization. Also of note here is the use of the same tag for two watches. This is because RAD clients use a common tag to group together one or more watches with a single anomaly module instance.rad> 1 anomaly ip14-80
: switch on the anomaly detector. This mnemonic refers to the ip_probe(1)
module tuned to watch SIE channels 14 and 80. Five watch hits are returned and then we exit.Using radtunnel
is much the same process as using sratunnel
. First invoke radtunnel
with the same anomaly watches as radtool
:
Next let's have a look what this looks like on the network using tcpdump
:
We use nmsgtool
to receive and decapsulate the data. Here we invoke it to capture and display three payloads:
radtunnel -s tls:user@rad.sie-remote.net,1022 -w ip=0.0.0.0/1 -w ip=128.0.0.0/1 -a ip14-80 -o nmsg:127.0.0.1,8000 &
: here, we started a background process to watch for the same IP-based amomalies as the radtool
example, but this time the results will be sent in NMSG format using UDP on a local socket (host 127.0.0.1, port 8000).tcpdump -n -c 3 -i lo udp port 8000
: we then used the tcpdump command to show that packets were being received on the local socket.nmsgtool -l 127.0.0.1/8000 -c 3
: We ran nmsgtool
which output three NMSGs, and then killed the background radtunnel
process.The AXA protocol is above a reliable stream protocol such as TCP and so has no provisions to detect or recover from duplicate, out-of-order, lost, or partially lost data. AXA data can be lost before encapsulation in AXA protocol messages or packets.
For most uses, a protocol such as ssh is used below the AXA layer and above TCP to provide authentication, confidentiality, and integrity.
The AXA protocol consists of a pair of streams of messages between a "client" such as sratool
and an AXA server, one stream in each direction, often ultimately over a single TCP connection.
The authoritative definition of the protocol starts with the axalib/protocol.h
file. This document is merely an informal supplement to protocol.h
.
Values that originate in SRA or RAD servers such as message lengths use little endian byte order in the AXA protocol. Other values such as IP addresses and port numbers are big endian for consistency with their sources such as host tables. SRA and RAD data such as NMSG messages and IP packets have their original byte orders.
The stream protocols below the AXA protocol are responsible for authentication and authorization. An AXA client and server pair on a computer can use unadorned TCP through the loop-back interface or use a UNIX domain socket. The AXA protocol assumes this is safe.
Between separate computers, the AXA protocol can use UNIX pipes to the stdin
and stdout
streams provided by the ssh command or the functions of an ssh library such as libssh2
(ssh must identify and authenticate the client and server to each other) or the TLS library.
The AXA client starts by waiting for an AXA_P_OP_HELLO
message from the server. Over a local stream, the client then sends an AXA_P_OP_USER
message to tell the server which parameters to use. When ssh
is used, the user name is provided by the ssh protocol.
Every AXA message starts with a fixed size header:
len
: The entire length of the AXA message including the header. Many AXA messages are variable length.tag
: A tag is a 16-bit identifier used to uniquely "tag" specific events during the lifetime of an AXA session. To refer to these events, the client or server will use the tag. Some AXA messages do not require tags, in that case the tag field should be 0
. Required tags must be unique during the lifetime of the corresponding client request. Some client requests such as a "watch" can last indefinitely and will elicit many server responses all with the same tag.pvers
: A one-byte protocol version number that allows AXA clients and servers of different ages to find a mutually compatible version of the AXA protocol.op
: The op (opcode) specifies an operation requested by the client, a response from the server, or data from the server. The universe of opcodes is discussed below.For a detailed discussions of the AXA protocol message types, see the doxygen generated page for protocol.h
The following is an AXA protocol quick reference chart intended for application developers building axalib
programs.
axalib/protocol.h
OPCODE | VAL | SENT BY | TAG | DESCRIPTION |
---|---|---|---|---|
AXA_P_OP_NOP | 0 | CLIENT / SERVER | NO | carries no data, is intended only to ensure that the TCP connection is still up |
AXA_P_OP_HELLO | 1 | SERVER | NO | helps the client choose a compatible AXA protocol version |
AXA_P_OP_OK | 2 | SERVER | YES | indicates the success of the preceding client request with the same tag |
AXA_P_OP_ERROR | 3 | SERVER | YES | indicates the failure of a preceeing client request with the same tag |
AXA_P_OP_MISSED | 4 | SERVER | NO | carries details about data or packet loss due to rate limiting or network congestion |
AXA_P_OP_WHIT | 5 | SERVER (SRA) | YES | reports a "watch hit" or packet or NMSG message that matched an SRA watch with the same tag |
AXA_P_OP_WLIST | 6 | SERVER (SRA) | YES | reports a current watch in response to AXA_P_OP_WGET from the client referenced by tag |
AXA_P_OP_AHIT | 7 | SERVER (RAD) | YES | reports an "anomaly hit" or packet or NMSG message detected by a set of anomaly detector |
AXA_P_OP_ALIST | 8 | SERVER (RAD) | YES | reports a current anomaly detector in response to AXA_P_OP_AGET |
AXA_P_OP_CLIST | 9 | SERVER (SRA) | NO | reports the on/off state and specification of an SRA channel |
AXA_P_OP_USER | 129 | CLIENT | NO | indicates the AXA protocol is used over a local stream and rejected otherwise |
AXA_P_OP_JOIN | 130 | CLIENT | NO | used to bundle TCP connections |
AXA_P_OP_PAUSE | 131 | CLIENT | NO | ask the server to temporarily stop sending packets or NMSG messages |
AXA_P_OP_GO | 132 | CLIENT | NO | ask the server to resume sending packets or NMSG messages |
AXA_P_OP_WATCH | 133 | CLIENT | NO | specify interesting packets or NMSG messages |
AXA_P_OP_WGET | 134 | SERVER (SRA) | – | requests one (with specified tag) or all (tag 0) current watches in AXA_P_OP_WLIST messages |
AXA_P_OP_ANOM | 135 | SERVER (RAD) | YES | specify an anomaly detector |
AXA_P_OP_AGET | 136 | SERVER (RAD) | – | requests one or all current anomaly detectors |
AXA_P_OP_STOP | 137 | CLIENT | NO | ask the server to delete the watch or anomaly detector by tag |
AXA_P_OP_ALL_STOP | 138 | CLIENT | NO | ask the server to delete all watches or anomaly detectors |
AXA_P_OP_CHANNEL | 139 | CLIENT (SRA) | NO | tell the SRA server to enable or disable one channel or all channels |
AXA_P_OP_CGET | 140 | CLIENT (SRA) | NO | get the specifications and states of all channels |
AXA_P_OP_OPT | 141 | CLIENT / SERVER | NO | set various options (rate limiting) report rate limits, how much has been used |
AXA_P_OP_ACCT | 142 | CLIENT / SERVER | NO | request accounting information |
AXA_P_OP_RADU | 143 | SERVER (RAD) | NO | request RAD Unit balance |
TODO.