pbreplay

pbreplay replays the contents of an I/O log file for an active or completed session.

If you set the iolog variable to a unique path name in a policy file, then Endpoint Privilege Management for Unix and Linux logs all of the input and output from the secured task to an I/O log file.

The input and output for the secured task can be logged to a file in /usr/adm with a file name, such as pb.jqpublic.ksh.a05998, that can be examined later using pbreplay. The name of the I/O log is a unique temporary file name that is generated by the logmktemp() function in the configuration file.

This is an example of such a filename:
iolog=mktemp("/usr/adm/pb." + user + . + basename(command) +".XXXXXX");

Endpoint Privilege Management for Unix and Linux sets the permissions on the I/O log file so that only root can read the file. No other user can examine the contents of the I/O log files. You must be logged in as root to use pbreplay on these files. You can also use Endpoint Privilege Management for Unix and Linux to delegate this privilege to the appropriate people.

Starting in version 9.4.0, when a user requests to replay an archived IO log, pbreplay makes a REST GET request for a copy of the archived logfile from the Log Archive Storage Server. The copy of the file is saved to a temporary file for use by pbreplay. When pbreplay exits, this temporary file is removed.

pbreplay has four main ways of replaying an iolog:

  • Interactively: The viewer interactively controls the speed of viewing the iolog.
  • Raw: The entire iolog is replayed at computer speed. The raw terminal control codes are interpreted by the terminal (resulting in visually correct output that is not easily searched via grep).
  • Processed: The entire iolog is replayed at computer speed. The terminal control codes are interpreted by pbreplay (resulting in output that is searchable).
  • Policy variables: The values of Endpoint Privilege Management for Unix and Linux policy variables are printed.

Interactive Syntax

pbreplay [ -ao | -ax ] [ -h ] [ -t <date format> ] <iolog filename>

Raw Syntax

pbreplay <[ -I | -i | -o | -e ]> [ [-ao | -ax | -am ] ] [ -h ] [ -m ] [ -t <date format> ]

Processed Syntax

pbreplay -O [--regex <regex expression> [--ignore-case ] [ -c <constraint expression> ] [ -p <format expression> ] ] <iolog filename>
pbreplay -O [--regex <regex expression> [--ignore-case ] [ -c <constraint expression> ] [ -p <format expression> ] --files <glob pattern>]

Solr or Elasticsearch Indexing Syntax

As of version 23.1, Solr is deprecated. BeyondInsight for Unix & Linux no longer supports installing Solr, but features that use an existing Solr installation will continue to work.

pbreplay -X [-T]
pbreplay -Z [-T]

Policy Variable Only Syntax

pbreplay -av <iolog filename>

The -O option by itself produces searchable output by processing the terminal control codes in a virtual screen, then produces output based on that virtual screen. This feature is intended to search shell sessions delegated by pbrun, for shell command entries. Searching for data within a CURSES application is not supported. The goal of being able to search for shell commands that the user enters is problematic. stdin is not used, since it can contain shell history recall and editing commands that the shell can process, but for which Endpoint Privilege Management has no context. This mechanism works on the stdout data stream which should normally contain the resulting command with editing completed. This is easily defeated, however, by turning echo off.

This has several limitations:

  • This means that the output has newline characters when the screen width is reached, which does not accurately represent a shell command entry that wraps across the screen from one line to the next.
  • Typeahead is another problem. If the user begins typing the command before the shell prompt is output, the first few characters of the command entry are not contiguous with the rest of the command.
  • Termcap data for a given terminal is actually different across different platforms. For example, the vt100 left arrow is very different between Solaris and HP-UX. It may be necessary to replay I/O logs on the same operating system as they were generated from.
  • Large window sizes require more memory and processing time.
  • For I/O logs that have no TERM environment variable (cron jobs, for example), the xterm TERM is used.
  • Terminal commands that do not directly affect the screen data or the cursor position are ignored (for example: reverse video, dim, bright, blinking, underlined).

Given the limitations, this output is suitable for processing via grep, awk, perl, etc. If initial searches fail to find the offending pattern, try searches allowing for typeahead, and try searching for commands that turn echo off.

The --regex option enables built-in searching via the standard regcomp mechanism.

This uses POSIX Extended Regular Expression syntax. Substring addressing of matches is not supported. The match-any-character operators don't match a newline. The match-beginning-of-line operator (^) matches the empty string immediately after a newline, and the match-end-of-line operator ($) matches the empty string immediately before a newline.

Since this feature works on output (not stdin), the beginning of line for command entry is typically a shell prompt.

The following options require both -O and --regex:

  • --ignore-case: Ignores case during the regex comparison.
  • -c <constraint expression>: Allows the search to be limited to I/O logs whose policy variables meet the criteria specified in the constraint expression (for example, the search can be limited to I/O logs for a specific runhost, or specific submituser).
  • -p <format expression>: Allows the output to be customized.
  • --files <glob pattern>: Allows multiple files to be searched. The glob mechanism supports the question mark symbol (?) matching any single character, the asterix (*) matching any string, and character classes, ranges, and complementation within square brackets ([ and ]).
  • The -X option processes the terminal control codes in the same way as -O, then sends the data to Solr or Elasticsearch for indexing. Whether the data is sent to Elasticsearch or Solr depends on whether a correct Elasticsearch or Solr configuration is configured in /etc/pb.settings. If both Elasticsearch and Solr are configured correctly, then Elasticsearch takes precedence and data will only be sent there.
  • The -Z option processes the terminal control codes in the same way as -O and -X, and creates XML data, without sending that data to Solr. The JSON message can be displayed on the console. If -Z is set and /etc/pb.settings is correctly configured to send iologs to Elasticsearch, then the data is rendered on the console in JSON format. Otherwise, if /etc/pb.settings is configured correctly for Solr, then the data is rendered in XML format. As with -X, if both Elasticsearch and Solr are configured correctly, then Elasticsearch takes precedence and the data is presented on the console in JSON.

Syntax

  • Version 3.5 and earlier: long command options not supported.
  • Version 4.0 and later: long command options supported.
pbreplay [options] I/O_log_name
    --history
    --history2
    --history3
    --hideshellstartup 
    --nolinenumbers--markshellstartup 
    --showall
    -am, --map_printable
    -ao, --map_octal
    -av, --variables
    -ax, --map_hex
    -aX
    -e, --show_stderr
    -h, --header
    -i, --show_raw_stdin
    -I, --show_translated_stdin
    -k, --keyfile=key_file
    -m, --more
    -o, --show_stdout
    -A --audit
    -t, --timestamp[=format]
pbreplay -O [options] [I/O_log_name]
    -R, --regex <regular expression>
    --files <file glob pattern>
    -c <constraint expression>
-p <format expression>
pbreplay <--sendindex | -X> [options] [I/O_log_name]
pbreplay <--index | -Z> [options] [I/O_log_name]
pbreplay --forward
pbreplay –v | --version
pbreplay --help

Arguments

--history Derives shell history from an ACA I/O log where session history was enabled via enablesessionhistory(true);
--history2 Create more detailed ACA Session History Report.
--history3 Create ACA Session History Report of all execs.
--hideshellstartup Version 10.2.0 and earlier: --hideshellstartup not available.

Version 10.3.0 and later: --hideshellstartup available.

Use alone, or in combination with the --history, --history2, and --history3 options.

Commands executed as part of the shell startup scripts (identified as processes with the same process group as the main shell) are omitted from the history report.

--markshellstartup Version 10.2.0 and earlier: --markshellstartup not available.

Version 10.3.0 and later: --markshellstartup available.

Use alone, or in combination with the --history, --history2, and --history3 options.

Commands executed as part of the shell startup scripts (identified as processes with the same process group as the main shell) are included in the history report with the text shellstartup preceeding the command and arguments.

[root@dev-01 tmp]# /tmp/pbreplay --history --markshellstartup iolog.CbCezgQDCBwV7Fl8tdVPAdi1
1 Info     working directory set to: /tmp
2 Allowed  shellstartup id -gn
3 Allowed  shellstartup id -un
4 Allowed  shellstartup uname -s
5 Allowed  shellstartup ls /etc/bash_completion.d
6 Allowed  shellstartup     | /bin/grep -q /home/bginn/.cabal/bin
7 Allowed  shellstartup /usr/bin/tty -s
8 Allowed  shellstartup /usr/bin/tput colors 2> /dev/null
9 Allowed  shellstartup /usr/bin/dircolors --sh /etc/DIR_COLORS 2> /dev/null
10 Allowed  shellstartup /bin/grep -qi ^COLOR.*none /etc/DIR_COLORS > /dev/null 2> /dev/null
10 Allowed  shellstartup     /usr/bin/id -u
11 Allowed  shellstartup /bin/hostname
12 Allowed  shellstartup     | sed -e s#\..*$##
12 Allowed  shellstartup     /bin/hostname
13 Allowed  shellstartup     | head -1
13 Allowed  shellstartup         | tail -1
13 Allowed  shellstartup         | sed -e s#\..*$##
13 Allowed  shellstartup         | head -1
13 Allowed  shellstartup         | tail -1
13 Allowed  shellstartup     /usr/bin/tty
14 Allowed  shellstartup     | sed -e s#/##g
15 Allowed  id
17 Allowed  date
[root@dev-01 tmp]#
--nolinenumbers Do not display line numbers on the ACA history report.
--showall Do not remove duplicate output from the ACA Audit report.
-am, --map_printable Optional. Maps unprintable characters in the selected streams (-e, - i, -I, -o) to printable sequences.
-ao, --map_octal Optional. Maps unprintable characters in the selected streams to octal format. (\xxx).
-av, --variables Optional. Displays the variables for the secured task.
-ax, --map_hex Optional. Maps unprintable characters in the selected streams to hexadecimal format.
-aX [mV], --map_xwindows

Optional. Dumps relevant X11 captured events from the iolog. Major events such as creating and destroying windows, textual window updates, text input and mouse clicks are displayed as a summary alongside any output from the parent process.

m adds selected streams, V logs all X events.

-e, --show_stderr Optional. Non-interactive. Dumps the contents of the standard error stream. This option is useful for redirecting the data to a file or another program. For example, the output can be piped to grep to search for specific words or sequences.
-h, --header Optional. Non-interactive. Prints a header that contains the secured task information. This option is useful only with dump options. The header is always printed in interactive mode.
-i, --show_raw_stdin

Optional. Non-interactive. Dumps the contents of the standard input stream. This option is useful for redirecting the data to a file or another program. For example, the output can be piped to grep to search for specific words or sequences.

If the user typed carriage returns during the session, the input stream might contain carriage returns without linefeeds. On replay these cause the cursor to return to the left margin of the display and overwrite the previous line with the next line. If you are examining the data, lines may appear to be lost. To add line feeds to the display, use the option: -I (--show_translated_stdin).

-I, --show_translated_stdin Optional. Non-interactive. Dumps the contents of the standard input stream, adding linefeeds to carriage returns to improve readability. This option is useful for redirecting the data to a file or another program. For example, the output can be piped to grep to search for specific words or sequences.
-k, --keyfile=<name> Optional. Uses the named key file to decrypt an encrypted I/O log file.
-m, --more Optional. Interactively display the I/O log file using a pager-styles display (for example, less, more, pg) instead of using the native display.
-o, --show_stdout Optional. Non-interactive. Dumps the raw contents of the standard output stream. The terminal interprets the raw terminal commands such as <beginning of line>, <delete char>, and <delete word>. This option is useful for viewing the logged output.
-A, --audit

Display ACA audit stream.

-t, --timestamp[=format]

Displays timestamps on each line of output. The optional format argument can be any format string that is suitable for the date command. If the optional format string is omitted, then the system -t, --timestamp[=format] default time format is used.

[ver 4.0 and earlier]: option not available.

[ver 5.0 and later]: option available.

-v, --version

Required. Displays the program’s version and exits.

--help

Optional. Displays the program’s help message and exits.

The ACA Audit report lists file related libc/system calls and whether those calls were allowed or blocked via ACA.

Prior to Endpoint Privilege Management for Unix and Linux 9.4, the output was similar to:

Fri Nov 11 12:02:41 2016:    7115    1    owner   9    execve /usr/bin/id
Fri Nov 11 12:02:41 2016:    7115    1    read    9    fopen  /etc/passwd
Fri Nov 11 12:02:41 2016:    7115    1    read    9    fopen  /etc/group

Starting withEPM-UL 9.4, the output is changed to:

Fri Nov 11 2016 12:02:41 PM [ 7115] Allowed exec /usr/bin/id
Fri Nov 11 2016 12:02:41 PM [ 7115] Allowed read /etc/passwd
Fri Nov 11 2016 12:02:41 PM [ 7115] Allowed read /etc/group

And with additional loglevels:

Fri Nov 11 2016 12:08:36 PM [ 7359] Allowed read /etc/group TAG:DEFAULT dev:64768 ino:2107740 mode:100644 uid:0 gid:0
Fri Nov 11 2016 12:08:37 PM [ 7368] Allowed exec /usr/bin/head ARGV:[head /etc/passwd] TAG:DEFAULT
    ENV: LOGNAME=jsmith
    ENV: PWD=/home/jsmith
ENV: HISTSIZE=1000

The ACA history report derives shell history from the ACA I/O log, and produces a report similar to a shell’s history command:

# pbreplay --history   aca.iolog.log.aZTkfJ
    1 Info     working directory set to: /home/jsmith
    2 Allowed  date
    3 Allowed  id
4 Allowed  head /etc/passwd

-O Optional. Non-interactive. Produces searchable output by interpreting tty commands such as <beginning of line>, <insert char>, and <delete word>. This option is useful for redirecting the data to a file or piping to another program. For example, the output can be piped to grep to search for specific words or sequences. This option also allows direct searching via the --regex option.

-O Arguments

--R, --regex <regular expression> Optional regular expression to search for using built-in search mechanism. The default output includes runhost, user, date/time, and matching line of text.
--ignore-case Optional flag to ignore case during regex search.
-c <constraint expression> Optional constraint expression using the policy language. Similar to constraints used by pblog. Requires the -O and --regex options.
-p <format expression> Optional output format expression using the policy language. Similar to format expressions used by pblog. Requires the -O and --regex options.
--files "<file glob pattern>"

Optional file glob pattern used to search more than one file at a time.

Quotes are required, so that the shell does not interpret the glob pattern prior to passing it to pbreplay.

Requires the -O and --regex options. The default output includes filename, runhost, user, date/time, and matching line of text.

-X Arguments

-T, --indextime Include newline timestamp in indexed data.
-Q Retrieve filenames from indexing queue.

-Z Arguments

-T, --indextime Include newline timestamp in indexed data.
--forward Index IOLogs identified in the IOLog index store and forward file.

The following table shows the keyboard keys that can be used with pbreplay in interactive mode to emulate the Unix/Linux pager:

Keyboard Keys Used with pbreplay in Interactive Mode

Key

Description

g Go to the beginning of the I/O log.
G Go to end.
Space Display the next screen of the I/O log.
<CR> or <NL> Advance the display one line.
s Skip to the next time marker.
u Undo.
t Display the time stamp from the current line in the I/O log file.
r Redraw from the start.
q or Q Quit.
v Display the variables for the I/O log file.
Backspace or Delete Back up to the last position.
c Continuous slow speed replay.

+ or -

Use + to increase the replay speed. Use a hyphen (-) to decrease the replay speed.

Version 5.1.1 and earlier: option not available.

Version 5.1.2 and later: option available.

f Find.
k Find time stamp. The format is [MM/DD/[CC]YY HH:M [:SS].
.h or ? Display a navigation help message.

Files

I/O log file

pbreplay /usr/adm/pb.jqpublic.ksh.a05998

Entering the command above produces output similar to the following:

Start of log =========================================
    2005/09/08 15:16:07 jqpublic@athena.unix.company.com -> root@athena.company.com ksh
    Commands:
    g - go to start,
    G - go to end,
    Space - go to next input
    <CR> or <NL> - go to next newline,
    s - skip to next time marker
    u - undo,
    t - display time, r - redraw from start, q/Q – quit
    v - dump variables, <BS> or <DEL> - backup to last position
    c – continuous slow speed replay, f - find, k – find time stamp
h or ? - display this help message

You can navigate the I/O log file by pressing the space key (next input character), the carriage return or newline key (newline), or the s character, which shows you what happened each second. Alternatively, you can back up through the log file by pressing the Backspace or Delete key. You can quickly go to the start or end of the log file using g or G, respectively. Display the time of an action at any point in the log file using t, redraw the log file using r, and undo your last action using u. You can also display all of the environment variables that were in use at the time the log file was created using v. Use q or Q to quit pbreplay.

pbreplay -O /var/log/pbul/iolog.aaaaaa
pbreplay -O --regex 'passwd' /var/log/pbul/iolog.aaaaaa
pbreplay -O --regex 'passwd' --files '/var/log/PBLOGS*/iolog.*'
pbreplay -O --regex "passwd" --files "/var/log/pbul.iolog.*" \
    -c "runhost=='hostabc.beyondtrust.com'" -c "date=='2012/04/10'"
pbreplay -O --regex 'passwd' --files '/var/log/PBLOGS*/iolog.*' \
-p "sprintf('%s %s %s %s\n', basename(iolog), user, runhost, regexmatch)"
For more information, please see the following: