axa
2.2.0
Farsight Security Advanced Exchange Access (AXA)
|
axa_protocol
contains the AXA protocol data types and macros.
This protocol uses network byte order to accommodate SRA clients on a modest variety of 32-bit and 64-bit *BSD and Linux systems.
It might need adjustment to accommodate clients on ARM and other platforms other than amd64 and x86.
These protocols should not allow the client ask for the server to run any program or do anything else that might change any permanent state on the server other than logging and accounting.
A client should only be able to set its only filter criteria and receive packets and messages matching those criteria. Other than inevitable side channels such as system load, one client must not be able to affect any other client. A client must treat the packets and messages it receives as pure data and not commands.
Data Structures | |
struct | _PK |
AXA protocol header. More... | |
struct | axa_p_ch_buf_t |
Null terminated ASCII string naming an SIE channel in configuration files, sratool commands, and sratunnel args. More... | |
union | axa_p_whit_t |
generic AXA protocol watch hit More... | |
union | axa_p_watch_pat_t |
AXA protocol watch pattern. More... | |
union | axa_p_body_t |
AXA protocol body. More... | |
Macros | |
#define | _PK __attribute__ ((__packed__)) |
Pack AXA structures in messages to make them the same for all platforms regardless of their word alignment restrictions. More... | |
#define | AXA_KEEPALIVE_SECS 30 |
Send an AXA_P_OP_NOP after this many seconds of silence. More... | |
#define | AXA_KEEPALIVE_MS (AXA_KEEPALIVE_SECS*1000) |
Send an AXA_P_OP_NOP after this many milliseconds of silence. More... | |
#define | AXA_TAG_NONE 0 |
no tag More... | |
#define | AXA_TAG_MIN 1 |
minimum tag More... | |
#define | AXA_TAG_MAX ((axa_tag_t)-1) |
maximum tag More... | |
#define | AXA_P2H_TAG(t) AXA_P2H16(t) |
Convert tag from protocol to host byte order. More... | |
#define | AXA_H2P_TAG(t) AXA_H2P16(t) |
Convert tag from host to protocol byte order. More... | |
#define | AXA_P_PVERS1 1 |
protocol versions More... | |
#define | AXA_P_PVERS2 2 |
#define | AXA_P_PVERS AXA_P_PVERS2 |
current protocol version More... | |
#define | AXA_P_PVERS_MIN AXA_P_PVERS1 |
minimum understood protocol version More... | |
#define | AXA_P_PVERS_MAX AXA_P_PVERS2 |
maximum understood protocol version More... | |
#define | AXA_H2P16(x) htole16(x) |
Choose a generally little endian protocol. More... | |
#define | AXA_H2P32(x) htole32(x) |
AXA host to protocol 32-bit. More... | |
#define | AXA_H2P64(x) htole64(x) |
AXA host to protocol 64-bit. More... | |
#define | AXA_P2H16(x) le16toh(x) |
AXA protocol to host 16-bit. More... | |
#define | AXA_P2H32(x) le32toh(x) |
AXA protocol to host 32-bit. More... | |
#define | AXA_P2H64(x) le64toh(x) |
AXA protocol to host 64-bit. More... | |
#define | AXA_P_MAX_BODY_LEN (64*1024*3) |
room for more than two full sized UDP packets More... | |
#define | AXA_AUTH_DELAY 30 |
Clients must authenticate themselves to the AXA server within this many seconds after connect(). More... | |
#define | AXA_OP_CH_PREFIX "ch" |
SIE channel name prefix in configuration files, commands, and args. More... | |
#define | AXA_OP_CH_ALL ((axa_p_ch_t)-1) |
"all SIE channels" in configuration files, commands, and args More... | |
#define | AXA_OP_CH_ALLSTR "all" |
"all SIE channels" in AXA protocol messages and some axalib functions More... | |
#define | AXA_OP_CH_MAX 4095 |
maximum channel number More... | |
#define | AXA_P2H_CH(ch) AXA_P2H16(ch) |
Convert binary channel number from protocol to host byte order. More... | |
#define | AXA_H2P_CH(ch) AXA_H2P16(ch) |
Convert channel number from host to protocol byte order. More... | |
#define | AXA_NMSG_IDX_RSVD ((axa_nmsg_idx_t)-16) |
values >= than this are not NMSG indices but flags More... | |
#define | AXA_NMSG_IDX_NONE (AXA_NMSG_IDX_RSVD+1) |
no NMSG index More... | |
#define | AXA_NMSG_IDX_ERROR (AXA_NMSG_IDX_RSVD+2) |
the SIE packet made no sense More... | |
#define | AXA_NMSG_IDX_DARK (AXA_NMSG_IDX_RSVD+3) |
the AXA message is a dark channel packet More... | |
#define | AXA_P2H_IDX(idx) AXA_P2H16(idx) |
Convert axa_nmsg_idx_t index from protocol to host byte order. More... | |
#define | AXA_H2P_IDX(idx) AXA_H2P16(idx) |
Convert axa_nmsg_idx_t index from host to protocol byte order. More... | |
#define | AXA_WHIT_MIN_LEN |
Smallest watch hit. More... | |
#define | AXA_WHIT_MAX_LEN |
Largest watch hit. More... | |
#define | AXA_PARMS_MAX 8192 |
max size of RAD module parms More... | |
#define | AXA_P_OPT_TRACE_REQ ((uint32_t)-1) |
Request server's current trace value. More... | |
#define | AXA_RLIMIT_MAX (1000*1000*1000) |
maximum rlimit More... | |
#define | AXA_RLIMIT_OFF (AXA_RLIMIT_MAX+1) |
Turn off a rate limit. More... | |
#define | AXA_RLIMIT_NA ((axa_cnt_t)-1) |
A rate limit value that doesn't apply or is not being set. More... | |
#define | AXA_P_OPT_SAMPLE_REQ 0 |
Request the output sampling ratio. More... | |
#define | AXA_P_OPT_SAMPLE_SCALE 10000 |
Request the output sampling ratio. More... | |
#define | AXA_P_OPT_SAMPLE_MAX (AXA_P_OPT_SAMPLE_SCALE*100) |
maximum scaled output sampling ratio More... | |
#define | AXA_P_OPT_SNDBUF_REQ 0 |
Request the TCP buffer size ratio. More... | |
#define | AXA_P_OPT_SNDBUF_MIN 1024 |
TCP buffer minimum window size. More... | |
Typedefs | |
typedef uint16_t | axa_tag_t |
A tag is a 16-bit identifier used to uniquely "tag" specific events during the lifetime of an AXA session. More... | |
typedef uint8_t | axa_p_pvers_t |
define old versions for eventual "#ifdef AXA_P_VERSx" More... | |
typedef uint64_t | axa_cnt_t |
a number of messages or seconds More... | |
typedef struct _PK | axa_p_hdr_t |
AXA protocol header. More... | |
typedef uint64_t | axa_p_clnt_id_t |
The AXA client ID is assigned by AXA server and echoed by the client to the server to bundle TCP connections. More... | |
typedef struct _PK | axa_p_hello_t |
The AXA HELLO protocol is a bidirectional handshaking process initiated by the server, once a client has authenticated. More... | |
typedef struct _PK | axa_p_join_t |
AXA protocol join. More... | |
typedef struct _PK | axa_p_result_t |
AXA protocol result. More... | |
typedef struct _PK | axa_p_missed_t |
AXA protocol SRA missed data. More... | |
typedef struct _PK | axa_p_missed_rad_t |
AXA protocol RAD missed data. More... | |
typedef struct _PK | axa_p_user_t |
AXA protocol user name. More... | |
typedef uint16_t | axa_p_ch_t |
a binary SIE channel number in the AXA protocol More... | |
typedef struct _PK | axa_p_whit_hdr_t |
AXA protocol header before all watch hits. More... | |
typedef uint16_t | axa_nmsg_idx_t |
NMSG (SIE) field or value index or a special flag. More... | |
typedef struct _PK | axa_p_whit_nmsg_hdr_t |
AXA protocol watch hit header before an NMSG message. More... | |
typedef struct _PK | axa_p_whit_ip_hdr_t |
AXA protocol watch hit header before an IP packet. More... | |
typedef struct _PK | axa_p_whit_nmsg_t |
AXA protocol watch hit before an NMSG message. More... | |
typedef struct _PK | axa_p_whit_ip_t |
AXA protocol watch hit before an IP packet. More... | |
typedef struct _PK | axa_p_watch_t |
AXA protocol watch. More... | |
typedef struct _PK | axa_p_wlist_t |
AXA protocol watch list. More... | |
typedef struct _PK | axa_p_an_t |
AXA protocol anomaly module name. More... | |
typedef struct _PK | axa_p_anom_t |
AXA protocol anomaly module specified by RAD client. More... | |
typedef struct _PK | axa_p_ahit_t |
AXA protocol anomaly module hit. More... | |
typedef struct _PK | axa_p_alist_t |
AXA protocol anomaly list. More... | |
typedef struct _PK | axa_p_channel_t |
AXA protocol channel enable/disable. More... | |
typedef struct _PK | axa_p_chspec_t |
AXA protocol channel specification. More... | |
typedef struct _PK | axa_p_clist_t |
AXA protocol channel list. More... | |
typedef struct _PK | axa_p_rlimit_t |
AXA protocol rlimit. More... | |
typedef struct _PK | axa_p_opt_t |
AXA protocol options. More... | |
Enumerations | |
enum | axa_p_op_t |
AXA protocol opcodes Use a single address space of opcodes in both directions. More... | |
enum | axa_p_whit_enum_t |
type of AXA watch "hit" being reported to the client More... | |
enum | axa_p_watch_type_t |
AXA protocol watch type. More... | |
enum | axa_p_opt_type_t |
AXA protocol options type. More... | |
#define _PK __attribute__ ((__packed__)) |
Pack AXA structures in messages to make them the same for all platforms regardless of their word alignment restrictions.
#define AXA_KEEPALIVE_SECS 30 |
Send an AXA_P_OP_NOP after this many seconds of silence.
#define AXA_KEEPALIVE_MS (AXA_KEEPALIVE_SECS*1000) |
Send an AXA_P_OP_NOP after this many milliseconds of silence.
#define AXA_TAG_NONE 0 |
no tag
#define AXA_TAG_MIN 1 |
minimum tag
#define AXA_TAG_MAX ((axa_tag_t)-1) |
maximum tag
#define AXA_P2H_TAG | ( | t | ) | AXA_P2H16(t) |
Convert tag from protocol to host byte order.
[in] | t | tag |
#define AXA_H2P_TAG | ( | t | ) | AXA_H2P16(t) |
Convert tag from host to protocol byte order.
[in] | t | tag |
#define AXA_P_PVERS1 1 |
protocol versions
#define AXA_P_PVERS AXA_P_PVERS2 |
current protocol version
#define AXA_P_PVERS_MIN AXA_P_PVERS1 |
minimum understood protocol version
#define AXA_P_PVERS_MAX AXA_P_PVERS2 |
maximum understood protocol version
#define AXA_H2P16 | ( | x | ) | htole16(x) |
Choose a generally little endian protocol.
This must not affect some values such as UDP port numbers and IPv4 addresses which must be big endian except when they are manipulated as numbers. Hence, AXA_H2Pxx() stands for "AXA Host to Protocol..." < 0=switch to big endian protocol for testing AXA host to protocol 16-bit
x | value to convert |
#define AXA_H2P32 | ( | x | ) | htole32(x) |
AXA host to protocol 32-bit.
x | value to convert |
#define AXA_H2P64 | ( | x | ) | htole64(x) |
AXA host to protocol 64-bit.
x | value to convert |
#define AXA_P2H16 | ( | x | ) | le16toh(x) |
AXA protocol to host 16-bit.
x | value to convert |
#define AXA_P2H32 | ( | x | ) | le32toh(x) |
AXA protocol to host 32-bit.
x | value to convert |
#define AXA_P2H64 | ( | x | ) | le64toh(x) |
AXA protocol to host 64-bit.
x | value to convert |
#define AXA_P_MAX_BODY_LEN (64*1024*3) |
room for more than two full sized UDP packets
#define AXA_AUTH_DELAY 30 |
Clients must authenticate themselves to the AXA server within this many seconds after connect().
#define AXA_OP_CH_PREFIX "ch" |
SIE channel name prefix in configuration files, commands, and args.
#define AXA_OP_CH_ALL ((axa_p_ch_t)-1) |
"all SIE channels" in configuration files, commands, and args
#define AXA_OP_CH_ALLSTR "all" |
"all SIE channels" in AXA protocol messages and some axalib functions
#define AXA_OP_CH_MAX 4095 |
maximum channel number
#define AXA_P2H_CH | ( | ch | ) | AXA_P2H16(ch) |
Convert binary channel number from protocol to host byte order.
[in] | ch | channel |
#define AXA_H2P_CH | ( | ch | ) | AXA_H2P16(ch) |
Convert channel number from host to protocol byte order.
[in] | ch | channel |
#define AXA_NMSG_IDX_RSVD ((axa_nmsg_idx_t)-16) |
values >= than this are not NMSG indices but flags
#define AXA_NMSG_IDX_NONE (AXA_NMSG_IDX_RSVD+1) |
no NMSG index
#define AXA_NMSG_IDX_ERROR (AXA_NMSG_IDX_RSVD+2) |
the SIE packet made no sense
#define AXA_NMSG_IDX_DARK (AXA_NMSG_IDX_RSVD+3) |
the AXA message is a dark channel packet
#define AXA_P2H_IDX | ( | idx | ) | AXA_P2H16(idx) |
Convert axa_nmsg_idx_t index from protocol to host byte order.
[in] | idx | index |
#define AXA_H2P_IDX | ( | idx | ) | AXA_H2P16(idx) |
Convert axa_nmsg_idx_t index from host to protocol byte order.
[in] | idx | index |
#define AXA_WHIT_MIN_LEN |
Smallest watch hit.
#define AXA_WHIT_MAX_LEN |
Largest watch hit.
#define AXA_PARMS_MAX 8192 |
max size of RAD module parms
#define AXA_P_OPT_TRACE_REQ ((uint32_t)-1) |
Request server's current trace value.
#define AXA_RLIMIT_MAX (1000*1000*1000) |
maximum rlimit
#define AXA_RLIMIT_OFF (AXA_RLIMIT_MAX+1) |
Turn off a rate limit.
#define AXA_RLIMIT_NA ((axa_cnt_t)-1) |
A rate limit value that doesn't apply or is not being set.
#define AXA_P_OPT_SAMPLE_REQ 0 |
Request the output sampling ratio.
#define AXA_P_OPT_SAMPLE_SCALE 10000 |
Request the output sampling ratio.
#define AXA_P_OPT_SAMPLE_MAX (AXA_P_OPT_SAMPLE_SCALE*100) |
maximum scaled output sampling ratio
#define AXA_P_OPT_SNDBUF_REQ 0 |
Request the TCP buffer size ratio.
#define AXA_P_OPT_SNDBUF_MIN 1024 |
TCP buffer minimum window size.
typedef uint16_t axa_tag_t |
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.
Tags are opaque to the SRA server except for AXA_TAG_NONE and that the server sorts or orders them like integers.
typedef uint8_t axa_p_pvers_t |
define old versions for eventual "#ifdef AXA_P_VERSx"
typedef uint64_t axa_cnt_t |
a number of messages or seconds
typedef struct _PK axa_p_hdr_t |
AXA protocol header.
This header starts all messages in either direction. At 8 bytes, it is alignment friendly.
typedef uint64_t axa_p_clnt_id_t |
The AXA client ID is assigned by AXA server and echoed by the client to the server to bundle TCP connections.
typedef struct _PK axa_p_hello_t |
The AXA HELLO protocol is a bidirectional handshaking process initiated by the server, once a client has authenticated.
server -> client After successful authentication, the server will send to the client a HELLO message via an axa_p_hello_t header announcing the protocol versions that the server understands, a version string, and a unique ID that can be later used by clients via AXA_P_OP_JOIN messages to flag connections that are part of a bundle. Because AXA_P_OP_HELLO is sent before the client has said anything and so declared its protocol version, AXA_P_OP_HELLO must remain the same in all versions of the AXA protocol.
client -> server After receiving the server's HELLO, the client will respond with its part of the handshake. It will populate the same axa_p_hello_t header announcing the protocol versions it speaks and a detailed JSON blob containing information about the client including the following:
The ID field of the axa_p_hello_t header is unused in this direction. It is expected the server will log this information for subsequent issue debugging or data mining.
typedef struct _PK axa_p_join_t |
AXA protocol join.
typedef struct _PK axa_p_result_t |
AXA protocol result.
typedef struct _PK axa_p_missed_t |
AXA protocol SRA missed data.
typedef struct _PK axa_p_missed_rad_t |
AXA protocol RAD missed data.
typedef struct _PK axa_p_user_t |
AXA protocol user name.
typedef uint16_t axa_p_ch_t |
a binary SIE channel number in the AXA protocol
typedef struct _PK axa_p_whit_hdr_t |
AXA protocol header before all watch hits.
typedef uint16_t axa_nmsg_idx_t |
NMSG (SIE) field or value index or a special flag.
typedef struct _PK axa_p_whit_nmsg_hdr_t |
AXA protocol watch hit header before an NMSG message.
typedef struct _PK axa_p_whit_ip_hdr_t |
AXA protocol watch hit header before an IP packet.
typedef struct _PK axa_p_whit_nmsg_t |
AXA protocol watch hit before an NMSG message.
typedef struct _PK axa_p_whit_ip_t |
AXA protocol watch hit before an IP packet.
typedef struct _PK axa_p_watch_t |
AXA protocol watch.
typedef struct _PK axa_p_wlist_t |
AXA protocol watch list.
typedef struct _PK axa_p_an_t |
AXA protocol anomaly module name.
typedef struct _PK axa_p_anom_t |
AXA protocol anomaly module specified by RAD client.
typedef struct _PK axa_p_ahit_t |
AXA protocol anomaly module hit.
typedef struct _PK axa_p_alist_t |
AXA protocol anomaly list.
typedef struct _PK axa_p_channel_t |
AXA protocol channel enable/disable.
typedef struct _PK axa_p_chspec_t |
AXA protocol channel specification.
typedef struct _PK axa_p_clist_t |
AXA protocol channel list.
typedef struct _PK axa_p_rlimit_t |
AXA protocol rlimit.
typedef struct _PK axa_p_opt_t |
AXA protocol options.
enum axa_p_op_t |
AXA protocol opcodes Use a single address space of opcodes in both directions.
enum axa_p_whit_enum_t |
enum axa_p_watch_type_t |
enum axa_p_opt_type_t |