Hardware Probe Agent

A comprehensive hardware analysis tool that connects to remote systems via SSH and generates detailed hardware reports including upgrade recommendations for AI workloads.

Features

• SSH-based remote probing - Connect to any system via SSH using IP addresses or SSH config aliases
• Comprehensive hardware detection - CPU, GPU, RAM, motherboard, storage, networking, USB devices
• AI workload focus - Specialized recommendations for machine learning and AI applications
• Structured reporting - Detailed markdown reports with upgrade pathways and cost analysis
• Security assessment - TPM status, patching information, and firewall configuration
• Virtualization detection - Identifies VMs and hypervisor configurations

Installation

1. Clone this repository:

git clone <repository-url>
cd Hardware-Probe-Agent-Template

2. Run the setup script:

./setup.sh

This will:

• Create a virtual environment using uv (or fallback to python -m venv)
• Install all dependencies
• Make scripts executable

Manual installation (if you prefer):

pip install -r requirements.txt
chmod +x src/main.py src/hardware_probe_agent.py src/report_generator.py

Usage

Basic Usage (Shell Wrapper - Recommended)

Probe a system using SSH config:

./run.sh 10.0.0.4

Probe with specific username:

./run.sh 192.168.1.100 -u admin

Probe with specific SSH key:

./run.sh myserver -k ~/.ssh/id_rsa

Direct Python Usage

Alternatively, activate the virtual environment and run directly:

source venv/bin/activate
python src/main.py 10.0.0.4

Advanced Usage

Custom output directory:

./run.sh 10.0.0.4 -o /tmp/reports

Use default output directory:

./run.sh 10.0.0.4
# Reports saved to ./output/

Generate only raw data (no formatted report):

./run.sh 10.0.0.4 --raw-only

Generate report from existing raw data:

./run.sh --report-only raw_data_host_20240815_181234.json

SSH Configuration

The agent works best with SSH key-based authentication. Ensure your SSH config (~/.ssh/config) is properly configured:

Host myserver
    HostName 10.0.0.4
    User daniel
    IdentityFile ~/.ssh/id_rsa
    Port 22

Then simply use:

./run.sh myserver

Output Files

The agent generates two types of output in the output/ directory:

1. Raw Data (raw_data_<host>_<timestamp>.json) - Complete probe results in JSON format
2. Formatted Report (hardware_report_<host>_<timestamp>.md) - Human-readable markdown report

All reports are saved to the output/ directory by default. You can specify a different location with the -o flag.

Report Structure

Generated reports include:

Part 1: System Parameters

• OS and kernel information
• System uptime
• High-level system description
• Motherboard details
• RAM configuration
• CPU specifications
• GPU information and AI suitability
• Storage analysis
• Network configuration
• USB devices
• Security status (TPM, firewall, patching)

Part 2: Upgrade Pathways

• Cost-effective upgrade recommendations
• Component compatibility analysis
• Part numbers and pricing
• AI workload optimization focus

Part 3: Software Optimization

• OS-level performance tuning suggestions
• Driver and acceleration setup
• Container and virtualization recommendations

Part 4: Data Backup

• Backup solution recommendations
• Storage capacity planning

Overall Assessment

• System suitability analysis
• Investment priorities
• Performance bottleneck identification

Requirements

• Python 3.6+
• SSH access to target systems
• paramiko library for SSH connectivity

Target System Requirements

For best results, target systems should have:

• SSH server running
• Standard Linux utilities (lscpu, lspci, dmidecode, etc.)
• Sudo access for hardware detection (optional but recommended)

Configuration

Modify config.py to customize:

• SSH connection settings
• Hardware probe commands
• GPU and memory recommendations
• Report formatting options

Examples

Probing Your LAN Infrastructure

Based on the user's network setup (10.0.0.0/24):

# Probe Proxmox host
./run.sh 10.0.0.2

# Probe Home Assistant
./run.sh 10.0.0.3

# Probe Ubuntu server
./run.sh 10.0.0.4

# Probe Synology NAS
./run.sh 10.0.0.50

Batch Processing

#!/bin/bash
# Probe multiple systems
for host in 10.0.0.2 10.0.0.3 10.0.0.4; do
    ./run.sh $host
done

Troubleshooting

SSH Connection Issues

• Verify SSH key authentication is working: ssh <host>
• Check SSH config syntax: ssh -F ~/.ssh/config <host>
• Ensure target system allows SSH connections

Permission Issues

• Some hardware detection requires sudo access
• The agent gracefully handles permission denials
• Consider adding your user to appropriate groups on target systems

Missing Commands

• The agent handles missing utilities gracefully
• Install additional tools on target systems for more detailed reports:
  • lm-sensors for temperature monitoring
  • smartmontools for disk health
  • dmidecode for detailed hardware info