feat(ne): add Linux SSH bastion hop type

Support hop_vendor=linux via Paramiko direct-tcpip tunnel; ZTE CLI hop unchanged. UI hop type selector and distinct list badges.

Co-authored-by: Cursor <cursoragent@cursor.com>

netx_api/ne_collect_runner.py

@@ -16,7 +16,7 @@ from .models import ManagedNE, NeCollectionJob, NeCollectionRun
 from .ne_collection_paths import clear_run_output_files, run_output_dir
 from .ne_crypto import CredentialCryptoError
 from .ne_service import get_device_credentials
-from .ne_session_factory import open_netmiko_connection
+from .ne_session_factory import close_netmiko_connection, open_netmiko_connection
 
 _log = logging.getLogger("netx.ne.collect")
 _executor: ThreadPoolExecutor | None = None
@@ -57,10 +57,7 @@ def _collect_on_device(creds: dict[str, Any], commands: list[str]) -> str:
             chunks.append("\n")
         return "".join(chunks)
     finally:
-        try:
-            conn.disconnect()
-        except Exception:
-            pass
+        close_netmiko_connection(conn)
 
 
 def _collect_with_timeout(creds: dict[str, Any], commands: list[str]) -> str:

netx_api/ne_connect.py

@@ -11,7 +11,7 @@ from .db import SessionLocal
 from .models import ManagedNE
 from .ne_crypto import CredentialCryptoError
 from .ne_service import get_device_credentials
-from .ne_session_factory import open_netmiko_connection
+from .ne_session_factory import close_netmiko_connection, open_netmiko_connection
 
 _log = logging.getLogger("netx.ne.connect")
 _executor: ThreadPoolExecutor | None = None
@@ -104,6 +104,7 @@ def _classify_connect_error(creds: dict[str, Any], exc: BaseException) -> str:
     raw = str(exc).lower()
     detail = str(exc).split("\n")[0][:480]
     if creds.get("hop_enabled"):
+        hop_v = str(creds.get("hop_vendor") or "zte").lower()
         if "hop_credentials_incomplete" in raw or "hop_command_template_invalid" in raw:
             return detail
         if "target_auth_timeout" in raw:
@@ -112,7 +113,9 @@ def _classify_connect_error(creds: dict[str, Any], exc: BaseException) -> str:
             if "hop_host" in raw or str(creds.get("hop_host") or "") in raw:
                 return "hop_auth_failed: " + detail
             return "target_auth_failed: " + detail
-        if "timed out" in raw or "timeout" in raw:
+        if "timed out" in raw or "timeout" in raw or "hop_connect_failed" in raw:
+            return "hop_connect_failed: " + detail
+        if hop_v == "linux":
             return "hop_connect_failed: " + detail
         return "hop_command_failed: " + detail
     return detail
@@ -142,11 +145,7 @@ def _probe_device(creds: dict[str, Any]) -> tuple[str, str, str | None]:
     except Exception as exc:
         return "fail", _classify_connect_error(creds, exc), None
     finally:
-        if conn is not None:
-            try:
-                conn.disconnect()
-            except Exception:
-                pass
+        close_netmiko_connection(conn)
 
 
 def _update_row(ne_id: str, status: str, message: str, discovered_name: str | None = None) -> None:

netx_api/ne_service.py

@@ -53,7 +53,7 @@ def _normalize_protocol(protocol: str) -> str:
 
 def _normalize_hop_vendor(vendor: str) -> str:
     v = str(vendor or "zte").strip().lower()
-    return v if v in ("zte",) else "zte"
+    return v if v in ("zte", "linux") else "zte"
 
 
 def _validate_hop_on_create(body: ManagedNeCreate) -> None:
@@ -287,8 +287,9 @@ def batch_apply_hop_proxy(db: Session, ids: list[str], hop: HopProxyConfig) -> d
     if not hop_pass:
         raise HTTPException(status_code=400, detail="hop_password_required")
 
+    hop_vendor = _normalize_hop_vendor(hop.hop_vendor)
     template = str(hop.hop_command_template or "").strip()
-    if not template:
+    if hop_vendor == "zte" and not template:
         template = default_zte_hop_template(hop.hop_protocol, hop.hop_vrf)
 
     ne_ids = [str(x).strip() for x in ids if str(x).strip()]
@@ -305,7 +306,7 @@ def batch_apply_hop_proxy(db: Session, ids: list[str], hop: HopProxyConfig) -> d
     now = _now()
     for row in rows:
         row.hop_enabled = True
-        row.hop_vendor = _normalize_hop_vendor(hop.hop_vendor)
+        row.hop_vendor = hop_vendor
         row.hop_host = hop_host
         row.hop_port = int(hop.hop_port or 22)
         row.hop_protocol = _normalize_protocol(hop.hop_protocol)

netx_api/ne_session_factory.py

@@ -1,4 +1,4 @@
-"""Netmiko session factory: direct connect or via ZTE jump host."""
+"""Netmiko session factory: direct connect, ZTE CLI hop, or Linux SSH bastion."""
 
 from __future__ import annotations
 
@@ -7,6 +7,7 @@ import re
 import time
 from typing import Any
 
+import paramiko
 from netmiko import ConnectHandler
 
 from .config import settings
@@ -182,8 +183,89 @@ def _connect_via_zte_hop(creds: dict[str, Any], *, session_timeout: int | None =
         raise
 
 
+def _hop_vendor(creds: dict[str, Any]) -> str:
+    return str(creds.get("hop_vendor") or "zte").strip().lower()
+
+
+def _connect_via_linux_hop(creds: dict[str, Any], *, session_timeout: int | None = None) -> ConnectHandler:
+    """SSH to Linux bastion, then direct-tcpip tunnel to target (classic ProxyJump-style)."""
+    hop_host = str(creds.get("hop_host") or "").strip()
+    hop_user = str(creds.get("hop_username") or "").strip()
+    hop_pass = str(creds.get("hop_password") or "")
+    if not hop_host or not hop_user or not hop_pass:
+        raise ValueError("hop_credentials_incomplete")
+
+    timeout = int(settings.ne_connect_timeout_sec or 30)
+    hop_port = int(creds.get("hop_port") or 22)
+    target_ip = str(creds["ip_address"])
+    target_port = int(creds.get("port") or 22)
+
+    jump = paramiko.SSHClient()
+    jump.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+    try:
+        jump.connect(
+            hop_host,
+            port=hop_port,
+            username=hop_user,
+            password=hop_pass,
+            timeout=timeout,
+            banner_timeout=timeout,
+            auth_timeout=timeout,
+            look_for_keys=False,
+            allow_agent=False,
+        )
+        transport = jump.get_transport()
+        if transport is None or not transport.is_active():
+            raise ConnectionError("hop_connect_failed: jump transport inactive")
+        channel = transport.open_channel(
+            "direct-tcpip",
+            (target_ip, target_port),
+            ("127.0.0.1", 0),
+            timeout=timeout,
+        )
+    except Exception:
+        try:
+            jump.close()
+        except Exception:
+            pass
+        raise
+
+    device_type = normalize_netmiko_device_type(creds["device_type"], creds["protocol"])
+    dev = _base_connect_kwargs(
+        device_type=device_type,
+        host=target_ip,
+        port=target_port,
+        username=str(creds["username"]),
+        password=str(creds["password"]),
+        enable_secret=str(creds.get("enable_secret") or ""),
+        session_timeout=session_timeout,
+    )
+    dev["sock"] = channel
+    conn = ConnectHandler(**dev)
+    conn._netx_jump_client = jump  # type: ignore[attr-defined]
+    return conn
+
+
+def close_netmiko_connection(conn: ConnectHandler | None) -> None:
+    """Disconnect target session and any Linux bastion SSH client."""
+    if conn is None:
+        return
+    jump = getattr(conn, "_netx_jump_client", None)
+    try:
+        conn.disconnect()
+    except Exception:
+        pass
+    if jump is not None:
+        try:
+            jump.close()
+        except Exception:
+            pass
+
+
 def open_netmiko_connection(creds: dict[str, Any], *, session_timeout: int | None = None) -> ConnectHandler:
     """Open a Netmiko connection to the target NE (direct or via configured hop)."""
     if creds.get("hop_enabled"):
+        if _hop_vendor(creds) == "linux":
+            return _connect_via_linux_hop(creds, session_timeout=session_timeout)
         return _connect_via_zte_hop(creds, session_timeout=session_timeout)
     return _connect_direct(creds, session_timeout=session_timeout)