Table of Contents

Description

This module manages the installation and configuration of tlog for active terminal session recording.

By default, the logs will be recorded to journald with systems running systemd and syslog otherwise.

See REFERENCE.md for full API details.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they may be submitted to our bug tracker.

Usage

You can simply include the tlog class to have the software installed.

To enable automatic session recording, include the tlog::rec_session class. You MUST then add all users and/or groups that you want to monitor to the tlog::rec_session::shell_hook_users Array.

Note: Groups should be prefixed with a percent sign (%).

When this is enabled, it will automatically hook into login and interactive shells based on scripts placed into /etc/profile.d.

Example: Auditing the 'root' user and 'administrators' group

---
tlog::rec_session::shell_hook_users:
  - 'root'
  - '%administrators'

NOTE: If you want to be 100% certain that all sessions are logged, you should not rely on this hook but should, instead, set /usr/bin/tlog-rec-session as the user's primary shell. This is not feasible in many situations so these hooks have been provided for the 90% case.

Limitations

The tlog project is still evolving so there may be breaking changes that occur in the future. We highly encourage all users to file feature requests and bug reports with the upstream project.

TLOG does not record all sessions

iWhen root is set to use the tlog hook, if a user is logged into a system using a graphical display such as gnome and attempts to su to root from more than one terminal window in the same session, the second su will not be recorded.

This occurs because, in order to prevent looping, if the session id is the same for both shells, tlog does not start a second recording session. A ticket has been entered for this issue.

The above error does not affect ssh logins.

tlog-play from file

To playback tlog from a file, the file must only contain json entries from a single session. The default SIMP implementation of tlog records all sessions with some additional non-json formatted information in a file, causing playback of the raw log file to fail. To generate a usable tlog file for playback, grep and awk can be utilized to filter and format entries for a tlog session. Identify the file containing the raw tlog data. Performing a grep for tlog-rec-session in the logs directory can help locate log files. After identifying the raw log file, examine the contents of the file to identify the rec, a host-unique recording id, for the session to be replayed. The rec can then be used with grep to generate a new file containing only logs from that session in json format:

grep <rec> <raw log file> | awk -F"tlog-rec-session: " '{print $2}' > /tmp/tlog_for_playback

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

NOTE: You will need to make sure that the nodesets can install the tlog packages from a repository (or install them via beaker) for the tests to run successfully.

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.

Reference

Table of Contents

Classes

Public Classes

• tlog: This module manages the configuration of TLog
• tlog::config::rsyslog: Manage local syslog hooks for tlog
• tlog::rec_session: Configure tlog-rec-session This is pulled out from the main tlog class because of the rapidly moving nature of the project. Having this

Private Classes

• tlog::install: This class is called from tlog for install.

Data types

• Tlog::RecSessionConf: Configuration options for the tlog-rec-session.conf

Classes

tlog

This module manages the configuration of TLog

Parameters

The following parameters are available in the tlog class:

• package_name
• package_ensure
• manage_rsyslog

package_name

Data type: String[1]

The name of the tlog package

Default value: 'tlog'

package_ensure

Data type: String[1]

What should be passed to the ensure parameter for all package resources

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

manage_rsyslog

Data type: Boolean

If true, manage logging configuration for tlog

Default value: simplib::lookup('simp_options::syslog', { 'default_value' => false })

tlog::config::rsyslog

Manage local syslog hooks for tlog

Parameters

The following parameters are available in the tlog::config::rsyslog class:

• logrotate_options
• match_rule
• log_file
• logrotate_create
• stop_processing
• logrotate

logrotate_options

Data type: Hash

Options to pass to the logrotate::rule defined type

• Will be deep merged through Hiera by default
• The log_files option will not be honored if passed

@see data/common.yaml

match_rule

Data type: String[1]

The rule that should be used for matching TLOG rules

• The default is set to match rules on the widest selection of systems possible.

Default value: '$programname == \'tlog-rec-session\' or $programname == \'-tlog-rec-session\' or $programname == \'tlog\''

log_file

Data type: Stdlib::Absolutepath

The log file in which to save the tlog logs

Default value: '/var/log/tlog.log'

logrotate_create

Data type: Pattern['\d{4} .+ .+']

The create options to specify in the logrotate rule

Default value: '0640 tlog tlog'

stop_processing

Data type: Boolean

Cease processing syslog rules after processing this rule

Default value: true

logrotate

Data type: Boolean

Enable log rotation for $log_file

Default value: simplib::lookup('simp_options::logrotate', { 'default_value' => false })

tlog::rec_session

Configure tlog-rec-session

This is pulled out from the main tlog class because of the rapidly moving nature of the project. Having this decoupled will allow us to refactor as necessary as the software progresses.

Parameters

The following parameters are available in the tlog::rec_session class:

• options
• custom_options
• shell_hook
• shell_hook_users
• shell_hook_users_file
• shell_hook_cmd

options

Data type: Tlog::RecSessionConf

Configuration options for tlog-rec-session

• Will be deep merged through Hiera by default
• Unfortunately, the file is not "real" JSON and so Augeas lenses and/or Ruby won't work to do ad-hoc configuration until after the file is managed.
• This set covers the known options in known formats. Use $custom_options for arbitrary settings.
• Note: If the writer option is not set, a sane default for the target platform will be selected.

@see data/common.yaml @see types/recsession.pp

custom_options

Data type: Hash

An unvalidated Hash of options that will be converted to JSON and merged, with preference, into $options

Default value: {}

shell_hook

Data type: Boolean

Add hooks into /etc/profile.d that will automatically record sessions for interactive and/or login shells

Default value: true

shell_hook_users

Data type: Array[String[1]]

The list of users that you want to automatically record that will be stored in $shell_hook_users_file

Default value: [ 'root' ]

shell_hook_users_file

Data type: Stdlib::Absolutepath

The path to the file containing the list of users and/or groups that you want to automatically record

• Users should be specified as Strings
• Groups should be prefaces with a %

Default value: '/etc/security/tlog.users'

shell_hook_cmd

Data type: Stdlib::Absolutepath

The path to tlog-rec-session

Default value: '/usr/bin/tlog-rec-session'

Data types

Tlog::RecSessionConf

Configuration options for the tlog-rec-session.conf

Alias of

Struct[{
  Optional['shell']    => Stdlib::Absolutepath,
  Optional['notice']   => String,
  Optional['writer']   => Enum['journal', 'syslog', 'file'],
  Optional['latency']  => Integer[1],
  Optional['payload']  => Integer[1],
  Optional['log'] => Struct[{
    Optional['input']  => Boolean,
    Optional['output'] => Boolean,
    Optional['window'] => Boolean
  }],
  Optional['limit'] => Struct[{
    Optional['rate']   => Integer[1],
    Optional['burst']  => Integer[1],
    Optional['action'] => Enum['pass','delay','drop']
  }],
  Optional['file'] => Struct[{
    'path' => Stdlib::Absolutepath
  }],
  Optional['syslog'] => Struct[{
    Optional['facility'] => Simplib::Syslog::LowerFacility,
    Optional['priority'] => Simplib::Syslog::LowerSeverity
  }],
  Optional['journal'] => Struct[{
    Optional['priority'] => Simplib::Syslog::LowerSeverity,
    Optional['augment']  => Boolean
  }]
}]

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.6.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 0.5.0

• Add AlmaLinux 8 support

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 0.4.0

• Add RockyLinux 8 support

• Tue Dec 21 2021 Kendall Moore kendall@sicura.us - 0.3.3

• Update default logrotate create options to tlog:tlog

• Mon Oct 04 2021 Kendall Moore kendall.moore@onyxpoint.com - 0.3.2

• Added file resource if file writer is specified

• Tue Aug 24 2021 Trevor Vaughan tvaughan@onyxpoint.com - 0.3.1

• Fixed
  • Corrected the logic in tlog.sh.epp in the case where a user does not have a login shell

• Thu Jun 17 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 0.3.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Wed Feb 03 2021 Liz Nemsick lnemsick.simp@gmail.com - 0.2.2

• Expanded simp/rsyslog dependendency range to < 9.0.0.

• Sat Dec 19 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 0.2.2

• Removed EL6 support

• Wed Apr 15 2020 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.1

• Fix tcsh template

• Tue Feb 25 2020 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.0

• Added EL8 support
• Updated acceptance tests to use net/ssh to prevent issues with large SSH keyrings
• Added REFERENCE.md and linked into the README.md
• Added optional dependencies for simp/logrotate and simp/rsyslog
• Added workaround to scripts in /etc/profile to work around a bug in tlog that would prevent logins if the system hostname could not be found

• Fri Aug 02 2019 Robert Vincent pillarsdotnet@gmail.com - 0.2.0

• Drop Puppet 4 support
• Add Puppet 6 support
• Add puppetlabs-stdlib 6 support

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.1.2

• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md

• Fri Dec 14 2018 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.1

• Fix infinite recursion issue in the SH profile script

• Mon Nov 05 2018 Liz Nemsick lnemsick-simp@gmail.com - 0.1.0

• Update to Hiera 5

• Mon Oct 15 2018 Jeanne Greulich jeanne.greulich@onyxpoint.com - 0.1.0

• Documented known limitation and work around README for TLOG hanging on second window issue.

• Fri Oct 12 2018 Michael Morrone michael.morrone@onyxpoint.com - 0.1.0

• Documentation updates

• Thu Jul 19 2018 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.0

• Initial release