Guard: watch logs, ban misbehaving addresses in Housecarl

Files and the journal, patterns with one <IP>, bounties within a window,
bans in a Housecarl ban list with repeat offenders' bans growing; presets
for sshd, jarl, housecarl, steward, bind-xfr, postfix-sasl, dovecot,
nginx-auth and housecarl-drops; guard run/check/test/status/bans/ban/unban;
a Debian package with a sandboxed unit; an end-to-end test with Housecarl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/install.md

@@ -0,0 +1,72 @@
+# Installing Guard
+
+Guard runs on any Linux machine whose logs it should watch: a web server
+behind the firewall, a mail server, the firewall itself. It needs
+Housecarl 0.2 or later (ban lists) on the firewall, reachable from the
+machine.
+
+## 1. A ban list and a token, in Housecarl
+
+On the firewall, make a ban list for this machine, and a user with a
+token that may ban into it and nothing else:
+
+```sh
+hc banlist add web --scope hosts --host 10.0.10.57 --host 2001:db8:10::57
+hc user add guard-web --no-password --grant bans:write:web
+sudo hc token create web --user guard-web
+```
+
+The scope says what a banned address is kept from:
+
+* `hosts`: this machine (its addresses), the usual choice for a server
+  behind the firewall. Port forwards to it are covered too.
+* `firewall`: the firewall itself, for Guard running on the firewall.
+* `everything`: the firewall and everything behind it.
+
+A watch that reads Housecarl's own log (`housecarl-drops`) also needs
+`--grant log:read`.
+
+## 2. The package
+
+```sh
+sudo apt install ./guard_0.1.0_amd64.deb
+```
+
+It makes the `guard` user (in the `adm` and `systemd-journal` groups,
+to read logs), installs `guard.service` without starting it, and writes
+an example `/etc/guard/guard.yaml`.
+
+From source instead (Go 1.27): `make && sudo make install`, then
+`sudo systemd-sysusers guard.conf && sudo chgrp guard /etc/guard
+/etc/guard/guard.yaml && sudo systemctl daemon-reload`.
+
+## 3. The configuration
+
+Put the token in `/etc/guard/token`:
+
+```sh
+sudo install -m 0640 -g guard /dev/stdin /etc/guard/token <<< 'housecarl_…'
+```
+
+and edit `/etc/guard/guard.yaml`: Housecarl's URL, the ban list, and the
+watches ([configuration.md](configuration.md)). Then:
+
+```sh
+sudo -u guard guard check                  # the file, the patterns, Housecarl
+sudo -u guard guard test ssh               # what the ssh watch finds in the journal
+sudo systemctl enable --now guard
+guard status                               # as root
+```
+
+On the firewall itself, use Housecarl's local socket instead of the URL
+(`housecarl.socket: /run/housecarl/housecarl.sock`), and give the guard
+user access to it: `SupplementaryGroups=adm systemd-journal housecarl`
+in `systemctl edit guard`. A token is still needed: Housecarl trusts
+only root and its own user on the socket without one.
+
+## fail2ban instead
+
+If you already run fail2ban, Housecarl ships an action for it that bans
+into a ban list the same way (Housecarl's docs/bans.md). Guard and
+fail2ban can also run side by side, on different machines or watching
+different logs.