[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: Audit Parsing Library Requirements



On Friday 10 March 2006 12:05, Steve Grubb wrote:
> so this is another round of updates with more details fleshed out.

OK. I think the last round of comments was helpful. I added some language to 
define the concept of multiple hosts in one log. This is the final draft 
unless there is an omission.

-Steve



Audit Event Parsing Library Specifications
==========================================

Definitions
-----------
An audit event is all records that have the same host, timestamp, and
serial number. Each event on a host has a unique timestamp and serial
number. An event is composed of multiple records which have information about
different aspects of an audit event. Each record is denoted by a type which
indicates what fields will follow. Information in the fields are held by a
name/value pair that contains an '=' between them. Each field is separated
from one another by a space or comma.


Ground Rules
------------
All functions that begin with ausearch are related to searching for a subset
of events based on certain criteria. All functions that begin with auparse
are used to access events, records, and fields sequentially and without
regard to any search options that may be in effect. All functions return 1
on success and 0 on failure unless otherwise noted. Where the return type is
a char pointer, NULL will indicate failure. The data structures would be
hidden from the external application. Access to fields is a name/value style.
You access the fields through functions that either return a pointer to an
immutable, zero-terminated array of ASCII characters or integral values. Every
function (except auparse_init) takes a parameter, au, which is the internal
state information for the current query.


Functions
---------
auparse_state_t - is an opaque data type used for maintaining library state.

typedef enum { AUSOURCE_LOGS, AUSOURCE_FILE, AUSOURCE_BUFFER } ausource_t;

auparse_state_t *auparse_init(ausource_t source, const void *b) - allow init 
of library. Set data source: logs, file, buffer. The pointer 'b' is used to 
set the file name or pass the buff when those types are given.

typedef enum { AUSEARCH_STOP_EVENT, AUSEARCH_STOP_RECORD, 
AUSEARCH_STOP_FIELD } austop_t;

int ausearch_set_param(auparse_state_t *au, const char *field, const char *op,
                       const char *value, austop_t where) - set search 
options. The field would be the left hand side of the audit name/value pairs. 
The op would be how to match: =,!=,>,<. The value would be the right hand 
side of the audit field name/value pairs. The where parameter tells the 
search library where to place the internal cursor when a match is found. It 
could be on first field of first record, first field of record containing the 
match, or the field that matches.

int ausearch_next_event(auparse_state_t *au) - traverse to the next event that
yields a match based on the given search criteria.

int auparse_next_event(auparse_state_t *au) - traverse to next event. This
allows access to time and serial number.

typedef struct
{
        time_t sec;             // Event seconds
        unsigned int milli;     // millisecond of the timestamp
        unsigned long serial;   // Serial number of the event
	const char *host;	// Machine's name
} event_t;

event_t auparse_get_timestamp(auparse_state_t *au) - retrieve time stamp of
current record
time_t auparse_get_time(auparse_state_t *au) - retrieve time in seconds of
current record
time_t auparse_get_milli(auparse_state_t *au) - retrieve milliseconds time of
current record
unsigned long auparse_get_serial(auparse_state_t *au) - retrieve serial number
of current record
const char *auparse_get_host(auparse_state_t *au) - retrieve host name
of current record

int auparse_first_record(auparse_state_t *au) - set iterator to first record
in current event

int auparse_next_record(auparse_state_t *au) - traverse to next record in
event. This allows access to the event type

int auparse_get_type(auparse_state_t *au) - retrieve type of current record

int auparse_first_field(auparse_state_t *au) - set field pointer to first in
current record

int auparse_next_field(auparse_state_t *au)  - traverse the fields in a record

const char *auparse_find_field(auparse_state_t *au, const char *name) - find a
given field in a event or record. Name is the left hand side of the name/value
pair. Returns pointer to the value as ascii text.

const char *auparse_find_field_next(auparse_state_t *au) - find the next
occurance of that field in the same record. Returns pointer to the value as
ascii text.

const char *auparse_get_field_str(auparse_state_t *au) - return current field
value as a string

int auparse_get_field_int(auparse_state_t *au) -  return current field value
as an int

const char *auparse_interpret_field(auparse_state_t *au) - interpret the 
current field

int auparse_destroy(auparse_state_t *au) - free all data structures and close
file descriptors


Code Example
------------
int main(void) 
{
	auparse_state_t *au = auparse_init(AUSOURCE_LOGS, NULL);
	if (au == NULL) 
		exit(1);

	if (!ausearch_set_param(au, "auid", "=", "500", AUSEARCH_STOP_EVENT)) 
		exit(1);

	while (ausearch_next_event(au)) {
		if (auparse_find_field(au, "auid")) {
			printf("auid=%s\n", auparse_interpret_field(au));
		}
	}
	return 0;
}


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]