winadmin

README

winadmin / fleet

A parallel fleet-automation tool for sysadmins — inspired by the classic overnight fleet-runners of the WinBatch / SMS 2003 era, rebuilt in Go. Point it at a list of machines and a task; it fans out across them with a bounded worker pool, a dry-run, staged rollouts, a live TUI, and a structured audit trail.

It started as a translation exercise — porting the "common things" out of a turn-of-the- millennium WinBatch desktop-automation codebase (registry edits, AD/NT group gating, run-as-with-password) into idiomatic Go. It grew into a real tool. The original overnight "run this batch file against 350 backup DCs" job — now with brakes and a paper trail.

^{A staged rollout (canary → waves) running across a real 10-machine fleet over SSH — live, in the terminal.}

📖 Start with the WinBatch → Go primer for the origin story.

---

Quick start

go install ./cmd/fleet        # puts `fleet` on your PATH
# (or: go build -o bin/fleet ./cmd/fleet  — note: -o fleet collides with the fleet/ pkg dir)

fleet tui                       # the fastest way to see it: the interactive TUI
fleet run -L hosts.txt -P 15 -c "uptime"   # or straight from flags

hosts.txt is one machine per line (#/; comments ok) — or skip the file entirely and let a query define the fleet (see Inventory).

---

What it can do

Verbs

Verb	Does	Example
run	run any command (templated with {{.Name}})	run -c 'ping -n 1 {{.Name}}'
svc	start/stop/restart/status a service	svc --name nginx --action restart --sudo
install	silent install MSI / EXE / script	install --package '\\dist\App.msi' --args ALLUSERS=1
push	copy files to each box	push --src '\\dist\app' --dst 'C$\App' --mirror
reboot	reboot (guarded by --yes)	reboot --backend win --delay 60 --yes
proc	kill a process	proc --image stuck.exe --force
task	manage a scheduled task	task --name Nightly --action run
localgroup	add/remove a local-group member	localgroup --member 'CORP\jdoe'
firewall	add/delete a firewall rule	firewall --name 'Block SMB' --port 445 --fw-action block
regset	set a registry value	regset --hive HKLM --key 'Software\X' --name On --data 1
deldir	delete a directory	deldir --path 'C$\Temp\junk'
ldapset	set an attribute on every user in an AD/LDAP OU	ldapset --base 'OU=Tellers,…' --attr department --value Retail
gather	run a query per box, tabulate it	gather -c 'wmic os get version' --format csv
agent	the pull side: each box fetches + runs its own job	agent --source \\share\job.txt --interval 60s

Transports (--transport)

	Reaches the box via	Use when
local (default)	the command itself — sc \\host, reg \\host, robocopy \\host (RPC/SMB)	classic Windows remote-admin from one control box
ssh	SSH (key / agent / password)	cross-platform; Linux, or Windows OpenSSH
winrm	WS-Man / PowerShell Remoting	the native Windows path, no SSH needed
psexec	SysInternals PsExec over SMB	boxes with neither SSH nor WinRM
wmi	wmic /node: (fire-and-forget)	kicking off work where you don't need output

Inventory

The fleet is whatever you point it at — a static file or a live query:

-L hosts.txt                                   # a file
--inventory-cmd 'aws ec2 describe-... | ...'   # any command's stdout (one target per line)
--inventory aws:'Name=tag:env,Values=prod'     # plugin: cloud query
--inventory ad-ou:'OU=Tellers,DC=corp,DC=com'  # plugin: every user in an OU (uses LDAP_* env)
--inventory ad-group:'CN=Admins,…'             # plugin: every member of a group

Safety — what makes it good, not just powerful

• --what-if — render every command without running anything.
• Staged rollout — --canary 1 --wave 25 --health-cmd ./probe.sh: hit one box, health-check, then let it ripple in waves; a failed gate aborts and skips the rest.
• --retries / --retry-backoff, --timeout, --stop-on-error.
• Confirm-on-blast — destructive verbs refuse >1 target without --yes.
• --export results.json|.csv — the artifact you staple to the change ticket.
• A structured slog audit trail on stderr — who/target/command/result/duration.

---

The TUI

fleet tui                              # interactive run builder → live dashboard
fleet run -L hosts.txt -c '…' --tui    # any verb + --tui jumps straight to the dashboard
fleet gather -L hosts.txt -c '…' --tui # a filterable results table

The run builder speaks every verb (fields change with the task — here, svc, with type-ahead over Windows service short/display names), plus transport and staged-rollout options. ctrl+o browses for the target list; ctrl+g launches.

It hands off to a live "btop-style" dashboard (the hero shot above) — per-target spinners, a progress bar, running→fail→queued→done ordering, canary/wave markers, and ok/fail/skip counts. And gather --tui turns the fleet into a filterable report:

---

The library

fleet is a thin CLI over reusable packages — build your own admin tools on these:

Package	Does
fleet	the engine: inventory (+plugins), bounded worker pool, staged rollout, transports, verb tasks, agent pull-model, slog audit
secret	CredentialProvider interface — plaintext / env / DPAPI / Windows Credential Manager. Secure by default; plaintext must be asked for by name
reg	WOW64-aware registry read/write
groups	group membership — current-user via the access token (no DC round-trip), arbitrary user via LDAP
runas	run a command as another user (CreateProcessWithLogonW)

---

Proven, not just compiled

Every feature gets a live-fire pass against throwaway cloud/container labs, not just unit tests — that's how the SSH-auth, --ssh-port, -v, and dynamic-inventory gaps were caught:

• SSH / LDAP — 10× EC2 over real internet SSH; an AD attribute set across an OU (OpenLDAP).
• Verbs + staged rollout — 6× EC2, healthy canary→waves and a health-gate abort.
• Windows transports — Server 2022 EC2: WinRM doing real registry read/write + service restart, WMI, PsExec — all driven from Linux.

Full backlog status: ROADMAP.md.

Build & CI

Builds, vets, and tests on macOS/Linux and cross-compiles clean to windows/amd64. The Win32-backed code (reg, runas, groups, registry) is behind //go:build windows with non-Windows stubs. CI runs gofmt / vet / test / govulncheck on every push, executes the Windows-tagged tests on a windows-latest runner, and on tag cuts cross-platform release binaries with a CycloneDX SBOM, SHA256SUMS, a keyless cosign signature, and SLSA build provenance.

License

MIT — see LICENSE.