Integration with osquery

[vikman90]

Related issue: #537.

We introduce a new module to run osquery and report scheduled results to the manager.

Main features

1. Enrich osquery configuration with pack files aggregation and agent labels as decorators.
2. Launch osquery daemon in background.
3. Monitor results file and send them to the manager.

Behavior

• If the osqueryd process gets down, the module will restart it automatically.
  • But if it runs during less than 10 seconds —likely due to a bad configuration or permissions issue—, the module gives up.
• If osquery is already running, the agents notifies it and reattempts each minute.
  • But the first time it does not report the error to the manager.
• When the agent gets stopped, it kills the osquery daemon.
• If the results log is not available, the module reattempts to open it with incremental delays of one second to one minute.
• If the JSON configuration includes C/C++ comments, the module will remove them.
• If the results log is shrunk, the module will go backward to the file begin.
• If the results log is rotated, the module will reopen it.
• If the agent labels contain single quotes ('), the module will escape them when inserting decorators.
• If the osquery daemon reports a warning or an error (via stderr), the module will send them to the manager (and produce alerts).

Extra features

• New option in rules <location> to filter events by osquery.
• Support folders in shared configuration. This makes easy to send pack folders to agents.
• Basic ruleset for osquery events and daemon logs.

New settings reference

<wodle name="osquery">
  <disabled>no</disabled>
  <run_daemon>yes</run_daemon>
  <bin_path>/usr/bin</bin_path>
  <log_path>/var/log/osquery/osqueryd.results.log</log_path>
  <config_path>/etc/osquery/osquery.conf</config_path>
  <add_labels>no</add_labels>
  <pack name="custom_pack">/path/to/custom_pack.conf</pack>
</wodle>

disabled

• yes prevents the module from running.
• no (default) enables the module.

run_daemon

• yes (default) makes the module run osqueryd as subprocess.
• no lets the module monitor the results log but does not run osquery.

bin_path

Full path to the folder that contains the osqueryd executable.

On Linux, if this value is undefined or empty, the module will find osqueryd in the system path.

Default value:

• Linux: (empty).
• Windows: C:\ProgramData\osquery\osqueryd.

log_path

Path to the results log written by osquery.

Default value:

• Linux: /var/log/osquery/osqueryd.results.log.
• Windows: C:\ProgramData\osquery\log\osqueryd.results.log.

config_path

Path to the osquery configuration file. This path can be relative to the folder where the Wazuh agent is running.

Default value:

• Linux: /etc/osquery/osquery.conf.
• Windows: C:\ProgramData\osquery\osquery.conf.

Suggested value to define in agent.conf:

<!-- Linux agent -->
<config_path>etc/shared/osquery.conf</config_path>
<!-- Windows agent -->
<config_path>shared\osquery.conf</config_path>

add_labels

• yes will add the agent labels defined as decorators.
• no (default) disables this feature.

pack

Add a query pack to the configuration. This option can be defined multiple times.

Testing items

• Enable/disable daemon.
• Invalid configuration. The module should log a warning and continue.
• Pack file definitions.
• Pack folder definition: <pack name="*">/usr/share/osquery/packs/*</pack>.
• Enrich existing decorators with agent labels.
• Add labels, no previous decorators defined.
• Combine <add_labels> and <pack> options.
• Invalid permissions (owner) for osqueryd binary. It should log an error and stop.
• Osqueryd already running when agent is started. It should log a message every minute.
• Restart Wazuh agent. Maybe it tries to start osqueryd before the previous process dies. It should reattempt to run one minute later.
• Invalid path for <log_path> or unexisting log file. The module should reattempt after one second, two, three, up to one minute delay.
• Truncate results log (echo -n > osquery.results.log). The module should go back to the file begin, no data lost.
• Rotate results log (rm osquery.results.log). The module should finish reading the current file and reload the new one, no data lost.
• Add query pack folder to a shared folder. That folder should appear in the agent.
• Agent labels with single quotes: <label key="node">Node for 'nginx'</label>. No SQL code injection.
• Insert C/C++ comments to JSON configuration, no content between the line starting and the comment (only spaces). The module should be able to insert decorators and packs.
• Kill osqueryd while being run by the agent. The module should restart it, if and only if it ran during 10 seconds at less.
• Unexisting folder /var/osquery. The module should report the error and the manager should create an alert.
• Declaring osquery module multiple times, for example, one in ossec.conf and another in agent.conf. Only the last one applies.
• Define an unexisting configuration file having <add_labels> disabled and no <pack> stanzas. The module should log it, wait 10 minutes and retry.

[vikman90]

Known issues:

• The module won't add a query pack folder (item 4).
• The module inserts all labels, including hidden ones (item 5).
• There are some cases in with the module restarts osquery although it has been running less than 10 seconds (item 17).
• Osquery will accept silently an unexisting configuration file. Test file before running osquery (item 20).

Thanks to @chemamartinez, @RaulMartinPineda, and @TJOSERAFAEL for this report.

[vikman90]

Issue update:

The module won't add a query pack folder (item 4)

False positive. We were using this configuration:

<pack name="*">/path/to/packs</pack>

The correct configuration is:

<pack name="*">/path/to/packs/*</pack>

However, commit 54e67bc makes the module check this condition.

The module inserts all labels, including hidden ones (item 5)

Fixed: a81b8a6

There are some cases in with the module restarts osquery although it has been running less than 10 seconds (item 17)

False positive. The agent was not connected, so the launcher thread got blocked until it could send the stdout. When that occurred, more than 10 seconds have passed and the module restarted the daemon.

Osquery will accept silently an unexisting configuration file (item 20)

Fixed: c375723

[RaulMartinPineda]

It's not possible to delete the file from osquery.results.log while the osquery daemon is running on windows, so we cannot truncate the log.

[vikman90]

Fixed: c9cc89e

Thanks @RaulMartinPineda for reporting!