Puppet Module for osquery

Build StatusReleasePuppet ForgeApache-2 License

A minimal Puppet module for installing and managing the osquery service.

Source available on GitHub

Example Usage

Most parameters are automatically set for each package manager (APT/RPM). The settings parameter accepts any hash which is saved as JSON to /etc/osquery/osquery.conf.

Manifest example:

class { 'osquery':
settings => {
options => {
config_plugin => 'filesystem',
host_identifier => 'hostname',
disable_logging => false,
logger_plugin => 'syslog',
worker_threads => '1',
},
discover => [
'SELECT pid FROM processes WHERE name = \'foobar\';',
'SELECT 1 FROM users WHERE username like \'www%\';',
],
}
}

JSON result:

{
"options": {
"config_plugin": "filesystem",
"host_identifier": "hostname",
"disable_logging": false,
"logger_plugin": "syslog",
"worker_threads": "1"
},
"discover": [
"SELECT pid FROM processes WHERE name = 'foobar';",
"SELECT 1 FROM users WHERE username like 'www%';"
]
}

Hiera example:

osquery::settings:
options:
config_plugin: filesystem
logger_plugin: syslog
host_identifier: uuid
discover:
- "SELECT pid FROM processes WHERE name = 'foobar';"
- "SELECT 1 FROM users WHERE username like 'www%';"
schedule:
foobar:
query: SELECT foo, bar, pid FROM foobar_table;
interval: 600
packs:
shard: 10
external_pack: /path/to/external_pack.conf
queries:
suid_bins:
query: SELECT * FROM suid_bins;
interval: 3600

JSON result:

{
"options": {
"config_plugin": "filesystem",
"host_identifier": "uuid",
"disable_logging": false,
"logger_plugin": "syslog",
"worker_threads": "4"
},
"discover": [
"SELECT pid FROM processes WHERE name = 'foobar';",
"SELECT 1 FROM users WHERE username like 'www%';"
],
"schedule": {
"foobar": {
"query": "SELECT foo, bar, pid FROM foobar_table;",
"interval": 600
}
},
"packs": {
"shard": 10,
"external_pack": "/path/to/external_pack.conf",
"queries": {
"suid_bins": {
"query": "SELECT * FROM suid_bins;",
"interval": 3600
}
}
}
}

Default Configuration

---
osquery::package_name: osquery
osquery::package_ensure: installed
osquery::service_name: osqueryd
osquery::service_enable: true
osquery::service_ensure: running

osquery::config_path: /etc/osquery/osquery.conf
osquery::config_owner: 0
osquery::config_group: 0

osquery::settings:
options:
config_plugin: filesystem
host_identifier: hostname
disable_logging: false
logger_plugin: syslog
worker_threads: "%{facts.processorcount}"
---
osquery::repo_url: https://pkg.osquery.io/deb
osquery::repo_key_id: 1484120AC4E9F8A1A577AEEE97A80C63C9D8B80B
osquery::repo_key_server: keyserver.ubuntu.com
---
osquery::repo_url: https://s3.amazonaws.com/osquery-packages/rpm/$basearch/
osquery::repo_key_server: https://pkg.osquery.io/rpm/GPG

Changelog

All notable changes to this project will be documented in this file.

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • osquery::config: osquery configuration
  • osquery::package: osquery package management
  • osquery::service: osquery service management

Classes

osquery

osquery

Parameters

The following parameters are available in the osquery class:

config_path

Data type: Stdlib::AbsolutePath

The absolute path to the osquery configuration file

Default value: '/etc/osquery/osquery.conf'

config_owner

Data type: Variant[Integer[0], String[1]]

The owner to set on the osquery configuration file

Default value: 0

config_group

Data type: Variant[Integer[0], String[1]]

The group to set on the osquery configuration file

Default value: 0

package_name

Data type: String[1]

The osquery package name

Default value: 'osquery'

package_ensure

Data type: String

The osquery package ensure state

Default value: 'installed'

service_name

Data type: String[1]

The osquery service name

Default value: 'osqueryd'

service_enable

Data type: Boolean

The osquery service enable state

Default value: true

service_ensure

Data type: Stdlib::Ensure::Service

The osquery service ensure state

Default value: 'running'

manage_repo

Data type: Boolean

Set to true to manage the osquery repository

Default value: true

repo_url

Data type: String

The osquery repository URL to use

Default value: undef

repo_key_id

Data type: Optional[String]

The osquery repository GPG key id (apt)

Default value: undef

repo_key_server

Data type: Optional[String]

The osquery GPG key server (apt) or GPG URL (yum)

Default value: undef

settings

Data type: Hash

A hash of settings to set in the osquery configuration file

Default value: {}