Test PAM Failure Paths with pam_stress

You will identify the installed pam_stress module, build a disposable PAM service entry, and select predictable success or failure behaviour for a test harness. Allow about 20 minutes if you already have a PAM test client. This module is for exercising PAM stacks, not for protecting a real login service.

1. Confirm the installed module and version

The module is shipped by Ubuntu's libpam-modules package on this machine. Check the package version and the shared object before writing any configuration:

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

Package revisions differ between Ubuntu updates, so record the version from your own host. The behaviour described here is the installed Linux-PAM pam_stress(8) interface, whose manual page is dated 5 July 2023. The module has no normal executable to run directly: PAM loads the shared object while processing a service configuration.

2. Prepare a disposable PAM service

Use a service name that only your test client invokes. The manual shows that the module provides auth, account, password and session module types. A minimal authentication test entry is:

auth required pam_stress.so

With elevated privileges, save that line as a separate file such as /etc/pam.d/pam-stress-demo, but only after confirming that your test client uses the same service name. Do not add it to an existing production stack. Preserve the original before changing an existing disposable file:

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/pam-stress-demo /etc/pam.d/pam-stress-demo.bak

If the file does not yet exist, the backup command should not be used as written. Create the file through your normal privileged editor instead. The PAM line is configuration, not a shell command.

3. Exercise the normal authentication path

Run the test client as an ordinary user and select the pam-stress-demo service. The exact client and its prompts are outside this module's manual page. A successful test means the client reports a PAM success result; the module itself does not promise a particular greeting or output format.

The default path may ask for a password through PAM's conversation function. That password is only test input, but use a throwaway value. Never use a real password while investigating debug. If your client can show the returned PAM code, the documented success value is PAM_SUCCESS.

4. Force controlled failures

Add one option at a time to the PAM line and rerun the same test:

auth required pam_stress.so fail_1
auth required pam_stress.so fail_2

fail_1 makes the module's first function fail. fail_2 makes its second function fail, if there is one. The returned error depends on the PAM function and can be one of the documented failure values, including PAM_AUTH_ERR, PAM_PERM_DENIED, PAM_CONV_ERR or PAM_SYSTEM_ERR. Test the result through the client rather than relying on a guessed message.

For an account or password-change path, expired makes the module act as though the user's password has expired. For password changing, prelim makes the preliminary check fail. required makes that module fail if the user has not already been authenticated by this module. These flags are deliberately specific to PAM module functions, so do not add them to an authentication test and assume they test account expiry.

5. Handle password tokens safely

The default module behaviour can prompt for a token. use_first_pass forbids a prompt and uses the existing PAM_AUTHTOK; it fails when that token is unavailable. try_first_pass uses the existing token when present, but prompts if it is absent. These options are useful when testing stack ordering, not as general fixes for a failed test.

6. Test password-change-specific branches

For a password-change test, use a separate disposable stack with the password type:

password required pam_stress.so prelim
password required pam_stress.so

The two lines represent separate module calls in one stack. The first tests the preliminary branch; the second exercises the ordinary password operation. The module also uses the PAM data string stress_new_pwd, with yes as its only possible value, to indicate that account management requires a new password. Do not infer that this changes a real account: it only affects the PAM conversation being tested.

rootok is intended for pam_sm_chauthtok and permits root to change the test user's password without entering the old password. Treat that as a security-sensitive test case and use a disposable account. It does not grant root access to unrelated services.

7. Remove the test configuration

After the test, remove the disposable service file with elevated privileges, or restore the backup if you changed an existing disposable file:

$ sudo rm -- /etc/pam.d/pam-stress-demo
$ sudo mv -- /etc/pam.d/pam-stress-demo.bak /etc/pam.d/pam-stress-demo

Run only the command matching what you actually created. The removal is irreversible unless you have a backup, so check the path carefully first. If a service is still using the test file, stop that test client before removing it. Do not delete system PAM files as a shortcut for cleanup.