Fleet logo
Menu An icon indicating that interacting with this button will open the navigation menu.
Fleet logo An 'X' icon indicating that this can be interacted with to close the navigation menu.
Device management + MDM Orchestration + monitoring Software management + CVEs, usage, app library Integrations
Get started Built-in checks Raw data App library Tutorials & guides API SUPPORT Chat Contribute Release notes "Why is Fleet on my computer?" Get your license
Stories
What people are saying News Ask around Take a tour Meetups COMPANY Origins   (Fleet & osquery) The handbook Logos/artwork Why open source?
Pricing Try it yourself
{{thisPage.meta.articleTitle}}
search

Queries

{{articleSubtitle}}

| The author's GitHub profile picture

Noah Talerman

Share this article on Hacker News Share this article on LinkedIn Share this article on Twitter
Docs Docs REST API REST API Guides Guides Talk to an engineer Talk to an engineer

Queries

{{articleSubtitle}}

| The author's GitHub profile picture

Noah Talerman

Queries

Queries in Fleet allow you to ask questions to help you manage, monitor, and identify threats on your devices. This guide will walk you through how to create, schedule, and run a query.

An icon indicating that this section has important information

Note: Unless a logging infrastructure is configured on your Fleet server, osquery-related logs will be stored locally on each device. Read more here

An icon indicating that this section has important information

New users may find it helpful to start with Fleet's policies. You can find policies and queries from the community in Fleet's query library. To learn more about policies, see What are Fleet policies? and Understanding the intricacies of Fleet policies.

In this guide:

Create a query

How to create a query:

  1. In the top navigation, select Queries.

  2. Select Create new query to navigate to the query console.

  3. In the Query field, enter your query. Remember, you can find common queries in Fleet's library.

    An icon indicating that this section has important information

    Avoid using dot notation (".") for column names in your queries as it can cause results to render incorrectly in Fleet UI. Please see issue #15446 for more details.

  4. Select Save, enter a name and description for your query, select the frequency that the query should run at, and select Save query.

View a query report

How to view a query report:

  1. In the top navigation, select Queries.

  2. In the Queries table, find the query you'd like to run and select the query's name to navigate to the query console.

  3. If you want to download the query report, select Export results to save it as a CSV.

Fleet will store up to 1000 results for each scheduled query to give users a snapshot of query results. If the number of results for a scheduled query is below 1000, then the results will continuously get updated every time the hosts send results to Fleet.

An icon indicating that this section has important information

You can tell Fleet to store more than 1000 results in query reports by setting server_settings.query_report_cap via the Modify configuration API endpoint.

Persisting query reports within Fleet creates load on the database, so you'll want to monitor database load as you add queries. If needed, you can disable query reports either globally or per-query.

Run a query

Run a live query to get answers for all of your online hosts.

An icon indicating that this section has important information

Offline hosts won’t respond to a live query because they may be shut down, asleep, or not connected to the internet.

How to run a query:

  1. In the top navigation, select Queries.

  2. In the Queries table, find the query you'd like to run and select the query's name to navigate to the query console.

  3. Select Live query to navigate to the target picker. Select All hosts and select Run. This will run the query against all your hosts.

  4. If you want to download the live query results, select Export results to save it as a CSV.

An icon indicating that this section has important information

Fleet 4.24.0 and later versions provide notifications in the activity feed for live queries.

The query may take several seconds to complete because Fleet has to wait for the hosts to respond with results.

An icon indicating that this section has important information

Fleet's query response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.

Schedule a query

Fleet allows you to schedule queries to run at a set frequency. By default, queries that run on a schedule will only target platforms compatible with that query. This behavior can be overridden by setting the platforms in Advanced options when saving a query.

Scheduled queries will send data to Fleet and/or your log destination automatically. Query automations can be turned off in Advanced options or using the bulk query automations UI.

How to configure query automations in bulk:

Only users with the admin role can manage query automations.

  1. In the top navigation, select Queries.

  2. Select Manage automations.

  3. Check the box next to the queries you want to send data to your log destination, and select Save. (The frequency that queries run at is set when a query is created.)

An icon indicating that this section has important information

Note: When viewing a specific team in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed.

Further reading