This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

osquery: Send log messages to osquery's syslog table

1: osquery() destination options

The osquery() driver sends log messages to osquery’s syslog table.

The syslog table contains logs forwarded over a named pipe from syslog-ng. When an osquery process that supports the syslog table starts up, it creates (and properly sets permissions for) a named pipe for AxoSyslog to write to.

Example: Using the osquery() destination driver

Run osqueryi:

   osqueryi --enable_syslog
             --disable-events=false

To store the database on disk:

   osqueryi --enable_syslog
             --disable-events=false
             --database_path=/tmp/osquery.db

To set up a custom named pipe:

   osqueryi --enable_syslog
             --disable-events=false
             --database_path=/tmp/osquery.db
             --syslog_pipe_path=/tmp/osq.pipe

Example configuration:

   @version: 3.12
    @include "scl.conf"
    
    source s_net {
      network(port(5514));
    };
    
    destination d_osquery {
      # custom pipe path:
      #osquery(pipe("/tmp/osq.pipe"));
    
      # backup outgoing logs:
      #osquery(file("/var/log/osquery_inserts.log" template(t_osquery)));
    
      # defaults
      osquery();
    };
    
    log {
     source(s_net);
     destination(d_osquery);
     flags(flow-control);
    };

1 - osquery() destination options

The osquery() destination has the following options:

file()


Type:	string
Default:	N/A

Description: Specifies a path to the file where log messages are stored, for example, for debug purposes.

Specifying this option is optional. However, when you start losing logs for some reason, then it is recommended to write outgoing log messages to a specified file, in the same format that messages are written to the pipe. You can also use a template() function called t_osquery, which re-formats messages so they comply with the text-based protocol that osquery accepts.

hook-commands()

Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.

Note The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.

Using `hook-commands()` when AxoSyslog starts or stops

To execute an external program when AxoSyslog starts or stops, use the following options:

`startup()`

Type:	string
Default:	N/A

Description: Defines the external program that is executed as AxoSyslog starts.

`shutdown()`

Type:	string
Default:	N/A

Description: Defines the external program that is executed as AxoSyslog stops.

Using the hook-commands() when AxoSyslog reloads

To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:

`setup()`

Type:	string
Default:	N/A

Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.

`teardown()`

Type:	string
Default:	N/A

Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.

Example: Using hook-commands() with a network source

In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.

The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.

source {
    network(transport(udp)
    hook-commands(
          startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
          shutdown("iptables -D LOGCHAIN 1")
        )
     );
};

pipe()


Type:	string
Default:	N/A

Description: Specifies a custom path to the named pipe that acts as the interface between osquery and syslog-ng. (The default path is set in the SCL file.)

Specifying this option is optional.