osquery Cookbook

This cookbook includes recipes and resources to install, configure, and start Facebook's osquery. osquery is an operating system instrumentation framework for OS X/macOS, Windows, and Linux.

Supported

Platforms

Ubuntu: 12.04, 14.04, 16.04
Centos/Redhat: 6.5, 7.0
OS X

Chef

Chef 11+

Cookbooks

apt

Usage

Include osquery::default in your node's run_list
Override attributes to fit your desired setup

Recipes

default

The default recipe determines if a node is within the supported platform list and includes the one of the platform specific recipes to setup osquery.

centos/ubuntu/mac_os_x

Install osquery via package (rpm, deb, or pkg)
Setup syslog ingestion if enabled
Create configuration file(s)
Start/enable osqueryd service

Attributes

attributes/default.rb:

Default attributes control the version to install, syslog configuration, and whether or not to use Facebook's Apt/Yum repo or your own internal repo.

name	type	default	description
`['osquery']['version']`	`String`	`2.2.1`	osquery version to install
`['osquery']['packs']`	`Array`	`%w(incident-response osx-attacks)`	packs to install
`['osquery']['pack_source']`	`String`	`osquery`	cookbook to load osquery packs from
`['osquery']['repo']['internal']`	`Boolean`	`false`	enable/disable the use the facebook repo
`['osquery']['syslog']['enabled']`	`Boolean`	`true`	enable syslog tables
`['osquery']['syslog']['filename']`	`String`	`/etc/rsyslog.d/60-osquery.conf`	syslog conf file path
`['osquery']['syslog']['pipe_user']`	`String`	`root`	syslog pipe user
`['osquery']['syslog']['pipe_group']`	`String`	`root`	syslog pipe group

attributes/config.rb:

Config attributes add options to the osquery config options key. This includes logger plugins, config plugin, splay, worker threads, and more.

name	type	default	description
`['osquery']['options']['config_plugin']`	`String`	`filesystem`	configuration plugin
`['osquery']['options']['logger_plugin']`	`String`	`filesystem`	logger plugin
`['osquery']['options']['schedule_splay_percent']`	`Fixnum`	`10`	query schedule splay percentage
`['osquery']['options']['events_expiry']`	`Fixnum`	`3600`	timeout to expire eventing pubsub results
`['osquery']['options']['verbose']`	`Boolean`	`false`	enable verbose informational messages
`['osquery']['options']['worker_threads']`	`Fixnum`	`2`	number of work dispatch threads
`['osquery']['options']['enable_monitor']`	`Boolean`	`false`	enable schedule monitor
`['osquery']['options']['syslog_pipe_path']`	`String`	`/var/osquery/syslog_pipe_test`	syslog pipe path

attributes/schedule.rb:

Schedule attributes control the main osquery query schedule. You can add additional queries this way:

default['osquery']['schedule']['query_name'] = {
  query: 'SELECT * FROM table_name;',
  interval: '86400',
  description: 'my new query'
}

name	type	default	description
`['osquery']['schedule']`	`Hash`	osquery_info	osquery scheduled queries

attributes/file_paths.rb:

File integrity monitoring paths.

name	type	default	description
`['osquery']['fim_enabled']`	`Boolean`	false	enable/disable file event tracking in config
`['osquery']['file_paths']`	`Hash`	homes, etc, and tmp	file paths to monitor events from
`['osquery']['exclude_paths']`	`Hash`	homes, etc, and tmp	file paths to ignore monitor events from (category must exist in file_paths)

attributes/decorators.rb:

Decorator query options.

name	type	default	description
`['osquery']['decorators']`	`Hash`	`{}`	load, always, or interval decorator queries

Custom Resources

`osquery_conf`: creates osquery config from selected options and packs

actions: :create or :delete
schedule: (required) Hash of scheduled queries to run
fim_paths: (optional) Hash of file integrity monitoring path descriptions and array of their paths
packs: (optional) List of osquery packs to install. Based on filenames ending in *.conf in pack_source/packs
pack_source: (optional) Cookbook source for osquery packs
The daemon configuration is compiled from the node['osquery']['options'] attributes.

create:

osquery_conf osquery_config_path do
  action      :create
  schedule    node['osquery']['schedule']
  fim_paths   node['osquery']['file_paths']
  fim_exclude_paths   node['osquery']['exclude_paths']
  packs       node['osquery']['packs']
  pack_source node['osquery']['pack_source']
  decorators  node['osquery']['decorators']
end

delete:

osquery_conf 'delete osquery config' do
  action :delete
end

`osquery_install`: installs osquery on centos/redhat, ubuntu, or os x

actions:
- :install_ubuntu, :install_centos, :install_os_x
- :remove_ubuntu, :remove_centos, :remove_os_x
version: (required - name attribute) string of the osquery version to install

install:

osquery_install node['osquery']['version'] do
  action :install_ubuntu
end

remove:

osquery_install node['osquery']['version'] do
  action :remove_ubuntu
end

`osquery_syslog`: creates osquery syslog config file

actions: :create or :delete
syslog_file: (required - name attribute) filename of the osquery syslog config
pipe_filter: the filter expression for routing events into the syslog pipe
pipe_path: the fifo pipe path
note: this resource installs rsyslog if not already configured