{"id":8391,"library":"osquery","title":"Osquery Python API","description":"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.","status":"active","version":"3.1.1","language":"en","source_language":"en","source_url":"https://github.com/osquery/osquery-python","tags":["osquery","security","monitoring","api","system-introspection","sql","daemon"],"install":[{"cmd":"pip install osquery","lang":"bash","label":"Install osquery Python library"}],"dependencies":[],"imports":[{"note":"Prior to v2.0.0, queries were made directly via `osquery.query()`. From v2.0.0 onwards, an `osquery.Client()` instance is required.","wrong":"import osquery\nresponse = osquery.query('...')","symbol":"Client","correct":"import osquery\nclient = osquery.Client()"},{"note":"From v3.0.0, the `extensions` module was moved to `osquery.api.extensions` to better align with the C++ structure.","wrong":"from osquery import extensions","symbol":"extensions","correct":"from osquery.api import extensions"}],"quickstart":{"code":"import osquery\nimport sys\n\ntry:\n    # Create an osquery client. \n    # By default, it tries to connect to the osquery socket at /var/osquery/osquery.em\n    # Ensure the osquery daemon is running and configured to use a socket.\n    # If the daemon uses a non-default socket, pass the path: osquery.Client(path='/path/to/socket.em')\n    client = osquery.Client()\n\n    # Execute a simple SQL query\n    query = \"SELECT name, version FROM osquery_info;\"\n    response = client.query(query)\n\n    print(f\"Query: {query}\")\n    print(f\"Status: {response.status}\")\n    if response.status:\n        print(f\"Results: {response.response}\")\n    else:\n        print(f\"Error: {response.error}\")\n        print(\"Make sure the osquery daemon is running and accessible.\")\n\nexcept ConnectionRefusedError:\n    print(\"Error: Could not connect to osquery daemon. Is it running?\", file=sys.stderr)\n    sys.exit(1)\nexcept FileNotFoundError:\n    print(\"Error: Osquery socket not found. Is osquery daemon running and configured?\", file=sys.stderr)\n    sys.exit(1)\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\", file=sys.stderr)\n    sys.exit(1)","lang":"python","description":"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."},"warnings":[{"fix":"Initialize `client = osquery.Client()` and then call `client.query(...)`.","message":"The primary API for running queries changed from direct `osquery.query()` calls to using an `osquery.Client()` instance.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update imports from `from osquery import extensions` to `from osquery.api import extensions`.","message":"The `osquery.extensions` module was moved to `osquery.api.extensions` to better align with the core C++ project structure.","severity":"breaking","affected_versions":">=3.0.0"},{"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='...')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Create an `osquery.Client()` instance and use `client.query(...)` instead. Example: `client = osquery.Client(); response = client.query(...)`","cause":"Attempting to use the old direct query API (`osquery.query(...)`) after upgrading to version 2.0.0 or later.","error":"AttributeError: module 'osquery' has no attribute 'query'"},{"fix":"Update the import path to `from osquery.api import extensions`.","cause":"Attempting to import `extensions` directly from `osquery` after upgrading to version 3.0.0 or later.","error":"ModuleNotFoundError: No module named 'osquery.extensions'"},{"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.","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.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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')`).","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/var/osquery/osquery.em'"}]}