Linux password and SSH key rotation

What this page covers

Layer 04 handles the lifecycle of the credentials the system holds: replacing passwords and SSH keys on target hosts on a schedule, and confirming a login works before committing the change. A rotation that does not verify stays in a pending state and retries on its own, so the credential in the system is never replaced by a value that cannot connect.

What you need

• A target host running the SSH service that accepts the system’s current credential.
• For key rotation, the SSH file transfer subsystem enabled on the target, with the authorized keys file in its standard place.
• A credential for that account already registered in the system.

How to set it up

Go to the Secret Rotation page and press Add plan:

1. Name.
2. Assets: the picker lists the assets that have a rotation channel set.
3. Account scope: all accounts, or a named list.
4. Secret type: password or SSH key.
5. Schedule: a frequency picker (daily / weekly / monthly / quarterly / yearly / custom), with a preview of the next three run times. The custom field is where a five-field timetable is filled in. Empty means manual runs only.
6. Enabled switch.

The password type takes a length (16 by default, from 12 to 64) and switches for including symbols and excluding easily confused characters. Generated passwords always leave out shell-sensitive characters and control characters.

The key type has two strategies:

• Add, verify, remove (default): append the new public key, verify with a real connection using the new private key, and only then remove the line the system pushed previously. Keys the user put there are untouched.
• Replace outright: rewrite the authorized keys file to hold the new key alone.

A plan can also set a “maximum credential age override”, where 0 keeps the global policy key. This value only affects what the rotation evidence report decides.

Once the plan exists, “Run now” runs it once by hand and Records shows the outcome.

What one run does

1. Generate the new secret and store it under envelope encryption as a candidate credential, marked unverified.
2. Make the change on the target. The new password and the elevation password travel on standard input, never in the command line arguments.
3. Sign in once with the new secret to verify it.
4. Commit the account credential to the new value only after that, and delete the candidate row at once.

A candidate that does not verify stays in the “unverified credentials” area and retries with exponential backoff, showing the attempt count, the next retry time, and the last reason. Past the deadline it is marked abandoned and an alert is pushed; an abandoned candidate is cleared explicitly by an administrator, and the clearing itself leaves a record.

Existing connections keep working after a rotation and use the new credential from the next login. Private keys are never sent to the target host.

What auditors can see

• Execution records carry four states: succeeded, failed, skipped, and unverified (retrying). The list carries a count per state.
• Each record holds both the account identifier and the account name at the time, so a later rename or deletion leaves it readable.
• Reasons for failures and unverified results are recorded as machine codes and rendered as text in the interface. What the target returned stays in the server log.
• A failed rotation is pushed to the existing notification channels, with the plan name, asset, account, and reason code.
• Clearing an abandoned candidate leaves a record with the asset, account, and operator, and holds no secret material.