osquery 1.7.3 introduced support for consuming and querying the Mac OSX system log via Apple System Log (ASL). osquery 1.7.4 introduced support for the Linux syslog via rsyslog. This document explains how to configure and use these syslog tables.

OSX Syslog

On Mac OSX, the asl virtual table makes use of Apple's ASL store, querying this structured store using the routines provided in asl.h.

Configuration

No configuration is required to begin using the asl table. Note, however, that the table is only able to query logs that are available in the ASL store.

If your target logs are not already being sent to the ASL store by your current configuration, take a look at the man page for asl.conf, and use the store action to ensure your logs of interest are available in the store. asl.conf is also responsible for the rotation and retention settings of the ASL store.

Note: the configuration for /var/log/install.log and /var/log/commerce.log is hardcoded into the Apple provided syslog binaries, and we are not aware of a way to configure ASL to send these logs to the store.

Usage

The asl table can be queried like any other osquery table. It exposes many of the columns of structured data from the ASL store, and other additional columns are made available as a JSON dictionary in the extra column. Use .schema asl in the osqueryi shell to see the schema.

Basic query predicates (<, <=, =, >=, >) are able to be efficiently queried in the store. The LIKE predicate is also supported, however it must be tested after applying all othe predicates and reading logs from the store. For performance reasons, it is suggested to use at least one basic predicate in a query against the asl table. For example,

select time, message from asl where facility = 'authpriv' and sender = 'sudo' and message like '%python%';

Linux Syslog

On linux, the syslog table queries logs forwarded over a named pipe from a properly configured rsyslogd. This method was chosen to support the widest range of linux flavors (in theory, anything running at least ryslogd version 5, and tested with Ubuntu 12/14, centos 7.1, RHEL 7.2), and to ensure that existing syslog routines and configurations are not modified. As syslog is ingested into osquery, it is written into the backing store (RocksDB) and made available for querying.

Configuration

The syslog table requires additional configuration before it can be used.

When an osquery process that supports the syslog table starts up, it will attempt to create (and properly set permissions for) a named pipe for rsyslogd to write to. The path for this pipe is determined by the configuration flag syslog_pipe_path (defaults to /var/osquery/syslog_pipe). If verbose logging is turned on, you should see a status message indicating whether osquery was able to successfully open the pipe for reading.

Permissions for the pipe must at least allow rsyslogd to read/write, and osquery to read. For security, it is advised that the least possible privileges are enabled to allow this.

Once the named pipe is created, rsyslogd must be configured to write logs to the pipe. Add the following to your rsyslog configuration files (usually located in /etc/rsyslog.conf or /etc/rsyslog.d/):

rsyslog versions < 7

$template OsqueryCsvFormat, "%timestamp:::date-rfc3339,csv%,%hostname:::csv%,%syslogseverity:::csv%,%syslogfacility-text:::csv%,%syslogtag:::csv%,%msg:::csv%\n"
*.* |/var/osquery/syslog_pipe;OsqueryCsvFormat

rsyslog versions >= 7

Note: the above configuration should also work, but rsyslog strongly recommends using the new style configuration syntax.

template(
  name="OsqueryCsvFormat"
  type="string"
  string="%timestamp:::date-rfc3339,csv%,%hostname:::csv%,%syslogseverity:::csv%,%syslogfacility-text:::csv%,%syslogtag:::csv%,%msg:::csv%\n"
)
*.* action(type="ompipe" Pipe="/var/osquery/syslog_pipe" template="OsqueryCsvFormat")

All versions

rsyslogd must be restarted for the changes to take effect. On many systems, this can be achieved by sudo service rsyslog restart.

Note: rsyslogd will only check once, at startup, whether it can write to the pipe. If rsyslogd cannot write to the pipe, it will not retry until restart.

Other configuration

Configuration flags control the retention of syslog logs. syslog_events_expiry (default 30 days) defines how long (in seconds) to keep logs. syslog_events_max (default 100,000) sets a maximum number of logs to retain (oldest logs are deleted first if this number is surpassed).

Usage

Once configuration is complete, the syslog table can be queried like any other osquery table. It's schema can be viewed with .schema syslog.

Note: only logs produced after this table was properly configured (and while osquery is running) will be available for querying.

If no logs are available to query, try turning on verbose logging, and see issue #1964 for debugging suggestions.