ssh-host-snapshot

Files (1)

• SKILL.md

SKILL.md (first lines)

# SSH Host Snapshot

A reproducible "this is what the host looked like at time T" capture.
The artifact is a directory of plain-text/JSON files plus a bundled
tar.gz + sha256, written either on the target host or pulled off-box.

The point is not the snapshot itself -- it is the **diff against the
next one**. A snapshot you never compare to anything is wasted I/O.
Take one whenever a future-you might ask "what changed since then?":

- Before an OS upgrade (`do-release-upgrade`, distro hop).
- Before a major Docker / compose stack rewrite.
- After an incident, to freeze the surviving state for forensics.
- On a quarterly cadence as a baseline for drift detection.
- Before handing a box off to another operator.

Not in scope: file-content backup (that's bareos / restic), security
drift on pinned binaries (that's
[ssh-integrity-audit](../ssh-integrity-audit/SKILL.md)), live metrics
(that's [ssh-host-healthcheck](../ssh-host-healthcheck/SKILL.md)).

## Default-on cheatsheet rejection (since v1.9.0)

`ssh_exec_run` refuses commands that have a native MCP tool -- see
`skills/ssh-exec-run/SKILL.md`. The native-tool flow below avoids
that. Composite scripts (where the script IS the artefact) opt out
via `SSH_EXEC_ALLOW_CHEATSHEET_PATTERNS=true` at the operator level.

Section 2a's exec-tier capture script IS such a composite artefact:
the umask+mkdir+dpkg+systemctl+tar+sha256 sequence MUST run
atomically under a single audit correlation id to be a meaningful
point-in-time snapshot. Running it as N separate native-tool calls
would produce a snapshot smeared across N audit records and would
race against host state. The composite is intentional; the opt-out
env var is the gate.

## Sequence

1. Decide label + destination
2. Capture the inventory
3. Bundle + checksum
4. Pull off-box + verify hash
5. Diff (later, when a question arises)

Steps 1-4 are one workflow -- a snapshot that stays only on the host
it was taken from is half-done. The on-host copy can be lost to the
same event the snapshot was meant to survive (disk failure, the
upgrade that breaks the box, the incident under investigation).
Always finish through step 4.

## 1. Decide label + destination

A snapshot needs a stable name so two captures of the same host are
comparable. Convention:

```text
/root/snapshots/<host>-<label>-<UTC-timestamp>/
                                ^ YYYYMMDD-HHMMSS
```

`<label>` is free-form but short and meaningful: `baseline`,
`pre-jammy-to-noble`, `pre-compose-rewrite`, `post-incident-2026-05-22`.
Don't bake the trigger reason into the label too tightly -- "snapshot
before the thing" is the same artifact regardless of which "thing"
came next.

Default storage path on the target is `/root/snapshots/`. That copy is
the *working set* -- it survives reboots and is what you compare
against on the same host. The **canonical copy lives off-box**: every
snapshot run ends with Section 4 pulling the bundle + sha256 to the
operator side. The on-host copy stays around for convenience until
retention rotates it.

## 2. Capture the inventory

There is no single MCP tool that "produces a snapshot". Two paths:

### 2a. Exec-tier path (preferred, comprehensive)

One scripted `ssh_exec_run` writes every artifact into the snapshot
directory. Requires the target to allow `ssh_exec_run` in its policy
tier AND `SSH_EXEC_ALLOW_CHEATSHEET_PATTERNS=true` on the server --
the script triggers multiple cheatsheet patterns (heredoc for
`SECRETS_WARNING.txt`, `mkdir`, `dpkg`/`systemctl`/`tar`
redirections) but is the versioned snapshot artefact and must run
atomically under one audit record. Skeleton -- adapt the package /
service manager calls to the target distro:

```python
ssh_exec_run(host="iruelg4", timeout=300, command="""
umask 077  # artifacts contain secrets; mode 0600 from creation
SNAP=/root/snapshots/$(hostname -s)-baseline-$(date -u +%Y%m%d-%H%M%S)-SECRETS
mkdir -p "$SNAP" && cd "$SNAP" || exit 1

# Marker the operator cannot miss
cat > SECRETS_WARNING.txt <<'EOF'
This snapshot contains sensitive credentials including but not limited to:
  - /etc/shadow (password hashes -- offline-crackable)
  - /etc/ssh/ssh_host_*_key (plaintext SSH host private keys)
  - /etc/ssl/private/*, /etc/letsencrypt/{archive,keys,live}/ (plaintext TLS keys)
  - app-specific keys under /etc (bareos, fail2ban, wireguard, ...)

Treat this archive like a credential file:
  - keep mode 0600 / dir 0700 throughout its lifecycle
  - do NOT commit to git, paste into chat, upload to pastebins, share via Slack
  - off-box copies belong in a vault (1Password, age/gpg-encrypted, hardware token)
  - delete from operator workstations once the diff / restore is done
EOF

# 00. Identity
{ echo "Host: $(hostname -f)"; date -u --iso-8601=seconds; } > 00-README.txt
uname -a > 01-uname.txt
cp /etc/os-release 02-os-release
uptime > 03-uptime.txt

# 10. Packages (Debian/Ubuntu)
dpkg-query -W -f='${binary:Package}\t${Version}\t${Architecture}\t${Status}\n' | sort > 10-packages-all.tsv
apt-mark showmanual | sort > 11-packages-manual.txt
apt-mark showhold   | sort > 12-packages-hold.txt

From Nightreaver/python-ssh-mcp, GPL-3.0.

More from Nightreaver/python-ssh-mcp