AUSEARCH-EXPRESSION(5)

💖 NAME 💖

ausearch-expression — it's the audit search expression format, bestie. that's the whole thing. this page is section 5 of the manual and it's giving format spec, and we're obsessed. 💅

✨ OVERVIEW ✨

okay so real talk: this page describes the format of "ausearch expressions". the parsing AND the evaluation of these expressions? that's all provided by libauparse, and it's common to every application that uses this library. so like, learn it once, use it everywhere. no cap. 🦋

🔤 LEXICAL STRUCTURE 🔤

white space between tokens is ignored — and when we say white space we mean ASCII space, tab, and new-line characters. the tokens you're gonna see are these:

• Punctuation — literally just these three: (, ), \
• Logical operators — !, &&, ||
• Comparison operators — <, <=, ==, >, >=, !==, i=, i!=, r=, r!=
• Unquoted strings — any non-empty sequence of ASCII letters, digits, and the _ symbol. simple. cute. effective. 🎀
• Quoted strings — a sequence of characters surrounded by the " quotes. the \ character starts an escape sequence. the only defined escape sequences are \\ and \". the semantics of other escape sequences is undefined — so like, don't, bestie. 🙈
• Regexps — a sequence of characters surrounded by the / characters. the \ character starts an escape sequence here too. the only defined escape sequences are \\ and \/. and yeah, the semantics of other escape sequences is undefined again. 💀

and here's the iconic part: anywhere an unquoted string is valid, a quoted string is valid as well, and vice versa. in particular, field names may be specified using quoted strings, and field values may be specified using unquoted strings. mix and match, it's your world. 🌈

🧠 EXPRESSION SYNTAX 🧠

so the primary expression has one of these two forms, periodt:

field comparison-operator value

\regexp string-or-regexp

now let's break it down, because the way that this works is lowkey elegant:

field is either a string, which specifies the first field with that name within the current audit record, OR it's the \ escape character followed by a string, which specifies a virtual field with the specified name (virtual fields get defined in a later section, stay tuned ✨).

field is a string. operator specifies the comparison to perform. okay? okay. 🫶

now the operators, one by one:

• r=, r!= — get the "raw" string of field, and compare it to value. for fields in audit records, the "raw" string is the exact string stored in the audit record (with all escaping and unprintable character encoding left alone); applications can read the "raw" string using auparse_get_field_str(3). each virtual field may define a "raw" string. and if field is not present or does not define a "raw" string, the result of the comparison is false — regardless of the operator. so like, false no matter what, even for r!=. noted. 💅
• i=, i!= — get the "interpreted" string of field, and compare it to value. for fields in audit records, the "interpreted" string is a "user-readable" interpretation of the field value; applications can read the "interpreted" string using auparse_interpret_field(3). each virtual field may define an "interpreted" string. if field is not present or does not define an "interpreted" string, the result of the comparison is false — regardless of the operator. same energy as above, different string. 🦋
• <, <=, ==, >, >=, !== — evaluate the "value" of field, and compare it to value. a "value" may be defined for any field or virtual field, but no "value" is currently defined for any audit record field. the rules of parsing value for comparing it with the "value" of field are specific for each field. if field is not present, the result of the comparison is false — regardless of the operator. and if field does not define a "value", an error is reported when parsing the expression. so that's a hard no, not a quiet false. 😭

now for the special case of \regexp regexp-or-string: the current audit record is taken as a string (without interpreting field values), and matched against regexp-or-string. and regexp-or-string is an extended regular expression, using a string or regexp token — in other words, delimited by " or /. 🌸

and if E1 and E2 are valid expressions, then ! E1, E1 && E2, and E1 || E2 are valid expressions as well, with the usual C semantics and evaluation priorities. one thing though, don't get it twisted: ! field op value is interpreted as !(field op value), not as (!field) op value. 🫶

🦋 VIRTUAL FIELDS 🦋

here's the roster of virtual fields, and honestly, they ate:

• \timestamp — the value is the timestamp of the current event. value must be formatted as:

ts:seconds.milli

where seconds and milli are decimal numbers specifying the seconds and milliseconds part of the timestamp, respectively. ⭐

• \timestamp_ex — this is similar to \timestamp but also includes the event's serial number. value must be formatted as:

ts:seconds.milli:serial

where serial is a decimal number specifying the event's serial number. 👑

• \record_type — the value is the type of the current record. value is either the record type name, or a decimal number specifying the type. 🌈

💅 SEMANTICS 💅

the expression as a whole applies to a single record. and the expression is true for a specified event if it is true for any record associated with the event. so like, one match and the whole event is a yes. main character energy, fr fr. 🔥

🌈 EXAMPLES 🌈

as a demonstration of the semantics of handling missing fields — which, lowkey, is the whole point — the following expression is true if field is present:

(field r= "") || (field r!= "")

and the same expression surrounded by !( and ) is true if field is not present. 😌

🔮 FUTURE DIRECTIONS 🔮

some things may change, so keep your eyes open, bestie:

• new escape sequences for quoted strings may be defined.
• for currently defined virtual fields that do not define a "raw" or "interpreted" string, the definition may be added. therefore, don't rely on the fact that comparing the "raw" or "interpreted" string of the field with any value is false. seriously. that's a trap. 💀
• new formats of value constants for the \timestamp virtual field may be added.

👑 AUTHOR 👑

Miloslav Trmac 💖

so that's the whole page, bestie — authored by Miloslav Trmac, brought to you by Red Hat, dated Feb 2008. this was AUSEARCH-EXPRESSION(5) and honestly? iconic. go write some expressions. slay. 💅✨🎀