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
120              have the ts:seconds.milli format, where seconds  and  milli  are
121              decimal  numbers specifying the seconds and milliseconds part of
122              the timestamp, respectively.
123
124
125       \record_type
126              The value is the type of the current record.   value  is  either
127              the record type name, or a decimal number specifying the type.
128
129

SEMANTICS

131       The  expression  as a whole applies to a single record.  The expression
132       is true for a specified event if it is true for any  record  associated
133       with the event.
134
135

EXAMPLES

137       As  a  demonstration  of  the semantics of handling missing fields, the
138       following expression is true if field is present:
139
140              (field r= "") || (field r!= "")
141
142       and the same expression surrounded by !( and ) is true if field is  not
143       present.
144
145

FUTURE DIRECTIONS

147       New escape sequences for quoted strings may be defined.
148
149       For  currently  defined  virtual  fields  that do not define a "raw" or
150       "interpreted" string, the definition may be  added.   Therefore,  don't
151       rely  on  the  fact that comparing the "raw" or "interpreted" string of
152       the field with any value is false.
153
154       New formats of value constants for the \timestamp virtual field may  be
155       added.
156
157

AUTHOR

159       Miloslav Trmac
160
161
162
163Red Hat                            Feb 2008             AUSEARCH-EXPRESSION(5)
Impressum