Osquery uses basic SQL commands to leverage a relational data-model to describe a device.
Agents - Deployment¶
To deploy an osquery agent to an endpoint, go to the Security Onion Console (SOC) Downloads page and download the proper osquery agent for the operating system of that endpoint. Use so-allow to allow the osquery agent to connect to port
8090 on the manager. Then install the osquery agent and it should check into the manager and start showing up in Fleet.
Osquery will attempt to connect to the Manager via the Manager’s IP or Hostname - whichever was selected during the Manager setup. If the hostname is used, the endpoints need to be able to resolve that hostname to the Manager’s IP. See this value by running the following command on the Manager:
sudo salt-call pillar.get global:url_base. If this value ever changes, the osquery packages under Downloads will need to be regenerated.
All the packages (except for the macOS PKG) are customized for the specific Grid they were downloaded from, and include all the necessary configuration to connect to that Grid. The macOS package is a stock Launcher package, and will require additional configuration once it has been deployed.
For macOS deployments, install the package and then configure the following:
/etc/so-launcher/secretwith the Fleet enroll secret. This can be found by running the following on the Manager:sudo salt-call pillar.get secrets:fleet_enroll-secret
/etc/so-launcher/launcher.flags- change the hostname to your Manager hostname, and change the port from
/etc/so-launcher/roots.pemwith the contents from the following file (on your Manager):
At this point, osquery should connect up to Fleet within a couple minutes - if not, try to manually restart the osquery agent on the macOS endpoint:sudo launchctl kickstart -k system/com.so-launcher.launcher
Agents - Updating¶
Security Onion uses Kolide Launcher as a management wrapper around Osquery. This allows for a simpler configuration as well as auto-updates of Launcher and Osquery from the Kolide TUF service. Launcher will check every hour to see if an update is available and, if so, will download and install it. This is the default configuration, but can be changed within the osquery Flags file.
In an airgap environment where the endpoints do not have Internet access, updated Osquery packages can be downloaded from the Security Onion Console and used to update the endpoints. Osquery packages are periodically updated on the Manager as new versions of Osquery are released.
Agents - Troubleshooting¶
Agent logs on Windows endpoints can be found under the Application channel in the Windows Eventlog - source is Launcher.
Agents - Regenerating Install Packages¶
To regenerate packages, run the following on the Manager (it will take up to 5 minutes to rebuild the packages):
sudo salt-call state.apply fleet.event_gen-packages
Hunt or Kibana¶
All osquery logs can be found by using the following query:
Kibana Dashboard: Host Data –> Modules/Osquery¶
This dashboard gives an overview of the osquery logs in the system. As long as the default osquery configuration is used, this dashboard should work out of the box regardless of how you schedule or name your queries and packs.
Shipping Windows Eventlogs¶
Windows Eventlogs from the local Windows system can be shipped with osquery to Security Onion. Current parsing support extends to core Windows Eventlog channels (
System ) as well as Sysmon under the default channel location. These logs will show up in Security Onion as
event.dataset: windows_eventlog or
- Confirm that you can successfully live query the logs:
SELECT * FROM windows_events limit 10;
- Save a new query: Query -> Manage Queries -> Create New Query
SELECT * FROM windows_events;-> Save
- Add the new query to a query pack that targets a Windows host - how often it should run depends on log volume on the local host; start off with 180 seconds, differential logging: Packs -> Manage Packs -> Select + Edit Pack (Modify Targets for Windows only if needed, Modify Logging options as needed)
- Save pack + Enable pack, if needed.
Please refer to the osquery documentation for further information on osquery Evented tables: https://osquery.readthedocs.io/en/stable/development/pubsub-framework/#the-pub-sub-evented-data-framework-of-osquery
We sponsored the development of Community ID support for osquery: