docs(adr): record the three decisions the lab buildout rests on - #46
Merged
Conversation
Three questions came up while planning what to actually build, and each turned on a judgment worth recording rather than a fact worth looking up. ADR-0006 puts network detection on the firewall. A sensor on the hypervisor sees VLAN 30, which is to say it sees the hypervisor; the segment worth inspecting is the one with seven cameras and a Tuya device on it. Mirroring the trunk into the lab would fix the visibility and break the trust boundary, so morpheus gets Suricata instead. The unconfigured Snort package goes. Honest cost: more load on the single point of failure, and a FreeBSD package rather than a digest-pinned container. ADR-0007 splits the lab in two. Saruman becomes the estate you practise defending; ifrit becomes the range that attacks it. Sharing one box would confound "my detection fired" with "my own tooling made that noise". Lab telemetry stays on VLAN 30 behind its own stack rather than remote-writing into management, because security.md names a lab VM reaching the house as a threat this design defends against. Costs a second observability stack and a machine not yet bought. ifrit's isolation mechanism is deliberately left open rather than assumed. ADR-0008 places services by what their data is worth. A password vault and a film library are not the same kind of thing, so they do not get the same segment: the sensitive tier lands on management under the rule that already exists, and the media tier lands with the televisions it serves, which answers the terminal-VLAN problem by placement instead of by exception. No new segment; the seven VLANs stand and ADR-0002 needs no amendment. That one carries a real cost and says so at length. Putting Immich on Winterfell dilutes the boundary ADR-0002 calls total, and that is the best argument for the dedicated segment this rejects. Single sign-on is deferred on the strength of two users and no remote access, which leaves the MFA gap in security.md open knowingly. When either premise changes, so does the decision. Also corrects two counts the previous pass missed in the README: three inter-VLAN rules rather than two, and eight ADRs rather than five. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_013fvaAiKsdyFkX9HgqmuBoj
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Three new ADRs, plus two count corrections in the README that the previous pass
missed. Nothing about the running lab changes.
morpheus, not on the hypervisorSarumanis the defended estate;ifritis the offensive rangeWhy
Each of these turned on a judgment worth recording rather than a fact worth
looking up — which is what
docs/adr/0001says an ADR is for.0006 — detect at the chokepoint. A sensor on the hypervisor sees VLAN 30,
which is to say it sees the hypervisor. The segment that warrants inspection is
Skids, with seven cameras and a Tuya device on it. Mirroring the trunk into the
lab would fix the visibility and damage the trust boundary at the same time, so
Suricata goes on the firewall instead. The unconfigured
pfSense-pkg-snortisremoved. Honest costs recorded: more load on the single point of failure, and a
FreeBSD package rather than a digest-pinned container.
0007 — the lab splits in two. Sharing one box between attack tooling and the
target estate confounds "my detection fired" with "my own tooling made that
noise." Lab telemetry stays on VLAN 30 behind its own stack rather than
remote-writing into management, because
security.mdnames a lab VM reaching thehouse as a threat this design defends against. Costs a second observability stack
and a machine not yet bought.
ifrit's isolation mechanism is left opendeliberately rather than assumed — adding a segment is a decision this project
has already declined once.
0008 — services by data trust. A password vault and a film library aren't the
same kind of thing, so they don't get the same segment. The sensitive tier lands
on Winterfell under the 50→99 rule that already exists; the media tier lands with
the televisions it serves, which answers the terminal-VLAN problem by placement
rather than by exception. No new segment — the seven VLANs stand and ADR-0002
needs no amendment.
That last one carries a real cost and says so at length rather than burying it:
putting Immich on Winterfell dilutes the boundary ADR-0002 calls total, and that
is the strongest argument for the dedicated segment this ADR rejects. The
mitigations are stated, and so is what would change the decision. Single sign-on
is deferred on the strength of two users, no remote access, which leaves the
"no MFA on internal services" gap in
security.mdopen knowingly.Also fixes two README counts the last pass missed: three inter-VLAN rules rather
than two, and eight ADRs rather than five.
Blast radius
secrets/*.sops.yamlDocumentation only. These ADRs describe rules 50→40 and 99→20 as decided, but
neither exists yet and neither is created here — they land with the hardware.
Verification
make validatepasses —all checks passeddocs/, service README, ordocs/roadmap.md)Form follows
docs/adr/0003and0004: Nygard structure, numbered options inContext, Consequences carrying the honest downsides rather than only the wins.
Generated by Claude Code