goaudit

Table of Contents

1. Description
2. Setup - The basics of getting started with goaudit
   • What goaudit affects
   • Setup requirements
   • Beginning with goaudit
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module allows you to manage Go-Audit using Puppet.

Setup

What goaudit affects

The module manages package, service and configuration files for Go-Audit.

The package name is assumed to be goaudit, via the default package provider for your system. It is assumed that such a package exists. This assumption may not hold true for your platform as-is, and you may need to provide such a package yourself. The module does not contain logic for installing Go-Audit by any other method.

Setup Requirements

The module depends on the Datacat module for composing the Go-Audit YAML config file.

Beginning with goaudit

To install Go-Audit with a default configuration:

class { '::goaudit': }

Usage

Manage rules

goaudit::rule { 'TLS private key access' :
  order   => 50,
  comment => 'Reads, writes and attribute changes on TLS private keys',
  content => [
    '-w /etc/ssl/private/foo.key -p rwa -k tls-key-access',
    '-w /etc/ssl/private/bar.key -p rwa -k tls-key-access',
  ]
}

### Manage filters

goaudit::filter { 'reduce the number of connect syscall events being logged':
  syscall      => 49,      # bind
  message_type => 1306,    # AUDIT_SOCKADDR
  # 0200....7F - ipv4 on any port to 127.x.x.x
  # 01 - local/unix domain sockets
  regex        => 'saddr=(0200....7F|01)'
}

Reference

Classes

goaudit

package_name

Sets the name of the Go-Audit package.

Default value: go-audit.

package_ensure

Whether the Go-Audit package resource should be present.

Valid values: present, absent.

Default value: present.

config_file

The filesystem path to the Go-Audit config file.

Valid values: an absolute file path on the target system.

Default value: /etc/go-audit.yaml.

service_name

Overrides the Go-Audit service name. May be required depending on what the package provides.

Default value: go-audit

service_enable

Specifies whether the service should be enabled.

Valid values: true, false.

Default value: true.

service_ensure

The service state that should be ensured.

Valid values: stopped, running.

Default value: running.

events_min

Lower bound of range of audit type codes of events to capture.

Default value: 1300

events_max

Upper bound of range of audit type codes of events to capture.

Default value: 1399

message_tracking_enabled

Whether to track messages and identify if any were missed.

Valid values: true, false.

Default value: true

message_tracking_log_ooo

Whether to log out-of-orderness. These messages typically signify an overloading system.

Valid values: true, false.

Default value: false

message_tracking_max_ooo

Maximum out of orderness before a missed sequence is presumed dropped.

Default value: 500

output_stdout_enabled

Whether to log Go-Audit program output to stdout.

Valid values: true, false.

Default value: true

output_stdout_attempts

Total number of attempts to write to stdout before considering giving up. If a write fails, Go-Audit will sleep for 1 second before retrying.

Valid values: positive integers

Default value: 3

output_syslog_enabled

Whether to log Go-Audit program output to syslog.

Valid values: true, false.

Default value: false

output_syslog_attempts

Total number of attempts to write to Syslog before considering giving up. If a write fails, Go-Audit will sleep for 1 second before retrying.

Valid values: positive integers

Default value: 5

output_syslog_network

The type of socket over which to communicate with Syslog.

Valid values: see network in Golang's net.Dial: https://golang.org/pkg/net/#Dial

Default value: unixgram

output_syslog_address

The remote address over which to connect to Syslog. Can be a filesystem path, IP address, hostname.

Valid values: see address in Golang's net.Dial: https://golang.org/pkg/net/#Dial

Default value: /dev/log

output_syslog_priority

Sets the facility and severity for all Syslog events generated by Go-Audit.

Default value: 129 (maps to local0 | emerg)

See any Syslog priority matrix reference material for details on calculating this value, e.g. https://en.wikipedia.org/wiki/Syslog

output_syslog_tag

A tag to apply to Syslog messages generated by Go-Audit. Typically this is the name of the program generating the message. The PID of the process is automatically appended.

Default value: go-audit

output_file_enabled

Whether to log Go-Audit program output to a logfile.

Valid values: true, false.

Default value: false.

output_file_attempts

Total number of attempts to write to the logfile before considering giving up. If a write fails, Go-Audit will sleep for 1 second before retrying.

Valid values: positive integers

Default value: 2

output_file_path

The path to the logfile.

Valid values: any absolute file path.

Default value: /var/log/go-audit/go-audit.log.

output_file_mode

The file mode of the logfile.

Valid values: any valid file mode octal expression, with leading zero.

Default value: 0600.

output_file_user, output_file_group

The user and group ownership of the logfile.

Valid values: any valid user and group name on the target system.

Default value: root.

log_flags

Control log file line prefixes. Add together constants defined in Golang's log module. https://golang.org/pkg/log/#pkg-constants

Valid values: an integer expressing a combination of flags as defined above.

Default value: 0 (no line prefixes)

auto_enable_rule

Manages a special rule in the ruleset, which always appears at the end of the ruleset and is applied last, regardless of ordering hints given to rules defined by goaudit::rule resources.

The rule tells the kernel to enable, disable, or lock the ruleset, and is applied by auditctl -e.

When set to enable, the last rule in the ruleset will be -e 1, which tells the kernel to enable the flow of audit messages.

When set to disable, the last rule in the ruleset will be -e 0, which tells the kernel to disable the flow of audit messages.

When set to lock, the last rule in the ruleset will be -e 2, which tells the kernel to enable the flow of audit messages, and prevent any further changes to the ruleset (until the next reboot).

When set to none, this rule is not added to the ruleset. Use this setting if you are managing this property through some other mechanism.

Valid values: none, disable, enable, lock

Default value: enable

Defined Types

goaudit::rule

Adds a rule, or multiple rules in a block, to the Go-Audit configuration. The rules will be applied to the kernel by Go-Audit on startup via a sequence of calls to the auditctl command.

order

An ordering hint. goaudit::rule resources will be sorted by their order before being applied to the configuration.

Valid values: integers

Default value: 10

comment

An optional comment to prepend to the rule(s). If provided, will be rendered in the configuration as a YAML comment.

content

A rule expression (string), or an array of rule expressions. Arrays will be rendered in the configuration in order. See the auditctl documentation for valid rule expressions.

goaudit::filter

Adds a filter to the Go-Audit configuration.

order

An ordering hint. goaudit::filter resources will be sorted by their order before being applied to the configuration.

Valid values: integers

Default value: 10

comment

An optional comment to prepend to the filter(s). If provided, will be rendered in the configuration as a YAML comment.

syscall

Required.

The syscall ID of the message group (a single log line from go-audit), to test against the regex

Valid values: Integers. See output of command ausyscall --dump for a list.

message_type

Required.

The message type identifier containing the data to test against the regex.

Valid values: integers. For a list of message types, see https://github.com/torvalds/linux/blob/master/include/uapi/linux/audit.h#L53.

regex

Required.

The regex to apply to the message text.