security: stabilize special-purpose IP classification across supported Python patches

[seonghobae]

Buyer-visible security compatibility gap

EgressWeave supports multiple Python patch lines, but standard-library ipaddress special-purpose classifications can change across supported runtime releases. Remote egress authority must not silently widen or narrow solely because a deployment uses a different supported Python patch.

The product therefore uses a small source-controlled compatibility overlay for reviewed special-purpose ranges and exceptions while continuing to rely on normal runtime classification outside that bounded overlay. The current IANA registries remain the primary allocation evidence; CPython is_private / is_global vocabulary is related but not identical to IANA Globally Reachable.

Current canonical candidate

The current replacement is Draft PR #223, exact head 811ba846757adb44dfc648b9b13761aa1536a110, based directly on protected main 7faf7a3b8a47980113982914000e724ab6a6cda5. Historical #96/#173 remain evidence only; #173 is closed as superseded and no checks, reviews, base identity, or mergeability transfer.

Test-first reconstruction is complete:

• RED-only head 8312a000197eabd7d7d3d7433f6341263c79f031 failed 22 new compatibility regressions across Python 3.10–3.14;
• GREEN production head 26be254deb11be6d5ff1bb10f35e9e70395b91be adds the bounded reviewed overlay, most-specific global exceptions, and IPv4-mapped recursion;
• exact final head 811ba846757adb44dfc648b9b13761aa1536a110 adds source-grounded guidance and corrects the documentation contract for 2001:2::/48 being covered by its reviewed 2001::/23 parent;
• exact-head CI passed Python 3.10–3.14, 1,049 tests, 1,773/1,773 production statements, and 598/598 production branches.

Current boundary

• reviewed global exceptions are applied before broader reviewed non-global parent ranges;
• IPv4-mapped IPv6 addresses inherit the reviewed underlying IPv4 decision;
• local-development hostname authority is not widened;
• no runtime registry download or mutable external lookup occurs;
• ordinary authority, DNS pinning/revalidation, TLS, proxy, request/response, credential, workflow, and generic-denial boundaries remain unchanged;
• 2002::/16 is documented as a deliberate conservative EgressWeave/CPython compatibility decision, not overclaimed as IANA Globally Reachable=False.

Acceptance criteria

• Reconstruct directly on exact protected main without transferring historical evidence.
• Preserve hosted RED evidence proving decisions cannot depend only on runtime is_private / is_global values.
• Cover reviewed IPv4/IPv6 non-global ranges and explicit current global exceptions.
• Apply most-specific exceptions before parent denials.
• Apply the reviewed IPv4 decision to mapped IPv6 addresses.
• Preserve local-development and all ordinary egress authority boundaries.
• Add an explicit future IANA/CPython update procedure and APA 7 primary references.
• Obtain fresh Python 3.10–3.14/package verification with 100% owned-production statement/branch coverage.
• Complete exact-head SAST and Security Scan on security: bind special-purpose address decisions to reviewed IANA registry #223.
• Require the actual pinned Dependency Review action and authoritative exact-head Strix evidence after .github#897 and .github#965 integrate.
• Resolve every current-head finding and obtain counted independent formal approvals.
• Revalidate exact head/base/ancestry, checks, reviews, threads, and rulesets immediately before protected merge.
• Verify the overlay and mapped-address contract from protected main, then close this issue.

Primary references

Internet Assigned Numbers Authority. (2025, October 9). IANA IPv4 Special-Purpose Address Space.

Internet Assigned Numbers Authority. (2025, October 9). IANA IPv6 Special-Purpose Address Space.

Python Software Foundation. (2026). ipaddress — IPv4/IPv6 manipulation library (Python 3.14 documentation).

Non-goals

No full mutable registry mirror, no runtime registry download, no production access to globally unreachable special-purpose destinations, no blanket denial of explicit globally reachable exceptions, no local/private-development widening, and no manual synthesis of security or review evidence.

[seonghobae]

Fresh 2026-08-29 KST traceability checkpoint for canonical Draft #223, unchanged exact head 811ba846757adb44dfc648b9b13761aa1536a110 on unchanged protected main@7faf7a3b8a47980113982914000e724ab6a6cda5:

• Revalidated the live IANA IPv4 and IPv6 Special-Purpose Address Space registries; both still report Last Updated: 2025-10-09. The bounded compatibility overlay and its explicit global exceptions remain source-consistent, including the deliberate conservative 2002::/16 EgressWeave/CPython policy distinction.
• Source docs already contain APA 7-style primary references and an explicit update procedure; no source blob was churned because the authoritative registries did not change.
• Exact-head repository CI and SAST are terminal-success. Security Scan wrapper is green, but job 94723408440 skipped the actual pinned Dependency Review step, so supply-chain evidence remains non-passing.
• Required exact-head strix check 94723399760 is terminal-failure; noema-review is terminal-success and opencode-review is terminal-success. No inline review threads exist; the only submitted formal review is author-side COMMENTED and is not approval.
• The issue/PR's historical Strix dependency .github#965 is stale: #965 is closed unmerged and explicitly superseded by current bounded successor .github#1009. #1009 remains open and non-merge-authoritative; .github#897 remains the canonical fail-closed Dependency Review owner. Both central lanes stay read-only dependencies from EgressWeave.
• Fresh repository searches found no Storybook, Figma, or web design-system surface in EgressWeave, so UI design/accessibility evidence is not applicable to this security-policy slice.

PR #223 body has been reconciled to this live state. Keep Draft; do not merge until corrected protected-central Dependency Review and Strix controls regenerate authoritative evidence on the unchanged current head (or a freshly revalidated successor), all required checks are substantive terminal-success, valid unresolved findings are zero, and a qualifying independent approval exists. No self-approval or administrator bypass.