Metadata-Version: 2.4
Name: aiossh
Version: 1.0.0
Summary: Async SSH client library for Python with connection pooling, tunneling, and security features
Author-email: PyHPDev <dev@pyhp.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pyhpdev/aiossh
Project-URL: Documentation, https://github.com/pyhpdev/aiossh#readme
Project-URL: Repository, https://github.com/pyhpdev/aiossh
Project-URL: Issues, https://github.com/pyhpdev/aiossh/issues
Keywords: ssh,async,asyncio,security,cryptography,sftp,pool,tunneling,proxy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
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

Async SSH client library for Python.

AIOSSH provides a high-level asynchronous interface for managing SSH connections,
executing commands, transferring files, and creating secure tunnels. It is built
on top of the asyncssh library and adds connection pooling, encrypted session
storage, strict input validation, rate limiting, audit logging, and support for
advanced features such as SOCKS5 proxies, port forwarding, plugins, and more.

This library is intended for developers and system administrators who need
reliable, secure, and efficient remote management capabilities in Python
applications and automation scripts.

## Features

- Asynchronous SSH connections and command execution using asyncssh
- Connection pooling with configurable limits, idle connection cleanup, and
  automatic health management
- Encrypted storage of session credentials using AES-256-GCM with HMAC-SHA512
  integrity checks and PBKDF2 key derivation (600,000 iterations)
- Rate limiting for connections and commands using sliding window algorithm
  with exponential backoff for repeat violations
- Comprehensive input validation (hosts, ports, usernames, commands, paths)
  with protection against SSRF, command injection, and path traversal
- Support for tunneling: SOCKS5 proxy, local port forwarding (-L), and remote
  port forwarding (-R)
- Plugin system for intercepting and modifying connection, command, and file
  transfer events
- Priority-based command queue with support for batch execution
- Webhook notifications for events (Discord, Telegram, and custom HTTP endpoints)
- Telnet session support for legacy systems
- Execution of commands inside Docker containers and Kubernetes pods via SSH
  or API
- High-speed parallel chunked file transfers (SCP/SFTP) with progress reporting
  and optional speed throttling
- Session recording and replay for auditing and debugging
- Structured logging to local files and external systems (Elasticsearch, Loki,
  Datadog, Syslog)
- Full static type hints and compatibility with strict type checkers
- Context manager support for automatic resource cleanup
- More than 40 specific exception classes for precise error handling
- Retry and timing decorators for resilience and observability

## Requirements

- Python 3.12 or newer
- asyncssh >= 2.14.0 and < 3.0.0
- cryptography >= 42.0.0
- aiofiles >= 23.0.0
- orjson >= 3.9.0 (orjson is recommended for performance; the library falls
  back to the standard library json module if orjson is not available)

Optional dependencies for additional features:
- aiohttp: required for Kubernetes exec support and webhook delivery

## Installation

Install from PyPI:

```bash
pip install aiossh
```

For development and testing:

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

To enable Kubernetes exec and webhook functionality:

```bash
pip install aiossh aiohttp
```

## Quick Start

The following example demonstrates basic usage with an async context manager.

```python
import asyncio
from aiossh import AIOSSH

async def main() -> None:
    async with AIOSSH() as client:
        session = await client.connect(
            host="192.0.2.10",
            username="admin",
            password="your-password",  # Prefer SSH keys in production
            port=22,
        )

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

        await client.close_session(session)

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

For tunneling examples and advanced usage, refer to the documentation in the
source code or the project wiki.

## Core Components

### AIOSSH Client

The AIOSSH class is the primary entry point. It manages a connection pool,
rate limiters, audit logging, and optional encrypted session storage.

Key methods:
- connect(): Establish a new SSH session (uses pool by default)
- execute_command(): Execute a command on a session with rate limiting
- execute_on_all() / execute_on_multiple(): Run commands across sessions
- temporary_session(): Context manager for short-lived connections
- save_session_to_file() / load_session_from_file(): Encrypted credential storage
- close_session() / close_all(): Resource cleanup

### Sessions

FastSSHSession provides direct control over a single SSH connection. It supports
command execution, file upload/download, streaming output, and exposes the
underlying asyncssh connection for advanced tunneling use cases.

### Connection Pool

ConnectionPool implements strict limits on concurrent connections, reuses idle
connections, and performs periodic cleanup of stale entries. Configuration is
done via PoolConfig.

### Tunneling and Proxy

ProxyConfig and create_tunnel (async context manager) allow creation of:
- SOCKS5 proxy (dynamic port forwarding)
- Local port forwards (-L semantics)
- Remote port forwards (-R semantics)

These features enable secure access to internal services through an SSH
bastion host.

### Security

- All user-supplied input passes through whitelist-based validators
- Private and reserved IP ranges are blocked by default (SSRF protection)
- Dangerous command patterns are rejected unless explicitly allowed
- Session files are encrypted at rest with authenticated encryption
- Audit log entries are individually signed with HMAC-SHA512
- Sensitive material is wiped from memory after use where possible
- Rate limiters protect against brute-force and resource exhaustion

### Plugins

The plugin system allows registration of hooks that run before and after
connection establishment, command execution, and file transfers. Plugins can
cancel operations or modify context objects.

Built-in plugins include command logging and basic validation. Custom plugins
are created by subclassing BasePlugin.

### Error Handling

All errors raised by the library are subclasses of AIOSSHException. Each
exception carries a machine-readable code, optional structured details, and
a UTC timestamp. Specific subclasses exist for connection failures,
authentication problems, command errors, file transfer issues, security
violations, and resource exhaustion.

## Development

The source layout follows the src/ package layout recommended for modern
Python projects.

To run static analysis and tests (after installing dev dependencies):

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

The library targets Python 3.12+ and uses modern async features including
asyncio.TaskGroup.

No test suite is included in this release. Comprehensive tests are planned
for subsequent versions.

## License

This project is licensed under the MIT License. See the LICENSE file for
details.

## Acknowledgments

This library is built on the excellent asyncssh package. Cryptographic
primitives are provided by the cryptography library.

Contributions and feedback are welcome via the project issue tracker.
