viewer9 documentation

Query Syntax

The query syntax in viewer9 is eclectic. Here are the basics to get you going.

A few examples

Show events with a Path equal to "hklm" (or "HKLM" because values are not case sensitive):

q Path=hklm

Show exes (not events) whose ExeName contains "smss" (uses the handy contains operator :):

q ExeName:smss

Show events whose process's ExeName contains "smss":

q ExeName:smss events

Show events where the Path has ".txt" extension using a wildcard:

q Path=*.txt

Show events with a ResultCode other than 0 (numbers can also be expressed in hex, and some have corresponding enumerated or formatted string values):

q ResultCode!=0

q ResultCode!=0x0

q ResultCode!=success

Show ReadFile events:

q Op=readfile

Show Registry events using Op which is the field for the operation name (knowing all registry operations happen to have "Reg" in their name):

q Op:reg

Show Registry events using the class (see PML Operations):

q class=Registry

q class:reg

Show exes where the description is an empty string:

q ExeDescrip=""

Show 64-bit modules containing wifi in their description:

q Mod64Bit=1 ModDescrip:wifi

Specify a numeric range (all criteria are ANDed, there is currently no OR logic):

q BufferSize>50 BufferSize<=200

Field names values and operators

There are about 200 fields that can be queried. They can be seen in all of the views displaying events, exes, processes, modules and captures, but also selected from a dropdown while entering queries. Except for events, field names usually have a prefix identifying the type of object for which they are a property: Exe Proc Mod Cap.

The comparison operators are = != : !: < > <= >=. Use no spaces around operators.

  • Correct:   q Path=hklm
  • Incorrect: q Path = hklm

A field's type affects how it's value is displayed and queried. Some are integer-only with default display in either decimal or hex, but many integers have corresponding string values consisting of enumerations, bit-flags, or other formatting. Dropdowns help in discovering field names, explain type, and aid in entering correct query syntax.

The contains and not contains operators (: !:) only work on string fields or the string form of an integer field, so they do no work with integer-only fields like CapEventCount.

Quoting values

Backslashes in a path are unaltered, and quotes are not required unless there is a space:

q Path=c:\temp\

q Path:"c:\program files"

A value must be quoted if it contains a space or curly brackets:

q RegAccessGranted="Maximum Allowed"

q Path:"{5e-094a}"

A value must also be quoted if it contains quotes, and the quotes are doubled up. So to show processes where the ProcCmdLine field contains /s"App:

q ProcCmdLine:"/s""App"

Enumerated and flag fields

Many fields like ResultCode and CreateOptions are enumerated or have bit-wise flags. They can be queried by either the underlying integer or the enumerations or flags which are treated as a string. The query results column will show the string representation (when available), though the tooltip will show the underlying integer. For example, if an event has a FileAccess field value of "Read Data/List Directory, Read Attributes, Synchronize" would be matched with both:

q FileAccess:sync

q FileAccess=0x00100081

Additional columns

Query results output always has default columns on the left and then columns for the fields queried. Querying non-SUCCESS ResultCode adds a column for the ResultCode:

q ResultCode!=success

However, with the = operator the column would be filled with the same value so no column is added:

q ResultCode=success

To add other columns to query results, specify field names without a comparison value. For example, show ResultCode for events with "windows" in their Path:

q ResultCode Path:windows

To show the ResultCode column even though it is always "SUCCESS":

q ResultCode=success ResultCode

Wildcards

The * (asterisk) character is used to match any text, including no text. It is allowed in string values with equals and contains operators (= != : !:). For example, hklm* will match "HKLM" alone and values starting with "HKLM". This example uses 2 wildcards:

q Path=C:\Users\*\Temp\*.txt

Use two asterisks ** to indicate a literal * asterisk not a wildcard. There is no way to indicate a literal asterisk immediately after a wildcard.

Existence

Many event fields are dynamic, meaning they may or may not exist for a given event. Even within a certain operation some fields are not always present, especially result fields. And parentproc is a dynamic process field.

An asterisk * alone is used to indicate whether or not the field exists.

Show events which do have a RegData field:

q RegData=*

Show events which do not have a RegData field:

q RegData!=*

Time field

To show events after a certain time using the full time string, it needs to be in this exact format because it is comparing it as a string:

q Time>"2018-01-29 19:56:14.6099922"

Time can also be queried with the LDAP/FILETIME 64-bit integer:

q Time>131617473746100335

Full time and corresponding LDAP/FILETIME integer are shown in the Time tooltip and, if you carefully move the mouse from the field into the tooltip, can be copied for use in a query.

Show events within a time range:

q Time>=131617473746100335 Time<=131617473746470701

Show all events which occurred during a particular second using the : (contains) operator:

q Time:"19:56:14"

See also

Posted 4 Jul 2022 last updated 8 Sep 2022   As viewer9 is just starting out, discussion is invited via email. Please send questions and comments to forum@viewer9.com directly. Threads that might be valuable to other users will be posted as part of the documentation. Posted messages will not include your address or your full name, and might be shortened for brevity.

Copyright 2022, bryantlite, Inc.