Audit Parsing Library Requirements

[Michael C Thompson]

linux-audit-bounces at redhat.com wrote on 03/10/2006 03:33:12 PM:

> 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.

I know this is not likely to change, but is there a reason why we don't 
have a common delimiter? I understand that going through the code and 
modifying this would be a large undertaking, and I'm not even saying I 
will do it (although I believe Loulwa was consider doing at one point, but 
don't hold me to that). Removing inconstancies in the records, such as 
using '_' in place of spaces in field names and removing these commas, 
would seem like a good thing to do, but before anyone does that work, will 
making that change be acceptable from a code point of view? (Discount any 
work which might be needed to update parsing code from ausearch etc, 
although there would be a fair amount to change I imagine).

> 
> 
> 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

Typo: The data structures [would -> will] 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.

Although it is clear from the code example (and I am sure this is not 
going to be the final version of the document, it would probably be nice 
to mention that auparse will, when not using auparse_next_event, will be 
parsing the record that was found (and is current being pointed to) by 
ausearch_* functions, for example. Your comment in the above, "without 
regard to any search options that may be in effect", is somewhat 
befuddling on this point. A clear statement such as "auparse_* functions 
will parse the current event found either through ausearch_* functions or 
auparse_* functions." I am not a writer though, so don't use my suggestion 
verbatim.

> 
> 
> 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, constchar 
*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;
> }
> 
> --
> Linux-audit mailing list
> Linux-audit at redhat.com
> https://www.redhat.com/mailman/listinfo/linux-audit
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/linux-audit/attachments/20060313/0b724e44/attachment.htm>