feat: the managing client and sshd's per-source penalties (NetOrk/netork#1800) #63

Merged
christianmanivong merged 1 commits from feat/ssh-penalties-1800 into main 2026-10-31 23:29:09 +00:00
5 changed files with 698 additions and 18 deletions

No files matched your search

+12
View File
@@ -14,6 +14,18 @@ recorded here; their history is the git log.
3.12 venv no longer has.
### Added
- `OpenSshServerMixin.exempt_from_ssh_penalties`: puts the address the host sees
the managing client at (`$SSH_CONNECTION`) into `PerSourcePenaltyExemptList`,
in `/etc/ssh/sshd_config.d/00-netork-penalty-exempt.conf`, next to the host's
own exemptions. Only where sshd has per-source penalties (OpenSSH 9.8+; an older
one refuses the directive) and sshd_config includes the drop-in directory;
checked with `sshd -t` and `sshd -T`, then a new session, and taken back on any
failure. Helpers: `parse_penalty_exemptions`, `client_address`, `is_exempt`
(NetOrk/netork#1800).
- `retry_refused` and `refused_before_banner` (`napalm_device_types.ssh_host_keys`):
a connection sshd closes before its banner -- what OpenSSH 9.8+ does to a source
it has just penalised -- is tried again after 1, 3, 7 and 15 s.
`HostKeyCheck.connect` does so itself (NetOrk/netork#1800).
- `ARP_AGE_UNKNOWN` (`napalm_device_types.arp`, `-1.0`): the `age` a driver reports
in `get_arp_table` and `get_ipv6_neighbors_table` when the device does not say how
old an entry is. `0.0` means "confirmed just now" and is no stand-in for it
+57 -2
View File
@@ -27,6 +27,11 @@ A caller that passes neither keeps working as before (first use, every time),
and a driver that ignores both still connects for a caller that passes them:
old and new versions on either side do not break each other.
A connection sshd turns away before its banner -- OpenSSH 9.8+ does that to a
source it has just penalised -- is tried again after a pause
(:func:`retry_refused`, :data:`REFUSED_RETRY_WAITS`); :meth:`HostKeyCheck.connect`
does so itself, a netmiko driver wraps its ``ConnectHandler`` in it.
:class:`HostKeyCheck` is the one implementation, for a paramiko ``SSHClient``
(:meth:`~HostKeyCheck.connect`) and for netmiko (:meth:`~HostKeyCheck.netmiko`,
then :meth:`~HostKeyCheck.observe`). Like :mod:`napalm_device_types.channel` it
@@ -40,7 +45,8 @@ import hashlib
import logging
import os
import tempfile
from collections.abc import Iterator, Mapping
import time
from collections.abc import Callable, Iterator, Mapping
from contextlib import contextmanager
from dataclasses import dataclass
from typing import Any
@@ -54,6 +60,13 @@ KNOWN_KEYS_ARG = "ssh_host_keys"
#: The ``optional_args`` key that carries the callable every seen key goes to.
OBSERVER_ARG = "ssh_host_key_observer"
#: The waits before each new attempt when sshd turns a connection away before its
#: banner. OpenSSH 9.8+ does that to every connection from a source it has just
#: penalised (``PerSourcePenalties``) -- one whose connections did not
#: authenticate, a scanner's probes -- for seconds to minutes. 26 s in all
#: outlasts the 16 s penalty seen on a new Ubuntu 26.04 host (NetOrk/netork#1800).
REFUSED_RETRY_WAITS = (1.0, 3.0, 7.0, 15.0)
#: The netmiko arguments this module decides; a caller's own values give way.
_NETMIKO_HOST_KEY_ARGS = ("ssh_strict", "system_host_keys", "alt_host_keys", "alt_key_file")
@@ -185,6 +198,48 @@ def _refused_key(exc: BaseException) -> Any | None:
return None
def refused_before_banner(exc: BaseException) -> bool:
"""Whether *exc*, or what it wraps, is sshd closing the connection before its banner.
paramiko says "Error reading SSH protocol banner" (netmiko and drivers wrap
it), with the connection's EOF or reset underneath. A failed login, a
silent host and a closed port are something else: waiting does not end them.
"""
seen: set[int] = set()
stack: list[BaseException | None] = [exc]
while stack:
current = stack.pop()
if current is None or id(current) in seen:
continue
seen.add(id(current))
if "protocol banner" in str(current):
return True
stack.extend([current.__cause__, current.__context__])
return False
def retry_refused[T](
attempt: Callable[[], T],
*,
waits: tuple[float, ...] = REFUSED_RETRY_WAITS,
sleep: Callable[[float], None] | None = None,
) -> T:
"""*attempt*, again after each of *waits* while sshd turns it away before its banner.
Any other error, and the last refusal, go to the caller unchanged.
"""
pause = sleep or time.sleep
for wait in waits:
try:
return attempt()
except Exception as exc:
if not refused_before_banner(exc):
raise
logger.info("SSH connection turned away before its banner; again in %s s", wait)
pause(wait)
return attempt()
class HostKeyCheck:
"""How one driver connection verifies its host's key.
@@ -220,7 +275,7 @@ class HostKeyCheck:
"""``client.connect()`` to this host with *kwargs*, verified and reported."""
self.prepare(client)
with self.refusing():
client.connect(hostname=self.host, port=self.port, **kwargs)
retry_refused(lambda: client.connect(hostname=self.host, port=self.port, **kwargs))
return self.observe(client.get_transport())
# ------------------------------------------------------------------
+211 -16
View File
@@ -30,10 +30,19 @@ Only without such an ``Include`` is sshd_config itself rewritten, after a copy.
3. After the reload, *verify* -- the caller's -- opens a new session. The
running one survives a reload, so if the new one cannot get in, this one
puts the old state back and reloads again.
**The managing client is exempt from per-source penalties** where sshd has them
(OpenSSH 9.8+, :meth:`OpenSshServerMixin.exempt_from_ssh_penalties`). sshd
penalises a source whose connections do not authenticate -- a scanner's probes
-- and then drops every connection from it, the managing session's included.
The address is the one the host sees (``$SSH_CONNECTION``); it joins the
host's own ``PerSourcePenaltyExemptList`` in :data:`PENALTY_DROPIN_PATH`, with
the same three checks. An older sshd is not touched: it refuses the directive.
"""
from __future__ import annotations
import ipaddress
import time
from collections.abc import Callable, Iterable, Mapping, Sequence
from dataclasses import dataclass, field
@@ -57,6 +66,9 @@ MAIN_CONFIG = "/etc/ssh/sshd_config"
DROPIN_DIR = "/etc/ssh/sshd_config.d"
#: ``00-`` so it sorts before every other drop-in: sshd keeps the first value it reads.
DROPIN_PATH = f"{DROPIN_DIR}/00-netork-ssh-hardening.conf"
#: Where :meth:`OpenSshServerMixin.exempt_from_ssh_penalties` names the managing
#: client; ``00-`` like the hardening drop-in, since sshd keeps the first value.
PENALTY_DROPIN_PATH = f"{DROPIN_DIR}/00-netork-penalty-exempt.conf"
#: What marks a line this module disabled in sshd_config.
DISABLED_PREFIX = "# netork: "
@@ -65,6 +77,11 @@ _HEADER = (
"# taken out of what this server offers. Delete this file to undo it.\n"
)
_PENALTY_HEADER = (
"# Written by netOrk: the address netOrk manages this host from, exempt from\n"
"# sshd's per-source penalties (PerSourcePenalties). Delete this file to undo it.\n"
)
#: Host key type, as ``ssh-keygen -l`` prints it -> the algorithms that key serves.
#: Certificate algorithms are left out: they also need a HostCertificate.
_KEY_TYPE_ALGORITHMS: dict[str, tuple[str, ...]] = {
@@ -302,6 +319,56 @@ def render_main_config(text: str, keep: Mapping[str, Sequence[str]], kinds: Iter
return render_dropin(keep, wanted) + "\n".join(out) + ("\n" if body.endswith("\n") else "")
def parse_penalty_exemptions(text: str) -> list[str] | None:
"""The ``persourcepenaltyexemptlist`` from ``sshd -T`` output; None without penalties.
Per-source penalties came with OpenSSH 9.8. An older sshd prints neither
line and refuses ``PerSourcePenaltyExemptList`` outright -- it does not
start with it in its configuration -- so None means: write nothing.
"""
penalties = False
exempt: list[str] = []
for raw in text.splitlines():
parts = raw.strip().split(None, 1)
if not parts:
continue
word = parts[0].lower()
if word == "persourcepenalties":
penalties = True
elif word == "persourcepenaltyexemptlist" and len(parts) == 2:
value = parts[1].strip()
exempt = [] if value.lower() == "none" else [a for a in value.split(",") if a]
return exempt if penalties else None
def client_address(ssh_connection: str) -> str | None:
"""The client's address in ``$SSH_CONNECTION`` (``client port server port``), or None."""
parts = ssh_connection.split()
if len(parts) != 4:
return None
try:
return str(ipaddress.ip_address(parts[0]))
except ValueError:
return None
def is_exempt(address: str, exempt: Iterable[str]) -> bool:
"""Whether *address* is one of *exempt*'s addresses or inside one of its networks."""
ip = ipaddress.ip_address(address)
for entry in exempt:
try:
if ip in ipaddress.ip_network(entry, strict=False):
return True
except ValueError:
continue
return False
def render_penalty_dropin(exempt: Sequence[str]) -> str:
"""The drop-in stating the full exempt list."""
return _PENALTY_HEADER + f"PerSourcePenaltyExemptList {','.join(exempt)}\n"
@dataclass
class SshHardeningResult:
"""What :meth:`OpenSshServerMixin.harden_ssh_server` did.
@@ -319,6 +386,30 @@ class SshHardeningResult:
message: str = ""
@dataclass
class SshPenaltyExemption:
"""What :meth:`OpenSshServerMixin.exempt_from_ssh_penalties` did.
*address* is the one the host sees the managing client at. *applied* is
True only when sshd uses the exemption and a new session got in;
*rolled_back* says the host was changed and then put back.
"""
address: str | None = None
applied: bool = False
rolled_back: bool = False
path: str | None = None
message: str = ""
def _unchanged(
result: SshPenaltyExemption, message: str, say: Callable[[str], None]
) -> SshPenaltyExemption:
result.message = message
say(message)
return result
class OpenSshServerMixin:
"""Adds :meth:`harden_ssh_server` to a driver that can run commands as root on an OpenSSH host.
@@ -484,7 +575,25 @@ class OpenSshServerMixin:
if main is None:
raise RuntimeError(f"cannot read {MAIN_CONFIG}")
restore = self._write_change(plan, main, result, say)
return self._apply_or_restore(plan, kinds, result, restore, verify, say)
def ignored() -> str | None:
now = self.get_ssh_server_algorithms()
names = [SSH_ALGORITHM_CLASSES[k][1] for k in kinds if now[k] != plan.keep[k]]
if not names:
return None
return (
f"sshd does not use the new {', '.join(names)}: a setting read before"
f" {result.path} decides them"
)
return self._apply_or_restore(
result,
restore,
verify,
say,
ignored=ignored,
done="The server no longer offers the selected algorithms.",
)
def _write_change(
self,
@@ -520,16 +629,23 @@ class OpenSshServerMixin:
return restore_main
def _apply_or_restore(
def _apply_or_restore[R: (SshHardeningResult, SshPenaltyExemption)](
self,
plan: SshHardeningPlan,
kinds: list[str],
result: SshHardeningResult,
result: R,
restore: Callable[[], None],
verify: Callable[[], bool] | None,
say: Callable[[str], None],
) -> SshHardeningResult:
def back(message: str, reload: bool) -> SshHardeningResult:
*,
ignored: Callable[[], str | None],
done: str,
) -> R:
"""Check what was written, reload, verify; put the old state back on any failure.
*ignored* reads ``sshd -T`` after ``sshd -t`` and says why sshd does not
use the change, or None when it does; *done* is the message of success.
"""
def back(message: str, reload: bool) -> R:
say(message)
say("Putting the previous configuration back")
try:
@@ -549,14 +665,9 @@ class OpenSshServerMixin:
complaint = self._sshd_accepts()
if complaint:
return back(f"sshd rejected the new configuration: {complaint}", reload=False)
now = self.get_ssh_server_algorithms()
ignored = [SSH_ALGORITHM_CLASSES[k][1] for k in kinds if now[k] != plan.keep[k]]
if ignored:
return back(
f"sshd does not use the new {', '.join(ignored)}: a setting read before"
f" {result.path} decides them",
reload=False,
)
why = ignored()
if why:
return back(why, reload=False)
say("Reloading sshd")
self._reload_ssh_server()
if verify is not None:
@@ -566,6 +677,90 @@ class OpenSshServerMixin:
except Exception as exc: # noqa: BLE001 - whatever went wrong, the host goes back
return back(f"The change failed: {exc}", reload=True)
result.applied = True
result.message = "The server no longer offers the selected algorithms."
result.message = done
say(result.message)
return result
# ── the penalty exemption ───────────────────────────────────────────
def exempt_from_ssh_penalties(
self,
*,
verify: Callable[[], bool] | None = None,
log: Callable[[str], None] | None = None,
) -> SshPenaltyExemption:
"""Exempt the address this session comes from from sshd's per-source penalties.
OpenSSH 9.8+ penalises a source whose connections do not authenticate --
a scanner's probes -- and then drops every connection from it, the
managing client's included (NetOrk/netork#1800). The address is the
one the host sees (``$SSH_CONNECTION``), so NAT and relays do not
matter. The host's own exemptions stay: the new list is the one sshd
uses now plus this address.
Only into the drop-in directory: a sshd_config that does not include it
is left alone, and the result says so. An sshd before 9.8 is not
touched -- it would not start with the directive. Checked like
:meth:`harden_ssh_server`: ``sshd -t``, ``sshd -T`` shows the address,
reload, then *verify*; on any failure the previous state goes back.
:raises RuntimeError: if the session names no client address, or
``sshd -T`` or sshd_config cannot be read.
"""
say = log or (lambda _line: None)
result = SshPenaltyExemption()
session = self.run_command('printf %s "$SSH_CONNECTION"', privileged=False, timeout=30)
address = client_address(session.stdout)
if address is None:
raise RuntimeError("the session names no client address ($SSH_CONNECTION)")
result.address = address
say(f"netOrk connects from {address}")
say("Reading sshd's per-source penalties (sshd -T)")
exempt = parse_penalty_exemptions(self._sshd_effective_text())
if exempt is None:
return _unchanged(
result,
"Nothing to change: this sshd has no per-source penalties (before OpenSSH 9.8).",
say,
)
if is_exempt(address, exempt):
return _unchanged(result, f"Nothing to change: {address} is already exempt.", say)
main = self._ssh_read(MAIN_CONFIG)
if main is None:
raise RuntimeError(f"cannot read {MAIN_CONFIG}")
if not has_dropin_include(main):
return _unchanged(
result,
f"Not changed: {MAIN_CONFIG} does not include {DROPIN_DIR},"
" where the exemption would go.",
say,
)
previous = self._ssh_read(PENALTY_DROPIN_PATH)
self._ssh_run(f"mkdir -p -- {quote(DROPIN_DIR)}")
self._ssh_write(PENALTY_DROPIN_PATH, render_penalty_dropin([*exempt, address]))
result.path = PENALTY_DROPIN_PATH
say(f"Wrote {PENALTY_DROPIN_PATH}")
def restore() -> None:
if previous is None:
self._ssh_remove(PENALTY_DROPIN_PATH)
else:
self._ssh_write(PENALTY_DROPIN_PATH, previous)
def ignored() -> str | None:
if is_exempt(address, parse_penalty_exemptions(self._sshd_effective_text()) or []):
return None
return (
"sshd does not use the new PerSourcePenaltyExemptList: a setting read before"
f" {PENALTY_DROPIN_PATH} decides it"
)
return self._apply_or_restore(
result,
restore,
verify,
say,
ignored=ignored,
done=f"{address} is exempt from sshd's per-source penalties.",
)
+250
View File
@@ -0,0 +1,250 @@
"""Exempting the managing client from sshd's per-source penalties (NetOrk/netork#1800).
OpenSSH 9.8 penalises a source whose connections do not authenticate and then
drops every connection from it. A security scanner's probes earn the managing
client exactly that, and its next session -- a poll, an Ansible run -- is
turned away. ``exempt_from_ssh_penalties`` puts the address the host sees the
client at into ``PerSourcePenaltyExemptList``, where that directive exists.
The real outputs this is held to were taken from Debian 13 (OpenSSH 10.0p2) and
Debian 12 (OpenSSH 9.2p1, which knows no penalties and rejects the directive).
"""
from __future__ import annotations
import re
import pytest
from napalm_device_types.channel import CommandResult
from napalm_device_types.ssh_server import (
DROPIN_DIR,
MAIN_CONFIG,
PENALTY_DROPIN_PATH,
OpenSshServerMixin,
client_address,
is_exempt,
parse_penalty_exemptions,
)
#: ``sshd -T | grep -i penalt`` on Debian 13, OpenSSH 10.0p2, as installed.
DEBIAN_13 = (
"persourcepenaltyexemptlist none\n"
"persourcepenalties crash:90 authfail:5 noauth:1 grace-exceeded:10 refuseconnection:10"
" max:600 min:15 max-sources4:65536 max-sources6:65536 overflow:permissive"
" overflow6:permissive\n"
)
# ── reading ──────────────────────────────────────────────────────────────
def test_a_new_sshd_has_penalties_and_no_exemption():
assert parse_penalty_exemptions(DEBIAN_13) == []
def test_the_exemptions_sshd_uses_are_read():
text = DEBIAN_13.replace("none", "10.40.100.10,192.0.2.0/24")
assert parse_penalty_exemptions(text) == ["10.40.100.10", "192.0.2.0/24"]
def test_an_sshd_before_9_8_has_no_penalties():
"""It prints neither line -- and refuses the directive, so nothing may be written."""
assert parse_penalty_exemptions("port 22\nmacs hmac-sha2-256\n") is None
@pytest.mark.parametrize(
("value", "address"),
[
("10.40.100.10 41866 10.40.100.118 22", "10.40.100.10"),
("fd00::10 41866 fd00::118 22", "fd00::10"),
("", None),
("not-an-address 1 2 3", None),
("10.40.100.10 41866", None),
],
)
def test_the_client_address_comes_from_ssh_connection(value, address):
assert client_address(value) == address
def test_an_address_inside_an_exempt_network_is_exempt():
assert is_exempt("10.40.100.10", ["192.0.2.0/24", "10.40.100.0/24"])
assert not is_exempt("10.40.100.10", ["10.40.100.11", "bogus"])
# ── the mixin, against a fake host ───────────────────────────────────────
class PenaltyHost(OpenSshServerMixin):
"""An sshd that reads the main config and the drop-in directory, first value wins."""
def __init__(
self,
*,
main: str = f"Include {DROPIN_DIR}/*.conf\nPort 22\n",
penalties: bool = True,
client: str = "10.40.100.10 41866 10.40.100.118 22",
) -> None:
self.files: dict[str, str] = {MAIN_CONFIG: main}
self.penalties = penalties
self.client = client
self.syntax_ok = True
self.reloads = 0
self.ran: list[str] = []
def _config_lines(self) -> list[str]:
lines: list[str] = []
for line in self.files[MAIN_CONFIG].splitlines():
if re.match(r"\s*include\s", line, re.I):
for path in sorted(p for p in self.files if p.startswith(DROPIN_DIR + "/")):
lines += self.files[path].splitlines()
elif re.match(r"\s*match\s", line, re.I):
break
else:
lines.append(line)
return lines
def exempt(self) -> str:
for line in self._config_lines():
parts = line.split()
if len(parts) == 2 and parts[0].lower() == "persourcepenaltyexemptlist":
return parts[1]
return "none"
def run_command(self, command, *, privileged=False, timeout=60, stdin=None):
self.ran.append(command)
if "SSH_CONNECTION" in command:
assert not privileged, "it is the login session's, not sudo's"
return CommandResult(self.client, "", 0)
if "mktemp" in command:
path = f"/tmp/netork-ssh.{len(self.files)}"
self.files[path] = (stdin or b"").decode()
return CommandResult(path, "", 0)
assert privileged, command
m = re.search(r"install -m \"\$m\" -- '?([^' ]+)'? '?([^' ]+)'?", command)
if m:
target = re.search(r"mv -f -- '?[^' ]+'? '?([^' ;]+)'?", command).group(1)
self.files[target] = self.files.pop(m.group(1))
return CommandResult("", "", 0)
if "sshd -T" in command:
if not self.penalties:
return CommandResult("port 22\n", "", 0)
return CommandResult(DEBIAN_13.replace("none", self.exempt()), "", 0)
if "sshd -t" in command:
return CommandResult(
"", "" if self.syntax_ok else "bad line 1", 0 if self.syntax_ok else 255
)
m = re.match(r"cat -- '?([^' ]+)'?$", command)
if m:
path = m.group(1)
if path in self.files:
return CommandResult(self.files[path], "", 0)
return CommandResult("", "No such file", 1)
m = re.match(r"rm -f -- '?([^' ]+)'?$", command)
if m:
self.files.pop(m.group(1), None)
return CommandResult("", "", 0)
if "reload" in command or "HUP" in command:
self.reloads += 1
return CommandResult("", "", 0)
if command.startswith("mkdir"):
return CommandResult("", "", 0)
raise AssertionError(f"unexpected command: {command}")
def test_the_client_address_is_exempted_in_a_dropin():
host = PenaltyHost()
lines: list[str] = []
result = host.exempt_from_ssh_penalties(log=lines.append)
assert result.applied and not result.rolled_back
assert result.address == "10.40.100.10"
assert result.path == PENALTY_DROPIN_PATH
assert host.exempt() == "10.40.100.10"
assert host.reloads == 1
assert lines
def test_the_hosts_own_exemptions_stay():
host = PenaltyHost(
main=f"Include {DROPIN_DIR}/*.conf\nPerSourcePenaltyExemptList 192.0.2.0/24\n"
)
result = host.exempt_from_ssh_penalties()
assert result.applied
assert host.exempt() == "192.0.2.0/24,10.40.100.10"
def test_nothing_is_written_to_an_sshd_without_penalties():
"""OpenSSH before 9.8 does not start with the directive in its config."""
host = PenaltyHost(penalties=False)
result = host.exempt_from_ssh_penalties()
assert not result.applied and not result.rolled_back
assert PENALTY_DROPIN_PATH not in host.files
assert host.reloads == 0
assert "9.8" in result.message
def test_nothing_changes_when_the_address_is_already_exempt():
host = PenaltyHost(
main=f"Include {DROPIN_DIR}/*.conf\nPerSourcePenaltyExemptList 10.40.100.0/24\n"
)
result = host.exempt_from_ssh_penalties()
assert not result.applied
assert PENALTY_DROPIN_PATH not in host.files
assert "already" in result.message
def test_an_sshd_config_without_the_include_is_left_alone():
host = PenaltyHost(main="Port 22\n")
result = host.exempt_from_ssh_penalties()
assert not result.applied
assert host.files[MAIN_CONFIG] == "Port 22\n"
assert DROPIN_DIR in result.message
def test_a_rejected_config_is_taken_back():
host = PenaltyHost()
host.syntax_ok = False
result = host.exempt_from_ssh_penalties()
assert result.rolled_back and not result.applied
assert PENALTY_DROPIN_PATH not in host.files
def test_an_exemption_sshd_does_not_use_is_taken_back():
"""A drop-in read before ours sets the directive; ours is valid and ignored."""
host = PenaltyHost()
host.files[f"{DROPIN_DIR}/00-aaa.conf"] = "PerSourcePenaltyExemptList 192.0.2.1\n"
result = host.exempt_from_ssh_penalties()
assert result.rolled_back
assert PENALTY_DROPIN_PATH not in host.files
def test_it_is_taken_back_when_a_new_session_cannot_get_in():
host = PenaltyHost()
result = host.exempt_from_ssh_penalties(verify=lambda: False)
assert result.rolled_back
assert PENALTY_DROPIN_PATH not in host.files
assert host.reloads == 2
def test_a_session_without_a_client_address_raises():
host = PenaltyHost(client="")
with pytest.raises(RuntimeError):
host.exempt_from_ssh_penalties()
+168
View File
@@ -0,0 +1,168 @@
"""A connection sshd turns away before the SSH banner is tried again (NetOrk/netork#1800).
OpenSSH 9.8+ drops every connection from a source it has just penalised
(``PerSourcePenalties``): it accepts the TCP connection and closes it at once,
and paramiko reports "Error reading SSH protocol banner". The penalty lasts
seconds to minutes, so a connection that waits a little gets in.
"""
from __future__ import annotations
import socket
import threading
import paramiko
import pytest
from napalm.base.exceptions import ConnectionException
from napalm_device_types import ssh_host_keys
from napalm_device_types.ssh_host_keys import (
REFUSED_RETRY_WAITS,
HostKeyCheck,
refused_before_banner,
retry_refused,
)
def _banner_error() -> paramiko.SSHException:
try:
try:
raise EOFError()
except EOFError as eof:
raise paramiko.SSHException("Error reading SSH protocol banner") from eof
except paramiko.SSHException as exc:
return exc
class TestWhatCountsAsRefused:
def test_paramikos_banner_error(self):
assert refused_before_banner(_banner_error())
def test_wrapped_by_a_driver(self):
try:
try:
raise _banner_error()
except paramiko.SSHException as exc:
raise ConnectionException(f"cannot connect: {exc}") from exc
except ConnectionException as wrapped:
assert refused_before_banner(wrapped)
@pytest.mark.parametrize(
"exc",
[
paramiko.AuthenticationException("Authentication failed."),
TimeoutError("timed out"),
ConnectionRefusedError(111, "Connection refused"),
ValueError("anything else"),
],
)
def test_not_a_failed_login_a_silent_host_or_a_closed_port(self, exc):
"""Those do not end by waiting: retrying them only delays the error."""
assert not refused_before_banner(exc)
class TestRetry:
def test_it_waits_and_tries_again(self):
slept: list[float] = []
attempts = iter([_banner_error(), _banner_error(), "connected"])
def attempt():
value = next(attempts)
if isinstance(value, BaseException):
raise value
return value
assert retry_refused(attempt, sleep=slept.append) == "connected"
assert slept == list(REFUSED_RETRY_WAITS[:2])
def test_it_gives_up_with_the_last_error(self):
slept: list[float] = []
def attempt():
raise _banner_error()
with pytest.raises(paramiko.SSHException):
retry_refused(attempt, sleep=slept.append)
assert slept == list(REFUSED_RETRY_WAITS)
def test_other_errors_are_not_retried(self):
slept: list[float] = []
def attempt():
raise paramiko.AuthenticationException("Authentication failed.")
with pytest.raises(paramiko.AuthenticationException):
retry_refused(attempt, sleep=slept.append)
assert slept == []
def test_the_waits_outlast_the_penalty_seen(self):
"""16 s on a new Ubuntu 26.04 VM on .50."""
assert sum(REFUSED_RETRY_WAITS) > 16
class _PenalisingServer:
"""A TCP server that closes the first *drops* connections at once, as a penalised
source's are, and then speaks SSH with any password."""
def __init__(self, drops: int) -> None:
self.drops = drops
self.listener = socket.create_server(("127.0.0.1", 0))
self.port = self.listener.getsockname()[1]
self.key = paramiko.ECDSAKey.generate()
self._thread = threading.Thread(target=self._serve, daemon=True)
self._thread.start()
def _serve(self) -> None:
while True:
try:
conn, _ = self.listener.accept()
except OSError:
return
if self.drops:
self.drops -= 1
conn.close()
continue
transport = paramiko.Transport(conn)
transport.add_server_key(self.key)
class _Any(paramiko.ServerInterface):
def get_allowed_auths(self, username):
return "password"
def check_auth_password(self, username, password):
return paramiko.AUTH_SUCCESSFUL
try:
transport.start_server(server=_Any())
except Exception:
pass
self.transport = transport
return
def close(self) -> None:
self.listener.close()
transport = getattr(self, "transport", None)
if transport:
transport.close()
def test_host_key_check_connects_once_the_penalty_is_over(monkeypatch):
server = _PenalisingServer(drops=2)
slept: list[float] = []
monkeypatch.setattr(ssh_host_keys.time, "sleep", slept.append)
client = paramiko.SSHClient()
try:
HostKeyCheck({}, "127.0.0.1", server.port).connect(
client,
username="admin",
password="s3cret",
look_for_keys=False,
allow_agent=False,
timeout=5,
banner_timeout=5,
)
assert client.get_transport().is_authenticated()
assert slept == list(REFUSED_RETRY_WAITS[:2])
finally:
client.close()
server.close()