hostwatch

Continuous host monitoring — availability, TLS expiry, DNS changes

v1.0.2

Linux

Quick Start

Install via jcli (recommended)

jcli install hostwatch

One-shot check

hostwatch --target example.com                       # single host
hostwatch --file hosts.txt                            # newline-delimited list
hostwatch --target example.com --output json         # for downstream alerting

What it does

hostwatch is a host-monitoring CLI. Feed it one host (or a file of them) and it runs every selected check against each, persisting a snapshot for diff-on-next-run. Designed for the "I want to know if anything important changed since I last looked" use case — run nightly from cron, get notified on real change instead of every alert from every module on every run.

Two-level concurrent fan-out. Outer concurrency across hosts (capped at --concurrency), inner across modules (futures::future::join_all). Total wall-clock scales like max(per-module-timeout, hosts × modules / concurrency).
State persistence. Snapshots live at ${HOSTWATCH_HOME:-~/.hostwatch}/state.json with mode 0600. Each module persists only the bits it cares about; the orchestrator merges fragments into the next-run snapshot.
First-run is the baseline. An empty previous snapshot means "this is what's normal" — no dns_change findings on first run, just the current state. Diffs fire from run two onwards.
Severity-gated exit codes. Steady-state pure-Info findings (status=200, A-records unchanged) don't trip exit 1. Use the exit code directly for cron-driven alerting: 0 = nothing changed, 1 = at least one change.

Modules

Module	Status	What it does
`availability`	working	HTTP HEAD via reqwest+rustls-tls. Status + response time, slow-response warning above `--slow-threshold` (default 2000 ms). status_changed → Medium on diff
`dns_change`	working	hickory-resolver A lookup. dns_change.added / dns_change.removed → Medium when the resolved set differs from the persisted snapshot
`tls_expiry`	stub	tokio-rustls peer cert chain. < 30 days → warn, < 7 days → critical
`tls_change`	stub	SHA-256 of the leaf cert; diff vs persisted snapshot
`redirect`	stub	HTTP → HTTPS redirect chain check

CLI

Flag	What it does
`-t, --target <HOST>`	Single host
`-f, --file <PATH>`	File of hosts (newline-delimited)
`-M, --modules <LIST>`	Comma-separated module subset
`--concurrency <N>`	Outer fan-out cap (default 16)
`--timeout <SECS>`	Per-check timeout
`--slow-threshold <MS>`	HTTP response time above which to warn (default 2000)
`-o, --output <FMT>`	terminal / json / csv / markdown
`--watch`	stub — continuous mode with `--interval` would loop
`--webhook <URL>`	stub — POST alerts on change

On-disk layout

~/.hostwatch/state.json    # per-host snapshot, chmod 600

The HOSTWATCH_HOME env var overrides the default — tests sandbox it with a tempdir; the live deploy reads from the operator's home.