surfguard 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aacbc35ed38c3d141b4feec39de01c2f1ba3abc32c4005c1473e9572d7e19153
-  data.tar.gz: 208a710d8914dde70f9df917052ef2f488945889d66b91c14ec0f4fc9a839ac3
+  metadata.gz: 33a528c627b74ee9bcd275aed8487baa4e357203bb70054dc809d30bba392b90
+  data.tar.gz: 50367ef6f086af1bcecf4da7ea6af2154be1d1f681f20677976f3a6a39dc7fca
 SHA512:
-  metadata.gz: f363b4ae2a0f75f5de64e4c160b7080944183cbd062eba85838f91518cfd3526a59ca64378499d9c66f582bdf8aeacb9325486c760e3ea0f3f7e22fc39015a5f
-  data.tar.gz: 5af39621dd81510a02136bd56c7b90eb9e5c1578ab79910b05f80f4a9c869c4686288b6d553cb4b7ec1366f6ead25dba2f5f0d92db195d1cdebdb2c2d0ccbf37
+  metadata.gz: ac217d4ef2ff066da26d12b2457d93e639faedde02261dcb7bd23a7c587ea875b3eb2a97044ec110cf40deca66e6a71934b1698c3ee7de331893080aeed4beb4
+  data.tar.gz: 946be8043a78695c841c9f694b4910d4300a6876836affbfc150b914d6e3cb1175500981a9a8afc8bdf1dc83c34a5988199dc198eee35423760843ec6046acba

data/README.md

@@ -77,6 +77,7 @@ question it was asked and never raises; use `enforce_public_ip` or
 |---|---|
 | IPv4 private (10/8, 172.16/12, 192.168/16), loopback (127/8), link-local (169.254/16) | refuse |
 | CGNAT (100.64/10), benchmark (198.18/15), TEST-NETs, IETF (192.0.0/24), 6to4 relay anycast (192.88.99/24), multicast (224/4), reserved (240/4), "this" (0/8) | refuse |
+| Azure WireServer `168.63.129.16/32` | refuse — a fixed Azure platform/fabric alias, not an RFC special-use range |
 | IPv6 ULA (fc00::/7, incl. IMDSv6 `fd00:ec2::254`), loopback (::1), link-local (fe80::/10), site-local (fec0::/10), multicast (ff00::/8), unspecified (::), discard/dummy (100::/64, 100:0:0:1::/64), documentation (2001:db8::/32, 3fff::/20), SRv6 SID (5f00::/16) | refuse |
 | IETF protocol assignments (2001::/23) | refuse by default, including Teredo, benchmark, PCP/TURN/DNS-SD anycast to nearby infrastructure, deprecated ORCHID, ORCHIDv2, DET, and unallocated space; allow only AMT (2001:3::/32) and AS112-v6 (2001:4:112::/48) |
 | IPv4-mapped `::ffff:0:0/96`, IPv4-compatible `::/96` | refuse outright |
@@ -96,7 +97,9 @@ local overlay rather than routed as ordinary public IP destinations.
 **1. Numeric parsing and name resolution are both part of the policy.** Before asking DNS,
 Surfguard asks the system numeric-host parser used by `Socket`/`Net::HTTP` whether the token is an
 address. This recognizes non-canonical decimal, hexadecimal, octal, and shortened IPv4 forms. A
-numeric token is classified directly and is never sent through DNS or a search domain.
+numeric token is classified directly and is never sent through DNS or a search domain. Malformed
+IPv4-shaped variants with empty dot labels or invalid zone/prefix suffixes are refused rather than
+reinterpreted as DNS names.
 
 Names resolve with `Resolv.getaddresses`, which uses Ruby's usual hosts-plus-DNS chain, honours
 search domains, and returns every address. The obvious alternatives each drop something a guard

data/lib/surfguard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Surfguard
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/surfguard.rb

@@ -59,15 +59,17 @@ module Surfguard
 
   extend self
 
-  # IPv4 special-use ranges that must never be a fetch target (RFC 5735/6890,
-  # plus CGNAT and benchmarking). RFC1918 / loopback / link-local are also
-  # covered by the IPAddr predicates in #disallowed_ipv4?; they are restated here
-  # so the policy is complete and auditable in one place.
+  # IPv4 special-use ranges and exact platform aliases that must never be a
+  # fetch target (RFC 5735/6890, plus CGNAT and benchmarking). RFC1918 /
+  # loopback / link-local are also covered by the IPAddr predicates in
+  # #disallowed_ipv4?; they are restated here so the policy is complete and
+  # auditable in one place.
   DISALLOWED_IPV4 = [
     IPAddr.new("0.0.0.0/8"),        # "This" network (RFC 1122)
     IPAddr.new("10.0.0.0/8"),       # Private (RFC 1918)
     IPAddr.new("100.64.0.0/10"),    # Carrier-grade NAT (RFC 6598)
     IPAddr.new("127.0.0.0/8"),      # Loopback (RFC 1122)
+    IPAddr.new("168.63.129.16/32"), # Azure host-node WireServer virtual IP
     IPAddr.new("169.254.0.0/16"),   # Link-local (RFC 3927) — includes the cloud metadata endpoint
     IPAddr.new("172.16.0.0/12"),    # Private (RFC 1918)
     IPAddr.new("192.0.0.0/24"),     # IETF protocol assignments (RFC 6890)
@@ -135,6 +137,11 @@ module Surfguard
   # the NAT64 well-known prefix it is a fixed /96, so decode the low 32 bits.
   IPV4_TRANSLATABLE = IPAddr.new("::ffff:0:0:0/96") # RFC 2765
 
+  # IPv4-compatible IPv6 is deprecated and must never be a DNS fetch target.
+  # Classify the prefix directly instead of calling IPAddr#ipv4_compat?, which
+  # has been obsolete since Ruby 2.5 and is expected to disappear in ipaddr 2.x.
+  IPV4_COMPATIBLE = IPAddr.new("::/96")
+
   # Every PUBLIC address the host resolves to, IPv4 ahead of IPv6, DNS order
   # preserved within each family so a provider's round-robin still spreads load.
   # Empty when the host resolves but every address is blocked; raises
@@ -204,7 +211,7 @@ module Surfguard
 
     # DNS never legitimately returns an IPv4 address embedded these two ways, so
     # refuse them regardless of the address they wrap.
-    if ipaddr.ipv4_mapped? || ipaddr.ipv4_compat?
+    if ipaddr.ipv4_mapped? || IPV4_COMPATIBLE.include?(ipaddr)
       true
     elsif ipaddr.ipv4?
       disallowed_ipv4?(ipaddr)
@@ -248,6 +255,13 @@ module Surfguard
   # here. IPAddr remains as a fallback for syntax it alone accepts, notably a
   # full-width /32 or /128 host prefix. nil means the token is a name.
   def numeric_literals(host)
+    # Refuse malformed IPv4-shaped text before consulting the platform parser.
+    # Some connection layers may accept decorations that others reject; none
+    # may turn them into a public DNS name after Surfguard classified them.
+    if malformed_numeric_host_candidate?(host)
+      raise InvalidHost, "malformed numeric-looking host #{host.inspect}"
+    end
+
     Socket.getaddrinfo(
       host, nil, Socket::AF_UNSPEC, Socket::SOCK_STREAM, 0, Socket::AI_NUMERICHOST
     ).map { |address| IPAddr.new(address[3]) }.uniq
@@ -268,11 +282,42 @@ module Surfguard
     text = host.to_s
     return true if text.include?(":") # Invalid IPv6 syntax is never a DNS name.
 
-    parts = text.split(".", -1)
+    legacy_ipv4_shape?(text)
+  end
+
+  def malformed_numeric_host_candidate?(host)
+    text = host.to_s
+    return false if text.include?(":") # IPv6 literals and zones go to AI_NUMERICHOST.
+
+    # Isolate the address: drop every leading separator, then keep only what
+    # precedes the next one. Removing a single separator would let a second one
+    # ("//127.0.0.1", "%127.0.0.1%lo") hide the legacy IPv4 shape, so the token
+    # would reach the platform parser and, failing there, be handed to DNS as a
+    # name — the parser/resolver identity gap this check exists to close.
+    core = text.sub(%r{\A[%/]+}, "")[%r{\A[^%/]*}]
+    labels = core.split(".", -1)
+    malformed = core != text || labels.any?(&:empty?)
+    return false unless malformed && legacy_ipv4_shape?(core)
+
+    # Full-width host prefixes are documented inputs and IPAddr parses them
+    # unambiguously. Shorter or otherwise invalid prefixes remain malformed.
+    return false if full_width_host_literal?(text)
+
+    true
+  end
+
+  def legacy_ipv4_shape?(text)
+    parts = text.split(".", -1).reject(&:empty?)
     (1..4).cover?(parts.length) &&
       parts.all? { |part| part.match?(/\A(?:0[xX][0-9A-Fa-f]+|[0-9]+)\z/) }
   end
 
+  def full_width_host_literal?(text)
+    host_address?(IPAddr.new(text))
+  rescue IPAddr::InvalidAddressError
+    false
+  end
+
   # nil for anything IPAddr cannot parse. A shortened prefix is not a host and
   # is rejected rather than normalized to its network address or sent to DNS.
   def ip_literal(host)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: surfguard
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - 37signals
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies: []
 description: 'Surfguard resolves a hostname to the public IP addresses it points at
   and refuses anything that would reach an internal network: private, loopback, link-local