Network Device Detail Fetcher Actor

An Apify Actor that fetches detailed information about network devices via SSH. This Actor is designed to efficiently retrieve device data from multiple hosts while maintaining robust error handling and minimal resource usage.

Features

• SSH-based device connectivity - Connect to multiple network devices securely using SSH
• Command execution - Execute arbitrary commands on remote devices with optional sudo support
• CSV-based device management - Load device configuration from CSV files
• Structured output - Organize command outputs in a structured JSON format for easy analysis
• Error handling - Graceful error handling with detailed logging for failed connections and commands
• Async support - Leverages async/await for efficient cloud execution on Apify platform

Input

The Actor accepts the following input configuration:

{
  "csvFilePath": "path/to/devices.csv"
}

CSV Format

Create a CSV file with device details in the following format:

Serial Number,IP,Port,Hostname,Password
2,192.168.215.2,22,root,root
3,192.168.215.3,22,admin,password123

Required fields:

• Serial Number - Unique device identifier
• IP - Device IP address
• Hostname - SSH username for authentication

Optional fields:

• Port - SSH port (default: 22)
• Password - SSH password for authentication

Output

The Actor pushes structured JSON data to the dataset for each device:

{
  "device_ip": "192.168.215.2",
  "device_name": "N/A",
  "commands_executed": [
    {
      "command": "ip -j addr show",
      "output": "...",
      "error": ""
    },
    {
      "command": "uname -a",
      "output": "...",
      "error": ""
    }
  ]
}

In case of errors:

{
  "device_ip": "192.168.215.2",
  "error": "SSH connection failed: [Errno -2] Name or service not known"
}

Configuration

Devices CSV

• Path: data/input.csv (default)
• Format: CSV with headers matching Device model fields

Commands

Edit src/constants.py to customize which commands execute on each device:

COMMANDS = [
    "ip -j addr show",
    "ip -j link show",
    "uname -a",
    "lscpu -J",
]

SSH Settings

Configure SSH connection timeout in src/constants.py:

SSH_CONNECTION_TIMEOUT = 10  # seconds

Local Development

Prerequisites

• Python 3.13+
• Paramiko (SSH client library)
• Pydantic (data validation)
• Apify SDK

Installation

# Install dependencies
pip install -r requirements.txt

# Run locally
apify run

Testing

Run the test script to verify device connectivity:

$python test.py

Deployment

Prerequisites

• Apify account
• Apify CLI installed (npm install -g apify-cli)

Steps

1. Authenticate with Apify:

$apify login

2. Deploy the Actor:

$apify push

3. Run on Apify platform through the web console or API

Project Structure

.
├── .actor/
│   ├── actor.json              # Actor configuration
│   └── INPUT_SCHEMA.json       # Input validation schema
├── src/
│   ├── __main__.py             # Entry point
│   ├── main.py                 # Actor logic
│   ├── models.py               # Pydantic data models
│   ├── constants.py            # Configuration constants
│   └── actor/
│       ├── connect.py          # SSH connection handler
│       └── device.py           # Device CSV loader
├── data/
│   └── input.csv               # Device configuration file
├── storage/                    # Local Apify storage (ignored in git)
├── Dockerfile                  # Container configuration
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Device Model

The src/models.py defines the structure for device configuration:

class Device(BaseModel):
    serial_number: str = Field(alias="Serial Number")
    ip: str = Field(alias="IP")
    port: Optional[int] = Field(alias="Port", default=22)
    hostname: Optional[str] = Field(alias="Hostname", default=None)
    password: Optional[str] = Field(alias="Password", default=None)

Error Handling

The Actor implements comprehensive error handling:

• CSV parsing errors - Logged and skipped, allowing other devices to process
• SSH connection failures - Caught and stored in output dataset
• Command execution errors - Captured and included in command output
• Timeout handling - Configurable SSH timeout with proper cleanup

Security Considerations

⚠️ Important: This Actor handles sensitive data (passwords, device IP addresses, command outputs).

• Store credentials securely using Apify's Secrets feature
• Use SSH keys instead of passwords when possible
• Avoid logging sensitive data
• Review device access policies before deployment
• Ensure CSV files are stored securely

Troubleshooting

Connection Refused

• Verify device IP address and port are correct
• Ensure SSH service is running on the device
• Check firewall rules allow SSH access

Authentication Failed

• Verify username (Hostname field) is correct
• Confirm password is accurate
• Check if device uses key-based authentication (not yet supported)

Command Execution Timeout

• Increase SSH_CONNECTION_TIMEOUT in src/constants.py
• Verify device is responsive
• Check if commands are hanging waiting for input

Future Enhancements

• Support SSH key-based authentication
• Batch command execution with parallel processing
• Output schema for better Apify Console integration
• Dataset schema for structured data display
• Support for custom device properties
• Command output parsing and structured extraction

License

MIT

Author

Sriniketh J

Support

For issues or questions, please refer to the Apify documentation.