spindlex 1.0.1

Quick Start • Documentation • Security • Contributing

⚡ Overview

SpindleX is a modern SSH protocol implementation for Python 3.9+. It is designed for high-performance automation and secure file transfers, providing a clean alternative to legacy SSH libraries.

[!NOTE] 1.0.0 - First stable release. SpindleX has graduated from beta: the public API surface is frozen under semantic versioning, with chacha20-poly1305@openssh.com as the preferred cipher, adaptive SFTP chunks via limits@openssh.com, and a hardened sync + async transport. Upgrading from 0.x? Read the migration guide. See also SECURITY.md, production usage expectations, and the compatibility policy.

🔥 Key Features

• 🚀 High Performance: Adaptive SFTP write chunks up to 255 KB via limits@openssh.com negotiation, pipelined transfers, and zero-copy internal buffering.
• 🔒 ChaCha20-Poly1305: Preferred AEAD cipher - no separate MAC pass, full Terrapin-defense strict-KEX, on par with leading SSH libraries.
• 🔄 Native Async: First-class asyncio support via AsyncSSHClient and AsyncSFTPClient.
• 🛡️ Secure by Default: Modern primitives only - Ed25519, ECDSA, ChaCha20-Poly1305, AES-CTR. Legacy/weak ciphers are not negotiated.
• 🔗 Advanced Tunneling: ProxyJump (bastion hosts) via direct-tcpip channels and TCP port forwarding.
• 📂 Recursive SFTP: Native support for recursive directory uploads and downloads.
• 🏷️ 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())

📊 Performance Benchmarks

SpindleX is optimized for high-throughput environments, with SFTP upload throughput in line with leading SSH libraries and ChaCha20-Poly1305 as the preferred cipher. See the comparison page for the full benchmark methodology.

[!TIP] Run the benchmark suite on your own hardware:

python scripts/benchmark_ciphers.py     # cipher comparison
python scripts/benchmark_production.py  # full protocol correctness + perf

🛡️ 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, ChaCha20-Poly1305, and AES-CTR only. SHA-1 and CBC mode are excluded.
• 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.