aiossh 2.2.0

Production-grade async SSH client library with military-grade security features

AIOSSH

Production-grade async SSH client library with military-grade security.

AIOSSH is a high-performance, secure asynchronous SSH client for Python 3.12+. Built on top of asyncssh with additional layers of security, pooling, encryption, and advanced features for infrastructure automation, DevOps, and secure remote management at scale.

✨ Features

Core

• Async-first architecture with full asyncio and TaskGroup support (Python 3.11+)
• High-performance connection pooling with automatic cleanup, health checks, and strict limits
• Encrypted session storage using AES-256-GCM + ChaCha20-Poly1305 with PBKDF2-HMAC-SHA512 (600k iterations)
• Advanced rate limiting with sliding window + exponential backoff penalty system
• 40+ specific exception types for precise error handling and recovery
• Command injection prevention, SSRF protection, path traversal prevention
• Audit logging with HMAC-SHA512 tamper-proof signatures

Security (Military-Grade)

• Constant-time cryptographic comparisons (timing attack resistant)
• Secure memory wiping for sensitive key material
• Full support for modern SSH algorithms (curve25519, chacha20-poly1305, etc.)
• Proxy support: SOCKS5, Jump hosts
• Input validation and sanitization on all user-controlled data

Advanced Capabilities

• Plugin system for middleware, hooks, and custom behaviors
• Command queue with priority scheduling and batch execution
• Webhook notifications (Discord, Telegram, custom)
• Telnet support (legacy systems)
• Kubernetes & Docker exec sessions
• High-speed parallel SCP/SFTP transfers with progress tracking and disk space checks
• Session recording & replay for auditing and debugging
• Comprehensive logging handlers: File, Elasticsearch, Loki, Datadog, Syslog

Developer Experience

• Full type hints (py.typed) + mypy strict mode compatible
• Context manager support (async with)
• Decorators for retry and timing
• Clean, professional API

📦 Installation

pip install aiossh

For development:

pip install aiossh[dev]

🚀 Quickstart

import asyncio
from aiossh import AIOSSH

async def main():
    async with AIOSSH(master_password="your-very-strong-master-password-here") as client:
        # Connect with automatic pooling and security checks
        session = await client.connect(
            host="server.example.com",
            username="admin",
            password="secret",  # or use key_filename
            # port=22, known_hosts=..., etc.
        )

        # Execute command safely
        result = await client.execute_command(session, "uptime")
        print(result["stdout"])

        # File operations with security
        await client.upload_file(session, local_path="app.tar.gz", remote_path="/tmp/app.tar.gz")

        # Batch commands with controlled concurrency
        results = await client.batch_execute(
            session,
            ["df -h", "free -m", "cat /etc/os-release"],
            max_concurrency=5
        )

        await client.disconnect(session)

if __name__ == "__main__":
    asyncio.run(main())

🔐 Security Considerations

• Never hardcode passwords in code. Use environment variables or secret managers.
• Master password for session encryption must be at least 12 characters.
• All connections go through strict input validation and rate limiting.
• Private keys and credentials are wiped from memory after use.
• Audit logs are signed to detect tampering.
• By default, blocks connections to private/internal IPs (configurable).

For production, always:

• Use SSH keys instead of passwords when possible.
• Enable known_hosts verification.
• Run behind proper firewall rules.
• Monitor audit logs.

📚 API Overview

• AIOSSH — Main client (recommended entrypoint)
• ConnectionPool + PoolConfig — Low-level pooling
• FastSSHSession + SSHConfig — Direct session management
• SecurityConfig, RateLimiter, AuditLogger, SecureChannel
• PluginManager, BasePlugin — Extensibility
• CommandQueue, WebhookManager, ParallelSCP, etc.

See full documentation and examples in the source or GitHub wiki.

🛠️ Development & Contributing

We welcome contributions! Please open issues or PRs on GitHub.

To run tests (after installing dev deps):

pytest
ruff check .
mypy src/aiossh

📄 License

MIT License — see LICENSE file.

🙏 Acknowledgments

Built on the excellent asyncssh library. Security primitives powered by cryptography.

---

AIOSSH v2.1.0 — Secure. Fast. Professional.