Found while going through the selfh.st directory, which carries a network-documentation category that awesome-selfhosted does not.
The question
docs/network.md and docs/hardware.md are hand-maintained, and this repository has an unusually well-documented record of what that costs:
That is five documented instances of the same failure mode. The repository's response so far has been to move truth into places CI can check: dashboards provisioned from files, alert counts checked in the deploy runbook, digests verified against the registry, promtool test rules for a rule that could not fire. The network inventory has not had that treatment, and it is the document that has been wrong most often.
What is out there
- NetBox (~21.4k stars) — the standard for network modeling and documentation: devices, racks, VLANs, IP address management, cabling. It is a source of truth you maintain, not a discovery tool, so on its own it moves the hand-maintenance rather than removing it. Its real payoff is different: it has an API, so
prometheus/targets/snmp.yaml and the VLAN tables could be generated from it instead of hand-written, which is the part that would actually stop the drift. It is also a Postgres-backed Django application — meaningful weight for a four-device estate.
- Scanopy (~5.5k stars) — automatic discovery and documentation of network infrastructure. Closer to the actual want, and it needs to reach the segments it documents, which is in direct tension with default-deny. A discovery tool that can see every VLAN is, by construction, a device that violates the segmentation model.
The honest counter-argument
Four SNMP devices, seven VLANs, five firewall rules and four hosts. That is small enough that a Markdown table is the right tool, and every one of the errors above was caught by a human reading the file rather than by tooling. Adding a Django app and a discovery scanner to a network this size may simply move the staleness somewhere less visible — and a NetBox whose contents nobody updates is a stale document with a database behind it.
The middle option, and probably the right one: do not add a service. Add a CI check that cross-references docs/network.md against prometheus/targets/snmp.yaml and docs/architecture.md's host table, and fails when they disagree. That is the pattern this repo already uses and it targets the specific failure — two places holding the same fact.
What closing this looks like
A decision, recorded: adopt one of the tools, or write the CI cross-check, or explicitly accept hand-maintenance and say why. Any of the three is fine; leaving it undecided is what produced the list at the top.
Which VLAN this touches
🔴 99 — Winterfell (management) — and potentially all of them, which is the concern
Security review
Related
#104, #72, #97, #87, #124.
Found while going through the selfh.st directory, which carries a network-documentation category that awesome-selfhosted does not.
The question
docs/network.mdanddocs/hardware.mdare hand-maintained, and this repository has an unusually well-documented record of what that costs:oraclewas recorded as an i5-1235U with 32 GB and a 2 TB SSD. It is a dual-core A6-9200 with 4 GB and a 5400 rpm disk. ADR-0008 notes the wrong entry was load-bearing in planning.shivawas treated as the hypervisor itself for several revisions; it is the iLO, andSarumanis the host at a different address.docs/roadmap.mdsays of itself: "this file has already been wrong about the switch answering SNMP and about the history purge."That is five documented instances of the same failure mode. The repository's response so far has been to move truth into places CI can check: dashboards provisioned from files, alert counts checked in the deploy runbook, digests verified against the registry,
promtool test rulesfor a rule that could not fire. The network inventory has not had that treatment, and it is the document that has been wrong most often.What is out there
prometheus/targets/snmp.yamland the VLAN tables could be generated from it instead of hand-written, which is the part that would actually stop the drift. It is also a Postgres-backed Django application — meaningful weight for a four-device estate.The honest counter-argument
Four SNMP devices, seven VLANs, five firewall rules and four hosts. That is small enough that a Markdown table is the right tool, and every one of the errors above was caught by a human reading the file rather than by tooling. Adding a Django app and a discovery scanner to a network this size may simply move the staleness somewhere less visible — and a NetBox whose contents nobody updates is a stale document with a database behind it.
The middle option, and probably the right one: do not add a service. Add a CI check that cross-references
docs/network.mdagainstprometheus/targets/snmp.yamlanddocs/architecture.md's host table, and fails when they disagree. That is the pattern this repo already uses and it targets the specific failure — two places holding the same fact.What closing this looks like
A decision, recorded: adopt one of the tools, or write the CI cross-check, or explicitly accept hand-maintenance and say why. Any of the three is fine; leaving it undecided is what produced the list at the top.
Which VLAN this touches
🔴 99 — Winterfell (management) — and potentially all of them, which is the concern
Security review
secrets/*.sops.yaml— SNMP communities and any device credentialsdocs/network.mdwith an OUI-truncated MAC — note that a discovery tool would collect full MACs, whichdocs/security.mddeliberately does not publishRelated
#104, #72, #97, #87, #124.