Puppet Module for osquery

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

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::validate_cmd: '/usr/bin/osqueryi --config_path % --config_check'

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_name: osquery.asc
osquery::repo_key_source: https://pkg.osquery.io/deb/pubkey.gpg

---
osquery::repo_url: https://s3.amazonaws.com/osquery-packages/rpm/$basearch/
osquery::repo_key_server: https://pkg.osquery.io/rpm/GPG

---
osquery::config_path: 'C:/Program Files/osquery/osquery.conf'
osquery::config_group: Administrator
osquery::config_owner: Administrator
osquery::package_provider: chocolatey
osquery::package_install_options:
  - -params
  - /InstallService
osquery::service_name: osqueryd
osquery::settings: ~
osquery::validate_cmd: 'C:/Program Files/osquery/osqueryi --config_path "%" --config_check'

Documentation

Change log

v1.2.0 (2025-04-26)

Full Changelog

Added
Fixed
  • Replace deprecated legacy apt keyring install #19 (gibbs)

v1.1.0 (2024-05-26)

Full Changelog

Added
Fixed

v1.0.0 (2022-07-13)

Full Changelog

Fixed
  • Explicitly set lint checks #3 (gibbs)

0.1.0 (2022-03-17)

Full Changelog

Added
  • Add Scientific Linux support #2 (gibbs)
  • Add redhat family support #1 (gibbs)

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'

package_provider

Data type: Optional[String]

The package provider to use (Windows)

Default value: undef

package_install_options

Data type: Optional[Array]

The install_options to provide when using Chocolatey (Windows)

Default value: undef

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: Optional[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

repo_key_name

Data type: Optional[String]

The osquery APT keyring name

Default value: undef

repo_key_source

Data type: Optional[String]

The osquery APT keyring file source

Default value: undef

settings

Data type: Hash

A hash of settings to set in the osquery configuration file

Default value: {}

validate_cmd

Data type: String

The command to validate osquery.conf format changes

Default value: '/usr/bin/osqueryi --config_path % --config_check'
Previous
Back to Projects