ssher

Lightweight SSH orchestration for quick audits and ad-hoc automation. Think of it as “nmap for SSH” with a focus on readable output and fast iteration.

Why ssher?

• Human-friendly automation: run commands, scripts, or file syncs without committing to full-blown configuration management.
• Batteries included: works with macOS/Linux shells and standard OpenSSH; optional sshpass for password-based hosts.
• Fast iteration: simple inventories, terse command flags, and parallel execution with live progress feedback.

Installation

nix/nixos

nix shell github:kr-nn/ssher

nix profile install github:kr-nn/ssher

{
  inputs.ssher = "github:kr-nn/ssher/master";
  outputs = { self, ssher, ... }:
  let
     ssherPkgs = import ssher { inherit system; }
  in
  {
    ... ssherPkgs.ssher ...    
  }
}

Clone the repo and invoke the script directly:

git clone https://github.com/kr-nn/ssher
cd ssher
./ssher

Ensure the script is executable (chmod +x ssher) if your checkout loses permissions.

Basic Concepts

• Inventory: text file listing hosts (one per line). Lines beginning with # are ignored.
• Mode: first positional argument; defines what action to run against each host.
• Parallel jobs: default to CPU count, adjustable via -J. The TUI shows queued/success/failed while jobs execute.

Usage

./ssher <mode> -i <inventory> [options]

Mode	Description
ping	Probe hosts and report authentication method (key vs password).
run	Execute a shell command on each host.
script	Pipe a local script to every host (bash -s).
upload	Append/overwrite a remote file with local contents.
collect	Pull remote file contents into a local report file.
update	Push data produced by collect back to the respective hosts.

Common Flags

• -i, --inventory <file>: host list (required).
• -u, --user <name>: override SSH username (defaults to current user).
• -l, --localfile <path>: local file for modes that read from disk (script, upload, collect, update).
• -r, --remotefile <path>: remote file target (upload, collect, update).
• -c, --command <cmd>: command for run.
• -p, --password: prompt once and use sshpass for password authentication.
• -o, --options: custom SSH options (e.g., jump hosts, custom ciphers). Overrides defaults; re-add safety flags if needed.
• -J <jobs>: parallelism degree; defaults to nproc.

Quick Examples

Run a health check:

./ssher run -i _inv/prod.txt -u root -c 'uptime && df -h /'

Audit SSH auth methods:

./ssher ping -i _inv/lan.txt | tee _reports/lan_ping.log

Harden your environment

./ssher script -i _inv/edge.txt -u ops -l scripts/hardening.sh -J 8

Collect configuration files:

./ssher collect -i _inv/prod.txt -u root -r /etc/ssh/sshd_config -l _reports/sshd_config.collect

Push updates generated by collect:

./ssher update -i _inv/prod.txt -u root -r /etc/ssh/sshd_config -l _reports/sshd_config.collect -a o

Upload an authorized key (with prompt to overwrite/append):

./ssher upload -i _inv/new_hosts.txt -l ~/.ssh/id_ed25519.pub -r ~/.ssh/authorized_keys

Tips

• Combine with nmap to build inventories quickly:
  nmap -n -Pn -p 22 192.168.1.0/24 -oG - | awk '/open/{print $2}' > _inv/lan.txt
• Use _-prefixed directories (e.g., _inv, _reports) to keep local data out of version control if you mirror the original workflow.
• Review the built-in help for detailed descriptions: ./ssher.