Docs

osquery is an open source tool created by Facebook for querying various information about the state of machines. This includes information like:

• Running processes

• Kernel modules loaded

• Active user accounts

• Active network connections

and much more. osquery exposes an operating system as a high-performance relational database and allows querying it using SQL statements.

osquery is currently available for the following operating systems:

• Linux

• Windows

• OS X

• FreeBSD

It can be installed by following the instructions on the osquery downloads page: https://osquery.io/downloads/. Alternatively, the osqueryi binary can simply be copied to /usr/bin.

Running queries manually on the host where osqueryi is installed is easy. Simply run the osqueryi command which enters the interactive query tool, then enter the query, followed by a semicolon:

$ osqueryi
Using a virtual database. Need help, type '.help'
osquery> select value as string_value1 from cpuid where feature="product_name";
+------------------------------------------+
| string_value1                            |
+------------------------------------------+
| Dual-Core AMD Opteron(tm) Processor 1218 |
+------------------------------------------+
osquery> .quit

Find more information on osquery here: https://osquery.readthedocs.io/en/stable/.

Agent OsQuery detail

Agent OsQuery parameters

The Tags dropdown list allows entering pre-defined variables into the fields above, e.g. $NAME$ for the name of the job.

The examples section below lists some of the queries that can be used. The output returned by the query must be mapped to Return values and String values in the correct order.

Alternatively, the order of the returned values and strings can be influenced by adapting the query to provide the expected value & string names, e.g. the following query will map the memory_free value to the first Return value and memory_total to the second Return value:

select memory_total as return_value2, memory_free as return_value1 from memory_info

The following query returns two String values in a specific order:

select feature as string_value1, value as string_value2 from cpuid limit 1

However, the Return values and String values must still be configured in the job's Job parameters section to appear in the job's Values section.

Agent OsQuery values and alarm limits

Agent OsQuery examples

Example 1 - Query the CPU model

This requires the following String value to be configured:

Output 1

Example 2 - Query total and free memory

This requires the following 2 Return values to be configured:

The Unit contains the Return value's name, a Unit and a divisor, since osquery returns the values in bytes:

Output 2

Additional example queries

Query	Description	Example output
select username,description,directory from users where username like '%eranger'	Read user information
select weekday, day, month, year, unix_time from time	Read system time
select count(pid) as total, name from processes group by name order by total desc limit 10	Return process count, name for the top 10 most active processes
select * from uptime	Return system uptime