docs/ausearch-expression.5

   1 .TH "AUSEARCH-EXPRESSION" "5" "Feb 2008" "Red Hat" "Linux Audit"
   2 .SH NAME
   3 ausearch-expression \- audit search expression format
   4
   5 .SH OVERVIEW
   6 This man page describes the format of "ausearch expressions".
   7 Parsing and evaluation of these expressions is provided by libauparse
   8 and is common to applications that use this library.
   9
  10 .SH LEXICAL STRUCTURE
  11
  12 White space (ASCII space, tab and new-line characters) between tokens is
  13 ignored.
  14 The following tokens are recognized:
  15
  16 .TP
  17 Punctuation
  18 .B ( ) \e
  19
  20 .TP
  21 Logical operators
  22 .B ! && ||
  23
  24 .TP
  25 Comparison operators
  26 .B < <= == > >= !== i= i!= r= r!=
  27
  28 .TP
  29 Unquoted strings
  30 Any non-empty sequence of ASCII letters, digits, and the
  31 .B _
  32 symbol.
  33
  34 .TP
  35 Quoted strings
  36 A sequence of characters surrounded by the
  37 .B \(dq
  38 quotes.
  39 The
  40 .B \e
  41 character starts an escape sequence.
  42 The only defined escape sequences are
  43 .B \e\e
  44 and \fB\e\(dq\fR.
  45 The semantics of other escape sequences is undefined.
  46
  47 .TP
  48 Regexps
  49 A sequence of characters surrounded by the
  50 .B /
  51 characters.
  52 The
  53 .B \e
  54 character starts an escape sequence.
  55 The only defined escape sequences are
  56 .B \e\e
  57 and \fB\e/\fR.
  58 The semantics of other escape sequences is undefined.
  59
  60 .PP
  61 Anywhere an unquoted string is valid, a quoted string is valid as well,
  62 and vice versa.
  63 In particular, field names may be specified using quoted strings,
  64 and field values may be specified using unquoted strings.
  65
  66 .SH EXPRESSION SYNTAX
  67
  68 The primary expression has one of the following forms:
  69 .IP
  70 .I field comparison-operator value
  71
  72 .B \eregexp
  73 .I string-or-regexp
  74 .PP
  75
  76 .I field
  77 is either a string,
  78 which specifies the first field with that name within the current audit record,
  79 or the
  80 .B \e
  81 escape character followed by a string,
  82 which specifies a virtual field with the specified name
  83 (virtual fields are defined in a later section).
  84
  85 .I field
  86 is a string.
  87 .I operator
  88 specifies the comparison to perform
  89
  90 .TP
  91 .B r= r!=
  92 Get the "raw" string of \fIfield\fR,
  93 and compare it to \fIvalue\fR.
  94 For fields in audit records,
  95 the "raw" string is the exact string stored in the audit record
  96 (with all escaping and unprintable character encoding left alone);
  97 applications can read the "raw" string using
  98 .BR auparse_get_field_str (3).
  99 Each virtual field may define a "raw" string.
 100 If
 101 .I field
 102 is not present or does not define a "raw" string,
 103 the result of the comparison is
 104 .B false
 105 (regardless of the operator).
 106
 107 .TP
 108 .B i= i!=
 109 Get the "interpreted" string of \fIfield\fR,
 110 and compare it to \fIvalue\fR.
 111 For fields in audit records,
 112 the "interpreted" string is an "user-readable" interpretation of the field
 113 value;
 114 applications can read the "interpreted" string using
 115 .BR auparse_interpret_field (3).
 116 Each virtual field may define an "interpreted" string.
 117 If
 118 .I field
 119 is not present or does not define an "interpreted" string,
 120 the result of the comparison is
 121 .B false
 122 (regardless of the operator).
 123
 124 .TP
 125 .B < <= == > >= !==
 126 Evaluate the "value" of \fIfield\fR, and compare it to \fIvalue\fR.
 127 A "value" may be defined for any field or virtual field,
 128 but no "value" is currently defined for any audit record field.
 129 The rules of parsing \fIvalue\fR for comparing it with the "value" of
 130 .I field
 131 are specific for each \fIfield\fR.
 132 If
 133 .I field
 134 is not present,
 135 the result of the comparison is
 136 .B false
 137 (regardless of the operator).
 138 If
 139 .I field
 140 does not define a "value", an error is reported when parsing the expression.
 141 .PP
 142
 143 In the special case of
 144 .B \eregexp
 145 \fIregexp-or-string\fR,
 146 the current audit record is taken as a string
 147 (without interpreting field values),
 148 and matched against \fIregexp-or-string\fR.
 149 .I regexp-or-string
 150 is an extended regular expression, using a string or regexp token
 151 (in other words, delimited by
 152 .B \(dq
 153 or \fB/\fR).
 154
 155 If
 156 .I E1
 157 and
 158 .I E2
 159 are valid expressions,
 160 then
 161 .B !
 162 \fIE1\fR,
 163 .I E1
 164 .B &&
 165 \fIE2\fR, and
 166 .I E1
 167 .B ||
 168 .I E2
 169 are valid expressions as well, with the usual C semantics and evaluation
 170 priorities.
 171 Note that
 172 .B !
 173 .I field op value
 174 is interpreted as \fB!(\fIfield op value\fB)\fR, not as
 175 \fB(!\fIfield\fB)\fI op value\fR.
 176
 177 .SH VIRTUAL FIELDS
 178
 179 The following virtual fields are defined:
 180
 181 .TP
 182 .B \etimestamp
 183 The value is the timestamp of the current event.
 184 .I value
 185 must have the \fBts:\fIseconds\fR.\fImilli\fR format, where
 186 .I seconds
 187 and
 188 .I milli
 189 are decimal numbers specifying the seconds and milliseconds part of the
 190 timestamp, respectively.
 191
 192 .TP
 193 .B \erecord_type
 194 The value is the type of the current record.
 195 .I value
 196 is either the record type name, or a decimal number specifying the type.
 197
 198 .SH SEMANTICS
 199 The expression as a whole applies to a single record.
 200 The expression is
 201 .B true
 202 for a specified event if it is
 203 .B true
 204 for any record associated with the event.
 205
 206 .SH EXAMPLES
 207
 208 As a demonstration of the semantics of handling missing fields, the following
 209 expression is
 210 .B true
 211 if
 212 .I field
 213 is present:
 214 .IP
 215 .B (\fIfield\fB r= \(dq\(dq) || (\fIfield\fB r!= \(dq\(dq)
 216 .PP
 217 and the same expression surrounded by
 218 .B !(
 219 and
 220 .B )
 221 is
 222 .B true
 223 if
 224 .I field
 225 is not present.
 226
 227 .SH FUTURE DIRECTIONS
 228 New escape sequences for quoted strings may be defined.
 229
 230 For currently defined virtual fields that do not define a "raw" or
 231 "interpreted" string, the definition may be added.
 232 Therefore, don't rely on the fact
 233 that comparing the "raw" or "interpreted" string of the field with any value
 234 is \fBfalse\fR.
 235
 236 New formats of value constants for the
 237 .B \etimestamp
 238 virtual field may be added.
 239
 240 .SH AUTHOR
 241 Miloslav Trmac