netpulse-ssh 0.1.0__py3-none-any.whl

netpulse/ssh/__init__.py

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

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+netpulse/ssh/__init__.py,sha256=gI9uL2EFnQk8XTlyZG3dNTx9c2yMYKIPBsh-Q8j89Ok,47
+netpulse/ssh/api.py,sha256=_Ni30zHAW7PgBmonvRw1kWH-ki7ByLMIZEPDSPsEfW0,2383
+netpulse/ssh/cli.py,sha256=B6-kclQluOPLAPLgcK1_KPI21OWPs_IGv_w_2rS6Wus,2656
+netpulse/ssh/models.py,sha256=BqTinDsrQ1vyD26gsc8FS2eG45FeOOAaoTPI8Umk49A,2980
+netpulse/ssh/runner.py,sha256=g3hfg30mSI2cSJPAZfbCLIva1XXbyPFYGY9t9mAfS3U,8813
+netpulse_ssh-0.1.0.dist-info/METADATA,sha256=ajgaFbzG1jKvxx-GiypdpggFqIUhiNvzpiK2R4J8c7w,4272
+netpulse_ssh-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+netpulse_ssh-0.1.0.dist-info/entry_points.txt,sha256=O1Mr_eNwjWTYiWy2RWPIJlxxhpIHsTDTklL_71b0ji0,54
+netpulse_ssh-0.1.0.dist-info/RECORD,,

netpulse_ssh-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

netpulse_ssh-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+netpulse-ssh = netpulse.ssh.cli:app