https://github.com/di3z1e/spindlex

Modern async SSH & SFTP library for Python. Fast, typed, and secure by default.
https://github.com/di3z1e/spindlex

automation devops infrastructure-as-code pure-python sftp ssh

Last synced: about 2 months ago
JSON representation

Modern async SSH & SFTP library for Python. Fast, typed, and secure by default.

• Host: GitHub
• URL: https://github.com/di3z1e/spindlex
• Owner: Di3Z1E
• License: mit
• Created: 2026-04-11T09:53:52.000Z (2 months ago)
• Default Branch: main
• Last Pushed: 2026-04-25T16:32:26.000Z (about 2 months ago)
• Last Synced: 2026-04-25T18:16:16.549Z (about 2 months ago)
• Topics: automation, devops, infrastructure-as-code, pure-python, sftp, ssh
• Language: Python
• Homepage:
• Size: 3.54 MB
• Stars: 4
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: docs/contributing.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Citation: CITATION.cff
  • Security: docs/security.md

Awesome Lists containing this project

README

          









[![CI Status](https://img.shields.io/github/actions/workflow/status/Di3Z1E/spindlex/ci.yml?branch=main&style=for-the-badge&logo=github&labelColor=1a1a1a)](https://github.com/Di3Z1E/spindlex/actions)

[![Coverage](https://img.shields.io/codecov/c/github/Di3Z1E/spindlex?style=for-the-badge&logo=codecov&labelColor=1a1a1a)](https://codecov.io/gh/Di3Z1E/spindlex)

[![PyPI Version](https://img.shields.io/pypi/v/spindlex?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a1a)](https://pypi.org/project/spindlex/)

[![License](https://img.shields.io/pypi/l/spindlex?style=for-the-badge&color=bb86fc&labelColor=1a1a1a)](https://github.com/Di3Z1E/spindlex/blob/main/LICENSE)




Quick Start • Documentation • Security • Contributing



---

## ⚡ Overview

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

> [!WARNING]

> **Beta software.** The 0.6.x line is stabilising the core protocol, transport, and SFTP layers. Review [meta/SECURITY.md](meta/SECURITY.md) before deploying in production-facing workflows, pin exact versions, and audit your host key policy.

### 🔥 Key Features

- 🚀 **High Performance**: Optimized internal buffering (32KB chunks) for high-throughput SFTP and command execution.

- 🔄 **Native Async**: First-class `asyncio` support via `AsyncSSHClient` and `AsyncSFTPClient`.

- 🛡️ **Security**: Prioritizes modern primitives (Ed25519, AES-256-CTR) and disables legacy/weak ciphers.

- 🔗 **Advanced Tunneling**: Support for **ProxyJump** (bastion hosts) 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



**Core Logic** ![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)

![Cryptography](https://img.shields.io/badge/Cryptography-FFD43B?style=flat-square&logo=python&logoColor=3776AB)

**Protocol** ![SSH](https://img.shields.io/badge/SSH-000000?style=flat-square&logo=ssh&logoColor=white)

![SFTP](https://img.shields.io/badge/SFTP-444444?style=flat-square&logo=files&logoColor=white)

**Concurrency** ![Asyncio](https://img.shields.io/badge/Asyncio-3776AB?style=flat-square&logo=python&logoColor=white)



---

## 🚀 Quick Start

### Installation

```bash

# Using pip

pip install spindlex

# Using uv

uv pip install spindlex

```

### 💻 Usage Preview

Synchronous Example

```python

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()}")

```

Asynchronous Example

```python

import asyncio

from spindlex import AsyncSSHClient

async def main():

    async with AsyncSSHClient() as client:

        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, significantly reducing protocol overhead compared to standard implementations.

| Operation | SpindleX | Legacy Libraries | Improvement |

|:---|:---:|:---:|:---:|

| **Handshake** | 0.32s | 0.85s | **~2.6x** |

| **Bulk SFTP** | 45 MB/s | 18 MB/s | **~2.5x** |

| **Overhead** | Low | High | 🔥 |

> [!TIP]

> Run the benchmark suite on your own hardware:  

> `python scripts/benchmark_compare.py`

---

## 🛡️ Security

- **Verification Enforced**: Host key verification is mandatory by default.

- **Log Sanitization**: Credentials and sensitive data are automatically filtered from logs.

- **Modern Defaults**: Ed25519 and ECDSA preferred for key exchange.

- **Full Policy**: See [meta/SECURITY.md](meta/SECURITY.md) for vulnerability reporting and security standards.

---

## 🤝 Contributing

Contributions are welcome. See `meta/CONTRIBUTING.md` for guidelines.

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



---

*SpindleX Project © 2026*