hostwatch

Continuous host monitoring — availability, TLS expiry, DNS changes

v1.0.3

NixOS x86_64

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.

Compliance crosswalk

This table lists controls where hostwatch's output may form part of the evidence set presented to an assessor. It does not claim hostwatch alone satisfies any framework — every control still requires assessor judgment and typically evidence from other sources.

Schema: compliance-crosswalk/v1 · Machine-readable: tools/hostwatch/compliance.json

ISO27001 — ISO/IEC 27001:2022

Ref	Name	How	Coverage
`A.8.15`	Logging	Continuous availability + response-time logs.	supports
`A.8.16`	Monitoring activities	Long-running monitoring of external asset availability.	evidences

NIS2 — NIS2 Directive (Dir. 2022/2555)

Ref	Name	How	Coverage
`Art. 21 §2(b)`	Incident handling	Availability drops trigger jfind findings usable in an incident workflow.	supports

Release artefacts & provenance

Every signed release ships with checksum + signature sidecars plus a CycloneDX SBOM. Enterprise procurement can pin third-party components without unpacking the binary.

manifest.json — pinned SHA-256 + .sig URL + SBOM URL per platform
johlem-release.pub — Ed25519 public key used by signify -V (fingerprint: 4532510f…6748, pinned in jcli verify)
CHANGELOG.md — semver-tagged release notes
Security contact: security@johlem.net