axa 3.0.2
Farsight Security Advanced Exchange Access (AXA)
_PK Struct Reference

AXA protocol header. More...

Data Structures

struct  _PK
 timestamp when the NMSG message was reported. More...
 
union  axa_p_opt_u
 option union More...
 

Data Fields

uint32_t len
 total length including header
 
axa_tag_t tag
 A tag is a 16-bit identifier used to uniquely "tag" specific events during the lifetime of an AXA session.
 
axa_p_pvers_t pvers
 protocol version
 
uint8_t op
 op code
 
axa_p_clnt_id_t id
 client ID for bundled TCP
 
axa_p_pvers_t pvers_min
 min protocol version accepted
 
axa_p_pvers_t pvers_max
 max protocol version accepted
 
char str [512]
 data about server/client
 
uint8_t orig_op
 original axa_p_op_t
 
axa_cnt_t missed
 The number of packets (SIE messages or raw IP packets) lost in the network between the source and the SRA server or dropped by the SRA server because it was too busy.
 
axa_cnt_t dropped
 by SRA client-server congestion
 
axa_cnt_t rlimit
 dropped by rate limiting
 
axa_cnt_t filtered
 total considered
 
uint32_t last_report
 UNIX epoch of previous report.
 
axa_cnt_t sra_missed
 missed by all SRA servers
 
axa_cnt_t sra_dropped
 for SRA client-server congestion
 
axa_cnt_t sra_rlimit
 discarded to SRA rate limit
 
axa_cnt_t sra_filtered
 considered by SRA servers
 
char name [64]
 ASCII, variable length, null terminated user name.
 
axa_p_ch_t ch
 channel number
 
uint8_t type
 axa_p_whit_enum_t
 
uint8_t pad
 to 0 mod 4
 
axa_p_whit_hdr_t hdr
 header for all watch hits
 
axa_nmsg_idx_t field_idx
 triggering field index
 
axa_nmsg_idx_t val_idx
 which value of field
 
axa_nmsg_idx_t vid
 NMSG vendor ID.
 
axa_nmsg_idx_t type
 NMSG type.
 
struct _PK::_PK ts
 timestamp
 
struct _PK::_PK tv
 timestamp
 
uint32_t ip_len
 packet length on the wire
 
axa_p_whit_nmsg_hdr_t hdr
 watch hit NMSG header
 
uint8_t b [0]
 start of SIE message
 
axa_p_whit_ip_hdr_t hdr
 watch hit IP header
 
uint8_t prefix
 IP address only.
 
uint8_t flags
 flags
 
axa_p_watch_pat_t pat
 watch pattern
 
axa_tag_t cur_tag
 current tag of watch
 
axa_p_watch_t w
 one of the listed watches
 
char c [32]
 < anomaly module name
 
axa_p_an_t an
 anomaly module name
 
char parms [AXA_PARMS_MAX]
 parms, null terminated
 
axa_p_whit_t whit
 anomalous SIE message or packet
 
axa_p_anom_t anom
 a listed anomaly module
 
uint8_t on
 boolean, 1 for on, 0 for off
 
axa_p_chspec_t spec
 < !=0 if on
 
axa_cnt_t max_pkts_per_sec
 When in an option AXA_P_OP_OPT message sent by the client, request the server to send no more than this many AXA AXA_P_OP_WHIT or AXA_P_OP_AHIT messages per second.
 
axa_cnt_t cur_pkts_per_sec
 This is the current value of the server's rate limit counter.
 
axa_cnt_t unused1
 reserved
 
axa_cnt_t unused2
 reserved
 
axa_cnt_t report_secs
 The minimum number of seconds between reports of rate limiting.
 
union _PK::axa_p_opt_u u
 holds actual option
 

Detailed Description

AXA protocol header.

AXA protocol options.

AXA protocol rlimit.

AXA protocol channel list.

AXA protocol channel specification.

AXA protocol channel enable/disable.

AXA protocol anomaly list.

AXA protocol anomaly module hit.

AXA protocol anomaly module specified by RAD client.

AXA protocol anomaly module name.

AXA protocol watch list.

AXA protocol watch.

AXA protocol watch hit before an IP packet.

AXA protocol watch hit before an NMSG message.

AXA protocol watch hit header before an IP packet.

AXA protocol watch hit header before an NMSG message.

AXA protocol header before all watch hits.

AXA protocol user name.

AXA protocol RAD missed data.

AXA protocol SRA missed data.

AXA protocol result.

AXA protocol join.

The AXA HELLO protocol is a bidirectional handshaking process initiated by the server, once a client has authenticated.

This header starts all messages in either direction. At 8 bytes, it is alignment friendly.

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:

  • hostname of client system
  • client system information as per the uname() function
  • client program of origin (sratool, sratunnel, etc)
  • libaxa version
  • libnmsg version
  • libwdns version
  • libyajl version
  • openssl version
  • libprotobuf version
  • AXA protocol version in current use

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.

Field Documentation

◆ len

uint32_t _PK::len

total length including header

◆ tag

axa_tag_t _PK::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 use tags. In those cases, the tag field should be 0. Required tags must be unique during the lifetime of the corresponding client request. Some requests such as a "watch" last indefinitely and can elicit many server responses all with the same tag.

◆ pvers

axa_p_pvers_t _PK::pvers

protocol version

◆ op

uint8_t _PK::op

op code

◆ id

axa_p_clnt_id_t _PK::id

client ID for bundled TCP

client ID originally from server

◆ pvers_min

axa_p_pvers_t _PK::pvers_min

min protocol version accepted

◆ pvers_max

axa_p_pvers_t _PK::pvers_max

max protocol version accepted

◆ str

char _PK::str[512]

data about server/client

Human readable string containing an error, success, or other about the recent operation in .op with the tag the header of this message.

It is variable length string up to 512 bytes the including terminating null.

◆ orig_op

uint8_t _PK::orig_op

original axa_p_op_t

◆ missed

axa_cnt_t _PK::missed

The number of packets (SIE messages or raw IP packets) lost in the network between the source and the SRA server or dropped by the SRA server because it was too busy.

◆ dropped

axa_cnt_t _PK::dropped

by SRA client-server congestion

for RAD client-server congestion

◆ rlimit

axa_cnt_t _PK::rlimit

dropped by rate limiting

discarded to RAD rate limit

◆ filtered

axa_cnt_t _PK::filtered

total considered

considered by RAD modules

◆ last_report

uint32_t _PK::last_report

UNIX epoch of previous report.

◆ sra_missed

axa_cnt_t _PK::sra_missed

missed by all SRA servers

◆ sra_dropped

axa_cnt_t _PK::sra_dropped

for SRA client-server congestion

◆ sra_rlimit

axa_cnt_t _PK::sra_rlimit

discarded to SRA rate limit

◆ sra_filtered

axa_cnt_t _PK::sra_filtered

considered by SRA servers

◆ name

char _PK::name[64]

ASCII, variable length, null terminated user name.

◆ ch

axa_p_ch_t _PK::ch

channel number

channel (binary)

◆ type [1/2]

uint8_t _PK::type

axa_p_whit_enum_t

option type

axa_p_watch_type_t

◆ pad

uint8_t _PK::pad

to 0 mod 4

to 0 mod 8 for axa_p_rlimit_t

◆ hdr [1/3]

axa_p_whit_hdr_t _PK::hdr

header for all watch hits

◆ field_idx

axa_nmsg_idx_t _PK::field_idx

triggering field index

◆ val_idx

axa_nmsg_idx_t _PK::val_idx

which value of field

◆ vid

axa_nmsg_idx_t _PK::vid

NMSG vendor ID.

◆ type [2/2]

axa_nmsg_idx_t _PK::type

NMSG type.

◆ ts

struct _PK::_PK _PK::ts

timestamp

◆ tv

struct _PK::_PK _PK::tv

timestamp

◆ ip_len

uint32_t _PK::ip_len

packet length on the wire

◆ hdr [2/3]

watch hit NMSG header

◆ b

uint8_t _PK::b

start of SIE message

start of IP packet

◆ hdr [3/3]

watch hit IP header

◆ prefix

uint8_t _PK::prefix

IP address only.

◆ flags

uint8_t _PK::flags

flags

◆ pat

watch pattern

◆ cur_tag

axa_tag_t _PK::cur_tag

current tag of watch

◆ w

axa_p_watch_t _PK::w

one of the listed watches

◆ c

char _PK::c[1024]

< anomaly module name

Human readable string specifying the channel.

wastefully null terminated

It often looks like an IP address or network interface name or SIE channel alias.

◆ an

axa_p_an_t _PK::an

anomaly module name

module that detected the anomaly

◆ parms

char _PK::parms[AXA_PARMS_MAX]

parms, null terminated

◆ whit

axa_p_whit_t _PK::whit

anomalous SIE message or packet

◆ anom

axa_p_anom_t _PK::anom

a listed anomaly module

◆ on

uint8_t _PK::on

boolean, 1 for on, 0 for off

◆ spec

axa_p_chspec_t _PK::spec

< !=0 if on

channel (human readable)

◆ max_pkts_per_sec

axa_cnt_t _PK::max_pkts_per_sec

When in an option AXA_P_OP_OPT message sent by the client, request the server to send no more than this many AXA AXA_P_OP_WHIT or AXA_P_OP_AHIT messages per second.

Use AXA_RLIMIT_OFF to request no limit. AXA_RLIMIT_NA to not change th

◆ cur_pkts_per_sec

axa_cnt_t _PK::cur_pkts_per_sec

This is the current value of the server's rate limit counter.

The counter is incremented each time a relevant AXA message is considered for sending to the client. If the new value is greater than the rate limit, the message dropped. The counter is reset every second.

◆ unused1

axa_cnt_t _PK::unused1

reserved

◆ unused2

axa_cnt_t _PK::unused2

reserved

◆ report_secs

axa_cnt_t _PK::report_secs

The minimum number of seconds between reports of rate limiting.

It is a rate limit on rate limit reports.

◆ u

union _PK::axa_p_opt_u _PK::u

holds actual option