Investigate: Filter Results in the Event Analysis View

Document created by RSA Information Design and Development on Mar 27, 2018Last modified by RSA Information Design and Development on Sep 11, 2018
Version 4Show Document
  • View in full screen mode
 

Note: The information in this topic applies to RSA NetWitness® Platform Version 11.1 and later.

In NetWitness PlatformVersion 11.0, you submit a query in the Navigate view or the Events view, and when you go to the Event Analysis view, a read-only breadcrumb shows the submitted query. You need to go to back to the Events view or Navigate view if you want to enter a different query.

In Version 11.1 and later, a query builder populates the interactive breadcrumb in the Event Analysis view so that you can create and edit each <meta key> <operator> <meta value> filter in the breadcrumb. In addition, you can select a different service and time range without going back to the Navigate view or the Events view. The remainder of this section provides information about using the query builder features.

How the Breadcrumb Works

When you click the Event Analysis option in Investigate to open the view, the service and time range selector is displayed. By default, the first service is auto selected (unless you previously selected a service and the selected service is remembered in the browser). If you do not select a time range, the default time range (3 hours) is used. The query builder field is an empty field to the right of the time range.

When you open the Event Analysis view from the Events view or the Navigate view, the service, time range, and any filters that were selected in the Events view or Navigate view are displayed in the breadcrumb. The service, time range, and individual filters can be modified.

Beginning with Version 11.2, in addition to building a query in Guided Mode, advanced analysts can enter a query in Free-Form Mode. The default mode is Guided Mode, which includes auto-suggest and validation options. Free-Form Mode allows you to type a complex query; validation is performed when you run the query.

Note: A complex query is any query other than a basic <meta key> <operator> <value> filter that contains (), ||, &&, length, or regex operators.

Two buttons switch between the modes, and place a cursor in the query bar so that you can begin creating a query immediately. If you selected Free-Form Mode the last time you logged in, this choice is in effect the next time you log in.

  • 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 builder as a single uneditable filter.
  • If you start building a query with multiple filters in Guided Mode, then switch to Free-Form mode, and back to Guided Mode with no changes, the multiple filters are in the same state that you left them.

The following figure is an example of the Event Analysis view with the Guided Mode query builder in effect.

example of a query in the Guided Mode query builder

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

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

Note: Version 11.2 included an undocumented beta feature, called Next Gen mode, in the Event Analysis view query builder that was still being developed and tested. Next Gen mode was disabled in the 11.2.0.1 patch. If you see Next Gen mode do not use it; you should use only the Guided Mode and Free-Form Mode in the query builder to ensure consistent and predictable results.
Next Gen Mode

Guided Mode Query Builder

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

Initial Event Analysis view with breadcrumb highlighted

Note: The Guided Mode query builder supports only simple filters in the form <meta key><operator><meta value>. If the Events view or Navigate view has a filter with more than one operator, not, >, <, <=, >=, ||,&&, (), REGEX, or LENGTH, the filter is added, but editing is not supported in the Event Analysis view. The same is true for a filter brought in from the Free-Form query builder.

As you create filters in the Guided Mode query builder, the breadcrumb is updated with each filter in an editable field. When you submit the query, all of the filters are AND'd to generate results. The query is not submitted until you click Query Events. Filters line up from left to right, representing the sequence in which the filters were created. Each filter is a simple expression of the form <meta key> <operator> <optional value>. As more filters 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.

As you create and edit filters, you are assisted with suggestions for auto-complete that show only valid meta keys and operators in the drop-down list. You can type or select from the drop-down list. In the drop-down list, operations that take more time to execute are marked by a stopwatch icon. Invalid filters are marked by a red outline, and if you hover the mouse over the filter, a tool tip that explains the error is displayed.

The Query Events button is on the right side of the breadcrumb input, and becomes active as needed to submit a query. A query is submitted when you click Query Events or press Enter after creating a filter. When you have a set of results loaded and you change the service, time range, or a filter, the Query Events button turns blue as an indicator that the data in the view is now stale. In Version 11.2 and later, the Query Events button will also turn blue if more than a minute has passed because the original query's time range no longer generates the same result set.

Note: If you change the service, a network call for data for reconstructions or more data in the Events panel (for example, Load More) uses the previous service/time range/metadata filters. The network call continues to use these previous query parameters until you submit the new query.

Keyboard Actions to Use in Guided Mode

In Guided Mode, the query builder allows entry, editing, and deletion of filters from the keyboard 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 when the cursor is located in the Guided Mode query builder portion of the breadcrumb; these do not apply to the service selector and time range.

                                                                   
ActionKeyboard Entry
Submit a query.With focus on the query builder and no pending filters, press Enter.
Select the filter to the immediate left if one exists.With no selection in the query builder, press the Left Arrow key.
Select the filter to the immediate right if one exists.With no selection in the query builder, press the Right Arrow key
Insert a new filter to the immediate left of the selected filter.With a filter selected, press the Left Arrow key
Insert a new filter to the immediate right of the selected filter.With a filter selected, press theRight Arrow key.
Insert a new filter to the immediate left of the selected filter, and open for editing.With a filter selected, press the Shift + Left Arrow keys.
Insert a new filter to the immediate left of the selected filter, and open for editing.With a filter selected, press the Shift + Right Arrow keys.
Select all filters to the right of the current filter.With a filter selected, press the Shift + Down Arrow keys.

Select all filters to the left of the current filter.

With a filter selected, press the Shift + Up Arrow keys.

Edit a selected filter

With a single filter selected, press the Enter key.

Deselect all filters.With a filter selected, press the ESC key.

Delete all selected filters.

With filters selected, choose the right-click > Delete selected filters option, press Delete, or press Backspace.

Update query with only the selected filters.With filters selected, choose the right-click > query with selected filters option.

Open a new tab with the selected filters.

With filters selected, choose the right-click > query with selected filters in a new tab option.

Feedback in Guided Mode

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

                            
FeedbackIconDescription
Green Circle Green circle inbetween filters The cursor has been placed between two existing filters. Clicking inserts a new filter at this location.

Red Outline of a Filter

Red outline example

The value-type is not valid for the selected meta key, for example, a string value for a meta key that expects an integer. A tool tip that explains the error is displayed.

Stopwatch Stopwatch Icon The selected 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 Filter in Guided Mode

To filter the data displayed in the Event Analysis view in Guided Mode:

  1. Go to the Event Analysis view, and select Guided Mode below the query builder.
    This is an example of the empty query builder in Guided Mode before you begin entering a filter.
    Guided Mode, empty query builder field
  2. To insert a filter, click in the query builder field, or before or after an existing filter.
    If the insertion point is between two filters, a green dot marks the insertion point. If the insertion point is at the end of the existing breadcrumb, the filter entry field opens with a blinking cursor at the entry point. A drop-down menu lists available meta keys for the selected service in alphabetical order. The available meta keys are passed from the service being investigated, and meta keys that require more time to process are marked by a stopwatch icon.
    the meta key drop-down list in the Guided Mode query builder
  3. To select a meta key do one of the following:

    1. If there is only one option in the drop-down menu, press the Enter.
    2. If there are two or more options in the drop-down menu, click on the meta key or use the up/down arrow and press Enter.
    3. Start typing the meta key. As you type the meta key, the list is further updated. To select the meta key, press Enter.
    4. If you want to edit or delete the meta key, press Backspace or Delete.
      As you backspace and delete a character, the meta key drop-down list is filtered to include meta keys that begin with those characters. To select a meta key, press Enter.
      The meta key is added to the query builder, a list of valid operators for the selected meta key is displayed. Operations that require more time to process are marked by a stopwatch icon.
      example of operators drop-down menu
  4. To select an operator do one of the following:

    1. If there is only one option in the drop-down menu, press Enter.
    2. If there are two or more options in the drop-down menu, click on the operator or use the up/down arrow and press Enter.
    3. Type the operator and press Enter.
      The drop-down list closes and you can add a value if the operator accepts a value.
  5. (Optional) Type a value and press Enter.

  6. 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 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.
    the completed filter with a value
  7. Correct any filters that have errors.
  8. When you are ready to execute the query in the breadcrumb, click Query Events.
  9. The Events List is refreshed to reflect the query.

Edit a Filter in Guided Mode

With a query in the Guided Mode query builder, 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 button.
    The Events List is refreshed to reflect the updated filter.

Query Using Selected Filters in Guided Mode

With one or more filters in the Guided Mode query builder, you can refocus the same query to include only selected filters. The results are displayed in the current browser tab or a new browser tab. To update the query using only selected filters:

  1. Begin with a Guided Mode query that includes one or more filters, for example a query has three filters: risk.info = exists, direction ="lateral", and threat.category exists.
  2. To open a new tab with the selected filters, 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.
    results in a new tab
  3. 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.

Delete a Filter in Guided Mode

To delete a filter:

  1. Click X in a filter, click on the filter to select it and press Delete , or right-click one or more filters and select Delete selected filters in the drop-down menu.
  2. If you want to execute the query again, click the Query button.
    The selected filter is deleted and the Events List is refreshed.

Free-Form Query Builder

Free-form queries are most useful when you have a complex query 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 Event Analysis view with the empty Free-Form query builder field.

Free-Form query builder, with the field empty

The blinking cursor indicates that it is ready for you to 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.
query from Guided Mode

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.

The Query Events button is on the right side of the breadcrumb input, and is highlighted in blue as needed to input a query. The query is applied when you click Query Events. At that time the query is validated to show syntax and logic errors.

a query that has been submitted

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 > Analyzing Raw Events and Meta Data in the Event Analysis View > Filter Results in the Event Analysis View

Attachments

    Outcomes