SSH Security & Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/ssh/manager.py
• examples/ssh_deployment.py
• src/cli.py
• README.md
• AGENT.md
• SKILLS.md

Introduction

The SSH Security & Management system within WIREDUP provides a robust framework for secure remote execution, connection pooling, and credential handling. It is designed to allow AI agents to interact with remote infrastructure securely and efficiently, supporting features like automated key rotation and connection lifecycle management.

This system serves as a core infrastructure component, integrated with the Auto-Wiring Engine and the Agent System, enabling "Execution Agents" to perform system operations, upload files, and manage remote servers through standardized interfaces.
Sources: README.md:12, AGENT.md:16-20, src/ssh/manager.py:7-12

System Architecture

The architecture is centered around the SSHManager, which coordinates between a high-performance connection pool and individual execution requests.

The diagram shows the flow from client components through the management layer to the remote server via pooled connections.
Sources: src/ssh/manager.py:246-265, AGENT.md:32-45, src/cli.py:228-256

Core Components

1. SSH Credentials & Connection Data

Connections are established using the SSHCredentials dataclass, which supports both password-based and key-based authentication. For security, sensitive data is masked when credentials are exported to dictionaries.
Sources: src/ssh/manager.py:24-46

Field	Type	Description
host	str	Remote hostname or IP address
port	int	SSH port (default: 22)
username	str	Login username
password	Optional[str]	Optional login password
key_filename	Optional[str]	Path to private SSH key
timeout	int	Connection timeout in seconds

Sources: src/ssh/manager.py:25-34

2. Connection Pooling

The SSHConnectionPool manages the lifecycle of paramiko.SSHClient instances. It implements thread-safe locking and a background cleanup worker to prune expired or idle connections.
Sources: src/ssh/manager.py:97-118

This sequence illustrates the logic for reusing existing connections or establishing new ones through the pool.
Sources: src/ssh/manager.py:136-175

Command Execution & File Operations

The SSHManager provides high-level methods for interacting with remote hosts.

Execution Methods

• execute: Runs a single command with optional retries and timeout settings.
• execute_batch: Runs multiple commands sequentially or in parallel using Python threading.
  Sources: src/ssh/manager.py:276-368

SFTP Operations

The system supports secure file transfers via SFTP through the following methods:

• upload_file: Transfers a local file to a remote path.
• download_file: Retrieves a remote file to a local destination.
  Sources: src/ssh/manager.py:370-428

CLI Integration

The system is accessible via the ai-wire command-line tool, allowing users to execute remote commands directly.

# Example CLI usage
ai-wire ssh-exec --host localhost --username user --key-file ~/.ssh/id_rsa "ls -la"

Sources: src/cli.py:228-238, setup.py:40-44

Security Implementation

Security is managed through several layers:

1. Key Management: Support for private key files and passphrases.
2. Data Masking: The SSHCredentials.to_dict() method ensures passwords are replaced with *** in logs and exports.
3. Connection Pruning: Automated cleanup of connections based on max_age (default 3600s) and idle_timeout (default 300s).
4. Auto-Add Policy: Uses paramiko.AutoAddPolicy() for host key verification during initial setup.
   Sources: src/ssh/manager.py:38-44, src/ssh/manager.py:102-105, src/ssh/manager.py:202-205

Usage Example

The following snippet demonstrates how to use the SSHManager to execute a batch of commands.

from src.ssh import SSHManager, SSHCredentials

manager = SSHManager()
creds = SSHCredentials(host='192.168.1.10', username='admin', key_filename='~/.ssh/id_rsa')

commands = ['pwd', 'whoami', 'uptime']
results = manager.execute_batch(commands, credentials=creds, parallel=True)

for res in results:
    if res.success:
        print(f"Result: {res.stdout.strip()}")

Sources: examples/ssh_deployment.py:45-56, src/ssh/manager.py:348-368

Summary

SSH Security & Management in WIREDUP provides a production-ready interface for remote operations. By utilizing connection pooling and integration with the project's Auto-Wiring system, it ensures that AI agents can perform infrastructure tasks with high performance and strong security defaults.
Sources: src/ssh/manager.py:7-15, AGENT.md:325-345