Osquery Python API

3.1.1 · active · verified Thu Apr 16

The `osquery` Python library provides a robust API for interacting with the osquery daemon, enabling users to execute SQL queries against the operating system, manage osquery extensions, and handle distributed queries. It acts as a client to a running `osqueryd` instance. The current version is 3.1.1, released in December 2023, with releases occurring periodically to keep pace with the core osquery project.

Common errors

```
AttributeError: module 'osquery' has no attribute 'query'
```
cause Attempting to use the old direct query API (`osquery.query(...)`) after upgrading to version 2.0.0 or later.

fix Create an `osquery.Client()` instance and use `client.query(...)` instead. Example: `client = osquery.Client(); response = client.query(...)`
```
ModuleNotFoundError: No module named 'osquery.extensions'
```
cause Attempting to import `extensions` directly from `osquery` after upgrading to version 3.0.0 or later.

fix Update the import path to `from osquery.api import extensions`.
```
ConnectionRefusedError: [Errno 111] Connection refused
```
cause The osquery daemon (`osqueryd`) is not running or is not configured to listen on the default socket path, or the Python process lacks permissions to connect.

fix Verify that `osqueryd` is running. Check its configuration for the socket path (e.g., `osqueryd --socket-path=/path/to/socket`). Ensure the Python process has read/write access to the socket file.
```
FileNotFoundError: [Errno 2] No such file or directory: '/var/osquery/osquery.em'
```
cause The osquery daemon (`osqueryd`) is not running, or it's configured to use a different socket path, or the default path (`/var/osquery/osquery.em`) does not exist/is inaccessible.

fix Ensure `osqueryd` is running and its socket file exists at the expected location. If a custom socket path is used, ensure the Python client is configured to connect to that path (e.g., `client = osquery.Client(path='/custom/socket.path')`).

Warnings

breaking The primary API for running queries changed from direct `osquery.query()` calls to using an `osquery.Client()` instance.
Fix: Initialize `client = osquery.Client()` and then call `client.query(...)`.
breaking The `osquery.extensions` module was moved to `osquery.api.extensions` to better align with the core C++ project structure.
Fix: Update imports from `from osquery import extensions` to `from osquery.api import extensions`.
gotcha The `osquery` Python library is a client to the `osqueryd` daemon. It requires a running `osqueryd` instance to function, typically communicating via a Unix socket. Without `osqueryd` running, all client operations will fail with connection errors.
Fix: Ensure the `osqueryd` daemon is installed, running, and its socket path is correctly configured and accessible by the Python process (e.g., `/var/osquery/osquery.em` on Linux/macOS). If a custom socket path is used, pass it to `osquery.Client(path='...')`.

Install

pip install osquery Install osquery Python library

Imports

Client
wrong:
```
import osquery
response = osquery.query('...')
```
correct:
```
import osquery
client = osquery.Client()
```
Prior to v2.0.0, queries were made directly via `osquery.query()`. From v2.0.0 onwards, an `osquery.Client()` instance is required.
extensions
wrong:
```
from osquery import extensions
```
correct:
```
from osquery.api import extensions
```
From v3.0.0, the `extensions` module was moved to `osquery.api.extensions` to better align with the C++ structure.

Quickstart

This quickstart demonstrates how to initialize an osquery client and execute a basic SQL query. It expects an osquery daemon to be running and accessible via its default Unix socket. Error handling is included for common connection issues.

import osquery
import sys

try:
    # Create an osquery client. 
    # By default, it tries to connect to the osquery socket at /var/osquery/osquery.em
    # Ensure the osquery daemon is running and configured to use a socket.
    # If the daemon uses a non-default socket, pass the path: osquery.Client(path='/path/to/socket.em')
    client = osquery.Client()

    # Execute a simple SQL query
    query = "SELECT name, version FROM osquery_info;"
    response = client.query(query)

    print(f"Query: {query}")
    print(f"Status: {response.status}")
    if response.status:
        print(f"Results: {response.response}")
    else:
        print(f"Error: {response.error}")
        print("Make sure the osquery daemon is running and accessible.")

except ConnectionRefusedError:
    print("Error: Could not connect to osquery daemon. Is it running?", file=sys.stderr)
    sys.exit(1)
except FileNotFoundError:
    print("Error: Osquery socket not found. Is osquery daemon running and configured?", file=sys.stderr)
    sys.exit(1)
except Exception as e:
    print(f"An unexpected error occurred: {e}", file=sys.stderr)
    sys.exit(1)

view raw JSON →