Version information
This version is compatible with:
- Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
- Puppet >= 4.10.4 < 6.0.0
- , ,
Start using this module
Add this module to your Puppetfile:
mod 'simp-tlog', '0.1.0'
Learn more about managing modules with a PuppetfileDocumentation
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.
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 Hangs
If a user is logged into a system using a graphical display and attempts to
su
to root
from more than one terminal window in the same session, the
second su
will hang.
This occurs because the session id is the same for both shells. When the
tlog-rec-session
is started the second time it sees a tlog-rec-session
with
the same session id and it replaces itself with a bash
shell which then
attempts to start a recording session and enters an endless loop. If the user
enters CTRL-C
, the root
session will still be recorded and the looping
process will be interuppted.
The above error does not affect ssh
logins. If a user requires more than
one root
shell they should ssh
into the local system and su
from that
terminal.
This bug is tracked as SIMP-5426
hidepid
If your system has the hidepid
option on /proc
set to anything besides 0
,
then the shell hooks will be unable to determine if they are already running in
a tlog
session. In this case, you MUST change the user's shell to
/usr/bin/tlog-rec-session
. This limitation does not apply to the root
user.
NOTE: hidepid
is set to 2
by default on SIMP
systems.
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.
- 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
Dependencies
- simp/simplib (>= 3.10.0 < 4.0.0)
- puppetlabs/stdlib (>= 4.13.1 < 5.0.0)
tlog - A module for managing Tlog Per Section 105 of the Copyright Act of 1976, these works are not entitled to domestic copyright protection under US Federal law. The US Government retains the right to pursue copyright protections outside of the United States. The United States Government has unlimited rights in this software and all derivatives thereof, pursuant to the contracts under which it was developed and the License under which it falls. --- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.