Skip to main content

Bitdefender B2B Help Center

Live Search

Overview

With Live Search you can retrieve information about events and system statistics directly from online endpoints using OSquery, an operating system instrumentation framework that uses the SQLite query language.

Note

For more information on OSquery, check the official documentation following the links below:

Activating Live Search on your endpoints

For the feature to be available on a specific endpoint, the policy applied to it needs to have the module activated. To activate Live Search for a specific policy follow these steps:

  1. Go to the Policies page and select the policy you want to edit.

  2. Go to the Live Search section.

  3. Select the Live Search option to enable the feature for all endpoints the policy is applied to.

    msp_cl_livesearch_policy_en.png

Using Live Search

After enrolling in the early access program you can access the feature by going to Incidents > Search and selected the Live tab.

214525_1.png

The page contains the following elements:

gz_livesearch_main_page_c_214525_en.png
  1. Queries panel, comprised of:

    • Search option - you can use this to search by title.

    • Recent - displays the last 25 queries that were performed.

    • Saved - a list of all the queries that have been saved for this user.

    • Predefined - a list of queries that are available by default for all customers.

  2. Filters section, comprised of:

    • Company - perform a query on endpoints from a specific company.

    • OS - perform a query on specific endpoints based on their operating system.

    • Tags - perform a query on specific endpoints based on their GravityZone tags.

    • Endpoint name - perform a query on specific endpoints from a company.

  3. Save - save changes to current query.

  4. Save as - used when creating a new query.

  5. Discard changes - revert the query to the last saved state. This option becomes available if the query or the filters are different from the saved state.

  6. Reset filters - revert all changes applied to the filters. This option becomes active if one or more filter values are changed.

  7. Download icon - used to download the query results as a .CSV file.

  8. Info icon - displays the Tables side panel.

  9. Clear - removes all text from the input field

  10. Run query - run the current selected query.

  11. Query text - write your query.

  12. Query results - the results of the performed query.

  13. Resize button - use this to adjust the size of the search section.

  14. Page numbering and items displayed per page

  15. Refresh button

  16. Metadata details - provides additional details on the level of success of the query run. This section will always be displayed at the bottom, even if no results are present.

Create a new query

You can create a new query by using one of the methods below:

  • By typing in the query instructions

    When first displaying the Live tab after logging in to GravityZone, a blank query will be displayed by default.

    1. Type in the query instructions.

    2. Select the Save button on the upper right side of the screen.

    3. Type in a name for the new query.

    4. Select Save.

      The query is now displayed under Saved queries.

  • By editing an already existing query

    1. Select the query you want to modify.

    2. Change the instructions assigned to the query.

    3. Select the Save as button on the upper right side of the screen.

    4. Type in a name for the new query.

    5. Select Save.

    The query is now displayed under Saved queries.

Run a query

To run a query follow the steps below:

  1. Locate and click the query you want to run on the left side of the screen, under Saved queries.

  2. Select Run query.

    gz_cl_livesearch_runquery_en_copy.png

    Depending on the complexity of the query and the size of your network, it may take a few minutes to return all of the results. For the duration of the data gathering, the message In progress and a timer is displayed and the Run query button is disabled until all data is gathered.

    Note

    Query results will be gathered from each endpoint for a maximum of 2 minutes, after which they will be timed out and no more results will be gathered. If all endpoints respond with valid data before the the time-out, the query will be completed sooner. The Run Query button and the Metadata section will not be available while the query is running.

    Results are returned depending on your query:

    gz_livesearch_query_results_c_214525_en.png

    Only the first results are automatically displayed. The grid will automatically check for new results every 5 seconds until the query run completes. To manually refresh the results, you can use the Refresh button. When refreshing the results grid, the Metadata will also refresh.

    gz_cl_livesearch_refresh_en.png

    The query results are available for 30 minutes. Once the time has passed, the results are deleted. A timer is available between the query instructions and the query results.

Note

You can use the 214525_7.png button on the upper right side of the screen to download the query results as a .CSV file.

Reading Metadata details
gz_livesearch_metadata_details_c_214525_en.png

This section is collapsed by default, and contains the following data:

  • Status - the status of the query:

    • In progress - query is currently running.

    • Finalized - the query has been completed.

    • N/A - no query has been ran or the results have expired.

  • Respondents - the number of endpoints that have responded to the query.

  • Total endpoints - the number of endpoints that have been queried.

When expanded, the following information is displayed:

  • Query name - Metadata details is always accompanied by the query name.

  • Assign tags button

  • A filter section comprised of:

    • Status filter:

      • All

      • Timed out

      • Successful

      • Error

      • Failed to connect

    • Sent rows filter:

      • All

      • No results

      • Results available

  • Endpoint - the endpoint name.

  • Query execution time - the time the query ran on this endpoint (milliseconds).

  • Available rows - the total number of rows returned by the query for this endpoint.

  • Sent rows - the number of rows that have been included in the results.

  • Status - the status of the query for this specific endpoint.

  • Error message - the error message returned by the endpoint when queried.

    Note

    The information listed in the Metadata is only kept for 24 hours.

Edit a query

To edit a query follow the steps below:

  1. Select the query you want to modify.

  2. Change the syntax of the query.

  3. Select the Save button on the upper right side of the screen.

    Note

    Predefined queries can not be modified. Use the Save as button to create a new query.

  4. Click Save.

The modifications to the query have been saved.

Delete a query

To delete a query follow the steps below:

  1. Locate the query on the left side of the screen, under Saved queries.

  2. Click the vertical ellipsis button for the query you want to remove.

  3. Select Delete.

    gz_cl_livesearch_delete_en.png
Rename a query

To rename a query follow the steps below:

  1. Locate the query on the left side of the screen, under Saved queries.

  2. Click the vertical ellipsis button for the query you want to rename.

  3. Select Rename.

    gz_cl_livesearch_rename_en.png
  4. Type in the new name for the query.

  5. Click the OK button.

    gz_cl_livesearch_rename_ok_en.png

Tables panel

You can inspect the database schema and search for available tables and fields using the Tables side panel.

gz_livesearch_schema_helper_c_214525_en.png

This section is accessed from the info icon located at the upper right side of the query text box.

The panel contains the following elements:

  • Learn more - link directs you to the available documentation.

  • Search field - search tables or columns using full or partial name.

  • All platforms filter:

    • All platforms

    • macOS

    • Linux

    • Windows

  • The number of items displayed.

  • The results found - multiple tables which can be collapsed to show the table content

Query results limitations

The following limitations apply to all query results:

  • Queries return a maximum of 50 000 rows per run.

  • Queries return a maximum of 1000 rows for each endpoint per run.

  • Individual endpoint row results are not redistributed to other endpoint results that have not reached their row count limit.

  • Live Search does not support OSquery evented tables.

  • Queries on individual endpoints will automatically time out after 30 seconds. This does not include the time for processing the results.

Eligibility

The program will be available to any cloud company that is licensed for GravityZone Business Security Enterprise or the GravityZone a la carteEDR Cloud.

Submitting feedback

You can submit feedback by sending an email to xdr-eap@bitdefender.com.