SSH Monitoring
Monitor SSH servers by reading the identification banner and optionally pinning the host key fingerprint to detect unauthorized key changes.
SSH Monitoring
SSH monitoring in UptimeHunt verifies that an SSH server is reachable and responding with a valid protocol banner, and can optionally capture the host key fingerprint so you are alerted if it ever changes. This guide covers configuration, how the check works, assertion types, and example scenarios.
Configuration
Required Fields
Service Name — Descriptive identifier for the monitoring service. Example: "Production Bastion SSH".
Host — Hostname or IP address of the SSH server. Example: ssh.example.com or 203.0.113.10. Maximum length: 255 characters.
Optional Fields
Port — TCP port the SSH daemon listens on. Default: 22. Valid range: 1–65535. Change this if your server runs on a non-standard port.
Timeout — Maximum time in seconds to wait for the banner read to complete. Default: 10 s.
Capture host key fingerprint — When enabled, the prober makes a second connection using the paramiko library to read the server's host key and compute its SHA256 fingerprint. Required for the ssh_hostkey_fingerprint assertion type. Disabled by default.
Project — Optional project assignment for organization.
Enabled — Toggle to activate or deactivate monitoring.
Check Interval — Monitoring frequency in seconds. Default: 180 s (3 min). Minimum is plan-dependent (Free: 300 s, Pro: 60 s, Team: 30 s, Enterprise: 10 s).
Host key capture requires paramiko
The "Capture host key fingerprint" option uses the optional paramiko dependency. Probers deployed by UptimeHunt have this available. If you run your own prober and need host key checking, ensure paramiko is installed.
How It Works
The SSH check does not log in or authenticate. It performs a lightweight protocol-level handshake:
- TCP connect — The prober opens a TCP connection to the configured host and port within the timeout.
- Banner read — The server immediately sends its identification string (RFC 4253). For example:
SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13. The prober reads this line without sending any SSH messages. - Banner parse — The banner is split into its components: protocol version (
2.0), software name (OpenSSH), and software version (9.6p1 Ubuntu-3ubuntu13). - Host key capture (optional) — If "Capture host key fingerprint" is enabled, a second connection is made and paramiko negotiates the key exchange to retrieve the server's public host key. The SHA256 fingerprint is computed as the lowercase hex digest of the raw key bytes.
- Result — The response time (banner-read latency in milliseconds) and all parsed fields are recorded and evaluated against any configured assertions.
Reachability: The check is marked reachable whenever the TCP connection succeeds and the server sends any data — even a non-standard banner. A missing or malformed SSH- prefix is not a transport failure; it is data evaluated by the ssh_banner assertion. A transport failure (TCP refused, DNS error, timeout) marks the check unreachable and raises an incident regardless of assertions.
No login or authentication
The SSH check never sends a username, password, or key. Firewall rules and sshd AllowUsers/DenyUsers restrictions do not affect whether the check succeeds — only TCP connectivity and banner delivery matter.
Assertions / Response Validation
Assertions let you define pass/fail conditions beyond basic TCP reachability. Configure them under Expectations on the service detail page. When no assertions are configured, UptimeHunt applies a default: banner contains "SSH-".
ssh_banner — Banner contains
Checks that the raw identification string sent by the server contains a given substring.
| Field | Value |
|---|---|
| Result path | response.banner |
| Operator | contains |
| Default severity | down |
Use cases:
- Confirm the server is running SSH at all (default assertion:
SSH-) - Detect if a non-SSH service is accidentally occupying port 22
Example:
Type: ssh_banner
Value: SSH-2.0ssh_software — Software version contains
Checks that the parsed software version field (everything after the first underscore in the software token) contains a given substring.
| Field | Value |
|---|---|
| Result path | response.software_version |
| Operator | contains |
| Default severity | degraded |
Use cases:
- Verify a minimum version is deployed (e.g., alert if
9.is absent when you expect OpenSSH 9.x) - Detect an unexpected SSH implementation
Example:
Type: ssh_software
Value: 9.ssh_hostkey_fingerprint — Host key fingerprint equals
Checks that the server's host key fingerprint exactly matches a pinned value. Raises an incident when the fingerprint changes — which can indicate key rotation (expected) or a machine-in-the-middle attack (unexpected).
| Field | Value |
|---|---|
| Result path | response.host_key.fingerprint |
| Operator | equals |
| Default severity | down |
Requires: "Capture host key fingerprint" must be enabled on the service.
The fingerprint is the SHA256 hex digest of the raw host key bytes (lowercase, no prefix). To obtain it from a running server:
ssh-keyscan -t ed25519 ssh.example.com | ssh-keygen -lf - -E sha256This outputs something like SHA256:AbCdEf.... Strip the SHA256: prefix and Base64-decode + rehash if needed, or connect once through UptimeHunt and copy the value from the check detail panel after the first successful run.
Fingerprint format
UptimeHunt stores the SHA256 fingerprint as a lowercase hex string (e.g. a1b2c3d4e5f6...), not the SHA256:<base64> format that ssh-keygen -l displays. Copy the value from the check detail panel after the first successful run to ensure the format matches.
Example:
Type: ssh_hostkey_fingerprint
Value: a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcdExamples
Basic availability check
Confirm port 22 is open and the server is speaking SSH.
Service Name: Production Bastion SSH
Host: bastion.example.com
Port: 22
Timeout: 10
Capture host key fingerprint: off
Check Interval: 60 s
Assertions:
ssh_banner contains "SSH-2.0"Non-standard port
A server running sshd on port 2222 (common for reduced scan noise).
Service Name: Dev SSH - port 2222
Host: dev.example.com
Port: 2222
Timeout: 10
Capture host key fingerprint: off
Check Interval: 180 sHost key pinning for MITM detection
Alert immediately if the server's host key changes. Pair this with a low check interval on infrastructure you own.
Service Name: Production DB SSH - key pinned
Host: db-primary.internal.example.com
Port: 22
Timeout: 10
Capture host key fingerprint: on
Check Interval: 60 s
Assertions:
ssh_hostkey_fingerprint equals a1b2c3d4e5f6... (severity: down)
ssh_banner contains "SSH-"Software version enforcement
Alert when a server falls below an expected OpenSSH major version during a fleet rollout.
Service Name: Gateway SSH - version check
Host: gateway.example.com
Port: 22
Timeout: 10
Capture host key fingerprint: off
Check Interval: 300 s
Assertions:
ssh_software contains "9." (severity: degraded)Troubleshooting
Connection refused
Causes: sshd not running, wrong port configured, firewall blocking the prober's source IP.
Steps: Verify sshd is active (systemctl status sshd), confirm the port, and check that the prober's IP ranges are permitted in your firewall rules.
Timeout
Causes: Network path blocked silently (no TCP RST), overloaded server, overly strict timeout setting.
Steps: Try increasing the timeout. Confirm the host is reachable from the same network region as the prober. Check for silent firewall drops.
DNS error
Causes: The hostname does not resolve from the prober's location.
Steps: Use an IP address temporarily to isolate. Verify the DNS record exists and has propagated. Check for split-horizon DNS that may not be visible to external probers.
Fingerprint mismatch alert after expected key rotation
If you intentionally regenerated the host key (e.g., new server, reprovisioning), update the pinned fingerprint in the ssh_hostkey_fingerprint assertion. Connect once to let UptimeHunt record the new value, copy it from the check detail panel, and replace the old value.