Osquery: The Definitive Handbook

Most endpoint tools answer the questions a vendor decided to ask. Osquery answers the questions you ask.

Osquery is an open source agent that exposes an operating system as a relational database. Processes, open sockets, installed packages, kernel modules, users, browser extensions, and hundreds of other pieces of system state become SQL tables you can query on demand or on a schedule. One agent, one query language, on Windows, macOS, and Linux. That is the entire pitch, and it has held up for more than a decade of production use.

This handbook is the hub for our osquery cluster. It covers what osquery is, how it works, where it fits in a security program, how to run it at fleet scale, and where it stops. Each section links to a deeper guide when one exists.

What is osquery?

Osquery is an instrumentation framework created at Facebook and released as open source on October 29, 2014. Windows support arrived with version 2.0 in 2016, and stewardship moved to the Linux Foundation in 2019, which matters for buyers who worry about single vendor control of critical agents. The project remains actively maintained. Version 5.23.1 shipped in June 2026 with security fixes to the Windows processes and authenticode tables, which tells you two things: the project patches itself, and even visibility agents have an attack surface.

The core idea is simple. Instead of writing a custom parser for every OS artifact, osquery maps each artifact into a virtual table. Want every process bound to a network port? That is a two table join, not a script. If you are starting from zero, read our companion piece, What is osquery? The SQL framework for endpoint visibility, which walks through the concept in plain terms.

Where did osquery come from?

The project's history matters because agent longevity matters. Security teams have been burned by agents that were acquired, abandoned, or relicensed, and every one of those events forced a fleet migration someone had to pay for.

Facebook built osquery to monitor its own infrastructure and released it publicly in October 2014, initially for Linux and macOS. Adoption came fast: Airbnb, Dropbox, Netflix, Etsy, and Uber brought it into production within the first years, per the osquery project site. Version 2.0 added full Windows support in October 2016, which turned a Unix tool into a fleet standard. In 2019 Facebook transferred the project to the Linux Foundation, where an independent foundation with engineers from multiple security vendors now stewards it.

The version 5 line, launched in late 2021, was the last major architectural shift: EndpointSecurity on macOS replaced the deprecated kernel extension approach, keeping the agent viable on modern Apple hardware. Since then the cadence has been steady maintenance and hardening. More than a decade in, with no single vendor owning it, osquery is about as safe a bet as endpoint agents get.

How does osquery work?

Osquery embeds a SQLite query engine, but almost nothing is stored in a database. Tables are virtual. When a query touches the processes table, osquery reads live process state from the kernel at execution time. The SQL layer is an interface, not a datastore. You get the expressive power of joins, filters, and aggregates over state that is generated the moment you ask.

There are two ways to run it:

• osqueryi is the interactive shell. An analyst opens it during an investigation and asks questions directly. No server, no configuration, results in seconds.
• osqueryd is the daemon. It runs a schedule of queries, computes differential results (what changed since the last run), and writes them to log pipelines. This is the mode that powers fleet visibility.

A query like this is the canonical first example, straight from the official osquery documentation:

That one statement answers a question security teams pay entire product categories to answer: what is actually listening on this machine, and what binary is behind it. No signature update required. No vendor roadmap request. Just a question, asked in a language most engineers already know.

Which tables matter most?

The schema ships with over 280 tables, and the honest answer is that a dozen of them do most of the work. The full list lives in the osquery schema reference, and our breakdown of the 25 most useful osquery tables organizes them by the question each one answers. The workhorses:

Event tables deserve a note. Since version 5.0, osquery consumes Apple's EndpointSecurity framework on macOS, replacing the deprecated kernel audit trail, as covered in the Trail of Bits announcement of osquery 5. Evented tables record things as they happen instead of sampling state on an interval, which closes the gap where short lived processes hide. For a working set of scheduled queries, see our library of osquery queries every security team should run.

What do useful osquery queries look like?

The join above is a pattern, and the pattern generalizes. Most valuable queries take one of three shapes: inventory, correlation, or drift.

Inventory queries enumerate state. What software is installed, what users exist, what certificates are trusted. On a Debian host, the entire installed package list with versions is one line:

Correlation queries join tables to expose relationships. The listening ports example correlates network exposure with process identity. Another classic finds processes running from suspicious locations:

Nothing legitimate should execute from /tmp on most server fleets. When that query returns rows, someone should look at them the same day.

Drift queries compare current state against an expectation. Scheduled in osqueryd with differential logging, they only report when something changes. A query watching authorized_keys or crontab entries is silent for months, then fires the day an attacker establishes persistence. That silence is the feature. We wrote up a real case where a modified crontab became the pivot point in anatomy of a lateral movement attack through a misconfigured crontab.

Two practical rules keep queries healthy. First, always filter early: a WHERE clause on an indexed column costs little, while a full table scan of file across a filesystem can pin a disk for minutes. Second, schedule at the slowest interval that still answers the question. Package inventory changes a few times a week, so querying it every 30 seconds burns 2,880 executions a day to learn nothing. Once an hour is 24. Same information, less than 1 percent of the cost.

How do you run osquery at fleet scale?

A single host is trivial. Five thousand hosts is an engineering problem with three parts: distribution, configuration, and results handling.

Distribution means packages and a management plane. Osquery publishes signed packages for every major platform (our guide to installing osquery on Windows, Linux, and macOS covers each one, including the flags that matter). Configuration and results are where a fleet manager earns its keep. Open source options like Fleet exist precisely because pushing query packs to thousands of hosts by hand does not scale, and commercial platforms build on the same agent.

Performance anxiety is the most common objection, and it is mostly solved by defaults. The osqueryd watchdog kills and restarts any worker that exceeds 200MB of memory or sustains more than 10 percent CPU, per the command line flags documentation. A poorly written query gets its process terminated, not your database server. Teams that still get paged about the agent almost always disabled the watchdog or scheduled a heavy query every 10 seconds. The tool has guardrails. Use them.

Do the math on what the alternative costs. A fleet of 5,000 hosts checked quarterly by manual audit, at even five minutes per host, is 416 hours of work per quarter. That is a full engineer doing nothing but inventory. An osqueryd schedule produces the same answer continuously, for the cost of writing the query once.

Results handling deserves more attention than it usually gets. Osqueryd ships with logger plugins for local filesystem, TLS endpoints, AWS Kinesis and Firehose, and syslog. The common production pattern is TLS to a fleet manager or a log pipeline, then into whatever your team already uses for analysis. Budget for volume before you turn on evented tables: process events on a busy build server can generate more log lines than the rest of the fleet combined. Start with snapshot queries on generous intervals, measure, then add events where the detection value justifies the storage bill.

Configuration management follows the same discipline as any other agent. Query packs (JSON bundles of related queries with their own schedules) are the unit of deployment. The community packs covering incident response, vulnerability management, and compliance are a reasonable starting point, but treat them as templates rather than gospel. Half the queries in any generic pack will be irrelevant to your environment, and irrelevant scheduled queries are pure waste.

Osquery for vulnerability management

This is where osquery moves from useful to strategic. The 2026 Verizon Data Breach Investigations Report found that vulnerability exploitation became the top initial access vector at 31 percent of breaches, up from 20 percent the prior year, and displacing credential abuse for the first time in the report's history. Attackers are winning the race to your unpatched software. The defense depends on knowing, at any moment, what is installed and what is exposed.

Scanners answer that question on a schedule, from the outside, by probing. Osquery answers it from the inside, by reading package databases, loaded libraries, listening sockets, and configuration files directly. The difference shows up in triage. A scanner reports that a host has a vulnerable OpenSSL version. Osquery can tell you whether any running process actually loaded that library, whether the service is listening beyond localhost, and whether a mitigating control is in place. One finding is a guess about risk. The other is evidence.

Evidence is also the raw material for judgment. Version matching alone floods teams with findings that are technically present and practically irrelevant, a failure mode we cover in how to reduce false positives in vulnerability management. Context from the endpoint is what separates the two piles.

The workflow looks like this in practice. Scheduled queries maintain a live software inventory per host. That inventory gets matched against advisory data to produce candidate findings. Then endpoint context does the triage a severity score cannot: is the vulnerable package actually loaded by a running process, is the service reachable beyond the host, does the host hold anything worth stealing. Scoring frameworks help rank what remains (we compared them in why CVSS alone cannot tell you which vulnerabilities matter), but the ranking is only as good as the state data underneath it. Osquery is the cheapest reliable source of that state data currently available.

There is also a compliance dividend. The same queries that feed vulnerability triage produce evidence for auditors: encryption status, screen lock policy, patch level, unauthorized software. Teams that already collect this for security stop paying twice for the same facts at audit time.

How does osquery compare to EDR and scanners?

The question every buyer asks is whether osquery replaces something they already pay for. Usually the answer is no, and the overlap is smaller than the marketing on all sides suggests.

Against EDR: an EDR agent is an opinionated detection product. It ships with behavioral rules, a response capability, and a vendor's judgment baked in. Osquery ships with none of that. It is a mechanism, not a policy. The practical consequence is that EDR finds what its vendor knows to look for, while osquery finds whatever you know to ask about. Teams with strong detection engineering get enormous value from that freedom. Teams without it get an empty SQL prompt.

Against vulnerability scanners: a network scanner infers what is installed by probing from outside, which produces the false positive problem every practitioner knows. Osquery reads ground truth from inside the host. It will not probe a web application or fuzz an API, so it does not replace application scanning. For OS and package level exposure, inside data beats outside inference on both accuracy and freshness.

Against configuration management tools: Ansible, Chef, and Puppet can all report state, but they report the state they manage. Osquery sees everything, including the things nobody declared. Configuration drift lives exactly in that gap, a problem we unpack in how configuration drift quietly changes vulnerability priority.

What osquery does not do

Honest scoping prevents bad deployments. Osquery is a visibility agent, and only that.

• It does not block anything. There is no prevention capability. It observes and reports. If you need inline blocking, that is an EDR job, and the two coexist well.
• It does not fix anything. Osquery can prove a host is misconfigured. Remediation is a separate workflow with separate tooling and separate approval requirements.
• It does not interpret anything. Query results are rows, not conclusions. Ten thousand hosts produce a firehose of differential logs, and someone or something still has to decide which rows matter.

That last gap is the expensive one. Collection got easy. Judgment did not. A team of five analysts spending six hours a week each reviewing telemetry burns 30 skilled hours weekly on reading rows, and most rows are noise.

There is a fourth gap worth naming: ownership. Osquery has no vendor to call when the schedule breaks or the log pipeline backs up. That is the trade you make for a free, open agent, and it is a fine trade for teams that treat the deployment as software they operate. It is a bad trade for teams that wanted a product. Know which team you are before you commit, or buy a platform that operates it for you.

A 90 day rollout plan that works

Most failed osquery deployments fail the same way: a team installs the agent everywhere, turns on a giant community query pack, drowns in logs for three weeks, and quietly turns it off. The fix is sequencing.

Days 1 to 30: run osqueryi on a handful of representative hosts. One server, one developer laptop, one anything else you own a lot of. Write ten queries that answer questions your team actually asked last quarter. Do not ship a single log yet. The goal is fluency, not coverage.

Days 31 to 60: promote the queries that earned their keep into an osqueryd schedule on a pilot group, 50 to 100 hosts. Stand up a fleet manager. Watch the log volume and the watchdog counters. Tune intervals until the pipeline is boring. Boring is the goal state for telemetry infrastructure.

Days 61 to 90: expand to the fleet in waves, add differential queries for persistence and exposure, and wire results into the place your team already looks every day. If results land in a dashboard nobody opens, the deployment is decorative. By day 90 you should be able to answer an auditor's inventory question or an incident responder's "where else does this process run" question in minutes, and you should have deleted at least a third of the queries you started with.

The osquery cluster: where to go next

This handbook anchors a growing set of focused guides:

• What is osquery? The plain language introduction for newcomers and the people who approve budgets.
• How to install osquery on Windows, Linux, and macOS. Package managers, service setup, and the first queries to run.
• Osquery queries every security team should run. A working library for detection and compliance.
• Deeper guides on tables, query packs, fleet management, performance tuning, and threat hunting are planned for this cluster and will be linked here as they publish.

Where Artemes AI fits

Artemes AI is built on the premise that collection is a solved problem and judgment is not. Our platform combines deep endpoint context (running processes, exposure, package state, configuration) with an AI engine that reads that context to decide which findings are real, then produces exact remediation commands for human approval. Tools like osquery answer what is true on a host. The open question is what happens to those answers next, and that is the layer Artemes was built for.

Frequently asked questions

What platforms does osquery support?

Windows, macOS, and Linux across the mainstream distributions, with signed packages published for each. The schema is mostly shared, with platform specific tables where the operating systems differ (registry on Windows, launchd on macOS, systemd units on Linux). Query portability is high enough that one schedule can serve a mixed fleet with light per platform tailoring.

Is osquery free?

Yes. Osquery is open source under Apache and GPL licensing, hosted by the Linux Foundation. You pay nothing for the agent. Real costs live in deployment, query engineering, and analyzing the output.

Does osquery replace EDR?

No. Osquery observes; EDR prevents and responds. Many mature teams run both: EDR for blocking known bad behavior, osquery for asking questions EDR vendors did not anticipate.

How much overhead does the osquery agent add?

With default watchdog settings, the worker is capped at 200MB of memory and 10 percent sustained CPU, and typical scheduled workloads sit far below both ceilings. Overhead problems almost always trace to a specific expensive query, not the agent itself.

Can osquery query custom application data?

Yes, two ways. Automatic Table Construction (ATC) exposes any SQLite database on the host as a queryable table through configuration alone, which covers a surprising amount of application state. For everything else, the extensions interface lets you write custom tables in several languages and run them alongside the core agent.

Who maintains osquery?

The osquery Foundation under the Linux Foundation, with contributors from multiple security companies. Facebook created it in 2014 and transferred stewardship in 2019, and releases have continued steadily since, including 5.23.1 in June 2026.

The takeaway

If you run more than a handful of endpoints and cannot answer "what is listening on port 443 across the fleet right now" in under a minute, deploy osquery this quarter. Start with osqueryi on one host, promote a dozen queries to an osqueryd schedule, and put a fleet manager in front of it before you cross a hundred hosts. The agent is free and the schema is documented. The only real decision is what you will do with the answers, and that decision is the difference between telemetry and security.