Audit Selected PAM Sessions with pam_tty_audit

You will finish with a PAM session rule that records TTY input for selected users, leaves other users unaudited, and gives you a command for reviewing the resulting audit records. 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. 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 that you run directly. It supports only 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: doing so can duplicate records, broaden collection and make rollback harder.

2. Back up the PAM file before editing

Use elevated privileges for the backup because 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 enables it for the named account. This ordering 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. For example, this audits two named accounts:

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

Patterns are glob patterns, not regular expressions. The module also accepts UID ranges. A range such as 1000: matches UID 1000 and above, while :1000 matches only UID 1000. Prefer explicit names for a small administrative group; use a UID range only when its boundary is part of the account-management policy.

Do not add log_passwd casually. Without that option, passwords are normally not logged when the terminal is in the usual password-entry mode, but the manual warns that passwords can still appear in some circumstances. For example, input to an SSH session is logged according to the local TTY state, even when the password is being entered 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 correct the account name rather than testing a rule that cannot match. If the file already contains a pam_tty_audit session line, edit the existing policy with care 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. Perform a harmless, recognisable action 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 important 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. If aureport is unavailable, that is a tooling gap, not proof that 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 contains 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. That includes processes a user starts after login and can include a daemon restarted by that user. Such a daemon may then audit input from other users unless those users are explicitly disabled. This 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 identifies 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.

TTY auditing is not a complete command audit. It records terminal input, not every process action, and it creates sensitive evidence that must be protected. Restrict access to audit logs, define retention, and tell operators what is collected. Never paste captured TTY data into tickets or chat while diagnosing the setup.

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 retain 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.