Audit Selected PAM Sessions with pam_tty_audit

pam_tty_audit records terminal input for the accounts you name, leaving everyone else alone. It is the tool for when a security review asks "can we prove what the admin typed". The examples use pam_tty_audit from Ubuntu's libpam-modules version 1.5.3-5ubuntu5.7.

• Allow about twenty minutes, plus time to test a real login.
• You need: root access, a service using PAM, Linux audit tooling if you want to inspect records with aureport, and a second session for recovery.
• Warning: this is security-sensitive. TTY auditing can capture confidential input. Do not enable it on a production service until the retention, access and deletion rules for audit data are agreed.

1. Check the installed module and choose a service

pam_tty_audit is a PAM module, not a command you run directly, and it only supports the session module type. First confirm the module and package version with ordinary, read-only commands:

$ test -r /usr/lib/x86_64-linux-gnu/security/pam_tty_audit.so && echo 'module present'
module present
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules:amd64 1.5.3-5ubuntu5.7

Choose one PAM service deliberately, such as SSH or a local login service; the exact file is host-specific. Do not add the rule to every file in /etc/pam.d: that duplicates records, broadens collection and makes rollback harder.

2. Back up the PAM file before editing

Use elevated privileges for the backup, since PAM files are normally owned by root. Replace the placeholder with the service you selected:

# PAM_SERVICE_FILE=/etc/pam.d/sshd
# cp --preserve=all "$PAM_SERVICE_FILE" "$PAM_SERVICE_FILE.bak-pam-tty-audit"
# ls -l "$PAM_SERVICE_FILE" "$PAM_SERVICE_FILE.bak-pam-tty-audit"

The backup is the recovery path. If the service stops accepting logins after the edit, use the already-open privileged session to restore it:

# cp --preserve=all "$PAM_SERVICE_FILE.bak-pam-tty-audit" "$PAM_SERVICE_FILE"

Do not remove the backup until a separate login and the audit review both work. The restore command changes system authentication configuration, so check the variable before pressing Enter.

3. Add a narrow session rule

Edit the selected file as root and add one line in its session section:

session required pam_tty_audit.so disable=* enable=ADMIN_USER

Replace ADMIN_USER with the exact account name to audit. The first option disables auditing for every user matched by *; the later enable option then turns it on for the named account. This order follows the module's documented precedence and is safer than enabling a name without first establishing a default-off rule.

Multiple names are comma-separated, so this audits two named accounts:

session required pam_tty_audit.so disable=* enable=alice,bob

• Patterns are glob patterns, not regular expressions.
• UID ranges work too. 1000: matches UID 1000 and above, :1000 matches only UID 1000. Prefer explicit names for a small administrative group, and use a UID range only when its boundary is part of the account-management policy.
• Do not add log_passwd casually. Without it, passwords are normally not logged when the terminal is in the usual password-entry mode, but the manual warns they can still appear in some circumstances, for example input to an SSH session logged according to the local TTY state even when the password goes into software on the remote host.

4. Check the rule before opening a test session

Run these ordinary inspection commands after saving the file:

$ grep -n 'pam_tty_audit' /etc/pam.d/sshd
42:session required pam_tty_audit.so disable=* enable=ADMIN_USER
$ getent passwd ADMIN_USER
ADMIN_USER:x:1001:1001:Administrator:/home/ADMIN_USER:/bin/bash

Your line number and account record will differ. If getent returns nothing, stop and fix the account name rather than testing a rule that cannot match. If the file already has a pam_tty_audit session line, edit the existing policy carefully instead of adding a second, competing rule.

5. Open a new session and verify the audit path

Start a new session through the service you changed; existing sessions do not retroactively acquire the new session flag. Do something harmless and recognisable as the selected account, then close that test session.

On a host with the Linux audit userspace tools installed, an administrator can review TTY records with:

# aureport --tty

The report format and whether records appear depend on the kernel audit configuration and the service's PAM session flow. The real check is that a new session for the selected user produces TTY audit activity, while a comparable session for a user matched by disable=* does not. No aureport? That is a tooling gap, not proof the PAM rule failed.

A successful PAM session returns PAM_SUCCESS. If the module cannot read or modify the TTY audit flag, it returns PAM_SESSION_ERR and the system log carries more detail. Check the service logs from the privileged recovery session rather than repeatedly retrying a failing login.

6. Account for inheritance and service-specific behaviour

TTY auditing is inherited by processes started by the audited user, including anything they start after login and even a daemon they restart. Such a daemon may then audit input from other users unless those users are explicitly disabled, which is why disable=* should normally be the first option for a daemon's PAM policy.

The open_only option sets the audit flag when the session opens but does not restore it when the session closes. The manual names services such as sudo, which do not fork to run the authenticated session, as cases where this behaviour can be necessary. Do not add it as a troubleshooting guess: it changes the lifetime of the flag and needs a service-specific reason.

7. Remove the rule and confirm the rollback

When the monitoring period ends, remove the pam_tty_audit line from the service file, or restore the backup if this guide's change was the only edit:

# cp --preserve=all /etc/pam.d/sshd.bak-pam-tty-audit /etc/pam.d/sshd
# grep -n 'pam_tty_audit' /etc/pam.d/sshd || echo 'pam_tty_audit rule removed'

Open another test session and check that the service still authenticates. Existing sessions keep their current process state, so close sessions created under the auditing rule. Treat already-recorded audit data separately: removing the PAM line does not erase it. Follow the approved audit retention and disposal process instead of deleting files by hand.