netpulse-ssh 0.1.0__tar.gz

netpulse_ssh-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Virtual Environments
+.venv/
+venv/
+ENV/
+
+# Python Caches & Bytecode
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Rust / Maturin Build Artifacts
+rust/target/
+*.so
+*.dylib
+*.dll
+*.pyd
+
+# Local Configuration / Environment
+.env
+.env*.local
+
+# Scratch / Temporary Files
+scratch/
+netpulse.db

netpulse_ssh-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: netpulse-ssh
+Version: 0.1.0
+Summary: High-speed concurrent SSH command runner
+Requires-Python: >=3.10
+Requires-Dist: asyncssh>=2.14.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+<h1 align="center">NetPulse SSH</h1>
+
+<p align="center">
+  <em>High-performance, standalone Python library & CLI for concurrent SSH command execution across network devices.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/netpulse-ssh/"><img src="https://img.shields.io/pypi/v/netpulse-ssh?color=magenta&label=pypi%20package" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/netpulse-ssh/"><img src="https://img.shields.io/pypi/pyversions/netpulse-ssh" alt="Python Versions"></a>
+  <a href="https://github.com/bonheurNE07/netpulse/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://github.com/bonheurNE07/netpulse"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
+</p>
+
+---
+
+**`netpulse-ssh`** is an ultra-fast, resilient SSH execution engine extracted from the [NetPulse](https://github.com/bonheurNE07/netpulse) discovery suite. It allows network engineers and automation pipelines to execute commands across hundreds of network devices simultaneously, without blocking I/O or crashing due to a single offline host.
+
+## ✨ Features
+
+- **Massive Concurrency**: Scales horizontally using `asyncio` to execute commands across hundreds of targets simultaneously.
+- **Legacy Equipment Healing**: Automatically detects strict OpenSSH cipher drops and seamlessly falls back to legacy algorithms (e.g., `diffie-hellman-group1-sha1`, `3des-cbc`) which are frequently required for older Cisco or Juniper gear.
+- **Smart Privilege Escalation**: Natively supports Cisco `enable` mode privilege escalation without breaking automation.
+- **Pagination Suppression**: Automatically injects `terminal length 0` before command execution to bypass interactive `--More--` prompts.
+- **REST API Enabled**: Run the built-in FastAPI uvicorn wrapper to serve concurrent execution logic dynamically to web dashboards or automation scripts.
+
+## 🚀 Quickstart
+
+### Installation
+
+Install globally or locally via `pip`:
+
+```bash
+pip install netpulse-ssh
+```
+
+### CLI Usage
+
+Execute a command across multiple devices concurrently and get a beautiful, structured table summary:
+
+```bash
+netpulse-ssh execute 192.168.1.5 10.0.0.1 -c "show ip interface brief" -u admin -p password
+```
+
+### Python API Integration
+
+Use our cleanly typed Pydantic models and logic natively inside your own tools. The runner is completely agnostic and returns an audit object containing stdout/stderr per host:
+
+```python
+import asyncio
+from netpulse.ssh.models import SshHostConfig
+from netpulse.ssh.runner import SshRunnerService
+
+async def main():
+    hosts = [
+        SshHostConfig(ip="192.168.1.1", username="admin", password="password"),
+        SshHostConfig(ip="10.0.0.1", username="admin", password="password"),
+    ]
+    
+    runner = SshRunnerService()
+    audit = await runner.execute_concurrently(hosts, "show version")
+    
+    for result in audit.results:
+        print(f"Host {result.ip} status: {result.status}")
+        print(result.stdout)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 📖 Documentation
+
+Detailed documentation is available in the `docs/` directory:
+- 🗺️ [**Usage Guide**](docs/usage.md) - Deep dive into CLI and REST API examples.
+- 🏗️ [**Architecture**](docs/architecture.md) - Understand the asynchronous execution engine and legacy fallbacks.
+- 🧠 [**Design Decisions**](docs/design.md) - Read about the decoupled persistence approach.
+- 🧪 [**Contributing**](docs/contributing.md) - The development onboarding guide.
+
+## 🤝 Contributing
+
+We welcome contributions from the community! `netpulse-ssh` is open-source and maintained actively. 
+Please read our [**Contributing Guidelines**](docs/contributing.md) to understand how to clone the repository and submit your Pull Requests. 
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.

netpulse_ssh-0.1.0/README.md

@@ -0,0 +1,85 @@
+<h1 align="center">NetPulse SSH</h1>
+
+<p align="center">
+  <em>High-performance, standalone Python library & CLI for concurrent SSH command execution across network devices.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/netpulse-ssh/"><img src="https://img.shields.io/pypi/v/netpulse-ssh?color=magenta&label=pypi%20package" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/netpulse-ssh/"><img src="https://img.shields.io/pypi/pyversions/netpulse-ssh" alt="Python Versions"></a>
+  <a href="https://github.com/bonheurNE07/netpulse/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://github.com/bonheurNE07/netpulse"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
+</p>
+
+---
+
+**`netpulse-ssh`** is an ultra-fast, resilient SSH execution engine extracted from the [NetPulse](https://github.com/bonheurNE07/netpulse) discovery suite. It allows network engineers and automation pipelines to execute commands across hundreds of network devices simultaneously, without blocking I/O or crashing due to a single offline host.
+
+## ✨ Features
+
+- **Massive Concurrency**: Scales horizontally using `asyncio` to execute commands across hundreds of targets simultaneously.
+- **Legacy Equipment Healing**: Automatically detects strict OpenSSH cipher drops and seamlessly falls back to legacy algorithms (e.g., `diffie-hellman-group1-sha1`, `3des-cbc`) which are frequently required for older Cisco or Juniper gear.
+- **Smart Privilege Escalation**: Natively supports Cisco `enable` mode privilege escalation without breaking automation.
+- **Pagination Suppression**: Automatically injects `terminal length 0` before command execution to bypass interactive `--More--` prompts.
+- **REST API Enabled**: Run the built-in FastAPI uvicorn wrapper to serve concurrent execution logic dynamically to web dashboards or automation scripts.
+
+## 🚀 Quickstart
+
+### Installation
+
+Install globally or locally via `pip`:
+
+```bash
+pip install netpulse-ssh
+```
+
+### CLI Usage
+
+Execute a command across multiple devices concurrently and get a beautiful, structured table summary:
+
+```bash
+netpulse-ssh execute 192.168.1.5 10.0.0.1 -c "show ip interface brief" -u admin -p password
+```
+
+### Python API Integration
+
+Use our cleanly typed Pydantic models and logic natively inside your own tools. The runner is completely agnostic and returns an audit object containing stdout/stderr per host:
+
+```python
+import asyncio
+from netpulse.ssh.models import SshHostConfig
+from netpulse.ssh.runner import SshRunnerService
+
+async def main():
+    hosts = [
+        SshHostConfig(ip="192.168.1.1", username="admin", password="password"),
+        SshHostConfig(ip="10.0.0.1", username="admin", password="password"),
+    ]
+    
+    runner = SshRunnerService()
+    audit = await runner.execute_concurrently(hosts, "show version")
+    
+    for result in audit.results:
+        print(f"Host {result.ip} status: {result.status}")
+        print(result.stdout)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 📖 Documentation
+
+Detailed documentation is available in the `docs/` directory:
+- 🗺️ [**Usage Guide**](docs/usage.md) - Deep dive into CLI and REST API examples.
+- 🏗️ [**Architecture**](docs/architecture.md) - Understand the asynchronous execution engine and legacy fallbacks.
+- 🧠 [**Design Decisions**](docs/design.md) - Read about the decoupled persistence approach.
+- 🧪 [**Contributing**](docs/contributing.md) - The development onboarding guide.
+
+## 🤝 Contributing
+
+We welcome contributions from the community! `netpulse-ssh` is open-source and maintained actively. 
+Please read our [**Contributing Guidelines**](docs/contributing.md) to understand how to clone the repository and submit your Pull Requests. 
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.

netpulse_ssh-0.1.0/docs/architecture.md

@@ -0,0 +1,18 @@
+# Architecture
+
+The `netpulse-ssh` package is architected to perform massively concurrent, non-blocking SSH executions across networking infrastructure.
+
+## Component Flow
+
+1. **API / CLI Layer (`netpulse.ssh.api` / `netpulse.ssh.cli`)**
+   - Ingests a list of `SshHostConfig` requests containing targets, credentials, and connection timeouts.
+   - Dispatches them to the runner.
+
+2. **Runner Service (`netpulse.ssh.runner.SshRunnerService`)**
+   - Uses `asyncio.gather` to launch parallel, non-blocking asynchronous routines for every target device.
+   - Collates outputs, latencies, and negotiation details into a structured `SshExecutionAudit` domain model.
+
+3. **Smart SSH Client (`netpulse.ssh.runner.SmartSshClient`)**
+   - Leverages `asyncssh` to connect to devices.
+   - Automatically detects strict OpenSSH cipher drops and falls back dynamically to legacy algorithms (e.g., `diffie-hellman-group1-sha1`, `3des-cbc`) which are frequently required for older Cisco or Juniper gear.
+   - Automatically injects configuration prerequisites, specifically sending `terminal length 0` to disable pagination before executing the desired command.

netpulse_ssh-0.1.0/docs/contributing.md

@@ -0,0 +1,31 @@
+# Contributing to NetPulse SSH
+
+Thank you for your interest in contributing to the `netpulse-ssh` package! This document outlines the process for contributing to this specific package.
+
+## Development Environment Setup
+
+This project uses `uv` for lightning-fast package management and `hatchling` as the build backend.
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/netpulse.git
+cd netpulse
+
+# Sync the workspace and install all dependencies
+uv sync
+
+# Run the SSH specific tests
+uv run pytest packages/netpulse-ssh/tests/
+```
+
+## Project Structure
+- `src/netpulse/ssh/`: The actual library source code.
+- `tests/unit/`: Unit tests isolating the client and runner logic.
+- `tests/integration/`: Integration tests validating the API and CLI wrappers.
+
+## Pull Request Guidelines
+1. Fork the repository and create your feature branch from `main`.
+2. Ensure you have added appropriate unit and integration tests for your changes.
+3. Verify all tests pass cleanly using `uv run pytest`.
+4. Follow standard PEP-8 style guidelines.
+5. Create a descriptive PR outlining the problem solved and the approach.

netpulse_ssh-0.1.0/docs/design.md

@@ -0,0 +1,14 @@
+# Design Decisions
+
+## Decoupling
+
+Previously, the SSH execution engine within `netpulse-core` tightly coupled the execution runtime with a native SQLite `DatabaseService`. 
+
+In `netpulse-ssh`, this logic was purposefully inverted:
+1. **Runner Agnosticism**: The `SshRunnerService` does absolutely zero persistence. It only yields a fully populated `SshExecutionAudit` model in memory.
+2. **Caller Responsibility**: The invoker (e.g., the monolithic `netpulse-api`) is now responsible for catching the domain model and applying it to its local `DatabaseService`.
+
+This architectural pivot guarantees that `netpulse-ssh` can be pulled off the shelf and utilized natively inside other Python applications completely independent of the broader `netpulse` ecosystem.
+
+## Error Handling
+Exceptions experienced on individual devices (e.g. `ConnectionRefusedError`, timeouts, authentication failures) are isolated at the `SmartSshClient` scope. They mutate the individual `SshHostResult.status` to `FAILED` and populate `error_message`, ensuring that a single unresponsive device does not crash the broader concurrent runtime array.

netpulse_ssh-0.1.0/docs/usage.md

@@ -0,0 +1,66 @@
+# NetPulse SSH Usage
+
+The `netpulse-ssh` package can be utilized as a standalone Command Line Interface (CLI), an independent REST API, or seamlessly imported as a standard Python library into your custom scripts.
+
+## Standalone CLI
+
+To execute a command across multiple devices concurrently:
+```bash
+netpulse-ssh execute 192.168.1.5 10.0.0.1 -c "show ip interface brief" -u admin -p password
+```
+
+Options:
+- `-c, --command`: The SSH command to execute.
+- `-u, --user`: The SSH login username.
+- `-p, --pass`: The SSH password.
+- `-e, --enable`: A privilege execution mode password (e.g., Cisco `enable`).
+- `--port`: The SSH port (default `22`).
+
+## Standalone API
+
+You can boot up a standalone FastAPI server containing only the SSH router:
+
+```python
+import uvicorn
+from fastapi import FastAPI
+from netpulse.ssh.api import ssh_router
+
+app = FastAPI()
+app.include_router(ssh_router)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8001)
+```
+
+**Endpoint:** `POST /api/v1/ssh/execute`
+```json
+{
+  "hosts": [
+    {
+      "ip": "192.168.1.1",
+      "port": 22
+    }
+  ],
+  "command": "show version",
+  "username": "admin",
+  "password": "secret_password"
+}
+```
+
+## Python Library
+
+```python
+import asyncio
+from netpulse.ssh.models import SshHostConfig
+from netpulse.ssh.runner import SshRunnerService
+
+async def run():
+    hosts = [
+        SshHostConfig(ip="10.0.0.1", username="admin", password="password")
+    ]
+    runner = SshRunnerService()
+    audit = await runner.execute_concurrently(hosts, "show version")
+    print(audit.results[0].stdout)
+
+asyncio.run(run())
+```

netpulse_ssh-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "netpulse-ssh"
+version = "0.1.0"
+description = "High-speed concurrent SSH command runner"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "asyncssh>=2.14.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "fastapi>=0.100.0",
+    "pydantic>=2.0.0"
+]
+
+[project.scripts]
+netpulse-ssh = "netpulse.ssh.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/netpulse"]

netpulse_ssh-0.1.0/src/netpulse/ssh/__init__.py

@@ -0,0 +1 @@
+# Implicit namespace package. No imports here.

netpulse_ssh-0.1.0/src/netpulse/ssh/api.py

@@ -0,0 +1,57 @@
+from fastapi import APIRouter, HTTPException, status, FastAPI
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+from netpulse.ssh.models import SshHostConfig, SshExecutionAudit
+from netpulse.ssh.runner import SshRunnerService
+
+app = FastAPI(title="NetPulse SSH API")
+ssh_router = APIRouter()
+
+class SshExecuteHost(BaseModel):
+    ip: str = Field(..., description="Target IP or hostname.")
+    port: int = Field(22, description="SSH port.")
+
+class SshExecuteRequest(BaseModel):
+    hosts: List[SshExecuteHost] = Field(..., description="List of SSH hosts.")
+    command: str = Field(..., description="SSH command to execute.")
+    username: str = Field(..., description="SSH login username.")
+    password: Optional[str] = Field(None, description="SSH login password.")
+    enable_password: Optional[str] = Field(None, description="Cisco enable password.")
+    auto_negotiate: bool = Field(True, description="Enable key-exchange auto-negotiate fallbacks.")
+    ignore_host_keys: bool = Field(True, description="Ignore host verification checks.")
+    timeout_seconds: int = Field(10, description="Connection timeout.")
+
+@ssh_router.post("/api/v1/ssh/execute", response_model=SshExecutionAudit, status_code=status.HTTP_200_OK)
+async def execute_ssh_command(req: SshExecuteRequest):
+    """
+    Executes a command concurrently across one or multiple remote SSH hosts.
+    Returns the audit trail containing stdout/stderr for each host.
+    """
+    try:
+        hosts_config = []
+        for h in req.hosts:
+            hosts_config.append(SshHostConfig(
+                ip=h.ip,
+                port=h.port,
+                username=req.username,
+                password=req.password,
+                enable_password=req.enable_password,
+                auto_negotiate=req.auto_negotiate,
+                ignore_host_keys=req.ignore_host_keys,
+                timeout_seconds=req.timeout_seconds
+            ))
+            
+        runner = SshRunnerService()
+        audit = await runner.execute_concurrently(hosts_config, req.command)
+        return audit
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "error": "SshExecutionError",
+                "message": f"Concurrent SSH runner failed: {e}"
+            }
+        )
+
+app.include_router(ssh_router)

netpulse_ssh-0.1.0/src/netpulse/ssh/cli.py

@@ -0,0 +1,63 @@
+import typer
+import asyncio
+from typing import List, Optional
+from rich.console import Console
+from rich.table import Table
+from rich import print as rprint
+
+from netpulse.ssh.models import SshHostConfig, SshStatus
+from netpulse.ssh.runner import SshRunnerService
+
+app = typer.Typer(help="NetPulse SSH: High-speed concurrent command runner.")
+console = Console()
+
+@app.command("execute")
+def execute(
+    hosts: List[str] = typer.Argument(..., help="List of IP addresses to target."),
+    command: str = typer.Option(..., "--command", "-c", help="Command to execute."),
+    username: str = typer.Option(..., "--user", "-u", help="SSH Username.", prompt=True),
+    password: str = typer.Option("", "--pass", "-p", help="SSH Password.", hide_input=True, prompt="Password (leave empty if using keys)"),
+    enable_password: str = typer.Option("", "--enable", "-e", help="Cisco enable password.", hide_input=True),
+    port: int = typer.Option(22, "--port", help="SSH port."),
+):
+    """
+    Execute a command concurrently across multiple SSH hosts and aggregate the results.
+    """
+    hosts_config = [
+        SshHostConfig(
+            ip=ip,
+            port=port,
+            username=username,
+            password=password if password else None,
+            enable_password=enable_password if enable_password else None,
+        ) for ip in hosts
+    ]
+
+    async def run():
+        runner = SshRunnerService()
+        with console.status(f"[bold cyan]Executing '{command}' across {len(hosts)} hosts...", spinner="dots"):
+            audit = await runner.execute_concurrently(hosts_config, command)
+        
+        table = Table(title=f"SSH Execution Summary: '{command}'")
+        table.add_column("Host IP", justify="left", style="cyan", no_wrap=True)
+        table.add_column("Status", justify="center")
+        table.add_column("Latency (ms)", justify="right", style="magenta")
+        table.add_column("Output / Error", justify="left", style="green")
+
+        for res in audit.results:
+            if res.status == SshStatus.SUCCESS:
+                status_str = "[bold green]SUCCESS[/bold green]"
+                output = res.stdout.strip()[:100] + ("..." if len(res.stdout) > 100 else "") if res.stdout else "No output"
+            else:
+                status_str = "[bold red]FAILED[/bold red]"
+                output = f"[red]{res.error_message}[/red]"
+
+            table.add_row(res.ip, status_str, f"{res.latency_ms}ms", output)
+
+        console.print(table)
+        rprint(f"[bold]Total Success:[/bold] {audit.success_count} | [bold]Total Failed:[/bold] {audit.failed_count}")
+
+    asyncio.run(run())
+
+if __name__ == "__main__":
+    app()

netpulse_ssh-0.1.0/src/netpulse/ssh/models.py

@@ -0,0 +1,57 @@
+import uuid
+from enum import Enum
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field, ConfigDict
+
+class SshStatus(str, Enum):
+    SUCCESS = "success"
+    FAILED = "failed"
+
+class SshHostConfig(BaseModel):
+    """Configuration for an individual SSH connection target."""
+    model_config = ConfigDict(
+        use_enum_values=True,
+        validate_assignment=True,
+        populate_by_name=True
+    )
+    ip: str = Field(..., description="Target host IP address or hostname.")
+    port: int = Field(22, description="SSH port (defaults to 22).")
+    username: str = Field(..., description="SSH login username.")
+    password: Optional[str] = Field(None, description="SSH login password.")
+    enable_password: Optional[str] = Field(None, description="Cisco enable password.")
+    auto_negotiate: bool = Field(True, description="Attempt dynamic legacy cipher negotiation if handshake fails.")
+    ignore_host_keys: bool = Field(True, description="Bypass strict SSH host key checking.")
+    timeout_seconds: int = Field(10, description="SSH connection timeout.")
+
+class SshHostResult(BaseModel):
+    """Execution result details for an individual target host."""
+    model_config = ConfigDict(
+        use_enum_values=True,
+        validate_assignment=True
+    )
+    ip: str = Field(..., description="Target host IP address.")
+    status: SshStatus = Field(..., description="Connection or execution outcome status.")
+    stdout: Optional[str] = Field(None, description="Command execution standard output.")
+    stderr: Optional[str] = Field(None, description="Command execution standard error.")
+    latency_ms: Optional[float] = Field(None, description="Execution latency/duration in milliseconds.")
+    negotiated_kex: Optional[str] = Field(None, description="The negotiated key exchange algorithm.")
+    negotiated_cipher: Optional[str] = Field(None, description="The negotiated encryption cipher.")
+    error_message: Optional[str] = Field(None, description="Detailed failure reason if status is FAILED.")
+
+class SshExecutionAudit(BaseModel):
+    """Aggregate model representing a multi-host SSH execution session."""
+    model_config = ConfigDict(
+        use_enum_values=True,
+        validate_assignment=True
+    )
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Unique execution audit UUID.")
+    command: str = Field(..., description="The command executed across the targets.")
+    targets: List[str] = Field(..., description="Target host IP addresses.")
+    success_count: int = Field(..., description="Number of hosts successfully executed.")
+    failed_count: int = Field(..., description="Number of hosts that failed.")
+    executed_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Timestamp when the audit was generated (UTC)."
+    )
+    results: List[SshHostResult] = Field(..., description="Individual execution results.")

netpulse_ssh-0.1.0/src/netpulse/ssh/runner.py

@@ -0,0 +1,233 @@
+import asyncio
+import time
+import logging
+import asyncssh
+from typing import List, Optional, Tuple
+from datetime import datetime, timezone
+
+from netpulse.ssh.models import SshHostConfig, SshHostResult, SshStatus, SshExecutionAudit
+
+logger = logging.getLogger(__name__)
+
+class TrustingSSHClient(asyncssh.SSHClient):
+    """Custom SSH client that trusts all host keys to prevent IP-reassignment blockage."""
+    def validate_host_key(self, host: str, port: int, key: bytes, fingerprint: str) -> bool:
+        return True
+
+class SmartSshClient:
+    """
+    Highly resilient, non-blocking SSH client optimized for network engineers.
+    Automatically handles legacy cryptographic negotiation, pagination pager suppression,
+    host key changes, and privilege enable escalation.
+    """
+
+    @classmethod
+    async def connect_and_execute(cls, config: SshHostConfig, command: str) -> SshHostResult:
+        """
+        Resiliently connects to a host via SSH, performs command executions,
+        and logs performance/cryptographic parameters.
+        """
+        ip = config.ip
+        port = config.port
+        username = config.username
+        password = config.password
+        enable_password = config.enable_password
+        timeout = config.timeout_seconds
+
+        start_time = time.perf_counter()
+        
+        # Standard modern connection options
+        connect_opts = {
+            "host": ip,
+            "port": port,
+            "username": username,
+            "password": password,
+            "login_timeout": timeout,
+        }
+
+        # Bypass host key checking using our custom validator
+        if config.ignore_host_keys:
+            connect_opts["client_factory"] = TrustingSSHClient
+
+        conn = None
+        negotiated_kex = None
+        negotiated_cipher = None
+        used_fallback = False
+
+        try:
+            # 1. Attempt connection using modern secure algorithms
+            try:
+                conn = await asyncssh.connect(**connect_opts)
+            except (asyncssh.misc.ProtocolError, asyncssh.misc.DisconnectError) as e:
+                # Catch cryptographic key exchange or cipher mismatch errors
+                if config.auto_negotiate:
+                    logger.warning(
+                        f"Handshake failed with {ip}:{port} ({e}). Retrying with legacy cryptographic support..."
+                    )
+                    used_fallback = True
+                    
+                    # Explicitly enable legacy KEX, signature (host keys), and encryption ciphers
+                    legacy_opts = {
+                        **connect_opts,
+                        "kex_algs": [
+                            "diffie-hellman-group1-sha1",
+                            "diffie-hellman-group14-sha1",
+                            "diffie-hellman-group-exchange-sha1",
+                            "diffie-hellman-group-exchange-sha256",
+                            "ecdh-sha2-nistp256",
+                            "ecdh-sha2-nistp384",
+                            "ecdh-sha2-nistp521",
+                        ],
+                        "encryption_algs": [
+                            "aes128-cbc",
+                            "aes192-cbc",
+                            "aes256-cbc",
+                            "3des-cbc",
+                            "aes128-ctr",
+                            "aes192-ctr",
+                            "aes256-ctr",
+                        ],
+                        "signature_algs": [
+                            "ssh-rsa",
+                            "ssh-dss",
+                            "ecdsa-sha2-nistp256",
+                            "ssh-ed25519",
+                        ],
+                    }
+                    conn = await asyncssh.connect(**legacy_opts)
+                else:
+                    raise e
+
+            # Log successfully negotiated parameters
+            negotiated_kex = conn.get_extra_info("kex_alg")
+            negotiated_cipher = conn.get_extra_info("cipher_alg")
+
+            # 2. Interactive execution shell session (VT100)
+            # This enables handling Cisco enable prompts and suppressing --More-- page breaks
+            stdout_str, stderr_str = await cls._execute_interactive(
+                conn=conn,
+                command=command,
+                enable_password=enable_password,
+                timeout=timeout
+            )
+
+            latency_ms = (time.perf_counter() - start_time) * 1000.0
+
+            return SshHostResult(
+                ip=ip,
+                status=SshStatus.SUCCESS,
+                stdout=stdout_str,
+                stderr=stderr_str if stderr_str else None,
+                latency_ms=round(latency_ms, 2),
+                negotiated_kex=negotiated_kex,
+                negotiated_cipher=negotiated_cipher
+            )
+
+        except Exception as e:
+            latency_ms = (time.perf_counter() - start_time) * 1000.0
+            error_msg = str(e)
+            if used_fallback:
+                error_msg = f"Legacy Handshake Fail: {error_msg}"
+            
+            return SshHostResult(
+                ip=ip,
+                status=SshStatus.FAILED,
+                latency_ms=round(latency_ms, 2),
+                error_message=error_msg
+            )
+        finally:
+            if conn:
+                conn.close()
+                await conn.wait_closed()
+
+    @classmethod
+    async def _execute_interactive(
+        cls, 
+        conn: asyncssh.SSHClientConnection, 
+        command: str, 
+        enable_password: Optional[str] = None,
+        timeout: int = 10
+    ) -> Tuple[str, str]:
+        """
+        Emulates a virtual terminal (pty) session to run enable escalations
+        and suppress terminal pagination natively.
+        """
+        # Open interactive virtual terminal process
+        async with conn.create_process(term_type='vt100') as proc:
+            # 1. Handle Cisco privilege exec escalation
+            if enable_password:
+                proc.stdin.write("enable\n")
+                await asyncio.sleep(0.15)
+                proc.stdin.write(f"{enable_password}\n")
+                await asyncio.sleep(0.15)
+
+            # 2. Suppress terminal pagination (works on Cisco IOS / Cisco Mock environments)
+            # Non-Cisco environments will ignore/error this but proceed cleanly
+            proc.stdin.write("terminal length 0\n")
+            await asyncio.sleep(0.1)
+
+            # 3. Execute the actual command
+            proc.stdin.write(f"{command}\n")
+            await asyncio.sleep(0.15)
+            
+            # Exit session cleanly
+            proc.stdin.write("exit\n")
+            
+            # Read streams asynchronously with safety timeout
+            try:
+                stdout_data = await asyncio.wait_for(proc.stdout.read(), timeout=timeout)
+                stderr_data = await asyncio.wait_for(proc.stderr.read(), timeout=timeout)
+            except asyncio.TimeoutError:
+                stdout_data = "Error: Interactive terminal execution timed out."
+                stderr_data = ""
+
+            return stdout_data, stderr_data
+
+
+class SshRunnerService:
+    """
+    Orchestrates high-speed, parallel SSH command executions across multiple network hosts.
+    Aggregates outcomes and returns a unified execution audit.
+    """
+
+    async def execute_concurrently(self, hosts: List[SshHostConfig], command: str) -> SshExecutionAudit:
+        """
+        Concurrently executes a command across multiple host configurations.
+        
+        Args:
+            hosts: List of SshHostConfig models
+            command: Configuration or diagnostic command string to run
+            
+        Returns:
+            An SshExecutionAudit model aggregating all host executions and metrics
+        """
+        if not hosts:
+            return SshExecutionAudit(
+                command=command,
+                targets=[],
+                success_count=0,
+                failed_count=0,
+                results=[],
+                executed_at=datetime.now(timezone.utc)
+            )
+
+        # Trigger concurrent executions using asyncio.gather
+        tasks = [SmartSshClient.connect_and_execute(cfg, command) for cfg in hosts]
+        results: List[SshHostResult] = await asyncio.gather(*tasks)
+
+        # Count outcomes and targets
+        success_count = sum(1 for res in results if res.status == SshStatus.SUCCESS)
+        failed_count = sum(1 for res in results if res.status == SshStatus.FAILED)
+        targets = [cfg.ip for cfg in hosts]
+
+        # Construct unified execution audit model
+        audit = SshExecutionAudit(
+            command=command,
+            targets=targets,
+            success_count=success_count,
+            failed_count=failed_count,
+            results=results,
+            executed_at=datetime.now(timezone.utc)
+        )
+
+        return audit

netpulse_ssh-0.1.0/tests/integration/test_api.py

@@ -0,0 +1,69 @@
+import pytest
+from unittest.mock import patch, AsyncMock
+from fastapi.testclient import TestClient
+
+from netpulse.ssh.api import app
+from netpulse.ssh.models import SshExecutionAudit, SshHostResult, SshStatus
+
+def test_api_execute_ssh_command_success():
+    """Verify POST /api/v1/ssh/execute returns execution audit successfully."""
+    client = TestClient(app)
+    
+    mock_audit = SshExecutionAudit(
+        command="show version",
+        targets=["192.168.1.1"],
+        success_count=1,
+        failed_count=0,
+        results=[
+            SshHostResult(
+                ip="192.168.1.1",
+                status=SshStatus.SUCCESS,
+                stdout="Cisco IOS Software",
+                latency_ms=12.5,
+                negotiated_kex="curve25519-sha256",
+                negotiated_cipher="aes256-gcm@openssh.com"
+            )
+        ]
+    )
+    
+    with patch("netpulse.ssh.api.SshRunnerService.execute_concurrently", new_callable=AsyncMock) as mock_exec:
+        mock_exec.return_value = mock_audit
+        
+        payload = {
+            "hosts": [{"ip": "192.168.1.1", "port": 22}],
+            "command": "show version",
+            "username": "admin",
+            "password": "password",
+            "timeout_seconds": 10
+        }
+        
+        response = client.post("/api/v1/ssh/execute", json=payload)
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["command"] == "show version"
+        assert data["success_count"] == 1
+        assert len(data["results"]) == 1
+        assert data["results"][0]["ip"] == "192.168.1.1"
+        assert data["results"][0]["stdout"] == "Cisco IOS Software"
+
+def test_api_execute_ssh_command_failure():
+    """Verify POST /api/v1/ssh/execute handles backend runner exceptions and returns 500."""
+    client = TestClient(app)
+    
+    with patch("netpulse.ssh.api.SshRunnerService.execute_concurrently", new_callable=AsyncMock) as mock_exec:
+        mock_exec.side_effect = Exception("Kernel Panic in asyncssh loop")
+        
+        payload = {
+            "hosts": [{"ip": "10.0.0.1", "port": 22}],
+            "command": "reboot",
+            "username": "root",
+            "password": "password"
+        }
+        
+        response = client.post("/api/v1/ssh/execute", json=payload)
+        
+        assert response.status_code == 500
+        data = response.json()
+        assert data["detail"]["error"] == "SshExecutionError"
+        assert "Kernel Panic" in data["detail"]["message"]

netpulse_ssh-0.1.0/tests/integration/test_cli.py

@@ -0,0 +1,66 @@
+import pytest
+from unittest.mock import patch, AsyncMock
+from typer.testing import CliRunner
+
+from netpulse.ssh.cli import app
+from netpulse.ssh.models import SshExecutionAudit, SshHostResult, SshStatus
+
+runner = CliRunner()
+
+def test_cli_execute_ssh_command_success():
+    """Verify that the execute command invokes the runner and prints results successfully."""
+    mock_audit = SshExecutionAudit(
+        command="show version",
+        targets=["10.0.0.1"],
+        success_count=1,
+        failed_count=0,
+        results=[
+            SshHostResult(
+                ip="10.0.0.1",
+                status=SshStatus.SUCCESS,
+                stdout="Cisco IOS Software",
+                latency_ms=15.5,
+                negotiated_kex="curve25519-sha256",
+                negotiated_cipher="aes256-gcm@openssh.com"
+            )
+        ]
+    )
+    
+    with patch("netpulse.ssh.cli.SshRunnerService.execute_concurrently", new_callable=AsyncMock) as mock_exec:
+        mock_exec.return_value = mock_audit
+        
+        result = runner.invoke(app, ["execute", "10.0.0.1", "-c", "show version", "-u", "admin", "-p", "password"])
+        
+        assert result.exit_code == 0
+        assert "SSH Execution Summary" in result.stdout
+        assert "10.0.0.1" in result.stdout
+        assert "SUCCESS" in result.stdout
+        assert "Cisco IOS Software" in result.stdout
+
+def test_cli_execute_ssh_command_failure():
+    """Verify that the execute command handles failures cleanly and prints them."""
+    mock_audit = SshExecutionAudit(
+        command="show version",
+        targets=["10.0.0.1"],
+        success_count=0,
+        failed_count=1,
+        results=[
+            SshHostResult(
+                ip="10.0.0.1",
+                status=SshStatus.FAILED,
+                error_message="Authentication failed: invalid username or password.",
+                latency_ms=10.0
+            )
+        ]
+    )
+    
+    with patch("netpulse.ssh.cli.SshRunnerService.execute_concurrently", new_callable=AsyncMock) as mock_exec:
+        mock_exec.return_value = mock_audit
+        
+        result = runner.invoke(app, ["execute", "10.0.0.1", "-c", "show version", "-u", "admin", "-p", "wrongpassword"])
+        
+        assert result.exit_code == 0
+        assert "10.0.0.1" in result.stdout
+        assert "FAILED" in result.stdout
+        assert "Authentication failed" in result.stdout
+        assert "Total Failed: 1" in result.stdout

netpulse_ssh-0.1.0/tests/unit/test_ssh.py

@@ -0,0 +1,152 @@
+import os
+import pytest
+import uuid
+import asyncio
+from unittest.mock import patch, MagicMock, AsyncMock
+from datetime import datetime, timezone
+import asyncssh
+
+from netpulse.ssh.models import SshHostConfig, SshHostResult, SshExecutionAudit, SshStatus
+from netpulse.ssh.runner import SmartSshClient, SshRunnerService
+
+def test_ssh_models_instantiation():
+    """Verify that SSH models validate inputs and set correct defaults."""
+    config = SshHostConfig(
+        ip="192.168.1.1",
+        username="admin",
+        password="secretpassword",
+        enable_password="enablepwd"
+    )
+    assert config.ip == "192.168.1.1"
+    assert config.port == 22
+    assert config.username == "admin"
+    assert config.password == "secretpassword"
+    assert config.enable_password == "enablepwd"
+    assert config.auto_negotiate is True
+    assert config.ignore_host_keys is True
+
+    result = SshHostResult(
+        ip="192.168.1.1",
+        status=SshStatus.SUCCESS,
+        stdout="interface GigabitEthernet0/1\n ip address 192.168.1.1",
+        latency_ms=45.2,
+        negotiated_kex="diffie-hellman-group14-sha1",
+        negotiated_cipher="aes128-cbc"
+    )
+    assert result.ip == "192.168.1.1"
+    assert result.status == SshStatus.SUCCESS
+    assert "GigabitEthernet0/1" in result.stdout
+    assert result.latency_ms == 45.2
+    assert result.negotiated_kex == "diffie-hellman-group14-sha1"
+    assert result.negotiated_cipher == "aes128-cbc"
+
+
+@pytest.mark.asyncio
+@patch("asyncssh.connect", new_callable=AsyncMock)
+async def test_ssh_client_success_standard(mock_connect):
+    """Verify that SmartSshClient connects and executes successfully under standard handshakes."""
+    mock_conn = MagicMock()
+    mock_conn.wait_closed = AsyncMock()
+    mock_conn.get_extra_info.side_effect = lambda key: {
+        "kex_alg": "curve25519-sha256",
+        "cipher_alg": "aes256-gcm@openssh.com"
+    }.get(key)
+    
+    # Mock the terminal process stream
+    mock_proc = AsyncMock()
+    mock_proc.stdout.read.return_value = "GigabitEthernet0/1 is up, line protocol is up"
+    mock_proc.stderr.read.return_value = ""
+    mock_conn.create_process.return_value.__aenter__ = AsyncMock(return_value=mock_proc)
+    mock_conn.create_process.return_value.__aexit__ = AsyncMock()
+
+    mock_connect.return_value = mock_conn
+
+    config = SshHostConfig(ip="192.168.1.5", username="admin", password="password")
+    
+    result = await SmartSshClient.connect_and_execute(config, "show interface description")
+    
+    assert result.status == SshStatus.SUCCESS
+    assert "GigabitEthernet0/1" in result.stdout
+    assert result.negotiated_kex == "curve25519-sha256"
+    assert result.negotiated_cipher == "aes256-gcm@openssh.com"
+    assert result.error_message is None
+    
+    # Ensure it only connected once (no legacy retry needed)
+    mock_connect.assert_called_once()
+
+
+@pytest.mark.asyncio
+@patch("asyncssh.connect", new_callable=AsyncMock)
+async def test_ssh_client_legacy_handshake_healing(mock_connect):
+    """Verify that SmartSshClient retries connection with legacy ciphers if initial handshake fails."""
+    # First connect attempt raises NegotiationError
+    # Second connect attempt succeeds
+    mock_conn = MagicMock()
+    mock_conn.wait_closed = AsyncMock()
+    mock_conn.get_extra_info.side_effect = lambda key: {
+        "kex_alg": "diffie-hellman-group1-sha1",
+        "cipher_alg": "3des-cbc"
+    }.get(key)
+    
+    mock_proc = AsyncMock()
+    mock_proc.stdout.read.return_value = "Legacy Cisco Switch Config..."
+    mock_proc.stderr.read.return_value = ""
+    mock_conn.create_process.return_value.__aenter__ = AsyncMock(return_value=mock_proc)
+    mock_conn.create_process.return_value.__aexit__ = AsyncMock()
+
+    mock_connect.side_effect = [
+        asyncssh.misc.ProtocolError("Key exchange failed: no matching algorithms"),
+        mock_conn
+    ]
+
+    config = SshHostConfig(ip="192.168.1.10", username="admin", password="password", auto_negotiate=True)
+    
+    result = await SmartSshClient.connect_and_execute(config, "show run")
+    
+    assert result.status == SshStatus.SUCCESS
+    assert "Legacy Cisco Switch" in result.stdout
+    assert result.negotiated_kex == "diffie-hellman-group1-sha1"
+    assert result.negotiated_cipher == "3des-cbc"
+    
+    # Ensure it connected twice (first fail, second legacy retry)
+    assert mock_connect.call_count == 2
+    # Second call must have legacy algorithms configured
+    legacy_call_args = mock_connect.call_args_list[1][1]
+    assert "diffie-hellman-group1-sha1" in legacy_call_args["kex_algs"]
+    assert "3des-cbc" in legacy_call_args["encryption_algs"]
+
+
+@pytest.mark.asyncio
+@patch("asyncssh.connect", new_callable=AsyncMock)
+async def test_ssh_runner_concurrent_execution(mock_connect):
+    """Verify that SshRunnerService executes commands across multiple hosts in parallel and saves results."""
+    mock_conn = MagicMock()
+    mock_conn.wait_closed = AsyncMock()
+    mock_conn.get_extra_info.side_effect = lambda key: {
+        "kex_alg": "curve25519-sha256",
+        "cipher_alg": "aes256-gcm@openssh.com"
+    }.get(key)
+    
+    mock_proc = AsyncMock()
+    mock_proc.stdout.read.return_value = "Command output"
+    mock_proc.stderr.read.return_value = ""
+    mock_conn.create_process.return_value.__aenter__ = AsyncMock(return_value=mock_proc)
+    mock_conn.create_process.return_value.__aexit__ = AsyncMock()
+    mock_connect.return_value = mock_conn
+
+    # Multi-host targets
+    hosts = [
+        SshHostConfig(ip="10.0.0.1", username="cisco", password="pwd"),
+        SshHostConfig(ip="10.0.0.2", username="cisco", password="pwd")
+    ]
+    
+    runner = SshRunnerService()
+    
+    audit = await runner.execute_concurrently(hosts, "show clock")
+    
+    assert isinstance(audit, SshExecutionAudit)
+    assert audit.success_count == 2
+    assert audit.failed_count == 0
+    assert len(audit.results) == 2
+    assert audit.results[0].stdout == "Command output"
+    assert audit.results[1].stdout == "Command output"