| viewer9 documentation | Index Home |
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.