SSH Fleet Doctor

Background

Make routine remote checks easier to inspect

SSH Fleet Doctor is an evolving administration and server-health toolkit, combining shell automation with a Python/Paramiko monitoring path. The problem it addresses is familiar in system operations: an operator needs a consistent way to inspect authorised remote hosts and collect selected health signals, but the checks should remain visible enough to review rather than disappearing behind a large management platform.

This is still a work in progress. The intended end state is broader than read-only monitoring, but diagnostics, issue detection, and remediation must be implemented and verified separately. A planned capability is not evidence that the current repository already supports it safely.

Architecture

A small Bash workflow with a Python monitoring path

The shell side handles operator-facing setup and orchestration; the Python path uses Paramiko for SSH connectivity and health checks. Remote operations depend on the target host, network access, authentication configuration, installed tools, and permissions. The toolkit should be treated as an administrative client, not as a replacement for a controlled configuration-management system.

Planned scope

Target workflow and development plan

The intended workflow has four distinct stages: connect to an approved host, gather system data, identify a condition that needs attention, and—only when a suitable fix has been reviewed—run a command or script and verify the result. The page describes the goal; it does not claim all four stages are implemented.

1. Connect and identify the host

• Use an explicit host inventory and a defined authorization scope.
• Keep SSH host-key verification enabled and use a dedicated least-privilege account.
• Handle credentials through supported SSH keys, agents, or a protected secret mechanism—not command-line password arguments or public logs.

2. Collect system information and detect issues

• Gather selected CPU, memory, disk, network, process, service, and operating-system details where the target supports them.
• Make thresholds and checks understandable; report the observed value and evidence behind each alert.
• Distinguish a warning or anomaly from a confirmed root cause. Missing data must not be presented as a healthy result.

3. Apply reviewed fixes only when safe

• Start with read-only diagnostics. Add a small, reviewed set of remediation actions rather than unrestricted shell execution as the default.
• Show the target, command or script, expected effect, required permissions, timeout, and rollback approach before a state-changing run.
• Require explicit authorization and confirmation for changes; capture the result and re-run the relevant check to verify the fix.

4. Development milestones

1. Reconcile and review the linked legacy scripts, authentication, and host-key handling.
2. Make one-host read-only connection and system-health reporting reliable.
3. Add configurable issue checks with examples and tests for missing, stale, and abnormal data.
4. Introduce separately tested remediation actions with confirmation, bounded execution, audit logs, and recovery instructions.
5. Consider fleet-wide scheduling only after single-host behavior, permissions, failure reporting, and recovery have been tested.

Current implementation caveat: the linked repository currently contains legacy SSH-Infiltrator naming and command-execution behavior. It needs a focused security and architecture review before the repository should be presented as a completed implementation of this target design.

Setup guide

Start on a test host and verify each layer

Prerequisites

• Python 3 and the repository’s documented dependencies.
• SSH reachability to a test host you own or are authorised to administer.
• A dedicated user with only the permissions required for the checks.
• Known host keys and a documented way to revoke the test credentials.

Steps

1. Read the repository README and inspect the launcher before executing it.
2. Create a virtual environment and install only the listed dependencies.
3. Configure a single test host first; do not begin with a broad production fleet.
4. Confirm SSH host-key verification and test authentication interactively.
5. Run the documented read-only checks and compare the output with the host’s own tools.
6. Inspect the logs to confirm they record useful context without secrets.

Use the exact setup commands from the current project repository; do not assume a command in an older copy is still valid.

Verification

What a safe first test should prove

• The expected Python/Paramiko imports succeed in the intended environment.
• The test host is identified as expected and authentication uses the planned credential.
• Read-only CPU, memory, disk, and network checks return plausible values for that host.
• Unavailable commands and SSH failures are reported clearly without exposing secrets.
• Logs contain enough detail to diagnose the issue and can be retained without leaking private information.

A successful read-only check is not proof that write or remediation actions are safe. Test each such operation separately with explicit authorization, clear preconditions, confirmation, and a rollback plan.

Troubleshooting and status

Diagnose in layers

• Connection failure: verify the hostname, routing, SSH service, port, firewall rules, and host-key entry.
• Authentication failure: check the intended account, key permissions, SSH agent, and server policy; do not fall back to pasting passwords into logs.
• Missing metrics: determine whether the remote command exists and whether the account can run it.
• Dependency problem: recreate the virtual environment from the current dependency manifest.
• Unexpected state change: stop the run, preserve the logs, and confirm which command was executed before repeating it.

This project is marked in development. Treat scripts and interfaces as evolving; read the latest repository notes and inspect code before running it against systems you depend on.

Source and current status

Explore the project

In development. This page documents the public project record. For the current code, dependencies, licence, issues, and setup steps, check the linked repository before using it.

For corrections, contact GLab Ent. or raise it in the linked repository.