agent-pard0x/SSH_TOOL_INTEGRATION.md

# SSH Tool Integration

This document explains how to use the new SSH tool alongside the existing Shell tool in both the simple-react-agent and multi-agent-supervisor approaches.

## Overview

We now have two complementary tools for system administration:

- **ShellTool**: Execute commands on the local machine
- **SSHTool**: Execute commands on remote servers via SSH

Both tools follow the same pattern as the original LangChain ShellTool, maintaining persistent connections for efficiency.

## Installation

First, install the required dependency:

```bash
uv add paramiko
```

## Usage Examples

### Simple React Agent

```python
from simple_react_agent.custom_tools import ShellTool, SSHTool, print_poem
from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent

# Create tools
shell_tool = ShellTool(ask_human_input=True)
ssh_tool = SSHTool(
    host="your-server.com",
    username="admin",
    key_filename="~/.ssh/id_rsa",
    ask_human_input=True
)

# Create agent
llm = init_chat_model("openai:gpt-4o-mini")
agent = create_react_agent(llm, [shell_tool, ssh_tool, print_poem])
```

### Multi-Agent Supervisor

```python
from multi_agent_supervisor.custom_tools import ShellTool, SSHTool, print_poem
from multi_agent_supervisor.agents import create_os_detector_worker

# Enhanced tools for all agents
tools = [
    ShellTool(),
    SSHTool(host="server1.com", username="admin", key_filename="~/.ssh/key"),
    print_poem
]

# Create agents with both local and remote capabilities
os_detector = create_os_detector_worker(llm=llm, tools=tools)
```

## SSH Tool Configuration

### Authentication Methods

#### SSH Key Authentication (Recommended)
```python
ssh_tool = SSHTool(
    host="server.example.com",
    username="admin",
    key_filename="~/.ssh/id_rsa",  # Path to private key
    port=22,  # Default SSH port
    timeout=30.0,  # Connection timeout
    ask_human_input=True  # Ask for confirmation before executing
)
```

#### Password Authentication
```python
ssh_tool = SSHTool(
    host="192.168.1.100",
    username="user",
    password="secure_password",
    port=22
)
```

### Security Features

1. **Human Confirmation**: Set `ask_human_input=True` to require user confirmation
2. **Connection Timeout**: Configurable timeout for connection attempts
3. **Warning Messages**: Automatic warnings about security risks
4. **Persistent Connections**: Single SSH connection reused for multiple commands

## Tool Integration Patterns

### Local + Remote System Analysis
```python
# Check local system
local_result = shell_tool.run(commands=["df -h", "free -m"])

# Check remote system
remote_result = ssh_tool.run(commands=["df -h", "free -m"])

# Compare results for comprehensive analysis
```

### Multi-Server Management
```python
# Create multiple SSH tools for different servers
web_server = SSHTool(host="web1.com", username="admin", key_filename="~/.ssh/web_key")
db_server = SSHTool(host="db1.com", username="admin", key_filename="~/.ssh/db_key")

# Agents can now manage multiple remote systems
tools = [ShellTool(), web_server, db_server, print_poem]
```

## Safety Considerations

1. **Start with Read-Only Commands**: Always begin diagnostics with non-destructive commands
2. **Use Human Confirmation**: Enable `ask_human_input=True` for production systems
3. **Secure Key Management**: Store SSH keys securely, use proper file permissions
4. **Network Security**: Ensure SSH connections are over secure networks
5. **Audit Logging**: Monitor SSH command execution for security compliance

## Example Use Cases

### System Monitoring
- Compare disk usage across local and remote systems
- Monitor performance metrics on multiple servers
- Analyze logs from distributed systems

### Troubleshooting
- Investigate network connectivity between local and remote systems
- Debug application issues across server tiers
- Perform maintenance tasks on remote infrastructure

### Infrastructure Management
- Deploy configuration changes to multiple servers
- Collect system information for inventory management
- Perform bulk operations across server farms

## File Structure

```
project/
├── simple-react-agent/
│   └── custom_tools/
│       ├── __init__.py          # Exports ShellTool, SSHTool, print_poem
│       ├── ssh_tool.py          # SSH tool implementation
│       ├── shell_tool_wrapper.py # Shell tool wrapper
│       └── poem_tool.py         # Existing poem tool
└── multi-agent-supervisor/
    └── custom_tools/
        ├── __init__.py          # Exports ShellTool, SSHTool, print_poem
        ├── ssh_tool.py          # SSH tool implementation
        ├── shell_tool_wrapper.py # Shell tool wrapper
        └── poem_tool.py         # Existing poem tool
```

## Next Steps

1. Configure SSH access to your target servers
2. Test SSH connectivity manually before using the tool
3. Start with read-only commands to validate functionality
4. Integrate SSH tools into your existing agent workflows
5. Monitor and log SSH tool usage for security compliance

## Troubleshooting

### Common Issues

1. **Connection Refused**: Check if SSH service is running on target server
2. **Authentication Failed**: Verify username, password, or SSH key
3. **Timeout Errors**: Increase timeout value or check network connectivity
4. **Permission Denied**: Ensure proper file permissions on SSH keys (600)

### Debug Commands

```python
# Test SSH connectivity
ssh_tool.run(commands="echo 'SSH connection successful'")

# Check SSH configuration
ssh_tool.run(commands="ssh -V")  # SSH version
ssh_tool.run(commands="whoami")  # Current user
```