Skip to main content

Osquery User Documentation

PurposeIf you ever need help or instructions on using the Osquery App or understanding how it works, make sure to consult this documentation. This resource is a helpful guide that contains all the information you need to use the Osquery App effectively.
CreatedOctober 18, 2023

What is osquery?​

Osquery is an open-source tool that empowers you to utilize SQL-like queries to retrieve and interact with information about the devices on your network. This tool offers detailed insights into the status and configurations of these devices, facilitating network monitoring and management of computers or servers.

For more information about osquery follow the links below:

Learn more about osquery documentation

Learn more about osquery schema

Features provided by Raven's Osquery App:​

  • Queries can be scheduled.

  • Interactive query console offers a SQL interface for experimenting with new queries and exploring your operating system.

  • Osquery is cross-platform, allowing you to build and use it on Windows, macOS, Ubuntu, CentOS, and other popular enterprise Linux distributions.

Raven's Osquery App Installation​

Here are example commands for installing the Osquery App on Linux, MacOS, and Windows.

Windows​

curl https://{CONFIGURATION}.apps.raven.dtact.com/install?target=linux|ps1

Linux​

curl https://{CONFIGURATION}.apps.raven.dtact.com/install?target=linux|bash

MacOS​

curl https://{CONFIGURATION}.apps.raven.dtact.com/install?target=linux|bash

The configuration for installing the Osquery App is a unique code that each organization will receive from the DTACT team.

Using Raven's Osquery App​

To access the Osquery App, simply select the Osquery App from the left side menu of the Raven portal. This will take you to the Osquery App with various sections:

  1. Dashboards

  2. Endpoints

  3. Live Query

  4. History

  5. Scheduled

  6. Events

  7. Logs

  8. Schema

  9. Documentation

These sections will be explained separately in the following sections of this documentation:

Dashboards​

This section is currently in development and aims to align these Dashboards with the others available in the Dashboard app.

Endpoints​

In this section, you can view all the devices within your network. Each device is described with details like name, OS, Osquery, computer name, and more. You can perform actions such as Query, edit, or delete each device by clicking the three-dotted button on the far right.

For more information on a specific device, double-clicking it opens a tab with a more detailed view, including previous queries and their statuses. You'll also find a "Query endpoints" button at the top right, allowing you to select devices and proceed to the "Live Query" section.

Live Query​

Here, you can perform queries on your devices. An excellent feature of the Live Query app is the ability to query multiple devices simultaneously by selecting the Endpoint bar and choosing the desired devices. You can write your queries or select predefined ones from the "Queries" button at the top right. Once queries are chosen, two buttons become available in the lower right corner. The first allows you to schedule the query by specifying the interval in seconds, and the second runs the query.

History​

Within this section, you will gain access to a comprehensive history of all the queries performed. Each query entry provides a summary of its actions, the query type, and the timestamp indicating when it was executed.

It's essential to note that queries fall into two main categories: distributed and scheduled.

  1. Distributed Queries: These queries are executed instantly, providing real-time results.

  2. Scheduled Queries: Scheduled queries are configured to run at specific intervals, allowing you to automate query execution based on your preferred timeframe.

Scheduled​

In this section, you will have an overview of all the scheduled queries, complete with vital information such as the Query ID, Query itself, query type, interval, creation timestamp, and its current activation status. This insight into scheduled queries helps you manage and keep track of your automated query executions efficiently.

Events​

Within this app section, you will gain visibility into all the events unfolding during the querying process. This comprehensive view of events allows you to closely monitor and assess the interactions taking place within your queries.

Logs​

The Osquery App daemon comes with a basic file logger. This means that it records and lets you know what is going on. Just like the settings, the information from this logger is written in a format called JSON.

When the system runs queries at specific times, the results are also recorded. You can find all these records on your computer at /var/log/osquery/osqueryd.results.log.

There are two kinds of logs in osquery:

  1. Status Logs: These tell you about the system's state like:

    • INFO

    • WARNING

    • ERROR

  2. Query Schedule Results Logs: These logs keep track of what happened when your system ran certain checks or queries.

In this part of the application, you can check and read all these logs to see what's been going on with your system.

For more information on Logs follow link below:

Learn more about Logs

Schema​

A schema describes the structure and organization of the data. When you explore a schema in a specific Osquery Table, it helps you understand how the data is laid out, making it easier to work with and analyze.

Documentation​

In this section, you will discover a collection of valuable references where you can access extensive information about osquery and Raven's Osquery App. These references serve as valuable resources for users seeking to deepen their understanding of osquery and the Osquery App.