[EPIC] this round of heinzel changes — order, shared files, open decisions

[jpawlowski]

16 open PRs, a little under 5 hours of review in total, split into four rounds. Each round stands on its own: stop after any of them. Start with round 1; it fixes things that go wrong on main today.

• Every PR merges cleanly into main, alone or together with all the others. None touches VERSION or CHANGELOG.
• After each merge, the authors rebase the remaining PRs. You never resolve a conflict.
• Only two fixed sequences: Read the SSH configuration sshd and ssh really use [10m] #29 → Cover SSH certificates and existing SSH CAs [30m after #29] #14 → Check what an SSH CA lets people get [10m after #14] #31, and Treat containers and VMs as servers, and reach a guest through its host [30m ?] #40 → Ask before a guest container or VM is stopped or deleted [15m ? after #40] #41.

Round 1: fixes for today's main (≈ 45 min)

PR	What goes wrong today	Review
#43	A short name like host01 does not resolve with dig, so the blacklist and read-only checks by IP are skipped.	10m
#29	OpenSSH 10.4 prints PermitRootLogin instead of permitrootlogin, so the audits no longer see sshd's settings. Also reads Include files and -f daemons.	10m
#13	The taboo guard lets writes to sshd_config and host keys through on FreeBSD, OPNsense and pfSense, where they live outside /etc/ssh.	5m
#15	heinzel knows no SSH port but 22: such hosts rely on ~/.ssh/config, and a firewall change opens only 22 and can lock heinzel out.	15m
#45	A second host01 in another search domain gets the first one's server memory. Records the FQDN; mails use it as sender.	1m
#47	A .local name answered by both mDNS and an old DNS zone can make the alias check link two different servers or report a migration that never happened.	5m

Round 2: SSH certificates (≈ 40 min)

PR	What it adds	Review
#14	Host and user certificates, expiry, principals, revocation, work across all servers of an existing SSH CA. Contains #29.	30m
#31	Whether an SSH CA hands out certificates too freely (anyone, any principal, root, long lifetimes). Contains #14.	10m

Decision, nothing waits for it: #18 – may heinzel write the four SSH CA directives into its own sshd_config.d file, or does all of sshd_config stay taboo?

Round 3: security and network (≈ 1 h 40 min)

PR	What it adds	Review
#23	A host filtering with plain nftables is reported as "no active firewall"; ports Docker publishes past the host firewall go unnoticed.	30m
#16	heinzel misreads sudo -n and falls back to root SSH where sudo would work; records where accounts and sudo rules come from.	20m
#22	Mesh VPNs (Tailscale, NetBird, …), heinzel's own access path, SSH servers that bypass sshd.	20m
#20	A network profile per host, checked for drift.	30m

Decision in #20: should every first contact run a network check (one SSH call on Linux) and create a network.md per host?

Round 4: new capabilities (≈ 1 h 35 min)

PR	What it adds	Review
#37	Run one task on several servers in one call (bin/heinzel-fanout).	20m
#40	Containers and VMs as servers; reach a guest through its host.	30m
#41	The guard asks before a guest is stopped or deleted. After #40, whose rule it enforces.	15m
#34	Own rules for Proxmox VE, OPNsense, pfSense and Home Assistant OS.	30m

Decisions:

• Treat containers and VMs as servers, and reach a guest through its host [30m ?] #40: should heinzel treat a system container or VM as a server of its own (SSH first, through its host only as a fallback), and take and later remove its own guest snapshots before risky changes?
• Ask before a guest container or VM is stopped or deleted [15m ? after #40] #41: should the guard ask before a guest is stopped, shut down or deleted (and deny where no prompt reaches a human), instead of letting stop and delete through and denying a guest shutdown as a host power-off?
• Give Proxmox VE, OPNsense, pfSense and Home Assistant OS their own rules [30m ?] #34: should heinzel cover Home Assistant OS at all, where SSH usually lands in an add-on container? Otherwise rules/haos.md is dropped.

Afterwards

One small PR adds the links between the new rule files. They are left out for now so that every PR can merge on its own.

Status

• Round 1: Resolve host names the way ssh does [10m] #43, Read the SSH configuration sshd and ssh really use [10m] #29, Guard sshd_config and host keys outside /etc/ssh [5m] #13, Remember a non-standard SSH port per server [15m] #15, Record each server's FQDN so short names stay unambiguous [1m] #45, Tell mDNS answers apart from DNS for .local names [5m] #47
• Round 2: Cover SSH certificates and existing SSH CAs [30m after #29] #14, Check what an SSH CA lets people get [10m after #14] #31
• Round 3: Recognize native nftables and Docker's firewall bypass [30m] #23, Find out where a host's accounts and sudo rules come from [20m] #16, Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22, Record each host's network profile and check it for drift [30m ?] #20
• Round 4: Run one task on several servers in one call [20m] #37, Treat containers and VMs as servers, and reach a guest through its host [30m ?] #40, Ask before a guest container or VM is stopped or deleted [15m ? after #40] #41, Give Proxmox VE, OPNsense, pfSense and Home Assistant OS their own rules [30m ?] #34
• Follow-up with the links

Checked on 2026-09-19: every pair of these PRs merges cleanly, and so do all 16 together in any order; the guard's test suite passes on the result (743 passed, 0 failed). Notes for the PR authors are in a comment below.

An AI agent wrote this text in my name. I know that is problematic.

[jpawlowski]

Coordination notes for PR authors. Not needed for review; the overview is in the issue body above. PR sessions follow these notes when they rebase or add to a shared file.

Rules

• Every PR is based on main. No PR contains another PR's commits, except the chain Read the SSH configuration sshd and ssh really use [10m] #29 → Cover SSH certificates and existing SSH CAs [30m after #29] #14 → Check what an SSH CA lets people get [10m after #14] #31.
• No links to files another open PR introduces. A rule may point only to files that exist on main or in its own PR. Links between topics are listed at the end of these notes and added in one small PR once everything has merged.
• One place per topic in each shared file. Add your own rule file for the content, and in shared files only the entries assigned below. Do not renumber lists or sections; new probe sections are unnumbered. An existing paragraph, list entry or skill description is edited only by its owner.
• Git merges hunks cleanly when at least one unchanged line separates them. The assignments below are chosen so that no two topics touch neighbouring lines.
• VERSION and CHANGELOG belong to the maintainer. No PR edits them.

Who edits what in shared files

CLAUDE.md

• Critical Safety Rules, the absolute-taboo paragraph: Guard sshd_config and host keys outside /etc/ssh [5m] #13 (owner).
• Critical Safety Rules, the "Ask before" bullet: containers (owner).
• SSH Options (after the fresh-login block) and the "Never remove or block SSH port" bullet: Remember a non-standard SSH port per server [15m] #15 (owner).
• No Shortcuts for "Quick" Questions, Server Memory, Network Memory: Record each host's network profile and check it for drift [30m ?] #20 (owner).
• Expected Software, Firewall Awareness for Service Changes: Recognize native nftables and Docker's firewall bypass [30m] #23 (owner).
• New sections, each directly after the section named:
  • SSH User & Language → Read the SSH configuration sshd and ssh really use [10m] #29 (SSH Configuration), then Cover SSH certificates and existing SSH CAs [30m after #29] #14 (SSH Certificates) after it
  • Privilege Escalation → Find out where a host's accounts and sudo rules come from [20m] #16
  • OS Detection (mandatory first step) → appliance rules
  • DNS Aliases → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22
  • Service Class Conflict Check → containers
  • How It Works → Local mode → containers (Via-host mode)
  • Fleet Audit → parallel commands

.claude/skills/heinzel-security/SKILL.md

• Frontmatter description: Cover SSH certificates and existing SSH CAs [30m after #29] #14 (owner).
• references/ssh.md entry: Read the SSH configuration sshd and ssh really use [10m] #29 (owner).
• "Scope and limits": parallel commands adds its bullet directly after the heading, before bullet 1; Cover SSH certificates and existing SSH CAs [30m after #29] #14 owns the FreeBSD bullet.
• New reference entries, each after the entry named: ssh.md → Check what an SSH CA lets people get [10m after #14] #31; firewall.md → Recognize native nftables and Docker's firewall bypass [30m] #23; user-accounts.md → Find out where a host's accounts and sudo rules come from [20m] #16; listening-services.md → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22; kernel-os.md → Record each host's network profile and check it for drift [30m ?] #20; macos-security.md → appliance rules.

.claude/skills/heinzel-housekeeping/SKILL.md

• Frontmatter description and the baseline-linux.md / baseline-macos.md entries: Record each host's network profile and check it for drift [30m ?] #20 (owner).
• New entries after: service-checks.md → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22; unprivileged.md → appliance rules.
• The service-checks.md entry text itself stays as it is.
• "Scope and limits": parallel commands adds its bullet directly after the heading, before bullet 1; Cover SSH certificates and existing SSH CAs [30m after #29] #14 owns the FreeBSD bullet.

.claude/skills/heinzel-fleet-audit/SKILL.md

• Frontmatter description: Record each host's network profile and check it for drift [30m ?] #20 (owner). Workflow step 3: Remember a non-standard SSH port per server [15m] #15 (owner). Workflow steps 1, 2, 6 and 7: parallel commands (owner); its helper paragraph follows step 3's last line, which stays unchanged.
• One sentence each in "Scope and limits": directly after the heading → parallel commands; after bullet 1 → Find out where a host's accounts and sudo rules come from [20m] #16; after bullet 2 → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22; after bullet 3 → containers. "When to use", at its end → appliance rules.

.claude/skills/heinzel-fleet-audit/references/probes.md

• Section 2 (sshd): Read the SSH configuration sshd and ssh really use [10m] #29 (owner of the filters), Cover SSH certificates and existing SSH CAs [30m after #29] #14 adds its rows (chain).
• Section 3 (firewall): Recognize native nftables and Docker's firewall bypass [30m] #23 (owner). The row-key line about the SSH port being open: Remember a non-standard SSH port per server [15m] #15 (owner); Recognize native nftables and Docker's firewall bypass [30m] #23 leaves it and its neighbours untouched.
• New, unnumbered sections, each directly before the heading named, and a marker line in the batched script after the marker named:
  • end of file / after ###reboot### → Find out where a host's accounts and sudo rules come from [20m] #16
  • before "6. Auto-reboot" / after ###time### → Record each host's network profile and check it for drift [30m ?] #20
  • before "5. Time sync" / after ###mta### → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22
• Each new section runs its own root / sudo -n check; there is no shared one.

rules/server-memory.md

• The "Adapt fields to OS" paragraph: Remember a non-standard SSH port per server [15m] #15 (owner). The example block: appliance rules (owner); Record each server's FQDN so short names stay unambiguous [1m] #45 adds one line - FQDN: directly after - IP:, the appliance rules' lines go after - Distro family:.
• New paragraphs, each after the paragraph named: first paragraph → Find out where a host's accounts and sudo rules come from [20m] #16; "Update memory immediately" → containers; "Update Last connected:" → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22; end of file → Record each host's network profile and check it for drift [30m ?] #20.

rules/first-connection.md

• Step 4: Remember a non-standard SSH port per server [15m] #15 (owner). Step 7: Record each host's network profile and check it for drift [30m ?] #20 (owner; no new step, no renumbering).
• New sections: after "Local mode" → containers; end of file → Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22.

rules/dns-aliases.md and rules/access-control.md

• Detection step 1 and the IP Verification section: Resolve host names the way ssh does [10m] #43 (owner). All of rules/access-control.md: Resolve host names the way ssh does [10m] #43.
• Detection step 2: Remember a non-standard SSH port per server [15m] #15 (owner). The blank line between steps 1 and 2 stays untouched.
• Detection step 4 ("No match -> new server"): Record each server's FQDN so short names stay unambiguous [1m] #45 (owner), including where hostname -f is read. A new section directly before "Removing an Alias": Record each server's FQDN so short names stay unambiguous [1m] #45 (short names matching more than one FQDN).
• mDNS (Tell mDNS answers apart from DNS for .local names [5m] #47): the logic goes in its own rules/mdns.md. In rules/dns-aliases.md only one new paragraph directly after the "Canonical name" paragraph in the intro, pointing to it; steps 1 to 4 and IP Verification stay untouched until Resolve host names the way ssh does [10m] #43 and Record each server's FQDN so short names stay unambiguous [1m] #45 have merged.
• rules/os-detection.md and rules/first-connection.md stay untouched by Record each server's FQDN so short names stay unambiguous [1m] #45; their steps are owned by Give Proxmox VE, OPNsense, pfSense and Home Assistant OS their own rules [30m ?] #34, Remember a non-standard SSH port per server [15m] #15 and Record each host's network profile and check it for drift [30m ?] #20.

.claude/skills/heinzel-email/SKILL.md

• Step 6 "From header", the remote-path bullet, and the - From: default in the per-server config block: Record each server's FQDN so short names stay unambiguous [1m] #45 (sender from - FQDN:).

memory/user.md.example

• After "Per-server overrides": Remember a non-standard SSH port per server [15m] #15. After the Preferences block: Cover SSH certificates and existing SSH CAs [30m after #29] #14.

The taboo guard (.claude/hooks/guard-taboos.sh, guard-taboos-test.sh)

• Definitions block and the sshd_config rule: Guard sshd_config and host keys outside /etc/ssh [5m] #13 (owner). Cover SSH certificates and existing SSH CAs [30m after #29] #14's revocation-list rule and certificate exemption sit in their own blocks; its header bullet goes after the interpreter bullet, so "any of the last three" stays as Guard sshd_config and host keys outside /etc/ssh [5m] #13 wrote it.
• Test blocks, each directly before the header named: Guard sshd_config and host keys outside /etc/ssh [5m] #13 where it is; Cover SSH certificates and existing SSH CAs [30m after #29] #14 before "SSH keys reached through their directory"; containers before "same effect through an interpreter"; parallel commands before "fallback path: malformed".
• Guard conflicts are resolved by whichever PR lands later, with the full test matrix green.

heinzel-security → references/report-format.md

• The SSH lines in the example: Cover SSH certificates and existing SSH CAs [30m after #29] #14 (owner).
• Find out where a host's accounts and sudo rules come from [20m] #16: one Issues line after "WARN SSH allows password authentication", three Checks items after "UID 0 accounts".
• Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22: one example line after "Listening services".

Everything else (README, rules/<family>.md, rules/ssh-unreachable.md, skill reference files): edit only the paragraph of your own feature, and add new sections directly before a heading no other topic uses. When in doubt, ask on this issue before pushing.

Topics 7 and 8

• rules/network.md (Record each host's network profile and check it for drift [30m ?] #20): the host's own network. Overlay interfaces are named so they are not taken for the uplink; no agent membership, control server, expiry or SSH servers.
• rules/mesh-vpn.md (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22): the mesh VPN agents, with product details in rules/mesh-vpn-<agent>.md; rules/access-path.md (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22): how heinzel reaches the host.
• Memory: mesh VPN details go in a ## Mesh VPN section of memory/servers/<host>/network.md; memory.md keeps one summary line (- Mesh VPN: … — see network.md) and the Access: line.

Cross-references left out until everything has merged

Added in one follow-up PR after all topics have merged:

• rules/ssh-config.md → rules/mesh-vpn.md: SSH servers built into VPN agents are not sshd (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22).
• rules/ssh-certificates.md → rules/mesh-vpn-pangolin.md: a user CA next to a running newt is Pangolin's (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22).
• rules/ssh-certificates.md → rules/accounts.md: sshd resolves the account before the certificate; accounts without a principals file (Find out where a host's accounts and sudo rules come from [20m] #16).
• rules/accounts-on-demand.md → rules/ssh-ca-issuing.md: who gets a certificate (Find out where a host's accounts and sudo rules come from [20m] #16, Check what an SSH CA lets people get [10m after #14] #31).
• rules/network.md ↔ rules/mesh-vpn.md and rules/access-path.md "Only one way in", both directions (Record each host's network profile and check it for drift [30m ?] #20, Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22).
• rules/mesh-vpn.md, SSH servers in agents → rules/accounts.md: Tailscale and NetBird need existing local accounts (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22, Find out where a host's accounts and sudo rules come from [20m] #16).
• rules/mesh-vpn-pangolin.md → rules/accounts.md: Newt creates accounts and 90-pangolin-* sudo files (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22, Find out where a host's accounts and sudo rules come from [20m] #16).
• rules/mesh-vpn.md, SSH servers in agents → rules/ssh-certificates.md: sshd's CA trust does not apply to agent logins (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22, Cover SSH certificates and existing SSH CAs [30m after #29] #14).
• rules/mesh-vpn-pangolin.md → rules/ssh-certificates.md: with newt running, /etc/ssh/ca.pem is Pangolin's CA (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22, Cover SSH certificates and existing SSH CAs [30m after #29] #14).
• rules/containers.md → heinzel-security → references/firewall-nftables-docker.md: published Docker ports bypass the host firewall (containers, Recognize native nftables and Docker's firewall bypass [30m] #23).
• rules/system-containers.md, "Stopping or deleting one": one sentence that the taboo guard asks the user, and denies where no prompt reaches a human (Treat containers and VMs as servers, and reach a guest through its host [30m ?] #40, Ask before a guest container or VM is stopped or deleted [15m ? after #40] #41).
• rules/ssh-port.md → rules/ssh-config.md: the Firewall section's sshd -T | grep -i '^port ' points to sshd -G without root and to the other config files (Remember a non-standard SSH port per server [15m] #15, Read the SSH configuration sshd and ssh really use [10m] #29).
• rules/deployment.md → rules/accounts.md: which password field a key-only account needs (Find out where a host's accounts and sudo rules come from [20m] #16).
• heinzel-security → references/ssh.md, SSH client on the server → rules/mesh-vpn-netbird.md, NetBird SSH: NetBird's 99-netbird.conf Match block with StrictHostKeyChecking no is not the "any host key accepted" finding (Cover mesh VPNs, heinzel's access path and the SSH servers VPN agents bring [20m] #22).

Clean-ups in the same follow-up:

• heinzel-fleet-audit → SKILL.md workflow step 1 and bin/heinzel-fanout: connect by - FQDN: when memory has it, else by the directory name (Run one task on several servers in one call [20m] #37, Record each server's FQDN so short names stay unambiguous [1m] #45). The change sits in bin/heinzel-fanout and rules/multi-host.md; the skill text follows. references/output-format.md and the hostname -f row in probes.md stay. No separate PR before then.
• rules/dns-aliases.md, Detection step 1 and IP Verification: record which source resolved the name and hand a DNS/mDNS mismatch to rules/mdns.md instead of treating it as an alias (Resolve host names the way ssh does [10m] #43, Tell mDNS answers apart from DNS for .local names [5m] #47).
• rules/network.md: note avahi-daemon or mDNSResponder running on the server, pointing to rules/mdns.md (Record each host's network profile and check it for drift [30m ?] #20, Tell mDNS answers apart from DNS for .local names [5m] #47).
• rules/network.md, PTR check: also compare the PTR name with the stored - FQDN:; on a host with an MTA, a mismatch counts like a PTR without forward confirmation (Record each host's network profile and check it for drift [30m ?] #20, Record each server's FQDN so short names stay unambiguous [1m] #45).
• guard-taboos.sh: fold Cover SSH certificates and existing SSH CAs [30m after #29] #14's second KEYPRIV assignment into its definition; it sits apart only to stay clear of Guard sshd_config and host keys outside /etc/ssh [5m] #13's lines.

Each PR that drops a link to keep this list adds its line here.

An AI agent wrote this text in my name. I know that is problematic.