SSH Key Guard

SSH Key Guard — a ServerGuard component that watches the SSH keys of Linux server users. It detects the addition and removal of keys in authorized_keys and stores a detailed event.

1. Why SSH Key Guard is needed

The authorized_keys file determines which public keys can sign in to the server as a specific user:

/home/<user>/.ssh/authorized_keys
/root/.ssh/authorized_keys

If someone else's key is added to it without your knowledge, that is a hidden way to sign in: it will keep working even after the password is changed. SSH Key Guard lets you quickly notice such a change.

detect a change → identify the key → record an event

2. Key features

• monitoring of authorized_keys for all users;
• detection of added and removed keys;
• baseline — a reference set of keys;
• fingerprint SHA256:... for convenient key identification;
• integration with Linux Audit (auditd): process, user, command;
• network information and GeoIP for public IPs;
• structured JSON events and local history;
• operation as a systemd service;
• a simple command interface.

3. How it works

The module combines two mechanisms:

Snapshot monitoring   — what changed?
Linux Audit           — which operation and which process did it?

authorized_keys
       |
       v
   snapshot
       |
       v
  comparison with the previous state
       |
  +----+-----------+
  |                |
  v                v
key_added      key_removed
  |                |
  +-------+--------+
          |
          v
   creating an event
          |
          v
    JSON log

4. Baseline

Before monitoring, a baseline is created — a list of keys that are considered known.

baseline:   KEY-A, KEY-B
later:      KEY-A, KEY-B, KEY-C
result:     KEY-C → new key (key_added)

Create a baseline manually:

python3 ssh_key_guard.py init

5. Events

Example: there was KEY-A, now there is KEY-A, KEY-B — a key_added is created for KEY-B.

6. What is stored about a key

{
  "type": "ssh-ed25519",
  "fingerprint": "SHA256:...",
  "comment": "admin@computer",
  "line": 3
}

Common types are supported: ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256/384/521, as well as security-key and certificate variants of OpenSSH.

Fingerprint allows a key to be identified without showing it in full.

7. User and file information

The event is associated with the account whose authorized_keys was changed:

{ "username": "admin", "uid": 1000, "home": "/home/admin", "shell": "/bin/bash" }

The file path and its metadata (size, permissions, modification time, SHA-256) are also stored.

8. Linux Audit

If auditd is installed on the server, SSH Key Guard receives additional context about the operation:

UID, AUID, PID, PPID
process name and executable file
command and working directory
operation result, terminal

For example: the key was added by a vim process of a user with UID 1000, or by a python3 script.

AUID preserves the original user even after sudo or su — this helps to understand exactly who performed the action.

sshd → bash → sudo → vim

9. Operation without auditd

Without auditd, the module continues to detect changes by comparing snapshots: which key was added or removed and which user was affected. Only the details about the process and operation will be missing, so for the full picture auditd is recommended.

10. Network information and GeoIP

The module can determine the IP address associated with the SSH session (from audit or the active session).

For public IPs, the external service ipinfo.io is used: country, region, city, organization, hostname. For local and private addresses, no request is made.

GeoIP does not determine a person's physical location. Use it as an additional hint. Keep in mind that the public IP is transmitted to a third-party service.

11. Data storage

• Events — the ssh_key_events.json log, up to the last 5000 events;
• State — the current known state for comparison.

Writes are performed through a temporary file followed by replacement, so an abnormal termination should not corrupt the log.

Each event has a unique ID:

{
  "id": "...", "version": "1.0.1", "timestamp": "...",
  "action": "key_added",
  "account": {}, "file": {}, "key": {}, "old_key": null,
  "modifier": {}, "network": {}, "server": {}
}

12. Launch and check interval

By default, the check is performed every 5 seconds:

python3 ssh_key_guard.py monitor

A different interval:

python3 ssh_key_guard.py monitor --interval 10

For continuous operation, the module is launched as a systemd service and starts automatically after the server reboots.

13. Commands

14. systemd service

systemctl status serverguard-ssh-key.service
systemctl start serverguard-ssh-key.service
systemctl stop serverguard-ssh-key.service
systemctl restart serverguard-ssh-key.service

Service log:

journalctl -u serverguard-ssh-key.service -n 50
journalctl -u serverguard-ssh-key.service -f

15. Requirements and permissions

Linux, Python 3, and OpenSSH are required. For extended auditing, auditd, auditctl, and ausearch are recommended; for network information, ss and curl are used.

Some functions require administrator permissions: reading other users' files, working with auditd, analyzing processes. Therefore, continuous monitoring is usually run as root.

16. Privacy

Events may contain the username, UID, the path to authorized_keys, fingerprint, IP address, command, and process information. This is sensitive data: restrict access to the logs and state files to trusted administrators only.

17. What SSH Key Guard does not do

This is a system for monitoring, detection, auditing, and logging. It does not:

• remove suspicious keys;
• block IP addresses;
• delete users or change passwords;
• stop the SSH server;
• replace a firewall or brute-force protection.

The decision on further actions is made by the administrator or other security components.

18. Limitations

• The module analyzes recognized SSH keys, so changing only a comment does not always create an event.
• The check is periodic: a change that was reverted between two checks may not make it into the snapshot. auditd reduces this risk.
• Unavailability of GeoIP or another additional source does not stop the main monitoring.

19. Recommendations

• create the baseline on a known-clean server;
• install and use auditd;
• do not modify the state files manually;
• restrict access to the logs;
• monitor the state of the systemd service;
• regularly review events and check unfamiliar keys;
• use SSH Key Guard together with SSH Hardening, Security, and FileGuard.

20. SSH key setup guide

This guide explains how to create an SSH key, install the public key on a Linux server, and connect to the server using ServerGuard.

Overview

ServerGuard can authenticate with Linux servers using an SSH private key instead of an account password.

SSH key authentication uses a pair of cryptographic keys: a private key stored on your computer and a public key installed on the Linux server.

Note: The private key stays on your computer. Only the public key should be installed on the server.

Requirements

Before starting, make sure you have:

• Windows 10 or Windows 11.
• OpenSSH Client installed on Windows.
• Access to a Linux server.
• The server IP address or hostname.
• A Linux account that can log in through SSH.
• The account password for the initial key installation.

Creating an SSH key

Open PowerShell on Windows.

Check that OpenSSH is available:

ssh -V

Create an Ed25519 SSH key:

ssh-keygen -t ed25519

When Windows asks where to save the key, press Enter to use the default location.

The default location is:

C:\Users\YOUR_USERNAME\.ssh\id_ed25519

You will then be asked to enter a passphrase. You can leave it empty or use an additional passphrase to protect the private key.

Private and public keys

After creating the key, Windows normally creates two files:

To display your public key:

Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub"

The output should look similar to:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... ServerGuard

Installing the public key on the Linux server

First connect to your Linux server using the normal SSH password:

ssh root@SERVER_IP

Replace SERVER_IP with the address of your server.

Create the SSH directory:

mkdir -p ~/.ssh
chmod 700 ~/.ssh

Open the authorized keys file:

nano ~/.ssh/authorized_keys

Paste the complete contents of your id_ed25519.pub file into this file.

Each public key must occupy its own line.

Save the file in nano:

Ctrl + O
Enter
Ctrl + X

Configuring SSH key permissions

Set the recommended permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

You can verify the file:

ls -la ~/.ssh

The authorized_keys file should not be writable by other users.

Testing SSH key authentication

Exit the current SSH session:

exit

From Windows, connect using the private key:

ssh -i "$env:USERPROFILE\.ssh\id_ed25519" root@SERVER_IP

If the key has no passphrase and everything is configured correctly, the Linux account password should not be requested.

Note: If your SSH key has a passphrase, SSH may ask for the passphrase protecting the private key. This is different from the Linux account password.

Testing password authentication

You can test password authentication without deleting the SSH key.

Use:

ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password root@SERVER_IP

SSH will attempt password authentication for this connection only.

Warning: This command does not remove or modify your SSH key. It only tells the SSH client not to use public-key authentication for this connection.

Connecting to the server using ServerGuard

Start ServerGuard and create or edit a server connection.

Enter the normal server connection information:

• Server IP address or hostname.
• SSH port, normally 22.
• Linux username.

For authentication, select:

Auth: Private key

Select your private key. For example:

C:\Users\YOUR_USERNAME\.ssh\id_ed25519

If the private key has a passphrase, enter it in the corresponding field.

In ServerGuard, complete the following connection steps:

1. Authentication method — select Private key instead of password authentication.
2. Private key path — select the private key stored on your Windows computer, for example C:\Users\YOUR_USERNAME\.ssh\id_ed25519.
3. Verify the connection — after connecting, ServerGuard should indicate that the server was authenticated using the private key.

SSH key passphrase

A passphrase is an additional password that protects the private key file.

There are two different credentials:

• Linux password — password of the server account.
• SSH key passphrase — protects the private key on your computer.

If the private key was created without a passphrase, leave the ServerGuard key passphrase field empty.

SSH Hardening

SSH key authentication is especially important when using ServerGuard SSH Hardening.

Hardening can change SSH authentication settings. Losing access to a server after changing SSH settings can be difficult to recover from.

ServerGuard therefore checks the authentication method before applying SSH Hardening.

Note: ServerGuard allows SSH Hardening to continue when the current ServerGuard connection uses SSH public-key authentication.

Important: If ServerGuard is connected using password authentication, SSH Hardening is blocked for safety. This prevents password authentication from being disabled while the current connection depends on that password.

Before using SSH Hardening, make sure that:

1. The public key is installed on the server.
2. SSH key authentication works.
3. ServerGuard is connected using Private key.
4. You can reconnect to the server using the private key.

Troubleshooting

Permission denied (publickey)

Check that the public key is present:

cat ~/.ssh/authorized_keys

Check the permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Check whether public-key authentication is enabled:

sshd -T | grep pubkeyauthentication

The expected result is:

pubkeyauthentication yes

ServerGuard cannot authenticate using the key

Verify that the selected key is the private key:

id_ed25519

Do not select:

id_ed25519.pub

The .pub file is the public key and should not be used as the private key in ServerGuard.

SSH asks for a password

Test the connection manually:

ssh -v -i "$env:USERPROFILE\.ssh\id_ed25519" root@SERVER_IP

The verbose output can show whether the client is actually attempting to use the selected key.

Test the key with maximum SSH debugging

ssh -vvv -i "$env:USERPROFILE\.ssh\id_ed25519" root@SERVER_IP

Security recommendations

Protect your private SSH key carefully.

• Never publish the private key.
• Never upload the private key to GitHub.
• Never send the private key through Telegram, email or other messaging services.
• Do not copy the private key to the Linux server unless there is a specific security reason.
• Consider using a passphrase to protect important private keys.
• Keep a secure backup of important keys.

Important: If someone obtains your private SSH key and can use it, they may be able to authenticate to servers where the corresponding public key is authorized. Treat a leaked private key as compromised and replace it.

Summary

The complete ServerGuard SSH key workflow is:

Windows
   │
   ├── id_ed25519
   │      └── Private key
   │
   └── id_ed25519.pub
          │
          ▼
Linux Server
   │
   └── ~/.ssh/authorized_keys
          │
          ▼
SSH key authentication
          │
          ▼
ServerGuard
   │
   └── Auth: Private key
          │
          ▼
SSH Hardening and server management

Once key authentication has been tested successfully, ServerGuard can use the private key to establish a secure SSH connection to the Linux server.

21. Conclusion

identifies users → finds authorized_keys → creates a baseline
→ compares snapshots → detects added and removed keys
→ adds context from auditd → stores a structured event

SSH Key Guard is responsible for a distinct security layer — control of SSH keys and the events related to them.

This documentation describes the purpose and operating principle of SSH Key Guard at the user level.