spindlex 1.0.4

Quick Start • Documentation • Security • Contributing

⚡ Overview

SpindleX is a modern SSH and SFTP implementation for Python 3.9 - 3.14 - client and server, sync and async. It is designed for high-performance automation and secure file transfers, providing a clean alternative to legacy SSH libraries.

🔥 Key Features

• 🚀 High Performance: Pipelined SFTP transfers with read/write sizes negotiated via limits@openssh.com (up to 255 KB), and the fastest handshake and command execution in our benchmarks.
• 🔒 Modern Cryptography: ChaCha20-Poly1305 (preferred) and AES-CTR, Curve25519/ECDH/DH-group14 key exchange, Ed25519, ECDSA and RSA (SHA-2) keys, Terrapin-defense strict KEX.
• 🔄 Native Async: First-class asyncio support via AsyncSSHClient and AsyncSFTPClient.
• 🖥️ SSH & SFTP Server: Build servers with SSHServer, SSHServerManager and SFTPServer - they work with the OpenSSH ssh and sftp clients.
• 🔑 Authentication: Password, public key, keyboard-interactive, GSSAPI/Kerberos and multi-factor (partial success).
• 🔗 Tunneling: Local and remote port forwarding, and ProxyJump (bastion hosts) via direct-tcpip channels.
• 📂 Recursive SFTP: get_recursive() / put_recursive() for whole directory trees.
• 🏷️ Fully Typed: Comprehensive type hints for IDE integration and static analysis.

💎 Why SpindleX?

• 💼 Business Friendly: MIT Licensed. Permissive use for commercial and proprietary projects.
• 📖 Maintainable Code: Modular architecture designed for clarity and easier security auditing.
• 🛠️ Modern API: Clean, intuitive interface with consistent error handling and minimal dependencies.
• 🧊 Focused Scope: No support for insecure legacy protocols, resulting in a leaner and more secure codebase.

🛠️ Tech Stack

🚀 Quick Start

Installation

# Using pip
pip install spindlex

# Using uv
uv pip install spindlex

💻 Usage Preview

from spindlex import SSHClient

with SSHClient() as client:
    client.get_host_keys().load()
    client.connect('example.com', username='admin')

    stdin, stdout, stderr = client.exec_command('uptime')
    print(f"Server Status: {stdout.read().decode().strip()}")

import asyncio
from spindlex import AsyncSSHClient

async def main():
    async with AsyncSSHClient() as client:
        client.get_host_keys().load()
        await client.connect('example.com', username='admin')
        stdin, stdout, stderr = await client.exec_command('df -h')
        print(await stdout.read())

asyncio.run(main())

from spindlex import SSHClient

with SSHClient() as client:
    client.get_host_keys().load()
    client.connect('example.com', username='admin')

    with client.open_sftp() as sftp:
        sftp.put('report.csv', '/srv/data/report.csv')
        sftp.get_recursive('/var/log/app', './app-logs')
        print(sftp.listdir('/srv/data'))

More examples - servers, port forwarding, ProxyJump, multi-factor login - are in the documentation and the cookbook.

📊 Performance Benchmarks

Median of 5 runs against a live OpenSSH 9.2 server on a local network (SpindleX 1.0.4, AsyncSSH 2.24, Paramiko 5.0, Python 3.12). Lower is better.

Network latency dominates in practice, so measure in your own environment. See the comparison page for methodology and feature differences.

🛡️ Security

• Verification Enforced: Host key verification is mandatory by default.
• Log Sanitization: Credentials and sensitive data are automatically filtered from logs.
• AEAD Preferred: chacha20-poly1305@openssh.com is the default cipher - authentication is integral, no separate MAC.
• Terrapin Defense: Strict-KEX (kex-strict-c-v00@openssh.com) enabled, sequence numbers reset after NEWKEYS.
• Modern Defaults: Ed25519, ECDSA, RSA with SHA-2 signatures, ChaCha20-Poly1305 and AES-CTR. CBC mode and SHA-1 (key exchange, MACs, ssh-rsa signatures) are off by default.
• known_hosts Aware: Hashed entries, non-standard ports and @revoked markers are honoured; private keys are written owner-only (0600).
• Hardened Server: Authentication only after key exchange, a login grace deadline, failed-attempt limits, and an SFTP server confined to its root.
• Full Policy: See SECURITY.md for vulnerability reporting and Security Guide for operational security guidance.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the GitHub entry point and docs/contributing.md for the maintained guide.

Distributed under the MIT License. See LICENSE for more information.