Skip navigation
All Places > Products > RSA NetWitness Platform > RSA NetWitness Platform Online Documentation > Documents
Log in to create and rate content, and to follow, bookmark, and share content with other members.

Investigate: Filter Results in the Events View

Document created by RSA Information Design and Development Employee on Mar 27, 2018Last modified by RSA Information Design and Development Employee on Jan 30, 2020
Version 7Show Document
  • View in full screen mode
 

Note: This section applies to version 11.1 and later.

You can filter events in the Events view using the query bar to select a service and time range and then query the service being investigated. Filtering events helps to narrow the focus of an investigation to a smaller, relevant set of events.

In Version 11.4, you can also use column groups to optimize the number or attributes (meta keys, meta groups, meta entities) you look at for a given event (see Use Columns and Column Groups in the Events List).

This figure illustrates the Query Bar with tools to filter results in the Events list.

an example of the Query Bar

When you go to Investigate > Events to open the Events view, the Query Profiles menu, the service and time range selectors, and the query builder field are displayed in the query bar.

  • The Query Profiles menu is available in Version 11.4 and later. You can encapsulate a query and a column group in a profile so that a useful combination of attributes is easily recalled and applied to a set of events in the Events list (see Use Query Profiles to Encapsulate Common Areas for Investigation.)

  • By default, the first service is automatically selected (unless you previously selected a service and the selected service is in browser cache). You can select a service as described in Begin an Investigation in the Events View
  • If you do not select a time range, the default time range (24 hours) is used.
  • The query builder field is an empty field to the right of the time range selector. This is where you build a query by creating filters. Clicking the submit query icon submits the query and sends a request to the selected service to load the data. In Version 11.3 and later, clicking the the query console icon (console icon) opens the query console, where detailed status of the query is provided.

When you go to the Events view from the Legacy Events view or the Navigate view, the service, time range, and any filters that were selected in the Legacy Events view or Navigate view are displayed in the query bar. The service, time range, and individual filters can be modified.

If a profile is selected in the Legacy Events view when you right-click or double-click an event and go to the Events view, the filters from the profile (preQuery) are added to the query builder field as an editable filter. The following figures show a preQuery in the Legacy Events view, and the same query added as the first filter in the Events view.
a  preQuery in the Events view

the preQuery added as a filter in the Event Analysis view

Query Builder Concepts

In the query builder, you can reduce the number of events to an interesting set by creating three types of filters: simple, free-form, or text.

The basic syntax for each filter is as follows: <meta key><operator><meta value>. Here is an example: direction = 'outbound'.

In Version 11.4, when you type or paste a query in the query bar, the text is parsed into individual filters separated by the AND operator if the parsing engine determines that AND is needed. Earlier versions use only the AND operator between filters, and the logical operator is not visible.

  • If you type action = 'get' action = 'put', the result is two filters separated by AND.
  • If you type action = 'get' OR action = 'put', the result is two filters separated by OR.

In Version 11.4, the parsing engine converts a longer string of text that you type or paste in the query bar into individual filters. Parts of the filter that are not parsable are converted to a free-form filter. In earlier versions, a long text string is added to the query bar as a single filter.

  • If you type, action = 'GET' OR action is 20 || action = 'PUT' in the query bar the Free-Form option is used. Part of this text cannot be parsed so the result is three filters separated by OR. You can also type text like this in Free-Form Mode.

  • Text filters (Version 11.4 and later) are text strings that do not contain spaces. You can search the data set for any exact match of indexed meta keys, not all meta keys. Here are some examples: failed, login, or attempt.

In the query builder, each filter becomes an editable field. Filters line up from left to right, representing the sequence in which the filters were created. As more filters are added and exceed the length of a single line, they wrap to another line and the input area expands vertically so that all filters are visible without scrolling to the right.

Successive versions of RSA NetWitness Platform 11 have more capability than the original 11.1 query bar, with Version 11.4 offering extensive help as you create a query.

Guided Mode vs. Free-Form Mode

In Guided Mode, you are guided with suggestions for auto-completion that show valid meta keys and operators, and suggested values in the filter entry form. In version 11.4, you can type, paste, choose a recent query, or select from the drop-down menu. Earlier versions do not support pasting text and recent queries. This is an example of the 11.4 filter entry form.

an example of the filter entry form in Version 11.4

As you create filters, the syntax of each filter is validated and invalid filters are marked by a red outline. If you hover the mouse over the filter, a message that explains the error is displayed.

In Version 11.3 and later, free-form filters are validated on the server side, which may take additional time. If you submit the query before the server has returned filter validation results, the the submit query icon is replaced by a spinner. When server validation returns, a query with no invalid filters begins execution. If the query contains an invalid filter, execution is terminated and the invalid filter is outlined in red. This is an example of an invalid query.

example of an invalid query after validation

In Free-Form Mode, you can type or paste a long text string. There is no auto-suggestion, and validation is performed on the server side when you submit the query. If an error is found, the query does not execute.

Note: The the submit query icon button has a different label in versions earlier than Version 11.3. It was previously named Query Events.

Clicking Guided Mode or Free-From Mode toggles between modes. If you selected Free-Form Mode the last time you logged in, this choice is stored in browser cache and is used until the browser cache is cleared.

  • When you switch from Guided Mode to Free-Form Mode, filters that you created in Guided Mode are transformed to a text query in the Free-Form field.
  • When you switch from Free-Form Mode to Guided Mode, the query you were typing is added to the query bar as individual simple filters, but it does not include auto-suggest options.

    Note: Before Version 11.3, a Free-Form filter could not be edited in Guided Mode.

The following figure is an example of the query bar with the Guided Mode query builder with several filters.

example of a query in the Guided Mode query builder

The following figure is an example of the Free-Form query builder in use.

example of the same query in the Free-Form query builder

Concepts for Editing Multiple Filters

As you work in the query builder, you can see when a filter has focus for editing (a green outline) and which filters are selected (blue background). This is useful because you can have multiple filters selected for right-click actions, but only one can be edited at a time. The figure below shows the green outline marking a filter that has focus and the blue background indicating that two filters are selected.

example of one filter in focus and two filters selected

This figure illustrates the same set of filters with all filters selected (blue background) and one filter that has focus (blue background and green outline).

example of one filter in focus and all three are selected

A right-click action from the drop-down menu applies to all selected filters as shown in this figure.

the right-click options for selected filters

These are a few basic concepts that explain how to work in the query builder:

  • You can select multiple filters, but only one can have focus and the last selected filter is the one with active focus at any point in time.
  • To select a filter and give it focus, click the filter. To deselect the filter and remove focus, click the filter again, press Esc, or click anywhere else on the page.
  • To add a filter, click before or after an existing filter. To create a new filter before or after the filter in focus, press the right or left arrow key.
  • To open a filter for editing, double-click the filter or click it and press Enter. To exit without saving changes and leave the filter in focus, press Esc.
  • To delete a filter, click the filter and press Delete or click X on the filter.

The Version 11.3 and Earlier Query Builder

In Version 11.1, the user interface guides you as you create and edit each simple filter: <meta key> <operator> <meta value> filter. The user interface supports only simple filters. If you open an event from the Legacy Events view or Navigate view and the filter has more than one operator, ||,&&, (), REGEX, or LENGTH, the filter is added, but editing is not supported in the Events view. Refer to the Investigate User Guide for NetWitness Platform 11.3 for details; it is available here in PDF form: Master Table of Contents for RSA NetWitness Platform Version 11.

In Version 11.2, the user interface has two modes: Guided Mode and Free-Form Mode. Guided Mode guides you as you create and edit each simple <meta key> <operator> <meta value> filter. The default mode is Guided Mode, which includes auto-suggest and validation options. You can enter a long text string in Free-Form Mode. In Free-Form Mode validation is performed when you run the query. Refer to the Investigate User Guide for NetWitness Platform 11.2 for details; it is available here in PDF form: Master Table of Contents for RSA NetWitness Platform Version 11.

In Version 11.3, the user interface has these added features:

  • When you go to the Events view from the Navigate or Events view, with a preQuery in effect for a profile, the preQuery that was displayed in the breadcrumb is available in the Events view query builder as an editable filter.
  • The auto-suggest options in the user interface are augmented with an Advanced Options section that allows for the creation of a free-form filter. Free-Form Mode is still useful for pasting an entire long text string.
  • You can cancel a query while it is executing.
  • You can view detailed status information about the query being executed in the query console.

The Version 11.4 Query Builder

You can type; select meta keys, operators, and values from the drop-down menus; or paste a filter in the query bar. Added 11.4 features in the Guided Mode filter entry form are described in detail below.

Meta Keys Cached for Faster Loading

When the Events view opens, meta keys from all connected services are cached for faster data loading. These meta keys are available in user interface elements that have auto-suggest meta keys. (When you are building a column group or profile, if you are expecting to see a meta key and it is not displayed, select the service where the key was added to force a cache update. This usually occurs only when a meta key is not added to all concentrators.)

Text Filter

You can create a text filter to find a text string in the data set. You can use a text filter with no knowledge of meta keys that would contain the values. One text filter per query is supported. A text filter looks through indexed meta keys, not all meta keys.

Pasting Text Instead of Typing

When creating a filter, you can paste a meta key or value in the filter entry form. When you paste text into the filter entry form instead of typing the text, the text is parsed appropriately to create one or more filters. Any portion of the text that cannot be parsed is converted to a free-form filter.

Use of Recent Queries

The filter entry form offers two methods of entering meta keys, operators, and values: the Meta tab and Recent Queries tab. The Meta tab is the same as the filter entry form for prior versions except that a count of matching results is given in the tab label and icons mark meta keys that are indexed by key, indexed by value, and not indexed. In the Recent Queries tab, up to 100 recent queries are displayed. The list is filtered as you type to show only queries that contain the typed text, and you can select a query from the list.

Use of Advanced Operators

Auto-suggest can parse the following advanced operators that you paste or type into the filter entry form: <, >, <=, >=, OR, ||, AND, &&, (), regex, and length. The text is parsed as multiple filters. For example, if you type or paste medium > 0 && medium <= 100, the text is parsed as two simple filters with an explicit AND operator: medium > 0 AND medium <= 100. If you type or paste bytes.src <= 5000 && medium = 1 || medium = 2 && bytes.src > 0, four simple filters are created with AND and OR operators separating them: bytes.src <= 5000 AND medium = 1 OR medium = 2 AND bytes.src > 0 to make as many valid filters as possible.
four filters in the query bar
This filter is an example of a filter in which it would be useful to add parentheses. You can select medium = 2 and bytes.src > 0, then right-click and select Wrap in Parentheses from the drop-down menu. Text filters are not supported inside parentheses.
the Wrap in parentheses option
The resulting query is bytes.src <= 5000 AND medium = 1 OR (medium = 2 AND bytes.src > 0).
the two filters wrapped in parentheses
If you encounter errors while creating filters, look for tooltip messages and check the documentation.

Easy Use of AND/OR Operators

When you type ||and &&, they are displayed as OR and AND in the query bar. You can change OR to AND and AND to OR by clicking the word. When you insert the cursor to add a filter, the AND operator is added before the cursor. When you delete a filter, orphaned OR and AND operators are removed. The operator for a text filter must be AND because text filters are always ANDed to a query.

Automatically Balanced Parentheses

When creating and editing filters in the query builder, parentheses pairs are automatically balanced as you type. If you type an open parenthesis in a filter that is open for editing or before a selected filter, the close parenthesis is added at the end of the filter. This works intuitively as you type so that you can add new filters on either side of the parenthesis and between parentheses when there are nested parentheses. Orphaned parentheses are automatically removed. If adding parentheses would create an invalid filter, the parentheses are not added. You can also right-click selected filters, and add parentheses using the Wrap in parentheses option. This option is only available when the result would be a valid filter.

Hints about Available Values

For properly indexed meta keys, the user interface provides hints about available values related to the time range of the query. Up to 100 suggested values are returned and, when you type text, the list of 100 values is filtered to include only relevant values. If no matching values are returned, a message advises "No suggestions found." (The suggested values are based solely on the time range; filters in the query do not filter the list of 100.)

CIDR Notation and Shorthand

When entering a value for an IP address in a filter, you can use CIDR notation to filter for addresses within a range.

The IPv4 CIDR block range is 0 to 32. For example 10.20.30.0/24 specifies 10.20.30.0 with a subnet mask of 255.255.255.0, which will match an IP in the range 10.20.30.0 through 10.20.30.255.

The IPv6 CIDR block range is 0 to 128, for example, 1203.0fe1:fe82:b896:89b0:8a7c:99bf:323d/32 specifies 1203:0fe1:0000:0000:0000:0000:0000:0000 through 1203:0fe1:ffff:ffff:ffff:ffff:ffff:ffff:ffff.

You can also use shorthand to remove groups of zeros or leading zeros in a group in IPv6 addresses, for example,

1203:fe1::

There must be no spaces between the IP address and the CIDR mask that you are using.

Ranges or Series of Values

For meta keys that have numerical data, you can use a range of values, a series of values, or both to filter data. For example, this query has a comma-separated list, and two of the values in the series are ranges src.port = 0-1023, 1024-1050, 65535. If a comma is a part of a value, the value must be wrapped in quotes. For example, get,post is interpreted as two separate values, while 'get,post' is interpreted as one value. A range of values must be a valid range of positive integers, separated by a dash (with our without a space before and after). The first number in the range must be smaller than the second. For example, 0-1023 and 0 - 1023 are valid ranges, but these are not valid ranges: -10 - 50, 50 - 10, 50.8 - 60.2, 50 - 70x.

Select a Time Range

The Time Range selector limits the events returned in the Events view to a specific time range. The time range is displayed in the format Start Time - End Time, showing the date, hours, and minutes in your current timezone based on timezone settings configured for your profile. In Version 11.3 and later, you can choose a time range relative to the current collection time or create a custom time range. The time and date format is based on preferences set for the Events view in the User Preferences dialog (select User Profile icon > Profile).

  • By default, the date format is MM/DD/YYYY. You can change the format to DD/MM/YYYY, or YYYY/MM/DD in the User Preferences dialog.
  • Start time and end time are in the format of HH:MM. Although seconds are not displayed, the value for start time always defaults to HH:MM:00 seconds, and the value for end time always defaults to HH:MM:59 seconds. As an example, a time range of 6:45 pm - 7:45 pm is interpreted as 06:45:00 - 07:45:59 pm.
  • The default time range is the 24-hour clock; you can change it to 12-hour periods.

The time format for a query is based on preferences set for the Events view in the Event Preferences dialog (select the Event Preferences icon). The time format can be either database time or wall clock time. When Database Time is selected, the start and end time for a query is based on the time that the event was captured (collection time). When Wall Clock Time is selected, the query is executed using the end time based on the current browser time; the start time is calculated based on that end time and the time range. This and other Events view preferences are described in Configure the Events View.

To edit the time range, do one of the following:

  1. Click the drop-down arrow inside the Time Range selector and select a time range from the list. Options are in minutes, hours, days, or all data.

     the Time Range drop-down menu

  1. (Version 11.3 and later) Edit the time range directly by clicking the year, month, day, hour, or minute displayed in the query bar. When a value is highlighted, type a new value for either the start or end time. If your time format preferences are set to 12-hour periods, click am or pm to toggle between the two options.

    time Selector Edit

    If the time range is invalid (for example, the start time is later than the end time), a red border appears around the Time Range selector. The the submit query icon button is disabled because the query is no longer possible, and a tool tip shows an error message explaining what you need to change. The following figure shows an invalid time range.

    an error in the Time Selector
    The selected time range is stored in your browser for the service being queried; you can set different time ranges for different services. A tool tip shows the calculated duration of the query. The following figure is an example of the tool tip.
    Time Selector Duration

Submit a Query

The the submit query icon button on the right side of the query bar is active as needed to submit a query. In version 11.3 and earlier, when you click the submit query icon, all of the filters are ANDed to generate results and the the submit query icon button becomes inactive. In Version 11.4, because the query may contain other operators besides AND, the query is submitted as is. The the submit query icon button becomes active again in these conditions:

  • If you change the service in the query bar or change the column group in the Events panel, a network call for data for a reconstruction in the Events panel continues to use the previous service, time range, and metadata filters until you submit the new query. The the submit query icon button becomes active as an indicator that the data in the view is stale.
  • If more than a minute has passed and the original query's time range would no longer generate the same result set, the the submit query icon button becomes active as an indicator that results may be stale. In Version 11.3 and later, a setting in the Events view preferences determines this behavior by enabling or disabling the Update Relative Time Window Automatically option (see Configure the Events View.)

Cancel Execution of a Query

After you click the submit query icon to submit a query, the button changes to the Cancel Query icon (the stop query option). The stop query option remains until all the events are loaded in the Events panel. To cancel the query, click the Cancel Query icon.

If the query is canceled before all results have been returned, the following message is displayed at the end of results in the Events list: "Because the query was canceled, only partial results are displayed."

View Status of a Query

After a query is submitted, you can click the information icon () in the query bar to open the query console. In the query console, you can see which service, time range, and metadata was queried as well as real-time information about the status of the query and the services being queried. The time range displayed in the Query console always shows each date as YYYY-MM-DD. Here is an example range from the Query Console: "2014-09-20 20:57:00"-"2018-11-02 18:57:59".)

The following figure is an example of the Query Console for Version 11.3 when a query executes successfully and the slowest service is marked by an amber stopwatch.

the query console after a query has executed with no errors or warnings, and the slowest service is marked by an amber stopwatch

The following figure is an example of the information in the Query Console for Version 11.4 after a query that includes a text filter executes. Notice that the query is shown in two fields, Meta Filter and Text Filter.

example of the query console showing a completed meta key filter and a text filter

While a query is executing, a progress bar indicates the query's completion percentage at the bottom of the console. The status lets you know details about what is happening; for example, you can tell when the query is executing, queued, reading the index file for the queried service, retrieving events, and complete. All statuses and non-fatal messages are displayed as they come in, and the border color of the query bar changes to amber if a non-fatal error occurs.

Icons provide additional information about individual services.

  • An amber stopwatch marks the slowest service.
  • An amber triangle indicates a warning was received.
  • A red triangle shows that an error was received when trying to query the service.

Executing and Reading the Index File to Find Events. The first stage of a query is complete when the queried services have found results. The query console provides a nested hierarchical listing of all the services being queried with indicators showing which are online or offline, and the time in seconds that the service took to find results.

Retrieving Events and Loading in the Events Panel. While the found events are being retrieved and loading in the Events panel, the progress bar shows a visual indicator and text description of what is happening. In the figure below, results were found and are being retrieved.

an example of the query console while retrieving

Request Complete. If there are no errors or warnings when loading is complete, the query console is outlined in blue and the the submit query icon button is disabled as an indicator that the data in the view is fresh. The following figure is an example of the query console for a completed query with no errors or warnings.

example of the status for a completed query with no errors or warnings

Errors and Warnings. A fatal error such as a syntax error in the query, or the queried service being offline, stops execution of the query. A red triangle is displayed in the upper right corner of the query console, and the console is outlined in red to indicate that the query failed. If the queried service is offline, only the queried service with no hierarchy of services is listed in the query console and marked by a red triangle.

A non-fatal error does not prevent a query from executing. The query is executed and events are loaded, but a red triangle is displayed in the upper right corner of the query console, and the console is outlined in red as a warning. The following figure shows the appearance of the query console when the queried service proxies to another service that is offline.

example of the query console with one service offline

A warning does not prevent a query from executing. The query is executed and events are loaded, but an amber triangle is displayed in the upper right corner of the query console, and the console is outlined in amber.

Build a Query in Guided Mode

Guided Mode is the easiest way to create a query with features to help analysts enter valid queries. The following figure illustrates the initial Events view with Guided Mode in effect in the query bar.

the Event Analysis view when initially opened, with Guided Mode in effect

Keyboard Actions to Use in Guided Mode

In Guided Mode, the query builder allows entry, editing, and deletion of filters using the key strokes without having to use a pointer. Although you can use the pointer, you have the option to keep your fingers on the keyboard. This table identifies the available keyboard actions in Guided Mode when the cursor is located in the query bar; these do not apply to the service selector and time range.

                                                                                           
ActionKeyboard Entry
Delete characters in a filter

Selected characters: With characters selected in the query bar, press Delete or Backspace.

Previous character (Version 11.4 and later): With the cursor next to a character in the query bar, press Backspace (Windows OS) or Delete (Mac OS).

All characters (Version 11.4 and later): With the cursor in a filter, press Delete (Windows OS) or FN + Delete (Mac OS).

Delete filters

Selected filters: With one or more filters selected do one of the following:

  • Right-click > Delete selected filters or Delete selection (11.4 and later).
  • Press Delete.
  • Press Backspace.

Filter that has focus (Version 11.4 and later): With the cursor in a filter that has focus, press Backspace (Windows OS) or Delete (Mac OS). The focused filter is deleted and focus moves to the left.

Filter that has focus (Version 11.4 and later): With the cursor in a filter that has focus, press Delete (Windows OS) or FN + Delete (Mac OS). The focused filter is deleted and the focus moves to the right.

Delete parentheses in a filter, do not delete the contents (11.4 and later)

With a set of parentheses, but not the contents selected, press Delete (Windows OS) or FN + Delete (Mac OS). The selected parentheses are deleted, but the contents of the parentheses remain.

Delete parentheses and their contents in a filter (11.4 and later)

Selected parentheses: With a set of parentheses selected, do one of the following:

  • Right-click > Delete selection.
  • Press Backspace (Windows OS) or Delete (Mac OS). The selected parentheses and contents are deleted and the focus moves to the left.
  • Press Delete (Windows OS) or FN + Delete (Mac OS). The selected parentheses and contents are deleted and the focus moves to the right.
Deselect all filtersWith a filter selected, press the ESC key.

Edit a selected filter

With a single filter selected, press the Enter key.

Insert a new filter at the beginning of the query bar, and open for editing (Version 11.4 and later)With a filter selected, press the HOME key (Windows OS) or the FN + Left Arrow keys (Mac OS).
Insert a new filter at the end of the query bar, and open for editing (Version 11.4 and later)With a filter selected, press the END key (Windows OS) or the FN + Right Arrow keys (Mac OS).
Insert a new filter to the immediate left of the selected filter, and open for editingWith a filter selected, press the Shift + Left Arrow keys.
Insert a new filter to the immediate right of the selected filter, and open for editing.With a filter selected, press the Shift + Right Arrow keys.
Insert a new filter to the immediate left of the selected filterWith a filter selected, press the Left Arrow key.
Insert a new filter to the immediate right of the selected filterWith a filter selected, press the Right Arrow key.

Open a new tab with the selected filters

With filters selected, right-click > Query with selected filters in a new tab.

Query with the selected filtersWith filters selected, right-click > Query with selected filters.
Query with content of parentheses (Version 11.4 and later)

With parentheses selected:

  • To query with the selected parentheses contents, select one side of a parentheses set and right-click > Query with selected filters.
  • To query with the selected parentheses contents in a new browser tab, select one side of a parentheses set and right-click > Query with selected filters in new tab.

Select all filters to the left of the current filter

(Version 11.3.x and earlier) With a filter selected, press the Shift + Up Arrow keys.

(Version 11.4 and later) With a filter selected, press the Shift + Right Arrow keys twice.

Select all filters to the right of the current filter

(Version 11.3.x and earlier) With a filter selected, press the Shift + Down Arrow keys.

(Version 11.4 and later) With a filter selected, press the Shift + Right Arrow keys twice.

Select the filter to the immediate left if one existsWith no filter selected, press the Left Arrow key.
Select the filter to the immediate right if one existsWith no filter selected, press the Right Arrow key.
Submit a query.With focus on the query bar and no pending filters, press Enter.

Visual Feedback in Guided Mode

Guided Mode provides visual feedback during query construction. This table identifies and describes the possible feedback.

                                                          
FeedbackIconDescription

Blue background on a Filter

a filter with blue background

Indicates that a filter is selected.

Green circle between two filters Green circle inbetween filters

the bold cursor at the insertion point

(Version 11.3 and earlier) A green circle indicates the location of the cursor between two existing filters. Clicking inserts a new filter at this location.
(Version 11.4) A bold cursor indicates the insertion point.
Green filter outline a filter with a green border Marks the single filter that has focus and ready to edit. This is combined with the blue background, when multiple filters are selected and this filter has focus.

Red filter outline

Red outline example

Indicates that the filter is invalid. A tool tip that explains the error is displayed.

Index indicators in the Meta tab example of one of the index indicators for meta keys

(Version 11.4 and later) Indicate the index level of the meta keys in the Meta tab, which determines if you can use it in a filter:

This meta key is indexed by meta value and can be used in a filter.

This meta key is indexed by meta key, and can be used in a filter.

This meta key is not indexed, and not selectable for a filter.

The sessionID meta key is a special case. Unlike other non-indexed meta keys, it is not configurable, but you can use it in a filter so it is marked by the key symbol. Supported operators are exists, !exists, =, and !=.

Query Events button the Query Events button

Used to submit a query, show the status of the query, and cancel a query. The button has three possible states:
Query Events button Ready to submit a query using filters in the Query Builder.
Query Events spinner Waiting for server validation to complete before executing the query.
Query builder submit icon when is Cancel mode The query is executing, click to cancel execution.

Slow Service icon slow service icon In the query console, marks the service that took the longest time to load results from the query.

Spinner in the Events list

the loading spinner

Indicates that the query is currently being processed. The Query Events button is disabled while this occurs.
Stopwatch the stopwatch icon Indicates that the meta key/operator combination requires extra time to process. While the query is still executable, a more efficient meta key or operator is recommended.

Add a Simple Filter in Guided Mode

To create a simple filter in Guided Mode:

  1. Go to the Events view (Event Analysis view in Version 11.3 and earlier) and do one of the following:
    1. (Version 11.4 and later) Select Guided Mode, click in the query bar and when the filter entry form is displayed, select the Meta tab if it is not already selected.
    2. (Version 11.2 and later) Select Guided Mode and click in the query bar.
    3. (Version 11.1) Click in the empty query bar, or before or after an existing filter. This is an example of the empty query bar in Guided Mode before you begin entering a filter.
      query bar before creating a filter
      If the insertion point is between two filters, a green circle (Version 11.3 and earlier) or a bold cursor (Version 11.4 and later) marks the insertion point. If the insertion point is at the end of the query bar, the filter entry form opens with a blinking cursor at the entry point. A drop-down list displays the available meta keys passed from the service being investigated in alphabetical order. This figure shows the filter entry form from Version 11.4.
      exaemple of the Meta tab drop-down menu with index symbols
  1. To select a meta key do one of the following:
    1. If there is only one option in the drop-down list, press Enter.
    2. If there are two or more options in the drop-down list, click a meta key or select a meta key using the up/down arrows, then press Enter.
    3. Start typing the meta key. As you type the meta key, the list is filtered to include only meta keys that contain the text you typed. The count next to the label on the Meta (0) tab increments to enumerate the indexed meta keys that match the typed text. Keys that are not indexed are disabled and not selectable and are not included in the count, for example, alias.mac in the figure below is not indexed and is dimmed. Click a meta key or select a meta key using the up/down arrow, then press Enter.
      example of the Meta drop-down list when filtered by typed text
    4. To select a highlighted meta key, press Enter.
      The count on the Meta label changes to 1.

      Note: If no meta key in the drop-down list is selected, and the list has no meta keys to select, either the Free-Form Filter or the Text Filter option is highlighted based on the content already typed in the query bar.
      --If the text typed in the query bar includes some form of query syntax and other operators not yet supported by the user interface, the Free-Form Filter option is highlighted and you can create a free-form filter. In Version 11.3 and earlier, the **, &&, ||, (), AND, OR, comma, -, length, and regex operators are not supported by the user interface. The Version 11.4 user interface supports these operators. If the Free-Form Filter is not highlighted, and the query bar has no text filter, the Text Filter is highlighted so you can create one.
      --If the first condition is true, and there is already one text filter, the Free-Form Filter option is highlighted so you can create a free-form filter.

    5. If you want to edit or delete the meta key, press Backspace or Delete.
      As you backspace and delete characters, the meta key drop-down list is filtered to include meta keys that contain those characters. To select a meta key, press Enter.
      The meta key is added to the filter entry form, and a list of valid operators for the selected meta key is displayed. Operations that require more time to process are marked by a the stopwatch icon (stopwatch icon). This figure shows the stopwatch icon marking the contains operator.
      example of the operators drop-down list in the query builder
  2. To select an operator, do one of the following:
    1. If there is only one option in the operators drop-down list, press Enter to select it.
    2. If there are two or more options in the operators drop-down list, click an operator or select one using the up/down arrows, then press Enter.
    3. Type the operator and press Enter. As you type, the operators drop-down list is filtered to show only operators that contain the typed text. Click an operator or select one using the up/down arrows, then press Enter.
      The operator is added to the filter entry form. In Version 11.4 and later, if the operator accepts a value, the suggested values drop-down list is displayed. Earlier versions leave the cursor in the filter entry form so that you can type a value.
      the Values auto-suggest menu before text is typed
  3. (Optional) If the selected operator in the filter entry form accepts a value, do one of the following:
    1. In Version 11.3 and earlier, type the value and press Enter.
    2. In Version 11.4 and later, paste a value that you have copied from somewhere and press Enter.
    3. In Version 11.4 and later, begin typing in the Query Filter field.
      As you type, the meta value drop-down list is filtered to return up to 100 properly indexed values that begin with the typed text. The suggested values are based solely on the time range; filters in the query do not filter the list of 100. The auto-suggest function looks for matches in all events in the current data set, not just the (up to 10,000) downloaded events. If nothing in the list matches exactly, the text you typed in the Query Filter field is highlighted and this message tells you that no suggestions were found. Some values, such as the integers for the service meta key, also display the definition of the service type.
      Value drop-down list for the service meta key
      If there is an exact match, that value is highlighted. In the following example, there is no exact match for the typed text, modi.
      example of the Values auto-suggest menu with typed text
      1. If the typed text is the value you want to use in the filter, press Enter.
      2. If you see the value that you want to query in the list and it is not highlighted, click the value or use the up/down arrows to highlight the value. Then press Enter.
      3. If you want to edit or delete the value, press Backspace or Delete.
        As you backspace and delete a character, the meta value drop-down list is filtered to include values that begin with the remaining characters. To select a value, press Enter.
        The value is added to the filter entry form.
  4. To create the filter, press Enter. If you click anywhere outside the box before pressing Enter, the filter is not created.
    The new filter is inserted, and the blinking cursor is refocused after the last filter, the meta keys drop-down list is displayed. If there is an error in the filter, it is outlined in red. You can hover over the filter to see a tool tip explaining the error. This figure shows a query being created with no errors.
    example of a filters created in Guided Mode with no errors
  5. If the filters have no errors, you are ready to execute the query in the query bar. Click the query events button.
    The results are returned and loaded in the Events panel. The first 10,000 events that match the query begin loading in the Events panel. As the events are loaded, a status bar at the top tracks progress and you can scroll to the bottom of the list to see the completion status.
  6. (Optional in Version 11.3 and later) If you want to see detailed status in the Query Console, click the information icon the Query Console icon, the blue letter i in a blue circle.
  7. (Optional in Version 11.3 and later) If you want to cancel the query before it finishes executing, click the cancel query button.
    The query stops executing and a notification that the query has been canceled is displayed.

Add a Free-Form Filter in Guided Mode (Version 11.3 and Later)

To filter the data displayed in the Events view using a free-form filter in Guided Mode:

  1. Go to the Events view, select Guided Mode below the query bar, and click in the query builder field.
    If the insertion point is between two filters, a green circle or a bold cursor marks the insertion point. If the insertion point is at the end of the query bar, the filter entry field opens with a blinking cursor at the entry point. A drop-down menu lists available meta keys passed from the service being investigated in alphabetical order.
    exaemple of the Meta tab drop-down menu with index symbols
  2. Do one of the following:
    1. Place the cursor in the Free-Form Filter field and begin typing the query.
    2. Begin typing the filter beginning with a meta key or with an open parenthesis. When entering and editing filters in the query builder, parentheses pairs are automatically balanced. If you type an open parenthesis, the other part of the pair is added to the filter.
      When no matching meta keys or operators are available in the drop-down menu, the Free-Form Filter option becomes available, and the text you typed is available in the Free-Form Filter field.
      the values drop-down menu with GET typed in
  3. Continue typing the entire expression and press Enter.
    (If you click anywhere outside the box before pressing Enter, the filter is not created.) This figure shows a free-form expression created by continuing to type after the value GET.
    the value drop-down menu with a complex query ready to enter
    The new filter is inserted, and the blinking cursor is refocused after the last filter, a new filter entry form is displayed. If there is an error in the filter, it is outlined in red. You can hover over the filter to see a tool tip explaining the error.
  4. To execute the query, click the query events button. While the query is executing, the the query events button button changes to the cancel query button.
    a query in progress in the Query builder with the Cancel Query button available
  5. If you want to cancel the query before it finishes executing, click the cancel query button.
    If you do not cancel the query, you can click the Info icon to view the status of query execution. When the query is finished executing, the Events panel displays appropriate results for the query.

Add a Text Filter to Find a Value Anywhere in the Data Set (Version 11.4 and Later)

In Version 11.4 and later, the text filter allows you to find a specific value in the current data set (endpoint, logs, and network events). The text filter initiates a case-insensitive search against all the data for meta keys that are indexed by value. The text filter does not search for values that are indexed by meta key or not indexed so you not see all results. A message advises that Results may be limited by a text filter, which matches only indexed meta keys. If you want to conduct a more exhaustive search against raw events, click here and choose the appropriate options in the Search Events drop-down menu. Icons in the drop-down list indicate the index level of each meta key:

  • indexed by meta key - indexed by meta key
  • a meta key indexed by value - indexed by meta value
  • not indexed - not indexed

Note: All services in the hierarchy being queried (Broker, Concentrators, and Decoders) must be at Version 11.3 or later. The text filter is not available in the drop-down menu when there are services below Version 11.3 in the hierarchy.

The text filter is useful when you have some idea of what you are looking for, but are not sure where to look (which meta key or service). As an example, if you are interested in looking for a file name, click in the query bar, type the complete text string, and click Text Filter. The text filter initiates a search against all the data in the index, within the services and time range being investigated, and returns exact matches to the text string.

A query can include one text filter and any combination of simple and free-form filters. The operator for a text filter must be AND because it acts as a filter over the results of all the other filters in the entire query. If one text filter already exists in the query bar, the Text Filter option is disabled as shown in the figure below. Text filters are not supported inside parentheses.

example of the query bar when attempting to create a second text filter

To create a text filter:

  1. Go to the Events view and click in the query bar.
    The query entry form is displayed.
    exaemple of the Meta tab drop-down menu with index symbols
  2. Type the text string that you want to find, for example, http.
    The text string is displayed in the meta key drop-down list under Advanced Options.
    The text filter option
  3. Click Text Filter under Advanced Options.
    The text filter is created in the query bar. The following figure illustrates the different appearance of a text search filter versus a free-form filter. The free-form filter is in a fixed-space font and outlined in red. The red outline indicates a syntax error because a valid expression is expected in a free-form filter. The text filter is marked by the search icon. No syntax requirements are applied to text search filters.
    the different appearance of text vs free-form filters
  4. (Optional) Create additional simple or free-form filters in the query bar. There can be only one text filter in the query. This example was created by typing http as a text filter and then adding two more filters - action = 'get' OR action = 'put'
    sample query with a text filter
  5. To submit the query, click the query events button.
    The results are displayed in the Events panel. This figure illustrates the Events panel with no results displayed and a message with instructions for improving results. Every time you use a text filter, this message is at the bottom of the results offering a link to expand your search.
    No results for the text filter
  6. Click the here link in the message.
    A new browser tab opens with the query results displayed in the Legacy Events view, where you have additional options to improve the search. This figure shows the results for the same query when non-indexed metadata is included.
    more results for the same query when all metadata is included
  7. Click the Information icon the Information icon in the query console to view the status of the query. This figure shows a text filter in the query console.
    a text filter as displayed in the query console

Paste Text in the Query Bar (Version 11.4 and Later)

While creating a filter in the Events view query bar, you can paste instead of typing the complete text of a filter that you have copied from somewhere else. You can paste the text into an empty query bar or next to an existing filter in the query bar. Depending on the text you typed, the query parsing engine parses the information that you pasted and creates a new filter, which can be a simple filter, a free-form filter, or a text filter.

  • A text string of this form is added as a new simple filter in the query bar: <valid meta key> <valid operator> <optional value>. This is an example: alias.host contains 's'.
  • A text string of this form is added as two simple filters in the query bar: <valid meta key> <valid operator> <optional value> && <valid meta key> <valid operator> <optional value>. This is an example: alias.host contains 's' && action exists, which is converted to alias.host contains 's' AND action exists.
  • A text string that contains unparsable text may be converted to a free-form filter. For example, using NOT (device.ip = 10.10.10.10) is unsupported for creation of a filter in Guided Mode, so this would be converted to a free-form filter. Free-form filters are validated by the server when they are submitted.
  • Text that does not conform to the filter syntax is added as a free-form filter.

To create a filter by pasting text:

  1. Go to the Events view > Events panel, select Guided Mode under the query bar, and click in the query bar.
    The query entry form is displayed.
    exaemple of the Meta tab drop-down menu with index symbols
  2. Type CTRL-V, CMD-V (MacOS), or right-click and Paste to paste text that you have copied into the clipboard from somewhere else. Do one of the following:
    1. If the text you pasted is a statement that can be parsed, one or more simple filters is created.
      If the text you pasted is a statement that cannot be parsed, a new free-form filter is created.
      If the text you pasted is not a statement and not a valid meta key, an invalid syntax error is displayed.
      If you pasted a valid meta key for a new filter you are building, the meta key is highlighted in the drop-down list, and you can continue creating a filter as usual by entering an operator and a value.
      After you select a valid meta key and a valid operator (for example, city.dst =) any text that you paste is treated as a text string if the meta key supports a text value, and one filter is created. If the meta key does not support a text value all of the text in the query bar is parsed as described in step a above.
  3. Add more filters in the query bar if you wish, and then submit the query.
    The query is executed.

Insert a Filter Based on a Recent Query (Version 11.4 and Later)

In the Guided Mode query bar, you can insert a filter based on a recent query. When the Recent Queries tab is opened and nothing has been typed in the query bar, up to 100 of your most recently executed queries are displayed in a scrollable list. The list is sorted to show the most recent at the top, and the Recent Query count is set to 0. When you begin typing, the list is filtered to display up to 100 queries from the query history database that contain matching text, even if the matches are not in the most recent 100 queries. The Recent Query count changes to reflect the number of matching queries as you type.

The top entry in the list is highlighted by default. To select a recent query, you can move the highlighting up and down in the list using the up and down arrow or by mouse-over of a recent query. As you type the list is filtered and the highlighting moves back to the top of the list. Clicking a query, or pressing ENTER while a query is highlighted, creates a new filter with the text of the selected query.

Whenever you submit a query, the list is sorted to add that query, now the most recent, at the top.

an example of the Recent Queries drop-down menu

To create a filter based on a recent query:

  1. Go to the Events view, select Guided Mode under the query bar, and click in the query bar.
    The Meta Key drop-down list is displayed in the Meta tab.
  2. Select the Recent Queries tab.
    The Recent Queries drop-down list is displayed with a count of 0.
    an example of the Recent Queries drop-down list
  3. To search for a recent query, do one of the following:
    1. Begin typing some text.
      As you type more characters or backspace to delete characters, the list is filtered to show recent queries that contain the text you typed. The count in the Recent Queries label increments to show the number of matching queries as you type.
      example of the Recent Queries tab with matching queries found
    2. To select a query and add a new filter, continue to type and use the up and down arrows until the query you want to use as a new filter is highlighted.
    3. With a query highlighted, press ENTER or simply click a query that you see in the list.
      The filter is added in the query bar.
  4. Add more filters in the query bar if you wish, and then submit the query.
    The query is executed and the list is sorted to add that query, now the most recent, at the top.

Edit a Filter in Guided Mode

With a query in the Guided Mode query bar, you can edit a filter. To edit a filter:

  1. Double-click the filter, or click the filter and press Enter.
  2. Edit the filter. When finished editing, press Enter to update the filter.
  3. If you want to execute the query again, click the query events button.
    The Events panel displays results for the updated filter.

Query Using Selected Filters in Guided Mode

When you have one or more filters in the query bar in Guided Mode, you can refocus the query to include only selected filters, displaying results in the current browser tab or a new browser tab. Some filters include expressions with nested parentheses in Version 11.4, and you can refocus part of a filter that includes nested parentheses. To update the query using only selected filters, do one of the following:

  1. Using a query that includes one or more simple filters, for example a query has three filters: risk.info exists, direction ='lateral', and threat.category exists.
    1. Select direction = 'lateral', right-click the filter and select Query with selected filters in a new tab in the drop-down menu.
      the Query with selected filters in a new tab option selected
      A new tab opens with the results for the selected filter and the original query is left intact on the previous tab.
    2. To query the selected filters in the same tab, select direction = "lateral" and threat.category exists. Then right-click and select Query with selected filters in the drop-down menu.
      the Query with selected filters option selected in the drop-down menu
      A query with only the selected filters is submitted and all remaining filters are removed.
  2. (Version 11.4) For a query that includes a filter containing nested parentheses, for example: action = 'get' AND (filename exists OR sourcefile exists OR content = 'application/octet-stream'), do one of the following:
    example of the menu with parenthese selected
    1. Select the close parenthesis after 'application/octet-stream', right-click, and select Query with selected filters in a new tab.
      A new tab opens with results for (filename exists OR sourcefile exists OR content = 'application/octet-stream').
    2. Select the same, right-click, and select Query with selected filters.
      The results for (filename exists OR sourcefile exists OR content = 'application/octet-stream') are displayed in the current tab.

Delete a Filter and Delete Text or Parentheses in a Filter in Guided Mode

Some keystroke editing features became available in Version 11.4; these are labeled in the steps.

  1. To delete a filter, do any of the following:
    1. Click X in a filter.
    2. Select the filter and press Delete (Windows OS) or FN + Delete (Mac OS).
    3. (Version 11.4 and later) Select the filter and press Backspace (Windows OS) or Delete (Mac OS).
    4. Right-click one or more filters and select Delete selected filters or Delete selection (Version 11.4 and later) in the drop-down menu.
      The filter and the operator to the right or left of the filter is deleted, ensuring that no extraneous operators remain in the query bar.
  2. (Version 11.4 and later) To delete characters in a filter or parentheses and contents in a filter, do any of the following:
    1. To delete the previous character: With the cursor next to a character in the query bar, press Backspace (Windows OS) or Delete (Mac OS).
    2. To delete all characters: With the cursor in a filter, press Delete (Windows OS) or FN + Delete (Mac OS).
    3. To delete the selected characters: With characters selected in the query bar, press Delete or Backspace.
    4. To delete parentheses, but not the characters inside the parentheses, select one of the parentheses and press Delete (Windows OS) or FN + Delete (Mac OS).
    5. To delete a set of parentheses and the contents, for example, (filename exists OR sourcefile exists OR content = 'application/octet-stream'), select the parenthesis after get, right-click, and select Delete selection.
      example of the menu with parenthese selected
      Everything except action = 'get' is deleted.

Create a Query in the Free-Form Mode

Free-form queries are most useful when you have a long text string saved that you want to paste, or if you have one in mind that you want to enter quickly, and you know the meta keys, valid operators, and valid syntax for entering values. The following figure illustrates the initial Events view with the empty Free-Form query builder field. The first example is Version 11.2 and the second example is Version 11.3.

Free-Form query builder, with the field empty

the empty query builder with Free-Form mode selected

The blinking cursor indicates that you can enter a query. You can enter free text here. As more expressions are added and they cannot be displayed in a single line, they wrap to another line and the input area expands vertically so that all filters are visible without scrolling to the right.

These are some examples of queries that you can enter in Free-Form mode:

To find events with an 8- to 11- character username similar to atreeman-72:
user.all length 8-11 && (user.all regex '^a[a-z]{2}ee[a-z]{3}-[0-9]{2}')

To find events that are either HTTP network events or related to aix or ciscoasa logs:
service=80 || (device.type = 'aix','ciscoasa')

To find all outbound events not going to Canada or the United States:
direction = 'outbound' AND not(country.dst = 'united states' || country.dst = 'canada')

If you have a submitted query in Guided Mode, the query is transformed into text when you click switch to Free-Form mode. This is an example of a query submitted in Guided Mode as two filters, service = 80 and direction = 'outbound', and then viewed in Free-Form mode.
query from Guided Mode

The the query events button button on the right side of the query builder is visible as needed to input a query. The query is applied when you click the query events button. At that time the query is validated to show syntax and logic errors.

Operations that require more processing time are not highlighted as they are in Guided Mode, but this table provides a summary of expensive operations for reference.

                                                    
Index MethodNon-Text ValueText ValueRegular OperationsExpensive Operations
By Key  exists, !existseq, !eq
By Key  exists, !existseq, !eq, begins, ends, contains
By Value  exists, !exists, eq, !eqno expensive operators
By Value  exists, !exists, eq, !eq, begins

ends, contains

By Nonespecial case for sessionid exist, !exits, eq, !eq

no expensive operators

You are here
Table of Contents > Refining the Results Set > Filter Results in the Events View

Attachments

    Outcomes