Custom Osquery Extensions
Relevant source files
The following files were used as context for generating this wiki page:
Custom Osquery Extensions allow users to extend the core capabilities of osquery by adding new tables and functionality not found in the standard distribution. Within the Fleet ecosystem, these extensions enable IT and security teams to collect specialized telemetry, such as macOS compatibility data or snap package information on Linux, and integrate it directly into Fleet's reporting and policy engines.
The deployment of custom extensions involves distributing a binary to target hosts and configuring the osquery extension loader to recognize these new capabilities. This process is managed alongside Orbit, Fleet's osquery intermediate agent, which handles the lifecycle of the osquery process and its associated extensions.
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:1-10, articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:65-73
Deployment and Configuration Lifecycle
Deploying a custom extension requires a structured approach to ensure the binary is correctly recognized by the osquery process managed by Orbit.
Binary Distribution and Permissions
The extension binary must be deployed to the target filesystem using standard package managers (.pkg, .msi, .deb, .rpm) or scripts. For security and execution reliability, specific ownership and permissions must be maintained:
- Ownership: The file should be owned by
root:wheel(macOS) orroot:admin(Linux). - Permissions: Execute permissions are typically set to
755.
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:12-25
The Extensions Loader
The extensions.load file serves as the configuration bridge. This text file contains absolute paths to custom extension binaries, with one entry per line. It is typically located in /var/osquery/ or /etc/osquery/ depending on the operating system.
/usr/local/bin/my-custom-extension.ext
/opt/security/monitoring-extension.ext
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:27-37
Process Restart Flow
Once the binary and the loader configuration are in place, the Orbit agent must be restarted to initialize the new extensions.
The diagram shows the standard workflow for distributing and activating a custom extension across different operating systems.
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:39-53
Integration with Fleet Schema and Documentation
Custom extensions effectively add new tables to the osquery schema. Fleet provides mechanisms to document these additions so they are available in the UI and documentation.
Schema Documentation Template
When adding custom tables via extensions, documentation can be managed via YAML files that override or extend the existing schema. This metadata includes table names, evented status, descriptions, and column details.
| Field | Type | Description |
|---|---|---|
name | String | Unique identifier for the table (required) |
evented | Boolean | Indicates if the table is an evented table |
description | String | Markdown-supported description of the table's purpose |
examples | String | Sample SQL queries using the table |
columns | Array | List of column objects containing name, type, and description |
Sources: schema/README.md:21-36, website/scripts/build-static-content.js:560-575
Data Processing and UI Rendering
The project uses scripts like build-static-content.js to parse these schemas and generate HTML partials for the website. This allows custom extension tables to be documented with syntax highlighting and platform-specific availability notes (e.g., macOS, Windows, Linux, ChromeOS).
Sources: website/scripts/build-static-content.js:580-600
Testing and Security Best Practices
Custom extensions run with high privileges and interact directly with system resources, requiring rigorous testing and security audits.
Local Verification
Before broad deployment via Fleet, extensions should be tested locally using the Orbit shell to ensure the SQL queries return the expected data.
sudo /path/to/orbit shell -- --extension /path/to/extension.ext
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:60-63
Security Requirements
- Open Source Priority: Fleet recommends using open-source extensions to allow for security audits and code transparency.
- Full Disk Access (FDA): Some extensions may require Full Disk Access on macOS to read specific system paths. These should be labeled as
(FDA Required)in Fleet policies. - Fleetd Integration: Certain custom tables are provided by
fleetd(Fleet's specific distribution of osquery and Orbit) and may have specific caveats, such as scope limitations to the current console user.
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:55-58, ee/cis/CIS-BENCHMARKS.md:120-135, ee/cis/CIS-BENCHMARKS.md:170-175
Common Extension Examples
The following table highlights specific custom extensions used within the project context:
| Extension Name | Purpose | Link |
|---|---|---|
macos_compatibility | Provides macOS version compatibility snapshots for hardware | Source |
snap_packages | Collects Linux snap package data using syntax similar to deb_packages | Source |
Sources: articles/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide.md:65-73
Custom Osquery Extensions provide a powerful path for extensibility in Fleet, allowing for specialized data collection while leveraging the existing deployment and management infrastructure of Orbit and Fleet GitOps workflows.
Sources: tools/fleet-slackbot/system-prompt.js:150-180, ee/cis/CIS-BENCHMARKS.md:1-10