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.