ssh-handler 1.0.0__py3-none-any.whl

ssh_handler/__init__.py

@@ -0,0 +1,52 @@
+"""
+ssh_handler
+===========
+
+An extensive SSH / SFTP / SCP / FTP handler built on Paramiko, usable from a
+test-automation framework, a standalone CLI, or a PyQt5 tool.
+
+Quick start
+-----------
+    from ssh_handler import SSHHandler, SSHConfig
+
+    with SSHHandler(SSHConfig(host="10.0.0.5", domain="EU",
+                              username="nkennedy", password="…")) as ssh:
+        print(ssh.run("hostname").stdout)
+        ssh.push("local.txt", "/tmp/remote.txt")
+        ssh.pull("/var/log/syslog", "syslog.txt")
+
+The password is wrapped in a Secret and never appears in logs or reprs.
+``pyqt_worker`` and the ``scp`` extra are imported lazily, so missing optional
+dependencies (PyQt5 / scp) don't break the core package.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from .config import SSHConfig, FTPConfig
+from .core import SSHHandler, ShellSession
+from .ftp import FTPHandler
+from .pool import SSHPool
+from .credentials import Secret, CredentialStore, prompt_password, mask
+from .results import CommandResult, TransferResult, ShellResult, OperationResult
+from .exceptions import (
+    SSHError,
+    SSHConnectionError,
+    SSHAuthenticationError,
+    SSHTimeoutError,
+    SSHCommandError,
+    SSHTransferError,
+    SSHNotConnectedError,
+    FTPError,
+    CredentialError,
+)
+
+__all__ = [
+    "SSHHandler", "ShellSession", "SSHConfig", "FTPConfig", "FTPHandler",
+    "SSHPool", "Secret", "CredentialStore", "prompt_password", "mask",
+    "CommandResult", "TransferResult", "ShellResult", "OperationResult",
+    "SSHError", "SSHConnectionError", "SSHAuthenticationError",
+    "SSHTimeoutError", "SSHCommandError", "SSHTransferError",
+    "SSHNotConnectedError", "FTPError", "CredentialError", "__version__",
+]

ssh_handler/__main__.py

@@ -0,0 +1,5 @@
+"""Enables `python -m ssh_handler ...`."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ssh_handler/cli.py

@@ -0,0 +1,152 @@
+"""
+Standalone command-line entry point.
+
+    python -m ssh_handler run   --host H --user U [--domain EU] CMD...
+    python -m ssh_handler push  --host H --user U LOCAL REMOTE [--recursive]
+    python -m ssh_handler pull  --host H --user U REMOTE LOCAL [--recursive]
+    python -m ssh_handler info  --host H --user U
+
+Credentials (password never echoed, never stored in plaintext):
+    --password           prompt interactively (hidden)
+    --use-stored         read from the OS credential vault
+    --store-credential   save to the OS vault, then exit
+    --key FILE           use a private key instead of a password
+"""
+
+from __future__ import annotations
+
+import sys
+import json
+import argparse
+
+from .config import SSHConfig
+from .core import SSHHandler
+from .credentials import CredentialStore, prompt_password, Secret
+from .exceptions import SSHError
+from .results import CommandResult, TransferResult
+
+
+def _add_conn_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--host", required=True)
+    p.add_argument("--port", type=int, default=22)
+    p.add_argument("--user", required=True)
+    p.add_argument("--domain", default=None, help="e.g. EU for EU\\user logins")
+    p.add_argument("--key", default=None, help="private key file")
+    p.add_argument("--password", action="store_true",
+                   help="prompt for password (hidden input)")
+    p.add_argument("--use-stored", action="store_true",
+                   help="read password from the OS credential vault")
+    p.add_argument("--service", default="ssh_handler",
+                   help="credential-vault namespace")
+    p.add_argument("--timeout", type=float, default=None)
+    p.add_argument("--no-fast-auth", action="store_true")
+    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+
+
+def _resolve_password(args, login_user: str) -> Secret | None:
+    if args.use_stored:
+        store = CredentialStore(args.service)
+        sec = store.get(login_user)
+        if sec is None:
+            print(f"No stored credential for {login_user!r} in service "
+                  f"{args.service!r}.", file=sys.stderr)
+            sys.exit(2)
+        return sec
+    if args.password:
+        return prompt_password(f"Password for {login_user}: ")
+    return None
+
+
+def _build_config(args) -> SSHConfig:
+    login_user = f"{args.domain}\\{args.user}" if args.domain else args.user
+    return SSHConfig(
+        host=args.host, port=args.port, username=args.user, domain=args.domain,
+        password=_resolve_password(args, login_user),
+        key_filename=args.key, command_timeout=args.timeout,
+        fast_auth=not args.no_fast_auth,
+    )
+
+
+def _output(args, obj) -> None:
+    if args.json:
+        if isinstance(obj, (CommandResult, TransferResult)):
+            print(json.dumps(obj.as_dict(), default=str, indent=2))
+        else:
+            print(json.dumps(obj, default=str, indent=2))
+    else:
+        print(obj)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="ssh_handler",
+                                     description="Extensive SSH/SFTP/SCP handler CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    # store-credential (no connection)
+    sc = sub.add_parser("store-credential", help="save a password to the OS vault")
+    sc.add_argument("--user", required=True)
+    sc.add_argument("--domain", default=None)
+    sc.add_argument("--service", default="ssh_handler")
+
+    p_run = sub.add_parser("run", help="execute a remote command")
+    _add_conn_args(p_run)
+    p_run.add_argument("command", nargs=argparse.REMAINDER)
+
+    p_push = sub.add_parser("push", help="upload a file/dir (SFTP)")
+    _add_conn_args(p_push)
+    p_push.add_argument("local")
+    p_push.add_argument("remote")
+    p_push.add_argument("--recursive", action="store_true")
+
+    p_pull = sub.add_parser("pull", help="download a file/dir (SFTP)")
+    _add_conn_args(p_pull)
+    p_pull.add_argument("remote")
+    p_pull.add_argument("local")
+    p_pull.add_argument("--recursive", action="store_true")
+
+    p_info = sub.add_parser("info", help="connect and report remote OS")
+    _add_conn_args(p_info)
+
+    args = parser.parse_args(argv)
+
+    # store-credential is handled without a connection
+    if args.cmd == "store-credential":
+        login_user = f"{args.domain}\\{args.user}" if args.domain else args.user
+        store = CredentialStore(args.service)
+        store.set(login_user, prompt_password(f"Password to store for {login_user}: "))
+        print(f"Stored credential for {login_user!r} in service {args.service!r}.")
+        return 0
+
+    try:
+        with SSHHandler(_build_config(args)) as ssh:
+            if args.cmd == "run":
+                cmd = " ".join(args.command).strip()
+                if not cmd:
+                    print("No command given.", file=sys.stderr)
+                    return 2
+                res = ssh.run(cmd, timeout=args.timeout)
+                if not args.json:
+                    if res.stdout:
+                        sys.stdout.write(res.stdout)
+                    if res.stderr:
+                        sys.stderr.write(res.stderr)
+                    return res.exit_code
+                _output(args, res)
+                return res.exit_code
+            elif args.cmd == "push":
+                _output(args, ssh.push(args.local, args.remote,
+                                       recursive=args.recursive))
+            elif args.cmd == "pull":
+                _output(args, ssh.pull(args.remote, args.local,
+                                       recursive=args.recursive))
+            elif args.cmd == "info":
+                _output(args, {"host": args.host, "remote_os": ssh.detect_os(),
+                               "connected": ssh.is_connected})
+        return 0
+    except SSHError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ssh_handler/config.py

@@ -0,0 +1,114 @@
+"""Connection/behaviour configuration objects."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional, Sequence, Union
+
+from .credentials import Secret, coerce_secret
+
+
+@dataclass
+class SSHConfig:
+    """
+    Everything needed to open and drive an SSH connection.
+
+    Domain accounts (Windows / RDP hosts running OpenSSH Server)
+    -----------------------------------------------------------
+    Set ``domain`` and ``username`` separately and let the handler build the
+    ``DOMAIN\\user`` login string for you::
+
+        SSHConfig(host="10.0.0.5", domain="EU", username="nkennedy",
+                  password=<Secret or str>)
+
+    Setting them separately avoids the classic trap where a literal Python
+    string ``"EU\\nkennedy"`` turns ``\\n`` into a newline. The password is
+    stored as a :class:`Secret`, so it never appears in logs or reprs.
+    """
+
+    host: str
+    port: int = 22
+    username: Optional[str] = None
+    domain: Optional[str] = None          # e.g. "EU" -> login "EU\\username"
+
+    # --- authentication (any combination; tried in a smart order) ---
+    password: Optional[Union[str, Secret]] = None
+    key_filename: Optional[Union[str, Sequence[str]]] = None
+    key_passphrase: Optional[Union[str, Secret]] = None
+    allow_agent: bool = True
+    look_for_keys: bool = True
+    allow_empty_password: bool = True     # accounts with a blank password
+    passwordless: bool = False            # force key/agent only
+
+    # --- connection behaviour ---
+    connect_timeout: float = 15.0
+    auth_timeout: float = 20.0
+    banner_timeout: float = 20.0
+    command_timeout: Optional[float] = None
+    keepalive_interval: int = 30
+
+    # --- performance ---
+    compress: bool = False                # enable on slow/high-latency links
+    fast_auth: bool = True                # skip key probing when a password is
+                                          # supplied -> much faster, avoids
+                                          # "Too many authentication failures"
+
+    # --- resilience ---
+    max_retries: int = 3
+    retry_backoff: float = 2.0
+    auto_reconnect: bool = True
+
+    # --- host key policy ---
+    host_key_policy: str = "auto"         # "auto" | "reject" | "warn"
+    known_hosts: Optional[str] = None
+
+    # --- jump host / bastion (ProxyJump) ---
+    jump_host: Optional["SSHConfig"] = None
+
+    # --- remote OS hint: "auto" | "linux" | "windows" ---
+    remote_os: str = "auto"
+
+    def __post_init__(self):
+        # Normalize secrets so they are never plain strings internally.
+        self.password = coerce_secret(self.password)
+        self.key_passphrase = coerce_secret(self.key_passphrase)
+
+    @property
+    def auth_username(self) -> Optional[str]:
+        """Login string, combining domain if present (``DOMAIN\\user``)."""
+        if self.domain and self.username:
+            return f"{self.domain}\\{self.username}"
+        return self.username
+
+    def normalized_key_files(self) -> list[str]:
+        if not self.key_filename:
+            return []
+        keys = self.key_filename
+        if isinstance(keys, (list, tuple)):
+            return [os.path.expanduser(k) for k in keys]
+        return [os.path.expanduser(keys)]
+
+    def __repr__(self) -> str:  # never leak the password
+        return (
+            f"SSHConfig(host={self.host!r}, port={self.port}, "
+            f"user={self.auth_username!r}, password={self.password!r}, "
+            f"jump_host={'yes' if self.jump_host else 'no'})"
+        )
+
+
+@dataclass
+class FTPConfig:
+    """Configuration for the (non-SSH) FTP/FTPS handler."""
+
+    host: str
+    port: int = 21
+    username: str = "anonymous"
+    password: Optional[Union[str, Secret]] = ""
+    use_tls: bool = False                 # FTPS (explicit TLS) when True
+    passive: bool = True
+    timeout: float = 30.0
+    encoding: str = "utf-8"
+
+    def __post_init__(self):
+        self.password = coerce_secret(self.password)