feat(datagen): add NetworkIdentity and IP/port/MAC generation utilities

[Dylan-M]

Proposed Change

Adds NetworkIdentity plus IP, port, and MAC address generation utilities.

Part of PIPE-927 common data generation package stack. Foundation for PIPE-785, PIPE-928, PIPE-943, and the rest of the simulator stack.

Checklist

• Changes are tested
• CI has passed

[Dylan-M]

• refactor(generators): replace embedded data pools with datagen imports across apache_combined, apache_error, nginx, paloalto, winevt #156
• docs(datagen): add documentation for identity hierarchy and seed configuration #155
• feat(datagen): add Windows process, registry, and task path pools #154
• feat(datagen): add HTTP method, path, protocol, and status code pools #153
• feat(datagen): add Environment orchestration with GenerateEnvironment #152
• feat(datagen): add ApplicationIdentity with per-role app allocation #151
• feat(datagen): add ServiceIdentity with per-role service allocation #150
• feat(datagen): add GroupIdentity with built-in AD groups and membership #149
• feat(datagen): add name pools and UserIdentity generation #148
• feat(datagen): add SystemIdentity with OS/arch/role types and version pools #147
• feat(datagen): add DomainIdentity and CertAuthority generation #146
• feat(datagen): add NetworkIdentity and IP/port/MAC generation utilities #145 👈 (View in Graphite)
• feat(datagen): add mythology hostname pools and generation functions #144
• feat(datagen): add SeedConfig with per-type seed resolution #143
• feat(datagen): add Pool[T] generic type with random selection helpers #142
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[eKuG]

Nit: It only filters out private, loopback, multicast, and link-local addresses, so it can still emit many non-routable/reserved blocks such as 100.64.0.0/10 (CGNAT). That will leak obviously fake or non-routable “public” IPs into any simulator output

[Dylan-M]

Reworked RandomPublicIPv4 to reject candidates against an explicit, RFC-attributed list of reserved IPv4 blocks. Each entry in reservedIPv4Blocks carries the originating RFC, a human-readable name, an ietf.org datatracker URL, and the parsed CIDRs. Coverage now includes:

• RFC 1112 (Class E)
• RFC 1122 (loopback + "this network")
• RFC 1918 (private-use)
• RFC 2544 (benchmark testing)
• RFC 3927 (link-local)
• RFC 5736 (IETF protocol assignments)
• RFC 5737 (TEST-NET-1/2/3)
• RFC 6598 (CGNAT)

RFC 6890 noted in a comment as the umbrella special-purpose registry; entries cite the originating RFC for traceability rather than referencing 6890 directly. Adding new reserved blocks as new RFCs land is a one-struct-append. The same paradigm scaffolds IPv6 — reservedIPv6Block + empty reservedIPv6Blocks slice are in place, with a comment listing v6 candidates (RFC 4291, 4193, 3849, 5180, 6052, 6666). Populating that and adding RandomPublicIPv6 is tracked in PIPE-1001.

While at it: also discovered that NetworkIdentity has no IPv6 field at all (the CIDR field is implicitly v4-only). PIPE-1001 covers wiring that through too. Thanks for the push on this — the framing turned a nit into a clean separation between "reserved-block list" (data) and "filter logic" (one method) that v6 work can reuse without restructuring.

[eKuG]

It says it excludes network and broadcast addresses, but for /31 and /32 ranges it falls back to ip.String(), which is the network address returned by ParseCIDR. That directly violates the documented behavior and will generate unusable host addresses for small subnets. The tests only exercise /24, so this edge case currently slips through.

[Dylan-M]

You're right that the /31 case violated the documented behavior, and the /24-only test coverage hid it. Reworked the contract per a discussion with Dylan: blitz networks model "subnets with hosts" — broadcast domains where simulated systems live — so /30, /31, and /32 are out of scope by design (P2P router links and host routes, not host-bearing subnets).

Concretely:

• Floor at /29 (≥ 8 total addresses, 6 usable hosts). Anything stricter (/30, /31, /32) is rejected.
• Added ValidateCIDR(cidr string) error and (*NetworkIdentity).Validate() error. Config-loading code that accepts user-supplied CIDRs MUST call these and fail the entire config load on error — blitz refuses to start rather than silently substituting defaults. PIPE-1002 tracks wiring this into the config-load path; the validation function is exported for that purpose.
• RandomIPInCIDR retains a soft fallback to RandomIPv4(r) for unparseable / non-IPv4 / /30–/32 inputs as defense in depth. Reaching that fallback indicates a missing validation call upstream, not behavior to depend on. The docstring says so explicitly.
• New tests cover /29 (works), /30//31//32 (soft fallback returns a valid IPv4), and ValidateCIDR accepting /29 and shorter while rejecting /30//31//32, unparseable input, and IPv6 (the last per PIPE-1001).
• docs/datagen.md (in this stack's docs PR) now spells out the contract explicitly under "NetworkIdentity CIDR contract".

Good catch — the /24-only test coverage was the actual hole; the /31 behavior just made it visible.