Install, Validate, and Integrate Osquery on Ubuntu 26.04

Introduction

This guide builds an endpoint-telemetry path from Ubuntu through Osquery and the Wazuh agent to the Wazuh manager and Threat Hunting interface. It emphasizes validation at each boundary so students can distinguish installation success from end-to-end telemetry success.

Purpose and Scope

Use the procedure on the validated Ubuntu 26.04 x86_64 lab endpoint. It covers repository verification, Osquery installation, configuration, scheduled queries, Wazuh wodle integration, event-volume tuning, validation, and rollback.

Chapter and Lab Alignment

1. Completion Status

Yes - the Ubuntu endpoint installation is complete. The workflow was validated end-to-end:

• Official Osquery APT repository configured and package candidate verified.

• Osquery 5.23.1 installed; osqueryi and osqueryd binaries validated.

• Interactive system and process queries returned data from UB2604.

• Osquery JSON configuration created and validated.

• Filesystem logging configured with an Osquery flagfile.

• Wazuh Osquery wodle enabled with run_daemon=yes.

• Wazuh successfully started osqueryd and followed osqueryd.results.log.

• Threat Hunting displayed Osquery events for agent u2604 using rule group osquery.

2. Pre-Installation Checks

Confirm the operating system and architecture:

cat /etc/os-release
uname -m

Validated result: Ubuntu 26.04 LTS and x86_64.

Confirm Osquery is not already installed:

which osqueryi
apt-cache search osquery

Before installation, which osqueryi returned no path.

3. Verify the Osquery Repository

The repository key and source were checked before installation.

ls -lh /usr/share/keyrings/
gpg --show-keys /usr/share/keyrings/osquery.asc
cat /etc/apt/sources.list.d/osquery.list

Validated source entry:

deb [arch=amd64 signed-by=/usr/share/keyrings/osquery.asc] https://pkg.osquery.io/deb deb main

Refresh APT:

apt update

Useful checks:

apt list --upgradable
apt-mark showhold
apt -s full-upgrade

4. Verify and Install Osquery

apt-cache policy osquery

Validated candidate:

Candidate: 5.23.1-1.linux

Install:

apt install osquery

5. Validate the Installation

which osqueryi
which osqueryd
osqueryi --version
osqueryd --version

Validated:

/usr/bin/osqueryi
/usr/bin/osqueryd
osqueryi version 5.23.1
osqueryd version 5.23.1

6. Test Osquery Interactively

osqueryi "SELECT hostname, cpu_brand, physical_memory FROM system_info;"

osqueryi "SELECT pid, name, path FROM processes LIMIT 10;"

These tests confirmed that Osquery could query host inventory and live processes on UB2604.

7. Inspect the Daemon and Package Defaults

systemctl status osqueryd --no-pager
systemctl is-enabled osqueryd
ls -la /etc/osquery/

Initial state: osqueryd.service existed but was disabled/inactive, and /etc/osquery was initially empty.

systemctl cat osqueryd
cat /etc/default/osqueryd

Validated package defaults:

FLAG_FILE="/etc/osquery/osquery.flags"
CONFIG_FILE="/etc/osquery/osquery.conf"
LOCAL_PIDFILE="/var/osquery/osqueryd.pidfile"
PIDFILE="/var/run/osqueryd.pidfile"

8. Back Up the Wazuh Agent Configuration

ls -lh /var/ossec/etc/ossec.conf
cp -a /var/ossec/etc/ossec.conf /var/ossec/etc/ossec.conf.pre-osquery
ls -lh /var/ossec/etc/ossec.conf*

9. Create /etc/osquery/osquery.conf

For the student lab, use reduced query intervals to limit endpoint and Wazuh index storage. The initial 60-second process/network schedule generated roughly 1,851 Osquery hits in the first hour, so the lab baseline was tuned.

{
  "options": {
    "logger_path": "/var/log/osquery",
    "disable_logging": "false"
  },

  "schedule": {
    "system_info": {
      "query": "SELECT hostname, cpu_brand, physical_memory FROM system_info;",
      "interval": 600
    },

    "logged_in_users": {
      "query": "SELECT user, tty, host, time FROM logged_in_users;",
      "interval": 300
    },

    "processes": {
      "query": "SELECT pid, parent, name, path, cmdline, uid, gid FROM processes;",
      "interval": 300
    },

    "listening_ports": {
      "query": "SELECT pid, port, protocol, address FROM listening_ports;",
      "interval": 300
    },

    "process_open_sockets": {
      "query": "SELECT p.pid, p.name, p.path, s.local_address, s.local_port, s.remote_address, s.remote_port, s.protocol FROM process_open_sockets s JOIN processes p ON s.pid = p.pid;",
      "interval": 300
    }
  }
}

10. Create /etc/osquery/osquery.flags

Osquery 5.23.1 warned that logger_plugin is a CLI-only flag when placed in the JSON configuration, so it was moved to the package flagfile.

--logger_plugin=filesystem
--logger_path=/var/log/osquery

mkdir -p /var/log/osquery
cat /etc/osquery/osquery.flags

11. Validate Osquery Configuration

Before Osquery is running:

osqueryd --config_path=/etc/osquery/osquery.conf --config_check

No output/fatal error indicates the configuration check completed cleanly.

systemctl stop wazuh-agent
ps -ef | grep '[o]squeryd'
osqueryd --config_path=/etc/osquery/osquery.conf --config_check
systemctl start wazuh-agent

12. Enable the Wazuh Osquery Wodle

The existing Wazuh agent configuration already contained an Osquery wodle. Enable it by changing disabled from yes to no.

<wodle name="osquery">
  <disabled>no</disabled>
  <run_daemon>yes</run_daemon>
  <log_path>/var/log/osquery/osqueryd.results.log</log_path>
  <config_path>/etc/osquery/osquery.conf</config_path>
  <add_labels>yes</add_labels>
</wodle>

A separate <localfile>{=html} block was not added; the Osquery wodle's log_path is used for this integration.

13. Validate and Restart Wazuh

/var/ossec/bin/wazuh-agentd -t
systemctl restart wazuh-agent
systemctl status wazuh-agent --no-pager

Validated Wazuh startup showed:

osqueryd started [version=5.23.1]

The Wazuh service process tree also showed /opt/osquery/bin/osqueryd running with /etc/osquery/osquery.conf.

14. Verify Osquery JSON Results

Do not type the log path by itself; Bash will try to execute it and return Permission denied. Read it with ls, tail, cat, or less.

ls -lh /var/log/osquery/osqueryd.results.log
tail -n 10 /var/log/osquery/osqueryd.results.log

Validated JSON contained scheduled results including processes and system_info. The file was actively growing.

15. Verify Wazuh Is Following the Results File

grep -a "2026/08/15" /var/ossec/logs/ossec.log | grep -i "osquery" | tail -n 50

Validated startup sequence:

wazuh-modulesd:osquery: INFO: Module started.
wazuh-modulesd:osquery: WARNING: Results file '/var/log/osquery/osqueryd.results.log' not available: No such file or directory (2). Retrying in 1 sec.
wazuh-modulesd:osquery: INFO: Following osquery results file '/var/log/osquery/osqueryd.results.log'.

The one-second missing-file warning occurred during startup before osqueryd created the results file; Wazuh followed it immediately afterward.

16. Validate in Wazuh Threat Hunting

In Wazuh Dashboard -> Threat Hunting -> Events, set a suitable time range (for example, Last 1 hour) and use:

agent.name:u2604 AND rule.groups:osquery

Validated dashboard results included:

• Agent name: u2604

• Rule description: osquery: processes query result

• Rule level: 3

• Rule ID: 24010

• Approximately 1,851 Osquery hits during the initial high-frequency configuration.

Useful pivots:

agent.name:u2604 AND rule.groups:osquery AND rule.description:"osquery: processes query result"

agent.name:u2604 AND rule.groups:osquery AND rule.description:"osquery: process_open_sockets query result"

agent.name:u2604 AND rule.groups:osquery AND rule.description:"osquery: listening_ports query result"

17. Student-Lab Storage Tuning

Reducing the schedule lowers both /var/log/osquery/osqueryd.results.log growth on the endpoint and event volume sent to the Wazuh indexer.

18. Final Validation Checklist

• Ubuntu reports x86_64.

• Osquery package is installed at version 5.23.1.

• osqueryi and osqueryd resolve and report the expected version.

• Interactive system_info and processes queries work.

• /etc/osquery/osquery.conf passes config_check.

• /etc/osquery/osquery.flags contains filesystem logger settings.

• Wazuh Osquery wodle is enabled and run_daemon is yes.

• Wazuh agent is active.

• osqueryd is running under Wazuh management.

• /var/log/osquery/osqueryd.results.log exists and contains JSON.

• ossec.log says Wazuh is following the Osquery results file.

• Threat Hunting returns agent.name:u2604 AND rule.groups:osquery.

• Student-lab query intervals are tuned to reduce disk/index growth.

19. Troubleshooting Quick Reference

20. Student-Lab Schedule Baseline

Validated environment: Ubuntu 26.04 LTS (x86_64), Wazuh agent 4.14.5, and Osquery 5.23.1. Final Dashboard validation used Wazuh agent name u2604 and Ubuntu hostname UB2604.

APT phasing: Six Ubuntu packages were reported as not upgrading because of phasing. apt-mark showhold returned no manually held packages, and apt -s full-upgrade proposed no upgrades or removals. The packages were not forced before installing Osquery.

Milestone backup: Keep the pre-Osquery copy until the endpoint and Dashboard have been validated. It provides a fast rollback point.

Important after integration: Once Wazuh is running osqueryd, a second osqueryd --config_check can encounter /var/osquery/osquery.db/LOCK. Do not delete the lock. Stop the Wazuh agent, verify osqueryd stopped, run the configuration check, and then start Wazuh again.

21. Technical Reference

• Osquery. (n.d.). Installing osquery on Linux. https://osquery.readthedocs.io/en/stable/installation/install-linux/