surfguard 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bbb6e8891a860c9c927fbcced35382c1ecdaf965bc4d3e41d56b06f94c5adf2
-  data.tar.gz: 0f309037fa0b37414dd964a9d15afdf0b3a68dbd706a90ee5f24660d8721dd4e
+  metadata.gz: 33a528c627b74ee9bcd275aed8487baa4e357203bb70054dc809d30bba392b90
+  data.tar.gz: 50367ef6f086af1bcecf4da7ea6af2154be1d1f681f20677976f3a6a39dc7fca
 SHA512:
-  metadata.gz: 8f12a95962cfa260c0fc1754d09c78b34c95e3db42dd35837b77b6532a030fd0562cf227d57be5b979c243832cfdd1c71612c495e6c305031f519050dd33d28f
-  data.tar.gz: 6f571b898b5c21214b12c27e2dcf6b8cec6b0fce2005cc48aa9b82753a49b4fd7f1b743abe20bb84141cf393f5c9a7e04d98efe9c57d7bb2692452d5ef0346a5
+  metadata.gz: ac217d4ef2ff066da26d12b2457d93e639faedde02261dcb7bd23a7c587ea875b3eb2a97044ec110cf40deca66e6a71934b1698c3ee7de331893080aeed4beb4
+  data.tar.gz: 946be8043a78695c841c9f694b4910d4300a6876836affbfc150b914d6e3cb1175500981a9a8afc8bdf1dc83c34a5988199dc198eee35423760843ec6046acba

data/README.md

@@ -97,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.2"
+  VERSION = "0.1.3"
 end

data/lib/surfguard.rb

@@ -137,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
@@ -206,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)
@@ -250,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
@@ -270,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.2
+  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