Query Syntax

Query Language Overview

A powerful query language lets you show only selected records from the log files, according to your criteria. You can create complex queries by using Boolean operators, wildcards, fields, and ranges. This section is a detailed reference to the query language.

When you use the GUI to create a query, the applicable criteria show in the Query Definition field.

The basic query syntax is [<Field>:] <Filter Criterion>.

You can put together many criteria in one query by using Boolean operators:

[<Field>:] <Filter Criterion> AND|OR|NOT [<Field>:] <Filter Criterion> ...

Most query keywords and filter criteria are not case sensitive, but there are some exceptions. For example, Risk:High is case sensitive (Risk:high will not match). If your query results do not show the expected results, change the case of your query criteria or try both upper and lower case.

Note: When you use queries with more than one criteria value, you must explicitly enter a Boolean operator.

Criteria Values

Criteria values are written as one or more text strings. You can enter one text string, such as a word, IP address or URL, without delimiters. Phrases or text strings that contain more than one word must be surrounded by apostrophes or quotation marks.

One character string examples:

• richard
• inbound
• 192.0.2.1
• mahler.ts.example.com
• dns_udp

Phrase examples

• 'John Doe'
• 'log out'
• 'VPN-1 Embedded Connector

  Note - You cannot put numbers or IP addresses in quotation marks. For example, 'John 1234' is invalid.

IP Addresses

IPv4 and IPv6 addresses used in SmartLog queries are counted as one word. You can enter IPv4 address using dotted decimal or CIDR notation. IPv6 addresses are typically entered using CIDR notation.

You can also use the '*' wildcard character with IPv6 addresses.

Examples:

• 20.20.20.1
• 10.0.0.0/24
• 2001:0db8::61:1/32
• 2001:0db8::*

IP Address Ranges

You can use IPv4 and IPv6 address ranges in free text queries or with the source and destination fields. Enter the range criteria using this notation: <starting IP address>-<ending IP address>

The query shows all IP addresses in the range, and includes the starting and ending addresses.

Examples:

• 192.0.2.0-192.0.2.255
• 2001:0db8::64:1-2001:0db8::64:199

Numeric Ranges

You can use ranges for numeric values in free text and numeric field queries, such as the port fields.

Syntax

<Number>-<Number>

Examples

• 65000-66000
• port:80-660

Null Values

You can use null (empty) values with field keywords in SmartLog queries with one of these syntax options:

• <field> ""
• <field> []

You can also use the Boolean NOT operator to return fields that are not null:

• NOT <field> ""
• NOT <field> []

Null value queries only work with fields contained in the field keywords table.

Wildcards

You can use the standard wildcard characters (* and ?) in queries to match variable characters or strings in log records. The wildcard character cannot be the first character in a query criterion. You can use more than wildcard character in query criteria.

Wildcard syntax

• The ? (question mark) matches one character.
• The * (asterisk) matches a character string.

Examples:

• Jo* shows John, Jon, Joseph, Joshua, John Paul, and so on.
• Jo? shows Joe and Jon, but not Joseph.

If your criteria value contains more than one word, you can use the wildcard in each word. For example, 'Jo* N*' shows Joe North, John Natt, Joshua Named, and so on.

Using Wildcards with IP Addresses

The wildcard character is useful when used with IPv4 addresses. It is a best practice to put the wildcard character after an IP address delimiter.

Examples:

• 192.168.2.* shows all records for 192.168.2.0 to 192.168.2.255 inclusive
• 192.168.* shows all records for 192.168.0.0 to 192.168.255.255 inclusive

Field Keywords

You can use predefined field names, followed by a colon, as keywords in filter criteria. SmartLog only shows log records that match the criteria in the specified field. If you do not use field names, SmartLog shows records that contain the criteria in all fields.

This table shows the predefined field keywords. Some fields also support keyword aliases that you can type as alternatives to the primary keyword.

The syntax for a field name query is: <field name>:<values>

• <field name> - One of the predefined field names
• <values> - One or more filter criteria

When using the Rule field as a criterion, you must specify rule number or rule UID together as one string. This is the syntax for this special case:

rule:<rule number or rule UID>/<policy name>

Examples:

• source:192.0.2.1
• rule:2/my_policy
• action:(drop or reject or block)

  You can use the OR Boolean operator in parentheses to include multiple criteria values.

Notes:

• When using fields with multiple criteria values, you must explicitly write the Boolean operator. SmartLog does not automatically presume the AND operator if it is not specified.
• You must use parentheses when using multiple criteria with fields.

Boolean Operators

You can use the Boolean operators AND, OR, and NOT to create filters with many different criteria. You can put multiple Boolean expressions in parentheses.

If you enter more than one criteria without a Boolean operator, the AND operator is implied. When using multiple criteria without parentheses, the OR operator is applied before the AND operator.

Examples:

• blade:"application control" AND action:block - Shows log records from the Application Control and URL Filtering Software Blade where traffic was blocked.
• 192.0.2.133 10.19.136.101 - Includes log entries that match the two IP addresses. The AND operator is presumed.
• 192.0.2.133 OR 10.19.136.101 - Includes log entries the match one of the IP addresses.
• (blade:Firewall or blade:IPS or blade:VPN) AND NOT action:drop - Includes all log entries from the Firewall, IPS or VPN blades that are not dropped. The criteria in the parentheses are applied before the AND NOT criterion.
• Source:(192.0.2.1 OR 192.0.2.2) AND destination:17.168.8.2 - Includes log entries from the two source IP addresses if the destination IP address is 17.168.8.2. This example also shows how you can use Boolean operators with field criteria.

Notes:

• Boolean operators are not case sensitive.

Date and Time Queries

You can define a query that shows logs generated during the preceding period of time using the last or past keywords. The applicable periods of time are:

• minute
• hour
• day
• week
• month
• year

The syntax for this criterion is:

last|past [<number>] <period of time>

You can specify the period of time in the singular or the plural. If you do not enter a number, the value is presumed to be the most recent period.

Examples

• last 12 hours - Shows logs generated during the last 12 hours.
• past 10 week - Shows logs generated during the last 10 weeks. Using the singular is permitted.
• last year - Shows logs generated

Preceding Time Period Queries

You can define a query that shows logs generated during the preceding period of time using the last or past keyword.

Preceding period of time queries show log records based on the time that you run the query. For example, if your criterion is 'last 2 weeks' at 3:15 PM, SmartLog shows all logs starting from 3:15 on the 14th day before today. A log generated at 1:15 PM on the 14th day does not show, but one generated at 6:50 does show.

The valid periods of time are:

• minute
• hour
• day
• week
• month
• year

The syntax is:

last|past [<number>] <period of time>

Examples

• last 12 hours - Shows logs generated during the last 12 hours before the most recent time.
• past 10 week - Shows logs generated during the last 10 weeks before the most recent date and time. This example shows that you can use the singular or plural interchangeably.
• last year - Shows logs generated during the last 365 days starting from the most recent date and time. This example shows that the default value (1) applies if no number value is entered.

Notes:

• You can specify the period of time in the singular or the plural.
• If you do not enter a <number> value, the number one is assumed.

From-To Queries

You can define queries that show log records between a starting date and time and an ending date and time. SmartLog shows records between and including the specified dates.

Syntax

dd/mmm/yyyy hh:mm:ss[-dd/mmm/yyyy hh:mm:ss]

• dd - Day of the month. The leading 0 is optional.
• mmm - Three character mnemonic for the month. This value is case insensitive.
• yyyy - Year (four digits are required).
• hh - Hour in 24 hour time notation. The leading 0 is optional.
• mm - Minutes. The leading 0 is optional.
• ss - Seconds. The leading 0 is optional.

Syntax Notes

• You can use the yesterday and today keywords as alternatives to the date parameter. You can use these with or without time values.
• The 'to' value is optional. If not specified, SmartLog shows all values on the specified 'from' value.
• The time value is optional. If no time is specified, SmartLog shows all records from 00:00 to 23:59 on the specified date.
• If you specify a time value, you must specify the hours and minutes. You can ignore the second values.
• The day and year values are optional. If you do not specify these values the most recent day and/or year is assumed.
• You can ignore the date value. Today is assumed.
• You must always specify the month value.
• You cannot use wildcards with dates and times.

Examples

• 1/mar/2012-5/mar/2012 - Shows all logs on and between these dates.
• 5/mar/2012 - Shows all logs for 5 March only.
• yesterday-today - Shows all logs from 00:00 yesterday to 23:59 today.
• 5/mar/2012 07:00-08:59 - Shows all logs from 7:00 on 5 March to 8:59 today. This example illustrates the fact that you can ignore the date value. Today is assumed.