Osquery

Osquery is an open source tool that lets you query operating systems, like a database, providing you with visibility into your infrastructure and operating systems. Using basic SQL commands, you can ask questions about devices, such as servers, Docker containers, and computers running Linux, macOS, or Windows. The extensive schema helps with a variety of use cases, including vulnerability detection, compliance monitoring, incident investigations, and more.

With Osquery, you can:

Osquery results are stored in Elasticsearch, so that you can search, analyze, and visualize Osquery data in Kibana.

Osquery is powered by the Osquery Manager integration. For information on how to set up Osquery Manager, refer to Manage the integration.

To use Osquery Manager, you must be assigned to a role with the following privileges:

To inspect a host or test queries you want to schedule, run a query against one or more agents or policies, and view the results.

To view a history of the past queries you have run, open the Live queries history.

Group and schedule queries to run on a specified interval, in seconds. For example, you might create a group that checks for IT compliance-type issues, and another group that monitors for evidence of malware.

When you schedule queries, you can optionally map query results to fields in the Elastic Common Schema (ECS), which standardizes your Osquery data for use across detections, machine learning, and any other areas that rely on ECS-compliant data. The query results include the original osquery.<field> and the mapped ECS field. For example, if you update a query to map osquery.name to user.name, the query results include both fields.

When mapping fields:

Add or edit saved queries to the Saved queries tab.

A query can have the following status:

For the fields that can be returned in Osquery results, refer to exported fields. Scheduled Osquery results can also include ECS fields, if the query has a defined ECS mapping.

Osquery responses include the following information:

The following example shows a successful Osquery result:

{
  "_index": ".ds-logs-osquery_manager.result-default-2021.04.12-2021.04.12-000001",
  "_id": "R3ZwxngBKwN-X8eyQbxy",
  "_version": 1,
  "_score": null,
  "fields": {
    "osquery.seconds": [
      "7"
    ],
    "action_data.id": [
      "72d3ec71-7635-461e-a15d-f728819ae27f"
    ],
    "osquery.seconds.number": [
      7
    ],
    "osquery.hours.number": [
      6
    ],
    "host.hostname": [
      "MacBook-Pro.local"
    ],
    "type": [
      "MacBook-Pro.local"
    ],
    "host.mac": [
      "ad:de:48:00:12:22",
      "a6:83:e7:cb:91:ee"
    ],
    "osquery.total_seconds.number": [
      1060627
    ],
    "host.os.build": [
      "20D91"
    ],
    "host.ip": [
      "192.168.31.171",
      "fe80::b5b1:39ff:faa1:3b39"
    ],
    "agent.type": [
      "osquerybeat"
    ],
    "action_data.query": [
      "select * from uptime;"
    ],
    "osquery.minutes": [
      "37"
    ],
    "action_id": [
      "5099c02d-bd6d-4b88-af90-d80dcdc945df"
    ],
    "host.os.version": [
      "10.16"
    ],
    "host.os.kernel": [
      "20.3.0"
    ],
    "host.os.name": [
      "Mac OS X"
    ],
    "agent.name": [
      "MacBook-Pro.local"
    ],
    "host.name": [
      "MacBook-Pro.local"
    ],
    "osquery.total_seconds": [
      "1060627"
    ],
    "host.id": [
      "155D977D-8EA8-5BDE-94A2-D78A7B545198"
    ],
    "osquery.hours": [
      "6"
    ],
    "osquery.days": [
      "12"
    ],
    "host.os.type": [
      "macos"
    ],
    "osquery.days.number": [
      12
    ],
    "host.architecture": [
      "x86_64"
    ],
    "@timestamp": [
      "2021-04-12T14:15:45.060Z"
    ],
    "agent.id": [
      "196a0086-a612-48b1-930a-300565b3efaf"
    ],
    "host.os.platform": [
      "darwin"
    ],
    "ecs.version": [
      "1.8.0"
    ],
    "agent.ephemeral_id": [
      "5cb88e34-50fe-4c13-b81c-d2b7187505ea"
    ],
    "agent.version": [
      "7.13.0"
    ],
    "host.os.family": [
      "darwin"
    ],
    "osquery.minutes.number": [
      37
    ]
  }
}

The following is an example of an error response for an undefined action query:

{
  "_index": ".ds-.fleet-actions-results-2021.04.10-000001",
  "_id": "qm7mvHgBKwN-X8eyYB1x",
  "_version": 1,
  "_score": null,
  "fields": {
    "completed_at": [
      "2021-04-10T17:48:32.268Z"
    ],
    "error.keyword": [
      "action undefined"
    ],
    "@timestamp": [
      "2021-04-10T17:48:32.000Z"
    ],
    "action_data.query": [
      "select * from uptime;"
    ],
    "action_data.id": [
      "2c95bb2c-8ab6-4e8c-ac01-a1abb693ea00"
    ],
    "agent_id": [
      "c21b4c9c-6f36-49f0-8b60-08490fc619ce"
    ],
    "action_id": [
      "53454d3b-c8cd-4a50-b5b4-f85da17b4be2"
    ],
    "started_at": [
      "2021-04-10T17:48:32.267Z"
    ],
    "error": [
      "action undefined"
    ]
  }
}

Depending on your subscription level, you can further customize the sub-feature privileges for Osquery Manager. These include options to grant specific access for running live queries, running saved queries, saving queries, and scheduling queries. For example, you can create roles for users who can only run live or saved queries, but who cannot save or schedule queries. This is useful for teams who need in-depth and detailed control.

The Osquery version available on an Elastic Agent is associated to the version of Osquery Beat on the Agent. To get the latest version of Osquery Beat, upgrade your Elastic Agent.

If you encounter issues with Osquery Manager, find the relevant logs for the Elastic Agent and Osquerybeat in the installed agent directory, then adjust the agent path for your setup.

The relevant logs look similar to the following example paths:

`/data/elastic-agent-054e22/logs/elastic-agent-json.log-*`
`/data/elastic-agent-054e22/logs/default/osquerybeat-json.log`

To get more details in the logs, change the agent logging level to debug: