|
Packit |
f0d170 |
.TH "AUSEARCH-EXPRESSION" "5" "Feb 2008" "Red Hat" "Linux Audit"
|
|
Packit |
f0d170 |
.SH NAME
|
|
Packit |
f0d170 |
ausearch-expression \- audit search expression format
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH OVERVIEW
|
|
Packit |
f0d170 |
This man page describes the format of "ausearch expressions".
|
|
Packit |
f0d170 |
Parsing and evaluation of these expressions is provided by libauparse
|
|
Packit |
f0d170 |
and is common to applications that use this library.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH LEXICAL STRUCTURE
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
White space (ASCII space, tab and new-line characters) between tokens is
|
|
Packit |
f0d170 |
ignored.
|
|
Packit |
f0d170 |
The following tokens are recognized:
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Punctuation
|
|
Packit |
f0d170 |
.B ( ) \e
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Logical operators
|
|
Packit |
f0d170 |
.B ! && ||
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Comparison operators
|
|
Packit |
f0d170 |
.B < <= == > >= !== i= i!= r= r!=
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Unquoted strings
|
|
Packit |
f0d170 |
Any non-empty sequence of ASCII letters, digits, and the
|
|
Packit |
f0d170 |
.B _
|
|
Packit |
f0d170 |
symbol.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Quoted strings
|
|
Packit |
f0d170 |
A sequence of characters surrounded by the
|
|
Packit |
f0d170 |
.B \(dq
|
|
Packit |
f0d170 |
quotes.
|
|
Packit |
f0d170 |
The
|
|
Packit |
f0d170 |
.B \e
|
|
Packit |
f0d170 |
character starts an escape sequence.
|
|
Packit |
f0d170 |
The only defined escape sequences are
|
|
Packit |
f0d170 |
.B \e\e
|
|
Packit |
f0d170 |
and \fB\e\(dq\fR.
|
|
Packit |
f0d170 |
The semantics of other escape sequences is undefined.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
Regexps
|
|
Packit |
f0d170 |
A sequence of characters surrounded by the
|
|
Packit |
f0d170 |
.B /
|
|
Packit |
f0d170 |
characters.
|
|
Packit |
f0d170 |
The
|
|
Packit |
f0d170 |
.B \e
|
|
Packit |
f0d170 |
character starts an escape sequence.
|
|
Packit |
f0d170 |
The only defined escape sequences are
|
|
Packit |
f0d170 |
.B \e\e
|
|
Packit |
f0d170 |
and \fB\e/\fR.
|
|
Packit |
f0d170 |
The semantics of other escape sequences is undefined.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.PP
|
|
Packit |
f0d170 |
Anywhere an unquoted string is valid, a quoted string is valid as well,
|
|
Packit |
f0d170 |
and vice versa.
|
|
Packit |
f0d170 |
In particular, field names may be specified using quoted strings,
|
|
Packit |
f0d170 |
and field values may be specified using unquoted strings.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH EXPRESSION SYNTAX
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
The primary expression has one of the following forms:
|
|
Packit |
f0d170 |
.IP
|
|
Packit |
f0d170 |
.I field comparison-operator value
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.B \eregexp
|
|
Packit |
f0d170 |
.I string-or-regexp
|
|
Packit |
f0d170 |
.PP
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is either a string,
|
|
Packit |
f0d170 |
which specifies the first field with that name within the current audit record,
|
|
Packit |
f0d170 |
or the
|
|
Packit |
f0d170 |
.B \e
|
|
Packit |
f0d170 |
escape character followed by a string,
|
|
Packit |
f0d170 |
which specifies a virtual field with the specified name
|
|
Packit |
f0d170 |
(virtual fields are defined in a later section).
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is a string.
|
|
Packit |
f0d170 |
.I operator
|
|
Packit |
f0d170 |
specifies the comparison to perform
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B r= r!=
|
|
Packit |
f0d170 |
Get the "raw" string of \fIfield\fR,
|
|
Packit |
f0d170 |
and compare it to \fIvalue\fR.
|
|
Packit |
f0d170 |
For fields in audit records,
|
|
Packit |
f0d170 |
the "raw" string is the exact string stored in the audit record
|
|
Packit |
f0d170 |
(with all escaping and unprintable character encoding left alone);
|
|
Packit |
f0d170 |
applications can read the "raw" string using
|
|
Packit |
f0d170 |
.BR auparse_get_field_str (3).
|
|
Packit |
f0d170 |
Each virtual field may define a "raw" string.
|
|
Packit |
f0d170 |
If
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is not present or does not define a "raw" string,
|
|
Packit |
f0d170 |
the result of the comparison is
|
|
Packit |
f0d170 |
.B false
|
|
Packit |
f0d170 |
(regardless of the operator).
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B i= i!=
|
|
Packit |
f0d170 |
Get the "interpreted" string of \fIfield\fR,
|
|
Packit |
f0d170 |
and compare it to \fIvalue\fR.
|
|
Packit |
f0d170 |
For fields in audit records,
|
|
Packit |
f0d170 |
the "interpreted" string is an "user-readable" interpretation of the field
|
|
Packit |
f0d170 |
value;
|
|
Packit |
f0d170 |
applications can read the "interpreted" string using
|
|
Packit |
f0d170 |
.BR auparse_interpret_field (3).
|
|
Packit |
f0d170 |
Each virtual field may define an "interpreted" string.
|
|
Packit |
f0d170 |
If
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is not present or does not define an "interpreted" string,
|
|
Packit |
f0d170 |
the result of the comparison is
|
|
Packit |
f0d170 |
.B false
|
|
Packit |
f0d170 |
(regardless of the operator).
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B < <= == > >= !==
|
|
Packit |
f0d170 |
Evaluate the "value" of \fIfield\fR, and compare it to \fIvalue\fR.
|
|
Packit |
f0d170 |
A "value" may be defined for any field or virtual field,
|
|
Packit |
f0d170 |
but no "value" is currently defined for any audit record field.
|
|
Packit |
f0d170 |
The rules of parsing \fIvalue\fR for comparing it with the "value" of
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
are specific for each \fIfield\fR.
|
|
Packit |
f0d170 |
If
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is not present,
|
|
Packit |
f0d170 |
the result of the comparison is
|
|
Packit |
f0d170 |
.B false
|
|
Packit |
f0d170 |
(regardless of the operator).
|
|
Packit |
f0d170 |
If
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
does not define a "value", an error is reported when parsing the expression.
|
|
Packit |
f0d170 |
.PP
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
In the special case of
|
|
Packit |
f0d170 |
.B \eregexp
|
|
Packit |
f0d170 |
\fIregexp-or-string\fR,
|
|
Packit |
f0d170 |
the current audit record is taken as a string
|
|
Packit |
f0d170 |
(without interpreting field values),
|
|
Packit |
f0d170 |
and matched against \fIregexp-or-string\fR.
|
|
Packit |
f0d170 |
.I regexp-or-string
|
|
Packit |
f0d170 |
is an extended regular expression, using a string or regexp token
|
|
Packit |
f0d170 |
(in other words, delimited by
|
|
Packit |
f0d170 |
.B \(dq
|
|
Packit |
f0d170 |
or \fB/\fR).
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
If
|
|
Packit |
f0d170 |
.I E1
|
|
Packit |
f0d170 |
and
|
|
Packit |
f0d170 |
.I E2
|
|
Packit |
f0d170 |
are valid expressions,
|
|
Packit |
f0d170 |
then
|
|
Packit |
f0d170 |
.B !
|
|
Packit |
f0d170 |
\fIE1\fR,
|
|
Packit |
f0d170 |
.I E1
|
|
Packit |
f0d170 |
.B &&
|
|
Packit |
f0d170 |
\fIE2\fR, and
|
|
Packit |
f0d170 |
.I E1
|
|
Packit |
f0d170 |
.B ||
|
|
Packit |
f0d170 |
.I E2
|
|
Packit |
f0d170 |
are valid expressions as well, with the usual C semantics and evaluation
|
|
Packit |
f0d170 |
priorities.
|
|
Packit |
f0d170 |
Note that
|
|
Packit |
f0d170 |
.B !
|
|
Packit |
f0d170 |
.I field op value
|
|
Packit |
f0d170 |
is interpreted as \fB!(\fIfield op value\fB)\fR, not as
|
|
Packit |
f0d170 |
\fB(!\fIfield\fB)\fI op value\fR.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH VIRTUAL FIELDS
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
The following virtual fields are defined:
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B \etimestamp
|
|
Packit |
f0d170 |
The value is the timestamp of the current event.
|
|
Packit |
f0d170 |
.I value
|
|
Packit |
f0d170 |
must be formatted as:
|
|
Packit |
f0d170 |
.sp
|
|
Packit |
f0d170 |
.in +5
|
|
Packit |
f0d170 |
.nf
|
|
Packit |
f0d170 |
.na
|
|
Packit |
f0d170 |
ts:seconds.milli
|
|
Packit |
f0d170 |
.ad
|
|
Packit |
f0d170 |
.fi
|
|
Packit |
f0d170 |
.in -5
|
|
Packit |
f0d170 |
.sp
|
|
Packit |
f0d170 |
where
|
|
Packit |
f0d170 |
.I seconds
|
|
Packit |
f0d170 |
and
|
|
Packit |
f0d170 |
.I milli
|
|
Packit |
f0d170 |
are decimal numbers specifying the seconds and milliseconds part of the
|
|
Packit |
f0d170 |
timestamp, respectively.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B \etimestamp_ex
|
|
Packit |
f0d170 |
This is similar to
|
|
Packit |
f0d170 |
.B \etimestamp
|
|
Packit |
f0d170 |
but also includes the event's serial number.
|
|
Packit |
f0d170 |
.I value
|
|
Packit |
f0d170 |
must be formatted as:
|
|
Packit |
f0d170 |
.sp
|
|
Packit |
f0d170 |
.in +5
|
|
Packit |
f0d170 |
.nf
|
|
Packit |
f0d170 |
.na
|
|
Packit |
f0d170 |
ts:seconds.milli:serial
|
|
Packit |
f0d170 |
.ad
|
|
Packit |
f0d170 |
.fi
|
|
Packit |
f0d170 |
.in -5
|
|
Packit |
f0d170 |
.sp
|
|
Packit |
f0d170 |
where
|
|
Packit |
f0d170 |
.I serial
|
|
Packit |
f0d170 |
is a decimal number specifying the event's serial number.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.TP
|
|
Packit |
f0d170 |
.B \erecord_type
|
|
Packit |
f0d170 |
The value is the type of the current record.
|
|
Packit |
f0d170 |
.I value
|
|
Packit |
f0d170 |
is either the record type name, or a decimal number specifying the type.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH SEMANTICS
|
|
Packit |
f0d170 |
The expression as a whole applies to a single record.
|
|
Packit |
f0d170 |
The expression is
|
|
Packit |
f0d170 |
.B true
|
|
Packit |
f0d170 |
for a specified event if it is
|
|
Packit |
f0d170 |
.B true
|
|
Packit |
f0d170 |
for any record associated with the event.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH EXAMPLES
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
As a demonstration of the semantics of handling missing fields, the following
|
|
Packit |
f0d170 |
expression is
|
|
Packit |
f0d170 |
.B true
|
|
Packit |
f0d170 |
if
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is present:
|
|
Packit |
f0d170 |
.IP
|
|
Packit |
f0d170 |
.B (\fIfield\fB r= \(dq\(dq) || (\fIfield\fB r!= \(dq\(dq)
|
|
Packit |
f0d170 |
.PP
|
|
Packit |
f0d170 |
and the same expression surrounded by
|
|
Packit |
f0d170 |
.B !(
|
|
Packit |
f0d170 |
and
|
|
Packit |
f0d170 |
.B )
|
|
Packit |
f0d170 |
is
|
|
Packit |
f0d170 |
.B true
|
|
Packit |
f0d170 |
if
|
|
Packit |
f0d170 |
.I field
|
|
Packit |
f0d170 |
is not present.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH FUTURE DIRECTIONS
|
|
Packit |
f0d170 |
New escape sequences for quoted strings may be defined.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
For currently defined virtual fields that do not define a "raw" or
|
|
Packit |
f0d170 |
"interpreted" string, the definition may be added.
|
|
Packit |
f0d170 |
Therefore, don't rely on the fact
|
|
Packit |
f0d170 |
that comparing the "raw" or "interpreted" string of the field with any value
|
|
Packit |
f0d170 |
is \fBfalse\fR.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
New formats of value constants for the
|
|
Packit |
f0d170 |
.B \etimestamp
|
|
Packit |
f0d170 |
virtual field may be added.
|
|
Packit |
f0d170 |
|
|
Packit |
f0d170 |
.SH AUTHOR
|
|
Packit |
f0d170 |
Miloslav Trmac
|