Metadata-Version: 2.4
Name: aiossh
Version: 2.1.0
Summary: Production-grade async SSH client library with military-grade security features
Author-email: PyHPDev <dev@pyhp.dev>
Maintainer-email: AIOSSH Maintainers <maintainers@aiossh.dev>
License: MIT
Project-URL: Homepage, https://github.com/aiossh/aiossh
Project-URL: Documentation, https://github.com/aiossh/aiossh#readme
Project-URL: Repository, https://github.com/aiossh/aiossh
Project-URL: Issues, https://github.com/aiossh/aiossh/issues
Project-URL: Changelog, https://github.com/aiossh/aiossh/releases
Keywords: ssh,async,asyncio,security,cryptography,sftp,pool,docker,kubernetes,telnet
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncssh<3.0.0,>=2.14.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: orjson>=3.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# AIOSSH

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

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.1.0-orange.svg)](https://github.com/aiossh/aiossh)

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

```bash
pip install aiossh
```

For development:

```bash
pip install aiossh[dev]
```

## 🚀 Quickstart

```python
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):

```bash
pytest
ruff check .
mypy src/aiossh
```

## 📄 License

MIT License — see [LICENSE](LICENSE) file.

## 🙏 Acknowledgments

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

---

**AIOSSH v2.1.0** — Secure. Fast. Professional.
