SSH & SFTP Host Key Rotation Monitor

Monitor the SSH server host key presented by authorized public SSH and SFTP endpoints. The Actor performs a bounded SSH handshake without authenticating, logging in, opening an SFTP session, or transferring data. It stores a named cross-run history and emits a structured record when the negotiated fingerprint changes.

This is useful for SFTP integrations, CI/CD systems, managed file-transfer jobs, and vendor endpoints where an unplanned host-key change can stop strict clients—or could indicate that the endpoint needs independent security review.

What it detects

• first successful fingerprint for a target and selected host-key algorithm
• unchanged fingerprint
• a different fingerprint, with separate fingerprint_first_seen context
• return to a fingerprint seen in an earlier run
• mismatch against an optional allowlist of expected fingerprints
• connection, DNS, timeout, handshake, and algorithm-negotiation failures without overwriting the last successful state

Input

Use a stable monitorId and 1–50 authorized public targets.

{
  "monitorId": "finance-sftp-vendors",
  "targets": [
    {
      "host": "sftp.example.com",
      "port": 22,
      "hostKeyAlgorithm": "ssh-ed25519",
      "expectedFingerprints": [
        "SHA256:..........................................."
      ],
      "label": "Settlement export"
    }
  ],
  "timeoutSeconds": 15,
  "maxConcurrency": 3
}

Field	Required	Description
monitorId	Yes	Stable ID separating one watchlist's history from another.
targets	Yes	1–50 public, authorized SSH/SFTP endpoints. Duplicate host/port/algorithm tuples are checked once.
host	Yes	Public FQDN or public IP address. Supply a host, not a URL.
port	No	TCP port, default 22; allowed range 1–65535.
hostKeyAlgorithm	No	Exact algorithm to negotiate, default ssh-ed25519. Select the algorithm used by the client workflow you want to protect.
expectedFingerprints	No	Up to 20 trusted OpenSSH SHA256: fingerprints. Multiple values support planned overlap rotations.
label	No	Human-readable integration label.
timeoutSeconds	No	Total bounded timeout per target, 5–30 seconds.
maxConcurrency	No	1–5 concurrent endpoint checks.

Supported algorithm selectors are ssh-ed25519, NIST P-256/P-384/P-521 ECDSA, rsa-sha2-512, rsa-sha2-256, and legacy ssh-rsa. Selecting an RSA SHA-2 signature algorithm can still return a key whose underlying key type is ssh-rsa; the record includes both the requested negotiation algorithm and returned key type.

The default checks GitHub's documented SSH-over-HTTPS endpoint on port 443, so a default QA run is non-empty. This product is independent and is not affiliated with GitHub.

Output

One record is emitted per target.

status	Meaning
initial_snapshot	First successful observation; baseline and history were stored.
unchanged	Same fingerprint as the previous successful run.
changed	Different from the previous successful run. Check fingerprint_first_seen to distinguish a never-before-seen key from a previously observed key reappearing.
connection_error	DNS, policy, TCP, timeout, SSH handshake, or algorithm negotiation failed. Successful prior state is preserved and no custom event is charged.

Important fields include fingerprint_sha256, previous_fingerprint_sha256, fingerprint_first_seen, observed_fingerprint_count, expected_fingerprint_match, requested_host_key_algorithm, key_type, key_bits, server_identification, resolved_ip, checked_at, and state_store_mode.

Persistence and rotation overlap

Successful observations are stored in the named key-value store ssh-sftp-host-key-monitor-state-v1, keyed by SHA-256 of monitorId + host + port + selected algorithm. Up to 20 distinct observed fingerprints are retained per target.

Some managed SFTP services present old and new keys interchangeably during a staged rotation. Such transitions still have status: changed, but a key already in history has fingerprint_first_seen: false. Configure every independently verified planned fingerprint in expectedFingerprints to distinguish an allowed overlap from an unknown key.

Pricing

The Actor charges one ssh_host_key_check event only after a public endpoint has resolved safely, completed the selected SSH host-key negotiation, produced a fingerprint, and stored the successful observation. Input rejects, blocked destinations, connection failures, and handshake failures are not charged by this event. The current Store price is shown on the listing.

Security and responsible use

• Check only endpoints you own or are authorized to monitor.
• Production rejects private, loopback, link-local, multicast, and reserved destinations, including hostnames resolving to any such address.
• The connection is pinned to a validated resolved public address to reduce DNS-rebinding risk.
• The Actor performs one bounded SSH handshake per target and does not authenticate, send credentials, enumerate accounts, execute commands, open SFTP, or transfer files.
• Targets are capped at 50, concurrency at five, and time at 30 seconds per target.
• Failed checks do not overwrite a successful baseline and are not charged by the custom event.

Critical trust limitation

A remotely observed host key is not self-authenticating. This Actor detects what the network endpoint presented from Apify's vantage point; it cannot prove that a first-seen or changed key belongs to the intended operator. Verify new fingerprints through an independent trusted channel such as the vendor's signed security notice, official documentation, account console, or support contact before updating production known_hosts data. Never auto-trust a changed fingerprint solely because this Actor observed it.

The Actor monitors one explicitly selected negotiation algorithm per target. It does not enumerate every key a server might advertise, test user authentication, validate SSH certificates against a CA, assess cipher/KEX policy, prove SFTP availability, or replace strict host-key verification in the real client.

Scheduling

Schedule daily or hourly according to the vendor's change process. Route changed, connection_error, or expected_fingerprint_match: false records to a human review workflow using Apify integrations or webhooks. Do not automate acceptance of new keys.

Local development

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
APIFY_LOCAL_STORAGE_DIR=./storage .venv/bin/python -m src

Run deterministic state and adversarial tests with:

$.venv/bin/python smoke_test.py