axa  1.2.1
Farsight Security Advanced Exchange Access (AXA)
axa_fields

Detailed Description

axa_fields contains NMSG field related data type definitions and function declarations.

Data Structures

struct  axa_nmsg_sf
 Some fields of some NMSG messages have a type/value structure such as JSON tags. More...
 
struct  axa_nmsg_help_t
 an auxiliary value such as DNS class or rtype More...
 
struct  axa_nmsg_field
 An NMSG message understood by AXA. More...
 
struct  axa_helper_cache_t
 AXA helper cache. More...
 

Macros

#define AXA_FIELD_NM_LEN   32
 maximum length of an AXA field name More...
 
#define AXA_HELPER_CACHE_LEN   4
 AXA helper cache size. More...
 
#define AXA_WDNS_RES_STRLEN   24
 buf is used only for bogus wres More...
 

Typedefs

typedef struct axa_nmsg_sf axa_nmsg_sf_t
 Some fields of some NMSG messages have a type/value structure such as JSON tags. More...
 
typedef struct vm_entry vm_entry_t
 NMSG vendor IDs and message types worthy decoding by SRA. More...
 
typedef struct axa_nmsg_field axa_nmsg_field_t
 An NMSG message understood by AXA. More...
 

Enumerations

enum  axa_fc_t
 nmsg field contents type More...
 
enum  axa_w2n_res_t
 axa_whit2nmsg return values More...
 

Functions

bool axa_get_helper (axa_emsg_t *emsg, const nmsg_message_t msg, const axa_nmsg_help_t *help, axa_nmsg_idx_t val_idx, void *val, size_t *val_len, size_t min_val_len, size_t max_val_len, axa_helper_cache_t *cache)
 Get the contents of a "helper" field for a fields file line. More...
 
const axa_nmsg_field_taxa_msg_fields (const nmsg_message_t msg)
 Check the global vid/msgtype hash table to see if we know a vendor ID and message type and if so, get our list of its interesting fields. More...
 
void axa_unload_fields (void)
 Unload all data from the global vid/msgtype hash table and free all memory. More...
 
void axa_load_fields (const char *fields_file)
 Read the NMSG fields file to build the tables of known vendor IDs, message types, and fields. More...
 
const char * axa_get_field_name (const nmsg_message_t msg, unsigned field_idx)
 Get the name of a field specified by index. More...
 
const char * axa_wdns_res (unsigned int wres, char *buf, size_t buf_len)
 Lookup wdns result code and return a canonical string representation. More...
 
const char * axa_rtype_to_str (char *buf, size_t buf_len, unsigned int rtype)
 Lookup wdns rrtype and return a canonical string representation. More...
 
axa_w2n_res_t axa_whit2nmsg (axa_emsg_t *emsg, nmsg_input_t nmsg_input, nmsg_message_t *msgp, axa_p_whit_t *whit, size_t whit_len)
 Create an NMSG from a watch hit. More...
 

Variables

const axa_nmsg_field_t axa_null_field
 an empty field definition used as a template or a placeholder More...
 

Macro Definition Documentation

#define AXA_FIELD_NM_LEN   32

maximum length of an AXA field name

#define AXA_HELPER_CACHE_LEN   4

AXA helper cache size.

A single NMSG message can have more than two or more fields involving the same helper values. For example, an NMSG message containing a DNS response message with domain and rdata fields can depend on a single field containing the DNS class. Helper caches are automatic variables in a caller's stack.

#define AXA_WDNS_RES_STRLEN   24

buf is used only for bogus wres

Typedef Documentation

typedef struct axa_nmsg_sf axa_nmsg_sf_t

Some fields of some NMSG messages have a type/value structure such as JSON tags.

typedef struct vm_entry vm_entry_t

NMSG vendor IDs and message types worthy decoding by SRA.

Each (vendor, message type) pair has a list of fields that contain domains or IP addresses.

An NMSG message understood by AXA.

Every interesting field in an interesting NMSG message is defined by a line in the fields file. Each line is compiled into a list of these structures, one for each interesting nmsg field. Some NMSG fields need the contents of other NMSG fields for proper decoding, such as DNS class and rtype for DNS rdata. Some NMSG fields have varying types, such as JSON or other values. When .enm is not AXA_NMSG_IDX_NONE, then one of these applies only to messages where contents of the NMSG field with the index in .enm is equal to .enm_val

Enumeration Type Documentation

enum axa_fc_t

nmsg field contents type

Enumerator
AXA_FC_UNKNOWN 

ignore this field

AXA_FC_IP_DGRAM 

IP datagram.

AXA_FC_IP 

binary IP address

AXA_FC_IP_ASCII 

ASCII IP address.

AXA_FC_DOM 

wire-format domain

AXA_FC_DOM_ASCII 

ASCII domain.

AXA_FC_HOST 

ASCII domain or IP address.

AXA_FC_RDATA 

DNS rdata.

AXA_FC_DNS 

complete DNS packet

AXA_FC_JSON 

JSON encoded.

axa_whit2nmsg return values

Enumerator
AXA_W2N_RES_FAIL 

failure

AXA_W2N_RES_SUCCESS 

success

AXA_W2N_RES_FRAGMENT 

fragment received (should be ignored)

Function Documentation

bool axa_get_helper ( axa_emsg_t emsg,
const nmsg_message_t  msg,
const axa_nmsg_help_t help,
axa_nmsg_idx_t  val_idx,
void *  val,
size_t *  val_len,
size_t  min_val_len,
size_t  max_val_len,
axa_helper_cache_t cache 
)

Get the contents of a "helper" field for a fields file line.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]msgthe NMSG to query
[in]helpNMSG helper
[in]val_idxvalue index
[out]valthe value will be stored here
[out]val_lenoptional length of value, can be NULL for fixed value length
[in]min_val_lenminimum allowed data length
[in]max_val_lenmaximum allowed data length
[in,out]cacheoptional cache pointer to expedite repeated fetches
Return values
truesuccessful lookup, val and val_len are set
falsesomething went wrong, check emsg
const axa_nmsg_field_t* axa_msg_fields ( const nmsg_message_t  msg)

Check the global vid/msgtype hash table to see if we know a vendor ID and message type and if so, get our list of its interesting fields.

Parameters
[in]msgNMSG message to query
Returns
success: pointer to axa_nmsg_field_t containing the NMSG vid and msgtype, failure: NULL
void axa_unload_fields ( void  )

Unload all data from the global vid/msgtype hash table and free all memory.

void axa_load_fields ( const char *  fields_file)

Read the NMSG fields file to build the tables of known vendor IDs, message types, and fields.

Parameters
[in]fields_fileconst char * canonical name of NMSG fields file
const char* axa_get_field_name ( const nmsg_message_t  msg,
unsigned  field_idx 
)

Get the name of a field specified by index.

Function is a wrapper for nmsg_message_get_field_name() that returns the string "???" if field name is not known.

Parameters
[in]msgNMSG to check
[in]field_idxfield index
Returns
success; the name of the field, failure: the string "???"
const char* axa_wdns_res ( unsigned int  wres,
char *  buf,
size_t  buf_len 
)

Lookup wdns result code and return a canonical string representation.

Return a value that can be used as an arg to printf().

Parameters
[in]wreswdns result code
[out]bufbuffer to hold string representation
[out]buf_lenlength of buffer
Returns
the contents of buf
const char* axa_rtype_to_str ( char *  buf,
size_t  buf_len,
unsigned int  rtype 
)

Lookup wdns rrtype and return a canonical string representation.

Wraps wdns_rrtype_to_str().

Parameters
[out]bufbuffer to hold string representation
[out]buf_lenlength of buffer
[in]rtypethe wdns rrtype code
Returns
the contents of buf
axa_w2n_res_t axa_whit2nmsg ( axa_emsg_t emsg,
nmsg_input_t  nmsg_input,
nmsg_message_t *  msgp,
axa_p_whit_t whit,
size_t  whit_len 
)

Create an NMSG from a watch hit.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]nmsg_inputnmsg_input_t
[out]msgpnmsg_message_t on success, pointer the nmsg
[in]whitaxa_p_whit_t pointer to the AXA watch hit buffer
[in]whit_lensize_t length of watch hit
Return values
AXA_W2N_RES_FAILfailure, check emsg
AXA_W2N_RES_SUCCESSsuccess, msgp contains the NMSG
AXA_W2N_RES_FRAGMENTignore fragments but don't fail on them

Variable Documentation

const axa_nmsg_field_t axa_null_field

an empty field definition used as a template or a placeholder