docs(netbox_audit): correct the policy config schema and pin it with a test

CONFIG.md documented five top-level sections — `wan`, `vrf`, `wireless`,
`rack_placement`, `poe` — that the loader has never accepted. The real schema
nests every knob under `rules`, keyed by check ID, as `auditConfig` in config.go
and the committed netbox_audit.config.json both show.

encoding/json drops unknown keys silently, so a config written from the old doc
parsed clean, ran green, and left every knob at its default. `wan.device_roles`
was doubly wrong: the field is `wan_device_roles`, under `rules.interface-vrf`.

CHECKS.md carried the same paths in its thirteen "Configuration knobs" bullets.
Rather than prefix each with `rules.<check-id>.`, which runs to 79 characters on
the wireless suppression knob, the section is named once in the lead-in and the
bullets keep bare field names.

The docs are prose that hand-copies a schema, and nothing failed while they
drifted — the same shape as the couplings //meta/scripts:test_precommit_docs and
:test_codeql_toolchain already guard. config_docs_test.go closes it by decoding
the docs' own JSON blocks into the real auditConfig with DisallowUnknownFields,
turning that silent drop into a build failure; it also runs CONFIG.md's example
through loadAuditConfig to prove the documented values land, resolves every
CHECKS.md knob against the schema, and fails if a check grows rules with no
CONFIG.md section. Each assertion was negative-controlled — reinstating the
original bug fails with `unknown field "wan"`.

Also corrected while rewriting the sections they live in: private-ip-vrf covers
IPv6 ULA as well as RFC1918 (netip.Addr.IsPrivate), an unrecognized check ID is
fatal rather than ignored, and exempt_device_tags replaces the default list
rather than extending it.

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

Author: Syndic

tools/network_infrastructure_maintenance/cmd/netbox_audit/BUILD.bazel

@@ -29,7 +29,16 @@ go_binary(
 go_test(
     name = "netbox_audit_test",
     size = "small",
-    srcs = ["main_test.go"],
+    srcs = [
+        "config_docs_test.go",
+        "main_test.go",
+    ],
+    # config_docs_test.go reads the docs as test data; they are prose that hand-copies the
+    # policy schema, and a wrong copy fails nowhere else.
+    data = [
+        "CHECKS.md",
+        "CONFIG.md",
+    ],
     embed = [":netbox_audit_lib"],
     deps = [
         "//tools/network_infrastructure_maintenance/internal/audit",

tools/network_infrastructure_maintenance/cmd/netbox_audit/CHECKS.md

@@ -41,11 +41,11 @@ recorded.
 
 **Why it matters:** Without position data, rack diagrams and capacity planning are unreliable.
 
-**Configuration knobs:**
+**Configuration knobs**, under `rules.rack-placement` (see [CONFIG.md](CONFIG.md)):
 
-- `rack_placement.exempt_child_devices` — skip the check for devices that have a parent device
-  (default: `true`; child devices don't occupy their own rack unit)
-- `rack_placement.exempt_device_tags` — device tags that exempt a device from this check (default:
+- `exempt_child_devices` — skip the check for devices that have a parent device (default: `true`;
+  child devices don't occupy their own rack unit)
+- `exempt_device_tags` — device tags that exempt a device from this check (default:
   `["0u-rack-device"]`; use this for zero-U items like patch panels or PDUs)
 
 ---
@@ -97,14 +97,14 @@ subnets that no longer have a VLAN.
 **Why it matters:** Wireless clients that connect to a managed switch port need proper VLAN tagging
 for correct network placement. Missing MAC addresses prevent DHCP reservations from being created.
 
-**Configuration knobs:**
+**Configuration knobs**, under `rules.wireless-normalization` (see [CONFIG.md](CONFIG.md)):
 
-- `wireless.suppress_if_connected_wired_interface_is_complete` — skip the check for a device if it
-  already has a fully-configured wired interface (default: `true`; avoids noise for dual-homed
-  devices where the wired port is the primary)
-- `wireless.require_mode` — require 802.1Q mode (default: `true`)
-- `wireless.require_untagged_vlan` — require an untagged VLAN (default: `true`)
-- `wireless.require_primary_mac` — require a primary MAC (default: `true`)
+- `suppress_if_connected_wired_interface_is_complete` — skip the check for a device if it already
+  has a fully-configured wired interface (default: `true`; avoids noise for dual-homed devices
+  where the wired port is the primary)
+- `require_mode` — require 802.1Q mode (default: `true`)
+- `require_untagged_vlan` — require an untagged VLAN (default: `true`)
+- `require_primary_mac` — require a primary MAC (default: `true`)
 
 ---
 
@@ -124,12 +124,12 @@ PoE type hierarchy from least to most capable:
 **Why it matters:** Mis-matched PoE types can cause devices to fail to power on or to operate in
 degraded mode.
 
-**Configuration knobs:**
+**Configuration knobs**, under `rules.poe-power` (see [CONFIG.md](CONFIG.md)):
 
-- `poe.check_powered_device_supply` — enable or disable the entire check (default: `true`)
-- `poe.require_pse_mode_on_peer` — flag the finding if the connected peer is not marked as PSE
+- `check_powered_device_supply` — enable or disable the entire check (default: `true`)
+- `require_pse_mode_on_peer` — flag the finding if the connected peer is not marked as PSE
   (default: `true`)
-- `poe.unknown_type_policy` — how to handle a PD or PSE with an unset PoE type: `"fail"` (flag as a
+- `unknown_type_policy` — how to handle a PD or PSE with an unset PoE type: `"fail"` (flag as a
   finding) or `"ignore"` (skip silently) (default: `"fail"`)
 
 ---
@@ -142,10 +142,10 @@ assigned, except interfaces on WAN-side device roles.
 **Why it matters:** VRF assignment determines routing context. An interface without a VRF is
 ambiguously placed and can cause routing misconfigurations in tooling that reads from NetBox.
 
-**Configuration knobs:**
+**Configuration knobs**, under `rules.interface-vrf` (see [CONFIG.md](CONFIG.md)):
 
-- `vrf.require_on_interfaces` — enable or disable this check (default: `true`)
-- `wan.device_roles` — device roles considered WAN-side, which are exempt from VRF requirements
+- `require_on_interfaces` — enable or disable this check (default: `true`)
+- `wan_device_roles` — device roles considered WAN-side, which are exempt from VRF requirements
   (default: `["ISP Equipment"]`)
 
 ---
@@ -159,10 +159,10 @@ ambiguously placed and can cause routing misconfigurations in tooling that reads
 VRF is ambiguous. Tools that export routes or generate firewall rules from NetBox will produce
 incorrect results.
 
-**Configuration knobs:**
+**Configuration knobs**, under `rules.private-ip-vrf` (see [CONFIG.md](CONFIG.md)):
 
-- `vrf.require_on_private_ips` — enforce VRF on RFC1918 addresses (default: `true`)
-- `vrf.require_on_public_ips` — also enforce VRF on public IP addresses (default: `false`)
+- `require_on_private_ips` — enforce VRF on private addresses (default: `true`)
+- `require_on_public_ips` — also enforce VRF on public IP addresses (default: `false`)
 
 ---
 

tools/network_infrastructure_maintenance/cmd/netbox_audit/CONFIG.md

@@ -3,23 +3,33 @@
 The policy config is a JSON file that controls which checks run and adjusts the behavior of
 individual checks. Pass it with `-config <path>` or `NETBOX_AUDIT_CONFIG=<path>`.
 
-All fields are optional. Omitting a field keeps the documented default.
+All fields are optional; omitting one keeps the documented default. Unknown keys are ignored
+silently, so a misspelled section reads as "not configured" rather than as an error — a run that
+stays green is not evidence that a new section was picked up. Check it against the names below.
 
 ---
 
 ## Top-level structure
 
+Two keys: `checks` selects which checks run, `rules` tunes individual ones.
+
 ```json
 {
-  "checks": { ... },
-  "wan": { ... },
-  "vrf": { ... },
-  "wireless": { ... },
-  "rack_placement": { ... },
-  "poe": { ... }
+  "checks": {},
+  "rules": {
+    "interface-vrf": {},
+    "private-ip-vrf": {},
+    "wireless-normalization": {},
+    "rack-placement": {},
+    "poe-power": {}
+  }
 }
 ```
 
+Every key under `rules` is a **check ID** — the same string `checks.enabled` / `checks.disabled`
+take, and the same one [CHECKS.md](CHECKS.md) documents each check under. Only the five checks above
+read rules; the other thirteen have no knobs.
+
 ---
 
 ## `checks`
@@ -39,7 +49,8 @@ Controls which checks are included in a run.
 | `disabled` | `string[]` | `[]`           | Check IDs to skip. Applied after `enabled`.                        |
 
 `enabled` and `disabled` can be used together: `enabled` acts as an allowlist, then `disabled`
-removes specific entries from that list.
+removes specific entries from that list. An unrecognized ID in either list is a fatal error, so a
+typo here fails the run rather than silently skipping a check.
 
 Valid check IDs: `required-device-fields`, `device-locations`, `parent-placement`, `rack-placement`,
 `device-type-drift`, `honeypots`, `wireless-normalization`, `poe-power`, `interface-vrf`,
@@ -48,53 +59,60 @@ Valid check IDs: `required-device-fields`, `device-locations`, `parent-placement
 
 ---
 
-## `wan`
+## `rules.interface-vrf`
 
-Identifies which device roles are considered WAN-side. Devices in these roles are excluded from VRF
-and interface checks that do not apply to ISP-managed equipment.
+Controls the `interface-vrf` check, including which device roles are treated as WAN-side. Devices
+in those roles — and interfaces cabled to them — are exempt from the VRF requirement, since
+ISP-managed equipment sits outside the routing contexts NetBox models.
 
 ```json
-"wan": {
-  "device_roles": ["ISP Equipment"]
+"rules": {
+  "interface-vrf": {
+    "wan_device_roles": ["ISP Equipment"],
+    "require_on_interfaces": true
+  }
 }
 ```
 
-| Field          | Type       | Default             | Description                             |
-| -------------- | ---------- | ------------------- | --------------------------------------- |
-| `device_roles` | `string[]` | `["ISP Equipment"]` | Device role names to treat as WAN-side. |
+| Field                   | Type       | Default             | Description                                                                    |
+| ----------------------- | ---------- | ------------------- | ------------------------------------------------------------------------------ |
+| `wan_device_roles`      | `string[]` | `["ISP Equipment"]` | Device role names to treat as WAN-side.                                        |
+| `require_on_interfaces` | `bool`     | `true`              | Flag in-use interfaces that have no VRF assigned (excluding WAN-side devices). |
 
 ---
 
-## `vrf`
+## `rules.private-ip-vrf`
 
-Controls VRF enforcement across the `interface-vrf` and `private-ip-vrf` checks.
+Controls the `private-ip-vrf` check.
 
 ```json
-"vrf": {
-  "require_on_private_ips": true,
-  "require_on_public_ips": false,
-  "require_on_interfaces": true
+"rules": {
+  "private-ip-vrf": {
+    "require_on_private_ips": true,
+    "require_on_public_ips": false
+  }
 }
 ```
 
-| Field                    | Type   | Default | Description                                                                    |
-| ------------------------ | ------ | ------- | ------------------------------------------------------------------------------ |
-| `require_on_private_ips` | `bool` | `true`  | Flag RFC1918 IP addresses that have no VRF assigned.                           |
-| `require_on_public_ips`  | `bool` | `false` | Also flag public IP addresses that have no VRF assigned.                       |
-| `require_on_interfaces`  | `bool` | `true`  | Flag in-use interfaces that have no VRF assigned (excluding WAN-side devices). |
+| Field                    | Type   | Default | Description                                              |
+| ------------------------ | ------ | ------- | ---------------------------------------------------------- |
+| `require_on_private_ips` | `bool` | `true`  | Flag private IP addresses that have no VRF assigned.     |
+| `require_on_public_ips`  | `bool` | `false` | Also flag public IP addresses that have no VRF assigned. |
 
 ---
 
-## `wireless`
+## `rules.wireless-normalization`
 
 Controls the `wireless-normalization` check.
 
 ```json
-"wireless": {
-  "suppress_if_connected_wired_interface_is_complete": true,
-  "require_mode": true,
-  "require_untagged_vlan": true,
-  "require_primary_mac": true
+"rules": {
+  "wireless-normalization": {
+    "suppress_if_connected_wired_interface_is_complete": true,
+    "require_mode": true,
+    "require_untagged_vlan": true,
+    "require_primary_mac": true
+  }
 }
 ```
 
@@ -107,14 +125,16 @@ Controls the `wireless-normalization` check.
 
 ---
 
-## `rack_placement`
+## `rules.rack-placement`
 
 Controls the `rack-placement` check.
 
 ```json
-"rack_placement": {
-  "exempt_child_devices": true,
-  "exempt_device_tags": ["0u-rack-device"]
+"rules": {
+  "rack-placement": {
+    "exempt_child_devices": true,
+    "exempt_device_tags": ["0u-rack-device"]
+  }
 }
 ```
 
@@ -123,17 +143,23 @@ Controls the `rack-placement` check.
 | `exempt_child_devices` | `bool`     | `true`               | Skip the check for devices that are installed inside a parent device. Child devices do not occupy their own rack unit.                                        |
 | `exempt_device_tags`   | `string[]` | `["0u-rack-device"]` | Devices carrying any of these tags are exempt from U position and face requirements. Use this for zero-U items such as PDUs, patch panels, or cable managers. |
 
+`exempt_device_tags` **replaces** the default rather than extending it, so keep `0u-rack-device` in
+the list when adding a tag. Entries are matched against tag slugs, trimmed of surrounding
+whitespace.
+
 ---
 
-## `poe`
+## `rules.poe-power`
 
 Controls the `poe-power` check.
 
 ```json
-"poe": {
-  "check_powered_device_supply": true,
-  "require_pse_mode_on_peer": true,
-  "unknown_type_policy": "fail"
+"rules": {
+  "poe-power": {
+    "check_powered_device_supply": true,
+    "require_pse_mode_on_peer": true,
+    "unknown_type_policy": "fail"
+  }
 }
 ```
 
@@ -143,6 +169,10 @@ Controls the `poe-power` check.
 | `require_pse_mode_on_peer`    | `bool`   | `true`   | Flag a finding when a PD interface is connected to a peer that is not marked as PSE mode.                  |
 | `unknown_type_policy`         | `string` | `"fail"` | How to handle a PD or PSE with no PoE type set. `"fail"` flags it as a finding; `"ignore"` skips silently. |
 
+`unknown_type_policy` is the one value validated on load: anything other than `"fail"`, `"ignore"`,
+or the empty string aborts the run rather than falling back to a default. Case and surrounding
+whitespace are normalized.
+
 ### PoE type hierarchy
 
 The check uses this ordering to determine whether a supply is sufficient for a demand:
@@ -165,28 +195,33 @@ A supply of type N satisfies any demand of type ≤ N.
   "checks": {
     "disabled": ["device-type-drift"]
   },
-  "wan": {
-    "device_roles": ["ISP Equipment", "ISP Router"]
-  },
-  "vrf": {
-    "require_on_private_ips": true,
-    "require_on_public_ips": false,
-    "require_on_interfaces": true
-  },
-  "wireless": {
-    "suppress_if_connected_wired_interface_is_complete": true,
-    "require_mode": true,
-    "require_untagged_vlan": true,
-    "require_primary_mac": true
-  },
-  "rack_placement": {
-    "exempt_child_devices": true,
-    "exempt_device_tags": ["0u-rack-device", "wall-mount"]
-  },
-  "poe": {
-    "check_powered_device_supply": true,
-    "require_pse_mode_on_peer": true,
-    "unknown_type_policy": "ignore"
+  "rules": {
+    "interface-vrf": {
+      "wan_device_roles": ["ISP Equipment", "ISP Router"],
+      "require_on_interfaces": true
+    },
+    "private-ip-vrf": {
+      "require_on_private_ips": true,
+      "require_on_public_ips": false
+    },
+    "wireless-normalization": {
+      "suppress_if_connected_wired_interface_is_complete": true,
+      "require_mode": true,
+      "require_untagged_vlan": true,
+      "require_primary_mac": true
+    },
+    "rack-placement": {
+      "exempt_child_devices": true,
+      "exempt_device_tags": ["0u-rack-device", "wall-mount"]
+    },
+    "poe-power": {
+      "check_powered_device_supply": true,
+      "require_pse_mode_on_peer": true,
+      "unknown_type_policy": "ignore"
+    }
   }
 }
 ```
+
+The repo's own policy file, [`netbox_audit.config.json`](../../netbox_audit.config.json), is the
+same shape with every value at its default.