diff --git a/README.md b/README.md index 6c957027..982df8d0 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ documents for different readers. the Makefile, the scripts, the workflow and the runbooks resolves its image from `compose.yaml` too, so an image that is not pinned there cannot be run at all. -- **Documented decisions and runbooks.** 34 ADRs covering what was chosen +- **Documented decisions and runbooks.** 35 ADRs covering what was chosen and what was rejected — including the costs accepted knowingly; 20 runbooks for the operations that are easy to get wrong at 1am, one of which is the handover page a successor reads first. @@ -184,15 +184,16 @@ Full topology and data flow in [`docs/architecture.md`](docs/architecture.md). ├── stacks/lab/ # the lab's own stack — four services, not yet deployed │ # runs on a guest on Saruman, never remote-writes │ # to VLAN 99. See its README and ADR-0020 -├── stacks/sensitive/ # the household's tier — Caddy and step-ca so far, -│ # authored for a host not yet built (ADR-0034, #404) +├── stacks/sensitive/ # the household's tier — Caddy, step-ca and Home +│ # Assistant so far, authored for a host not yet +│ # built (ADR-0034, #404) ├── secrets/ # SOPS-encrypted; see secrets/README.md ├── scripts/ # bootstrap, render, validate, pin-digests, purge ├── SECURITY.md # disclosure policy and known exposure ├── docs/ │ ├── architecture.md network.md hardware.md │ ├── observability.md security.md roadmap.md -│ ├── adr/ # 23 architecture decision records +│ ├── adr/ # 35 architecture decision records │ └── runbooks/ # successor handover (start here), deploy, converge, │ # add device, rotate creds, certs, key backup, │ # purge, restore the firewall, restore the stack, diff --git a/docs/adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md b/docs/adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md new file mode 100644 index 00000000..be013e6a --- /dev/null +++ b/docs/adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md @@ -0,0 +1,184 @@ +# ADR-0035: Scope the 99 → 20 rule to the Hue bridge + +**Status:** Accepted · 2026-09 + +## Context + +[ADR-0008](0008-place-services-by-data-trust.md) put Home Assistant on +Winterfell (99) rather than among the devices it controls — it holds their +credentials, and Skids (20) is the segment whose stated assumption is that +everything on it is already compromised — and added one row to pay for the +placement: `99 → 20`, *"Home Assistant reaching IoT devices"*. A direction and +a purpose; not a source, a destination or a port. +[#134](https://github.com/Gerrrt/HomeLab/issues/134) asks that the rule be +written down before it is created and *"scoped as tightly as the devices +actually require rather than opening the segment wholesale"*, and `roadmap.md` +names the part the firewall cannot answer: **how wide**. The source did not +exist when it was written. The destination is the whole segment unless the +devices have addresses that hold. + +Three things were read before deciding, in the order +[ADR-0013](0013-segment-access-as-implemented.md) established: the ruleset, +the inventory, and the code that would use the rule. + +### The ruleset, on `morpheus`, 2026-09-09 + +Winterfell's interface blocks every other VLAN explicitly above its egress +pass — *Block access to Skids* among them, `inet` and `inet6` — and above that +stack sit the three passes ADR-0013 lists for `10.0.99.20`: SNMP to the iLO, +SNMP and HTTP to the switch. So the rule is the fourth insertion above a deny +that has been there since the segments were, beside the SNMP passes, exactly +where `roadmap.md` said it would go. Appended at the bottom of the tab it +would match nothing, which is the fault ADR-0013 found in *Allow Hicks access +to ImaginationLAN*. + +Skids as a source is untouched by anything here: it blocks the five other +VLANs, carries [#223](https://github.com/Gerrrt/HomeLab/issues/223)'s tripwire, +then egresses. The return half of a session Home Assistant opens is carried by +state and never reaches that ruleset. + +**Skids has no DHCP reservations.** None — against three on Winterfell — and +its pool is `10.0.20.100–200`, which contains every address `network.md` +lists for the segment. The Hue bridge is at `.104` by lease, not by +reservation. A host-scoped pass to a leased address is a rule that stops +matching the day the lease moves, silently, with nothing to say why the lights +stopped answering. + +### The inventory: what on Skids has a local API + +`network.md` lists the segment. Read for what Home Assistant would actually +open a connection *to*, from 99: + +| Device | How Home Assistant reaches it | Needs the rule | +| --- | --- | --- | +| `bifrost`, the Philips Hue bridge | Its local API, over HTTPS — the bridge is the radio, the bulbs are Zigbee behind it | **Yes** | +| Ring cameras, floodlights, doorbell, alarm hub | Ring's cloud. No local stream, no local API — the fact [ADR-0032](0032-decline-frigate-while-the-cameras-are-ring.md) turned on | No | +| Amazon Echo ×5 | Amazon's cloud, if at all | No | +| Apple HomePod ×4 | HomeKit over mDNS, which does not cross a VLAN; and a HomePod is a controller, not an accessory | No | +| Litter-Robot 4 | Its vendor's cloud | No | +| Tuya white-noise machine | Tuya's cloud | No | +| VTech baby monitors | Nothing — they are not integrated | No | +| eero ×3 | Nothing — [ADR-0019](0019-read-device-joins-from-the-dhcp-server.md) declined the cloud integration | No | + +One device. The phrase ADR-0008 used — *"credentials to the locks and +cameras"* — describes a house this is not: there are no locks, and the cameras +are reached through a vendor rather than across a VLAN. What the rule is for, +on this inventory, is one bridge. + +### The code: which ports the Hue integration opens + +Read from `aiohue` and Home Assistant's `hue` config flow on 2026-09-09, not +from the Hue documentation: + +- Adding the bridge by address runs `discover_bridge`, which probes + `http:///api/config` — **port 80** — to confirm it is a Hue bridge and + then `https:///clip/v2/resource` to confirm it speaks v2. +- Pressing the link button runs `create_app_key`, which tries HTTPS first. +- Every request after that, and the event stream the integration lives on, is + `https:///` — **port 443**. + +So the pairing needs 80 once and the running integration needs 443 always. +The integration's other way of finding a bridge, `discover_nupnp`, asks +`discovery.meethue.com` over the WAN and would return this bridge's address — +a path 99 already has, and one this decision does not depend on. + +## Decision + +**One pass, host to host, on two ports, above the deny — created after the +destination holds still.** + +| On interface | Rule | Position | Purpose | +| --- | --- | --- | --- | +| 99 | `10.0.99.40 → 10.0.20.104:80,443/tcp` | **above** *Block access to Skids*, beside the SNMP passes | `trinity`'s Home Assistant to `bifrost`, the Hue bridge | + +1. **Source is `trinity`, not Winterfell.** `10.0.99.40` is the address + [#404](https://github.com/Gerrrt/HomeLab/issues/404) reserved for the tier's + host. `prometheus` and `oracle` gain nothing from this rule and get nothing. +2. **Destination is the bridge, not the segment.** Every other device on Skids + is reached through a cloud or not at all, so a segment-wide pass would + grant access to nineteen devices for the benefit of one. A second device + with a local API is a second row in this table, argued on its own, not a + widening of this one. The direction ADR-0008 cares about is preserved in + both halves: management initiates into IoT, and nothing on IoT can initiate + anywhere. +3. **Ports are the two the code uses.** 80 for the identification probe the + config flow runs at pairing, 443 for everything else. Not `any`: the bridge + also listens for SSDP and mDNS, and neither is wanted from a segment away. +4. **`bifrost` gets a Kea reservation first.** At `10.0.20.104`, where it is — + an in-pool reservation holds under Kea, as the `Saruman` note in + `network.md` records, and keeping the address means no document changes. + The reservation is the first Skids will have, and it is what turns the + destination above from a guess into a fact. The bridge's MAC is already in + the inventory, truncated; the reservation carries the full one on the + firewall, where every other reservation's already is. +5. **The rule is not created by this ADR.** Its source does not exist yet. + #404 builds `trinity`; the pass is created in the same sitting as the + reservation, once there is a host to test it from, and `network.md`'s + Winterfell and Skids notes carry the rule as decided until then and as + enforced after. `security.md`'s sentence that IoT *"gets internet and + nothing more"* is about what Skids initiates, stays true, and is left + alone — the same treatment [ADR-0016](0016-open-casabonita-inward-and-keep-it-terminal-outward.md) + gave CasaBonita's. + +**Discovery is not a reason to network the container differently.** Home +Assistant's compose example upstream is `network_mode: host`, for mDNS and +SSDP. Both are link-local; the bridge is a VLAN away; nothing on 20 would be +discovered from 99 however the container were attached. So Home Assistant is +an ordinary member of the tier's bridge network behind Caddy, the bridge is +added by address, and ADR-0008's containment sentence — *"only the reverse +proxy publishing a port"* — stays a property of `compose.yaml`. + +### The credentials stay where Home Assistant puts them + +The estate's rule is that a credential lives in `secrets/*.sops.yaml` and +nowhere else, rendered at deploy time. Home Assistant cannot be made to obey +it, and this is the service that accumulates more credentials than anything +else on the tier: the Hue application key, the Ring account token, and +everything else a config flow produces are written by Home Assistant into +`/config/.storage/`, and no environment variable or rendered file is a way in. +Rather than a rendered `secrets.yaml` that nothing reads, the deviation is +recorded: **those credentials live in the application's own store, in the +`home-assistant-config` volume, protected by the disk-encryption decision #404 +makes and by the volume backup, not by SOPS.** What *can* be held the estate's +way is: a long-lived access token minted for another service belongs in that +service's SOPS file, and the first YAML-configured integration that needs a +credential is the day `/config/secrets.yaml` is rendered from SOPS the way +Alertmanager's URL files are. + +## Consequences + +- **Skids stops being terminal inbound, for one host on two ports, and stays + terminal outbound.** The same trade ADR-0016 made for CasaBonita, with the + same test: #223's tripwire counter on the Skids interface, zero today, must + not move after the rule lands. `network.md`'s *Reaches* column for Skids is + unchanged, and Winterfell's gains "named ports on 20" on the day the rule + exists. +- **The bridge's address is now load-bearing.** `network.md`'s `bifrost` row + is what the rule is written from, and the reservation is what keeps the row + true. That is a stronger coupling than the segment has had, and it is the + price of a host-scoped rule; the alternative was a segment-scoped one. +- **The rule is per device, and that is what keeps it small.** ADR-0032 already + refused continuous RTSP through this row; this ADR refuses a second + destination through it. A Zigbee coordinator, an MQTT broker, a locally + reachable lock: each is a row of its own, each above the same block, and the + table above is where they go. +- **A hardware answer falls out.** No device needs a USB radio, so `trinity`'s + placement is unconstrained by Home Assistant — the question + [ADR-0034](0034-run-the-sensitive-tier-on-the-prodesk-and-make-it-the-spare-hardware.md) + left to #404, answered for this service's part. +- **Nothing depends on the eero or on Ring being reachable locally.** Ring's + integration is cloud-side; the tier being down takes the automations with it + and leaves the Ring app working, which is the property + [ADR-0023](0023-keep-the-household-recovery-path-outside-the-estate.md) + requires — nothing physical may be operable only through Home Assistant. +- **The credential store is a second class of secret on the tier.** SOPS holds + what the stack takes from outside; Home Assistant holds what it obtained + itself. The volume archive therefore carries live credentials and has to be + treated as `grafana-data` already is — encrypted at rest, never tracked, and + `security.md` names it beside the age key as something an unencrypted disk + exposes. +- **Reopened by:** a device on Skids that serves a local API and is wanted in + Home Assistant, which adds a row; the cameras being replaced with ones that + do, which is ADR-0032's reopen condition and not this one's; or Home + Assistant gaining a way to take config-flow credentials from a file, which + would retire the deviation above. diff --git a/docs/network.md b/docs/network.md index d7409d0d..3757d80c 100644 --- a/docs/network.md +++ b/docs/network.md @@ -152,6 +152,20 @@ listed under [Hicks](#hicks--vlan-50--trusted), and nothing else. - pfSense's admin UI is reachable on this interface from Hicks only, by a named pass to `10.0.99.1:443`. Winterfell itself is blocked from it: the 99 interface drops HTTP and HTTPS to `10.0.99.1` above its egress rule. +- **One pass into Skids is decided and not yet created:** + `10.0.99.40 → 10.0.20.104` on `80,443/tcp` — `trinity`'s Home Assistant to + `bifrost`, the Hue bridge, and nothing else on 20 — inserted **above** + *Block access to Skids*, beside the two SNMP passes that already sit above + that block. Read on 2026-09-09: every other device on Skids is reached + through a vendor's cloud or not at all, so the segment-wide row ADR-0008 + wrote as `99 → 20` narrows to one host on two ports, and a second device + with a local API is a second row rather than a wider one. + [ADR-0035](adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md) records + the reading and the reasons. It is created under + [#404](https://github.com/Gerrrt/HomeLab/issues/404), in the same sitting as + the reservation that pins `bifrost` — Skids has none today — and once there + is a `trinity` to test it from. The *Reaches* column above gains "named + ports on 20" that day, not before. - DHCP enabled, with static reservations for everything listed. - `oracle` runs the Lemmiwinks wiki and its Postgres — it has since 2025-11-12, and [ADR-0011](adr/0011-keep-the-wiki-internal.md) depends on it — and holds @@ -387,6 +401,23 @@ the least trusted. - Internet only. No device here can initiate a connection to any other segment, which is the entire reason this VLAN exists. A camera or a $20 Tuya device with a hardcoded credential is a foothold, not a light switch. +- **Inbound, one exception is decided and not yet in force.** `trinity`'s Home + Assistant reaches `bifrost` on `80,443/tcp` — the Hue bridge's local API, + the only one on this segment; everything else here is reached through its + vendor's cloud or not at all + ([ADR-0035](adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md)). The + rule sits on Winterfell's interface, so nothing here changes: the blocks + above, the [#223](https://github.com/Gerrrt/HomeLab/issues/223) tripwire and + the egress rule stay as they are, and the tripwire's counter — zero — is + the test that the return traffic rides state and never reaches them. Skids + stays terminal outbound; the day the rule lands it is no longer terminal + inbound, for one host on two ports. +- **No address here is reserved.** The pool is `.100–.200` and every device + above sits inside it by lease, so a row in this table is what a device had + when it was read, not what it will have. That is fine for a segment nothing + initiates into and stops being fine for `bifrost` the day a firewall rule + names it: the reservation is the precondition ADR-0035 puts before the + rule, and the first this segment will carry. - Device addresses and rooms are collapsed above deliberately. The exact camera-to-room mapping is not something a public repository needs to carry. diff --git a/docs/roadmap.md b/docs/roadmap.md index 51f317e6..c4b56f00 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -471,6 +471,24 @@ what left this one unfireable for months. link-local and does not cross a VLAN boundary, so nothing on 20 appears by itself however the pass is written. + **Settled 2026-09-09, and narrower than the row read.** + [ADR-0035](adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md) read the + Skids inventory for what Home Assistant would actually open a connection to + and found one device: the Hue bridge. Ring, the Echos, the HomePods, the + litter robot and the white-noise machine are all reached through a vendor's + cloud or not at all. So the pass is `10.0.99.40 → 10.0.20.104:80,443/tcp` — + the two ports the `aiohue` code uses, 80 once at pairing and 443 after — + above *Block access to Skids*, and it waits on two things: `trinity`, and a + Kea reservation for the bridge, because Skids has none and its pool holds + every address on the segment. **Home Assistant itself is authored** + ([#134](https://github.com/Gerrrt/HomeLab/issues/134)): the Container + flavour, no Supervisor and no add-ons, as an ordinary member of the tier's + network behind Caddy — not `network_mode: host`, which exists for discovery + that cannot cross a VLAN anyway — booted read-only with every capability + dropped against the pinned image before it was committed. Its credentials + are the one place the tier steps outside SOPS, and the ADR says why. No + USB radio, so where the box sits is not this service's concern. + **Two of the three things said to be waiting on this tier are not waiting on it.** [#67](https://github.com/Gerrrt/HomeLab/issues/67)'s watcher went to `oracle` under ADR-0015 and needs no self-hosted ntfy; diff --git a/docs/security.md b/docs/security.md index cee7767a..a20a6822 100644 --- a/docs/security.md +++ b/docs/security.md @@ -208,7 +208,21 @@ it for as long as it was a number. Everything else — IoT, media, guest — gets internet and nothing more. -That last sentence is now checked rather than asserted. Four **tripwire** rules +That sentence is about what those segments *initiate*, and two decisions now +reach into them without touching it. +[ADR-0016](adr/0016-open-casabonita-inward-and-keep-it-terminal-outward.md) +writes three passes into CasaBonita for the NAS, and +[ADR-0035](adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md) one into +Skids — `10.0.99.40 → 10.0.20.104:80,443/tcp`, Home Assistant to the Hue +bridge, the one device on that segment with a local API — above the block +that has stood between 99 and 20 since the segments existed. Neither is +created yet; both wait on the host that would use them. The row ADR-0008 +wrote as `99 → 20` is narrower than it read: one host to one device on two +ports, with the twenty other devices on Skids still unreachable from +anywhere, and the segment still initiating nothing. The tripwire below is the +check that the second half holds when the first lands. + +That sentence is now checked rather than asserted. Four **tripwire** rules sit below the block rules that stop each cross-segment path and above the `→ any` egress rule: three on the terminal interfaces ([#223](https://github.com/Gerrrt/HomeLab/issues/223)), `pass` + `log` for @@ -279,6 +293,18 @@ assumption consistent with what they are. - CI runs `gitleaks` with rules specifically for SNMP communities, inline Grafana passwords, PEM private keys and age secret keys, and separately asserts that every `secrets/*.sops.yaml` is genuinely encrypted. +- **One service on the sensitive tier keeps its credentials outside SOPS, by + necessity and on the record.** Home Assistant obtains device credentials + through its own pairing flows — the Hue application key, the Ring token — + and writes them to its store inside the `home-assistant-config` volume; no + environment variable or rendered file is a way to hand them in. So the rule + above covers what that stack takes from outside, and the tier's most + numerous credentials are protected instead by the disk-encryption decision + [#404](https://github.com/Gerrrt/HomeLab/issues/404) makes and by the + encrypted volume archive — which therefore carries live credentials, as + `grafana-data` already does. + [ADR-0035](adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md) records + the deviation and what would retire it. ### Known historical exposure diff --git a/secrets/sensitive.example.yaml b/secrets/sensitive.example.yaml index ac8bf3be..d76923e5 100644 --- a/secrets/sensitive.example.yaml +++ b/secrets/sensitive.example.yaml @@ -3,13 +3,18 @@ # # ONE KEY, for now. Read the list as a description of the stack: Caddy needs # no credential — its certificate and key are files under certificates/, never -# tracked, handled the way the estate's Grafana leaf is — and step-ca needs -# exactly one, the password that unlocks its intermediate key. Vaultwarden's -# admin token, Immich's database credentials and Home Assistant's device -# credentials arrive here with their services (#131, #132, #134); this file -# grows with the tier and the compose file's `${VAR:?}` guards say what is -# required, so `make render STACK=sensitive` asks for what this stack needs -# and nothing else. +# tracked, handled the way the estate's Grafana leaf is — step-ca needs +# exactly one, the password that unlocks its intermediate key, and Home +# Assistant needs NONE from here, which is not the same as needing none. Its +# device credentials — the Hue application key, the Ring token, everything a +# config flow produces — are written by Home Assistant into its own store in +# the home-assistant-config volume, and no environment variable or rendered +# file could carry them in; compose.yaml and ADR-0035 say what protects them +# instead. Vaultwarden's admin token and Immich's database credentials arrive +# here with their services (#131, #132); this file grows with the tier and the +# compose file's `${VAR:?}` guards say what is required, so +# `make render STACK=sensitive` asks for what this stack needs and nothing +# else. # # --------------------------------------------------------------------------- # Create this ON TRINITY, not on the monitoring host diff --git a/stacks/sensitive/Caddyfile b/stacks/sensitive/Caddyfile index 80f9207d..af17e509 100644 --- a/stacks/sensitive/Caddyfile +++ b/stacks/sensitive/Caddyfile @@ -35,14 +35,25 @@ https:// { respond "ok" 200 } - # Nothing is routed yet. Each service from #131 onward adds a block here: + # One block per service, matched on Host. Each name needs two things + # outside this file: a SAN on the leaf (compose.yaml's `make certs` line) + # and a host override on morpheus pointing it at 10.0.99.40 + # (docs/runbooks/add-a-host-override.md) — a Host the leaf does not carry + # fails the handshake, and a name the resolver does not know never arrives. # - # @vaultwarden host vaultwarden.matrix.elysium - # handle @vaultwarden { - # reverse_proxy vaultwarden:80 - # } + # Home Assistant (#134). Its frontend runs over a websocket, which + # reverse_proxy upgrades without being told; nothing here needs a header + # Caddy does not already set — X-Forwarded-For is what its + # `trusted_proxies` line reads, and Caddy's fixed address is what it trusts. + @homeassistant host homeassistant.matrix.elysium + handle @homeassistant { + reverse_proxy home-assistant:8123 + } + + # Vaultwarden, Immich, Paperless-ngx and the rest (#131–#137) add a block + # of the same shape above this line. What matches nothing lands here. handle { - respond "trinity: the sensitive tier. Nothing is routed here yet." 404 + respond "trinity: the sensitive tier. Nothing is routed under this name." 404 } log { diff --git a/stacks/sensitive/README.md b/stacks/sensitive/README.md index a08063c7..71e05d00 100644 --- a/stacks/sensitive/README.md +++ b/stacks/sensitive/README.md @@ -15,9 +15,11 @@ make up STACK=sensitive | --- | --- | --- | --- | | caddy | `caddy` | 443 (https) | The one published port on the tier. Terminates TLS, routes by name to every service behind it ([#129]) | | step-ca | `smallstep/step-ca` | *internal* (9000) | The tier's certificate authority — an intermediate beneath the lab CA, so nothing that trusts `certificates/ca.pem` is re-pointed ([#130]) | +| home-assistant | `ghcr.io/home-assistant/home-assistant` | *internal* (8123) | Home automation, and what the `99 → 20` rule exists for — one pass, to the Hue bridge, scoped by [ADR-0035] ([#134]) | -Two services, and both are plumbing. What is absent is as deliberate as what -is here: +Two of the three are plumbing; the third is the first household service and +the shape every later one takes. What is absent is as deliberate as what is +here: - **No Prometheus, Loki or Grafana.** The lab has its own because its telemetry must never reach VLAN 99 ([ADR-0007]); this host *is* on VLAN 99, @@ -25,17 +27,26 @@ is here: `scripts/deploy-agent.sh`, pushing to `10.0.99.20`, needing no new rule and no new port. The agent is not in this compose file for the same reason it is not in the lab's: it is the estate's, deployed identically everywhere. -- **No services yet.** Vaultwarden, Immich, Paperless-ngx, Home Assistant, - AdGuard Home, ntfy and Homepage ([#131]–[#137]) each arrive as a service with - `expose:` and a block in the `Caddyfile`, in that order of build, and only - after the foundation runs. A service in this file with `ports:` of its own is - the one thing a review of it should refuse. +- **No other services yet.** Vaultwarden, Immich, Paperless-ngx, AdGuard Home, + ntfy and Homepage ([#131]–[#133], [#135]–[#137]) each arrive as Home + Assistant did: a service with `expose:`, a block in the `Caddyfile`, a name + on the leaf. A service in this file with `ports:` of its own is the one thing + a review of it should refuse. +- **No Supervisor, no add-ons, no MQTT broker, no Zigbee coordinator.** Home + Assistant *Container* has no add-on store, which is why it was chosen: an + add-on is a second package manager outside `compose.yaml` and outside digest + pinning. What an add-on would have supplied becomes a pinned service here + on the day a device needs it, and today none does — Ring is cloud, the Hue + bridge is its own radio, the speakers are Wi-Fi. No USB radio means where + `trinity` sits is not this service's concern. ## Layout ```text -compose.yaml two services, one network, health-gated ordering +compose.yaml three services, one network, health-gated ordering Caddyfile every route the tier serves; validated in CI +home-assistant/ configuration.yaml and packages/, mounted read-only + over the volume Home Assistant writes its state to .env.example non-sensitive tunables — edit this, not .env ``` @@ -65,15 +76,51 @@ CA key stays. either would mint a root of its own. The key password is `STEPCA_PASSWORD` in SOPS, written to a private tmpfs at start and nowhere on disk. - **The certificate is hand-issued until ACME is wired.** `make certs - ARGS="--host trinity.matrix.elysium --ip 10.0.99.40 --dns trinity"` on the - monitoring host, three files copied over as `build-the-lab-guest.md` §5 - does it. `render-config.sh` refuses to render while any of them is missing. + ARGS="--host trinity.matrix.elysium --ip 10.0.99.40 --dns trinity --dns + homeassistant.matrix.elysium"` on the monitoring host, three files copied + over as `build-the-lab-guest.md` §5 does it. `render-config.sh` refuses to render while any of them is missing. The `Caddyfile` carries the `tls { ca … }` block that replaces this once [#130]'s ACME provisioner is configured. - **80 is not published.** ADR-0012: a port is published when something off-host consumes it, and nothing consumes 80 — browsers on Hicks type `https`, and ACME's `tls-alpn-01` challenge runs over 443. A redirect is a later choice, made in `.env.example` and `compose.yaml` together. +- **Every routed name needs a SAN and a host override.** The `Caddyfile` + matches on Host, so `homeassistant.matrix.elysium` has to be on the leaf + (`compose.yaml`'s `make certs` line carries one `--dns` per name) and in + `morpheus`'s resolver, pointed at `10.0.99.40` + ([`add-a-host-override.md`](../../docs/runbooks/add-a-host-override.md)). + A name missing from the leaf fails the handshake; one missing from the + resolver never arrives. +- **Home Assistant is an ordinary member of the network, not `network_mode: + host`.** Upstream's example uses host networking and `privileged` for + discovery and USB. Discovery is mDNS and SSDP, which are link-local, and + every device it controls is on Skids, a VLAN away — nothing on 20 would be + found from 99 however the container were attached. Devices are added by + address, through the one pass [ADR-0035] writes down. It runs with every + capability dropped, a read-only root and two tmpfs mounts, as root because + the image has no other mode; `compose.yaml` numbers the differences. +- **Home Assistant's credentials are not in SOPS, and cannot be.** The Hue + application key, the Ring token and everything else a config flow produces + are written by Home Assistant into `/config/.storage`, inside the + `home-assistant-config` volume. Nothing this repository renders can hand + them in, so the volume is where the tier's most numerous credentials live, + protected by [#404]'s disk-encryption decision and by the encrypted volume + archive rather than by SOPS. [ADR-0035] records the deviation. A long-lived + access token minted for another service goes in *that* service's SOPS file + — none exists yet — and TOTP is enrolled at first login, as [#404] step 6 + says. +- **Automations are YAML in `home-assistant/packages/`, not the UI editor.** + `configuration.yaml` is mounted read-only from this directory and loads the + packages directory beside it; there is no `automations.yaml`, because the + UI editor's include fails hard on a file that does not exist and the file + is one Home Assistant writes rather than one this repository ships. The + packages README says the rest. Integrations and devices are still added + through the UI: a config flow has no YAML form. +- **Caddy has a fixed address, `172.28.99.2`, for one reader.** Home + Assistant's `trusted_proxies` names the proxy it will believe + `X-Forwarded-For` from, and a Docker-assigned address is not a name. The + network's subnet is fixed for that one line and nothing else. - **Nothing converges this stack.** The `homelab-*` timers are the estate's; `make validate` notes their absence here as a skip, not a failure. This stack is deployed by hand, from a checkout on `trinity`. @@ -104,15 +151,30 @@ it matters: volume, and the volume is populated by a procedure run on two hosts. A fresh `make up` on a bare `trinity` fails on `config/ca.json`, loudly and on purpose. -- **That the leaf matches the name.** `caddy validate` loads a throwaway pair; - whether the real one carries `trinity.matrix.elysium` in its SANs is checked - by the first browser, or by `openssl x509 -noout -ext subjectAltName` on the - monitoring host before the files travel. +- **That the leaf matches the names.** `caddy validate` loads a throwaway + pair; whether the real one carries `trinity.matrix.elysium` *and* + `homeassistant.matrix.elysium` in its SANs is checked by the first browser, + or by `openssl x509 -noout -ext subjectAltName` on the monitoring host + before the files travel. +- **That Home Assistant keeps booting under its hardening.** It was booted + once, on the monitoring host on 2026-09-09, from the pinned digest with the + exact `compose.yaml` settings — read-only root, every capability dropped, + the two tmpfs mounts, this directory's `configuration.yaml` — on an + internal Docker network with no route out. It served onboarding, wrote only + to `/config`, and logged one error it will log on every start: the `dhcp` + discovery integration wants `CAP_NET_RAW` to sniff for devices, which on a + bridge network a VLAN away from every device would sniff nothing, so the + capability stays dropped and the line is expected. That was one boot of one + digest. Dependabot moves the digest monthly; nothing here re-runs the boot. [ADR-0007]: ../../docs/adr/0007-defensive-estate-and-offensive-range.md [ADR-0034]: ../../docs/adr/0034-run-the-sensitive-tier-on-the-prodesk-and-make-it-the-spare-hardware.md [#129]: https://github.com/Gerrrt/HomeLab/issues/129 [#130]: https://github.com/Gerrrt/HomeLab/issues/130 [#131]: https://github.com/Gerrrt/HomeLab/issues/131 +[#133]: https://github.com/Gerrrt/HomeLab/issues/133 +[#134]: https://github.com/Gerrrt/HomeLab/issues/134 +[#135]: https://github.com/Gerrrt/HomeLab/issues/135 [#137]: https://github.com/Gerrrt/HomeLab/issues/137 +[ADR-0035]: ../../docs/adr/0035-scope-the-99-to-20-rule-to-the-hue-bridge.md [#404]: https://github.com/Gerrrt/HomeLab/issues/404 diff --git a/stacks/sensitive/compose.yaml b/stacks/sensitive/compose.yaml index 42d5ed6b..c03145dc 100644 --- a/stacks/sensitive/compose.yaml +++ b/stacks/sensitive/compose.yaml @@ -11,13 +11,14 @@ # --------------------------------------------------------------------------- # What is here, and what is not # --------------------------------------------------------------------------- -# Two services: the foundation. Caddy (#129) is the only thing on the tier -# that publishes a port, and the whole containment argument in ADR-0008 — -# "containers sit on private bridge networks with only the reverse proxy -# publishing a port" — is a property of this file or it is a sentence in an -# ADR. step-ca (#130) issues the certificates behind it. Vaultwarden, Immich, -# Paperless-ngx, Home Assistant, AdGuard Home, ntfy and Homepage (#131–#137) -# land behind Caddy on the network below, each with `expose:` and no `ports:`. +# The foundation, and the first household service on it. Caddy (#129) is the +# only thing on the tier that publishes a port, and the whole containment +# argument in ADR-0008 — "containers sit on private bridge networks with only +# the reverse proxy publishing a port" — is a property of this file or it is a +# sentence in an ADR. step-ca (#130) issues the certificates behind it. Home +# Assistant (#134) is the first service behind them, and the shape every later +# one takes: `expose:` and no `ports:`. Vaultwarden, Immich, Paperless-ngx, +# AdGuard Home, ntfy and Homepage (#131–#133, #135–#137) land the same way. # # --------------------------------------------------------------------------- # On the comments in this file @@ -28,7 +29,7 @@ # NOT repeated here; two copies of an argument drift the same way two copies # of a config do. What IS written out here is every place this stack differs # from that one, because those are the only lines a reader cannot get from -# the sibling file. There are four such places, each marked DIFFERENCE. +# the sibling file. There are six such places, each marked DIFFERENCE. name: sensitive @@ -85,6 +86,15 @@ services: <<: *service-defaults image: caddy:2.11.4@sha256:df7f1c2fb114453b951de51a98efc010db1655a92c2e86be6706714e2417a78d container_name: sensitive-caddy + # A fixed address, for one reader: Home Assistant's `trusted_proxies` + # names the proxy it will believe X-Forwarded-For from, and "whatever + # Docker handed Caddy this boot" is not a name. The mapping form replaces + # the anchor's `networks: [sensitive]`; the subnet is declared at the + # bottom of this file. `.1` is the bridge's own address, so `.2` is the + # first a container can hold. + networks: + sensitive: + ipv4_address: 172.28.99.2 mem_limit: 128m memswap_limit: 128m cap_drop: [ALL] @@ -100,9 +110,12 @@ services: - caddy-config:/config # The leaf comes from scripts/gen-certs.sh until step-ca issues it # (#129: "initially, replaced by step-ca issuance once that lands"): - # make certs ARGS="--host trinity.matrix.elysium --ip 10.0.99.40 --dns trinity" - # Issued on the monitoring host, where the CA key lives and stays; the - # three files travel the way the lab's did (build-the-lab-guest.md §5). + # make certs ARGS="--host trinity.matrix.elysium --ip 10.0.99.40 \ + # --dns trinity --dns homeassistant.matrix.elysium" + # One --dns per name the Caddyfile routes by, until step-ca issues each + # its own; a Host the leaf does not carry fails the handshake, not the + # route. Issued on the monitoring host, where the CA key lives and stays; + # the three files travel the way the lab's did (build-the-lab-guest.md §5). # render-config.sh refuses to render while any of these is missing, so # `make up` cannot start a Caddy that would fail its first TLS handshake. - ../../certificates/trinity.matrix.elysium.pem:/etc/caddy/tls/cert.pem:ro @@ -196,15 +209,148 @@ services: retries: 3 start_period: 30s + # --------------------------------------------------------------------------- + # Home Assistant — the automation hub, and what the 99 → 20 rule is for (#134) + # --------------------------------------------------------------------------- + # Home Assistant CONTAINER, not Supervised and not OS: no Supervisor, so no + # add-ons — and that is the point rather than the price. An add-on is a + # second package manager operating outside this file and outside digest + # pinning, the objection roadmap.md records against Nextcloud's app store. + # Anything an add-on would have supplied — an MQTT broker, a Zigbee bridge — + # arrives as its own pinned service in this file, on the day a device needs + # it. None does today: Ring is cloud, the Hue bridge is its own radio, the + # speakers are Wi-Fi (roadmap.md, "Everything still to buy"). So there is no + # `devices:` line, no USB coordinator, and where trinity physically sits is + # not constrained by this service — the question ADR-0034 left to #404, + # answered for #134's part: a rack in a closet is fine. + # + # Upstream's compose example is `network_mode: host` and `privileged: true`. + # Neither is here, and this estate is the one place refusing them costs + # nothing. Host networking exists for discovery — mDNS and SSDP — and + # discovery is link-local: every device this controls is on Skids (VLAN 20), + # a broadcast domain away, so nothing on 20 would be found from 99 however + # the container were networked. Devices are added by address, through the + # one pass ADR-0035 scopes. `privileged` exists for USB radios and Bluetooth, + # and there are none. So this is an ordinary member of the `sensitive` + # network with `expose:` and no `ports:`, behind Caddy like everything else, + # and ADR-0008's containment sentence stays true of it. + # + # DIFFERENCE 5: `init: false`. The image's entrypoint is s6-overlay v3, an + # init in its own right, and it refuses to be anything but PID 1 — measured + # on the pinned image, not read: with `init: true` the container exits at + # once on `s6-overlay-suexec: fatal: can only run as pid 1`. Every other + # service here takes tini from x-service-defaults; this one brings its own. + # + # DIFFERENCE 6: root, like Caddy, and for a worse reason — the image has no + # other mode. s6 starts as root and runs Home Assistant as root; there is no + # PUID, and a `user:` line breaks the supervision tree before it starts. What + # bounds that is the same set as Caddy's, minus the capability: everything + # dropped, no-new-privileges, a read-only root with two tmpfs mounts (s6 + # needs /run and Home Assistant needs /tmp; S6_READ_ONLY_ROOT tells stage 2 + # to stage its scripts under /run instead of /etc), and one writable path, + # the config volume. Booted exactly so on the monitoring host on 2026-09-09 + # from the pinned digest, on an internal Docker network with no route out: + # onboarding served in about twenty seconds, zero read-only errors, CapEff 0 + # for PID 1 and for the Home Assistant process. Root with no capabilities and + # a read-only root writes /config and nothing else. Two things that boot + # taught, both kept: /run has to be mounted `exec` — Docker's tmpfs default + # is noexec and s6 stages its own binaries there, so without it stage 0 dies + # on `Permission denied` — and one error line is logged on every start, + # `aiodhcpwatcher: Cannot watch for dhcp packets: Operation not permitted`. + # That is default_config's `dhcp` discovery wanting CAP_NET_RAW to sniff + # for devices; on a bridge network a VLAN away from every device it would + # sniff nothing, so the capability stays dropped and the line is expected. + # + # WHERE THE CREDENTIALS ARE, because this service accumulates more of them + # than anything else on the tier and the estate's rule is `secrets/*.sops.yaml` + # or nowhere. Home Assistant does not take device credentials from the + # environment or from any file this repository could render: the Hue + # application key, the Ring refresh token and everything else a config flow + # produces is written by Home Assistant into /config/.storage/ — in the + # volume, on trinity's disk, in the volume archive. So the rule holds for + # what this file can hold, which today is nothing — there is no `${VAR:?}` + # guard because there is no secret this service takes from outside — and + # the deviation is written down rather than papered over: the tier's most + # numerous credentials live in an application store, protected by #404's + # disk-encryption decision and by the volume backup, not by SOPS. ADR-0035 + # records that. Two rules follow from it. A long-lived access token minted + # in the UI for another service to use is that service's secret and goes in + # ITS SOPS file — none exists yet, and #98's would-be consumer was declined + # by ADR-0019. And the first YAML-configured integration that needs a + # credential is the day /config/secrets.yaml gets rendered from SOPS the way + # alertmanager's URL files are; not before, because a rendered file with + # nothing to hold is a mount nothing reads. + home-assistant: + <<: *service-defaults + image: ghcr.io/home-assistant/home-assistant:2026.9.1@sha256:612d76760b544cb40b7ba01387fdac964c59a6a550a50a4d30b4773c822d2918 + container_name: sensitive-home-assistant + init: false + # A ceiling to catch a leak, not a measurement: #114's method — median and + # peak over a fortnight of real use — replaces it once the tier runs. The + # only number there is: 316 MiB RSS at the end of a first boot on the + # pinned image, with default_config loaded and no devices, and 35 + # tasks against the anchor's pids_limit of 512. Python threads count as + # tasks and Home Assistant is thread-heavy — its executor alone may hold + # 64 — so the margin under 512 is stated rather than assumed. + mem_limit: 1g + memswap_limit: 1g + cap_drop: [ALL] + security_opt: + - no-new-privileges:true + read_only: true + tmpfs: + - /tmp:size=64m + - /run:size=16m,exec + environment: + S6_READ_ONLY_ROOT: "1" + volumes: + - home-assistant-config:/config + # The config is the repository's; the volume is the application's. A + # single-file mount over a volume works — Docker mounts the deeper path + # last — and it is pinned to an inode like every other single-file mount + # here, so `make up` runs check_mounted_config.py --fix for it (#355). + - ./home-assistant/configuration.yaml:/config/configuration.yaml:ro + - ./home-assistant/packages:/config/packages:ro + expose: + - "8123" + # The recorder flushes on shutdown; cut it off at compose's default 10s + # and the next start replays or repairs the database. Upstream's example + # sets the same figure. + stop_grace_period: 60s + healthcheck: + # /manifest.json answers 200 with no session. `/` answers 302 — to + # onboarding, then to the login page — which --spider would also pass, + # but a redirect is a weaker claim than a document. busybox wget, as in + # Caddy's check; --probe proves the binary is there. + test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/manifest.json"] + interval: 30s + timeout: 5s + retries: 3 + # A first boot on the i5-8500T is well under this; the figure covers a + # recorder repair after an unclean stop, which is the slow start that + # matters. + start_period: 90s + # DIFFERENCE 4: one network, and it is the point. Every later service joins # `sensitive` with `expose:` only; Caddy is the sole member with `ports:`. # A service that adds `ports:` here is undoing ADR-0008's containment, and # the review question for every PR against this file is that one line. +# +# The subnet is fixed so that one address on it can be: Caddy's, which Home +# Assistant's `trusted_proxies` names. 172.28.99.0/24 is inside Docker's +# default 172.16/12 pool, so nothing else on trinity changes; outside the two +# subnets the estate routes; and outside the 172.30.30.0/24 ADR-0017 keeps +# unrouted on ifrit, so a 172.28.99.x source in a firewall log still means +# what that ADR says a 172.30.30.x one means — a leak reporting itself. networks: sensitive: driver: bridge + ipam: + config: + - subnet: 172.28.99.0/24 volumes: caddy-data: caddy-config: step-ca-data: + home-assistant-config: diff --git a/stacks/sensitive/home-assistant/configuration.yaml b/stacks/sensitive/home-assistant/configuration.yaml new file mode 100644 index 00000000..cd412d3c --- /dev/null +++ b/stacks/sensitive/home-assistant/configuration.yaml @@ -0,0 +1,41 @@ +--- +# Home Assistant's core configuration (#134). +# +# Mounted read-only at /config/configuration.yaml, over the volume that holds +# everything Home Assistant writes for itself — .storage/, the recorder +# database, ip_bans.yaml, .HA_VERSION. So this file is the config that runs, +# reviewed and checked like every other config here, and the volume is state. +# +# What is deliberately NOT here — the container's shape, where the credentials +# live, why there is no `automation: !include automations.yaml` — is argued in +# compose.yaml beside the service, not repeated. + +# The standard set: onboarding, the frontend, the automation and script +# engines, the recorder, history, logbook, mobile_app, and the rest. +default_config: + +homeassistant: + # Everything beyond this file lives in packages/, a directory mounted + # read-only beside it. An empty directory loads as nothing, which is why the + # split is packages rather than `!include automations.yaml`: that include + # fails hard when its file is missing, and the file is one Home Assistant + # writes for its own editor, not one this repository ships. Automations are + # YAML in that directory, in git, or they do not exist — the UI editor is + # not used here, for the reason the README gives. + packages: !include_dir_named packages + +http: + # Home Assistant refuses proxied requests unless told who the proxy is — + # "A request from a reverse proxy was received from …, but your HTTP + # integration is not set-up for reverse proxies". Caddy is the only thing + # that reaches 8123 (`expose:`, no `ports:`), and compose.yaml gives it a + # fixed address on the `sensitive` network for exactly this line. One + # address rather than the network's subnet, so a sibling container cannot + # forge X-Forwarded-For and have Home Assistant believe it. + use_x_forwarded_for: true + trusted_proxies: + - 172.28.99.2 + # Five failed logins from one address bans it. The ban list is written to + # /config/ip_bans.yaml, in the volume; lifting one is editing that file. + ip_ban_enabled: true + login_attempts_threshold: 5 diff --git a/stacks/sensitive/home-assistant/packages/README.md b/stacks/sensitive/home-assistant/packages/README.md new file mode 100644 index 00000000..93a8f41e --- /dev/null +++ b/stacks/sensitive/home-assistant/packages/README.md @@ -0,0 +1,19 @@ +# Home Assistant packages + +Every `*.yaml` in this directory is loaded by `configuration.yaml`'s +`packages: !include_dir_named packages` and mounted read-only into the +container at `/config/packages`. Automations, scripts, scenes, template +sensors — anything beyond the core configuration — is a file here, in git, +and nothing else. This README is not YAML and Home Assistant ignores it; it +exists so the directory does. + +There is no `automations.yaml`. The UI automation editor writes that file into +`/config` and needs `automation: !include automations.yaml` to load it, and +that include fails hard on a file that does not exist yet — which on a fresh +volume it never does, because this repository ships the configuration and +Home Assistant only writes the file when it ships its own. So automations are +authored here, reviewed like every other config, and the UI editor is not +used. Devices and integrations are still added through the UI: a config flow +has no YAML form, and what it produces lands in `/config/.storage`, which is +state, not configuration — `compose.yaml` says where that leaves the +credentials.