1AUSEARCH-EXPRESSION(5)            Linux Audit           AUSEARCH-EXPRESSION(5)
2
3
4

NAME

6       ausearch-expression - audit search expression format
7
8

OVERVIEW

10       This  man page describes the format of "ausearch expressions".  Parsing
11       and evaluation of these expressions is provided by  libauparse  and  is
12       common to applications that use this library.
13
14

LEXICAL STRUCTURE

16       White  space  (ASCII space, tab and new-line characters) between tokens
17       is ignored.  The following tokens are recognized:
18
19
20       Punctuation
21              ( ) \
22
23
24       Logical operators
25              ! && ||
26
27
28       Comparison operators
29              < <= == > >= !== i= i!= r= r!=
30
31
32       Unquoted strings
33              Any non-empty sequence of ASCII letters, digits, and the _  sym‐
34              bol.
35
36
37       Quoted strings
38              A  sequence  of  characters  surrounded  by the " quotes.  The \
39              character starts an escape sequence.  The  only  defined  escape
40              sequences  are  \\  and  \".   The  semantics  of  other  escape
41              sequences is undefined.
42
43
44       Regexps
45              A sequence of characters surrounded by the / characters.  The  \
46              character  starts  an  escape sequence.  The only defined escape
47              sequences  are  \\  and  \/.   The  semantics  of  other  escape
48              sequences is undefined.
49
50
51       Anywhere an unquoted string is valid, a quoted string is valid as well,
52       and vice versa.  In particular, field  names  may  be  specified  using
53       quoted  strings,  and  field  values  may  be  specified using unquoted
54       strings.
55
56

EXPRESSION SYNTAX

58       The primary expression has one of the following forms:
59
60              field comparison-operator value
61
62              \regexp string-or-regexp
63
64       field is either a string, which specifies the  first  field  with  that
65       name  within  the  current audit record, or the \ escape character fol‐
66       lowed by a string, which specifies a virtual field with  the  specified
67       name (virtual fields are defined in a later section).
68
69       field is a string.  operator specifies the comparison to perform
70
71
72       r= r!= Get  the  "raw"  string  of field, and compare it to value.  For
73              fields in audit records, the "raw" string is  the  exact  string
74              stored  in  the  audit record (with all escaping and unprintable
75              character encoding left alone); applications can read the  "raw"
76              string  using  auparse_get_field_str(3).  Each virtual field may
77              define a "raw" string.  If field is  not  present  or  does  not
78              define  a  "raw"  string,  the result of the comparison is false
79              (regardless of the operator).
80
81
82       i= i!= Get the "interpreted" string of field, and compare it to  value.
83              For  fields  in  audit  records,  the "interpreted" string is an
84              "user-readable" interpretation of the field value;  applications
85              can   read   the   "interpreted"   string  using  auparse_inter‐
86              pret_field(3).  Each virtual field may define  an  "interpreted"
87              string.   If  field is not present or does not define an "inter‐
88              preted" string, the result of the comparison is  false  (regard‐
89              less of the operator).
90
91
92       < <= == > >= !==
93              Evaluate  the  "value"  of  field,  and  compare it to value.  A
94              "value" may be defined for any field or virtual  field,  but  no
95              "value"  is  currently  defined for any audit record field.  The
96              rules of parsing value for comparing  it  with  the  "value"  of
97              field are specific for each field.  If field is not present, the
98              result of the comparison is false (regardless of the  operator).
99              If  field  does  not define a "value", an error is reported when
100              parsing the expression.
101
102       In the special case of  \regexp  regexp-or-string,  the  current  audit
103       record  is  taken  as a string (without interpreting field values), and
104       matched against regexp-or-string.  regexp-or-string is an extended reg‐
105       ular expression, using a string or regexp token (in other words, delim‐
106       ited by " or /).
107
108       If E1 and E2 are valid expressions, then !  E1, E1 && E2, and E1 ||  E2
109       are  valid  expressions as well, with the usual C semantics and evalua‐
110       tion priorities.  Note that !  field op value is interpreted as !(field
111       op value), not as (!field) op value.
112
113

VIRTUAL FIELDS

115       The following virtual fields are defined:
116
117
118       \timestamp
119              The  value is the timestamp of the current event.  value must be
120              formatted as:
121
122                   ts:seconds.milli
123
124              where seconds and milli are decimal numbers specifying the  sec‐
125              onds and milliseconds part of the timestamp, respectively.
126
127
128       \timestamp_ex
129              This  is  similar  to  \timestamp  but also includes the event's
130              serial number.  value must be formatted as:
131
132                   ts:seconds.milli:serial
133
134              where serial is a decimal number specifying the  event's  serial
135              number.
136
137
138       \record_type
139              The  value  is  the type of the current record.  value is either
140              the record type name, or a decimal number specifying the type.
141
142

SEMANTICS

144       The expression as a whole applies to a single record.   The  expression
145       is  true  for a specified event if it is true for any record associated
146       with the event.
147
148

EXAMPLES

150       As a demonstration of the semantics of  handling  missing  fields,  the
151       following expression is true if field is present:
152
153              (field r= "") || (field r!= "")
154
155       and  the same expression surrounded by !( and ) is true if field is not
156       present.
157
158

FUTURE DIRECTIONS

160       New escape sequences for quoted strings may be defined.
161
162       For currently defined virtual fields that do  not  define  a  "raw"  or
163       "interpreted"  string,  the  definition may be added.  Therefore, don't
164       rely on the fact that comparing the "raw" or  "interpreted"  string  of
165       the field with any value is false.
166
167       New  formats of value constants for the \timestamp virtual field may be
168       added.
169
170

AUTHOR

172       Miloslav Trmac
173
174
175
176Red Hat                            Feb 2008             AUSEARCH-EXPRESSION(5)
Impressum