surfguard 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 743b735d0f0abcce2bcfa3660b7f658cceb1a760b90d970a86df76e91cb19622
-  data.tar.gz: 866a867fbde519a8512ae93c4fb6d8051d01b7de1591210e7f40f071376860a0
+  metadata.gz: aacbc35ed38c3d141b4feec39de01c2f1ba3abc32c4005c1473e9572d7e19153
+  data.tar.gz: 208a710d8914dde70f9df917052ef2f488945889d66b91c14ec0f4fc9a839ac3
 SHA512:
-  metadata.gz: c3c1b340115fa7bc1190bec41e76ae2171ec23dfab10855122ddc91c3efb74864cdeed7960c4ab6c8d60770f04f520712e36118bf5c39750486b69a9f735f310
-  data.tar.gz: 587059deea1f701b3a8df14558a7b85c4dc24deb229a4fb61bdb02358c4120647c2e2624da498d4ce15658cbe5de77a1e394af50bf8acd8ac5f9ec080ee6cdef
+  metadata.gz: f363b4ae2a0f75f5de64e4c160b7080944183cbd062eba85838f91518cfd3526a59ca64378499d9c66f582bdf8aeacb9325486c760e3ea0f3f7e22fc39015a5f
+  data.tar.gz: 5af39621dd81510a02136bd56c7b90eb9e5c1578ab79910b05f80f4a9c869c4686288b6d553cb4b7ec1366f6ead25dba2f5f0d92db195d1cdebdb2c2d0ccbf37

data/README.md

@@ -7,19 +7,10 @@ One SSRF address policy for Ruby apps that fetch a URL someone else supplied.
 It consolidates several drifting in-house copies of this policy into one — copies that had grown
 four different ideas of what "internal" means, including one that decoded a NAT64 prefix whose length
 is not recoverable from the address. This gem is their union, decided once and tested against the
-full IPv4 × IPv6 range matrix.
+IPv4 × IPv6 range matrix it enforces.
 
 ## Installation
 
-Not yet published to RubyGems — `v0.1.0` will be the first packaged release. Until it ships,
-install from source:
-
-```ruby
-gem "surfguard", github: "basecamp/surfguard"
-```
-
-Once `v0.1.0` is published:
-
 ```ruby
 gem "surfguard"
 ```
@@ -35,7 +26,7 @@ Surfguard.resolve_public_ips("feeds.example.com")
 # => ["93.184.216.34", "2606:2800:220:1:248:1893:25c8:1946"]   (IPv4 first, blocked removed)
 # Iterate THIS list on failover; do not resolve again inside a retry loop.
 
-# Non-pinning caller (hands the hostname straight to Net::HTTP, which resolves again):
+# Non-pinning preflight (hands the hostname to Net::HTTP, which resolves again):
 Surfguard.resolvable_public_ip?("https://feeds.example.com/atom")  # => true only if EVERY address is public
 Surfguard.enforce_public_ip(url)                                   # raises otherwise
 
@@ -46,6 +37,21 @@ Surfguard.resolve_public_ip(url)   # => "93.184.216.34" or nil
 Surfguard.blocked_address?(IPAddr.new("169.254.169.254"))  # => true
 ```
 
+The non-pinning helpers conservatively require every address in their lookup to be public. They do
+not bind the later connection to that answer, so a second lookup can still change underneath them.
+Pinning is required when attacker-controlled DNS or DNS rebinding is in scope.
+
+The direct address APIs accept endpoint addresses, not networks. A prefix shorter than `/32` or
+`/128` is refused rather than normalized into a host: `blocked_address?("10.0.0.1/8")` is `true`,
+and `resolve_public_ips("10.0.0.1/8")` is `[]`.
+
+### Caller responsibilities
+
+Surfguard classifies an address; it is not an HTTP client. The URL helpers do not restrict schemes,
+follow redirects, or make the request. Allow only the schemes your fetcher supports, and validate
+and pin every redirect target just as you did the original target. A pinning client must connect to
+the selected returned address while retaining the original hostname for HTTP Host and TLS identity.
+
 ## Refused vs. unresolvable
 
 "We refuse that address" and "the host didn't answer" are different answers, and
@@ -71,35 +77,54 @@ 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 |
-| IPv6 ULA (fc00::/7, incl. IMDSv6 `fd00:ec2::254`), loopback (::1), link-local (fe80::/10), site-local (fec0::/10), multicast (ff00::/8), unspecified (::), discard (100::/64), Teredo (2001::/32), docs (2001:db8::/32), benchmark (2001:2::/48) | refuse |
+| 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 |
 | **SIIT `::ffff:0:0:0/96`** | decode embedded IPv4 (low 32 bits), re-check |
 | NAT64 well-known `64:ff9b::/96` | decode embedded IPv4 (low 32 bits), re-check |
 | **RFC 8215 NAT64 local-use `64:ff9b:1::/48`** | **refuse outright** — the Pref64 length is not recoverable from the address (RFC 6052 §2.2), so a low-32-bit decode reads the wrong octets; and the block is never globally routed |
 | 6to4 `2002::/16` | refuse (a 6to4 address is just an IPv4 address in disguise) |
 
-## Two things worth knowing
+This is an SSRF address policy, not a label-only copy of the IANA special-purpose registry. It
+refuses internal, non-destination, non-global domain, and overlay-identifier ranges plus transition
+encodings that can conceal a blocked target. Actual globally reachable IP-layer services such as
+AMT and AS112 remain valid; ORCHID and DET identifiers do not, because they can be interpreted by a
+local overlay rather than routed as ordinary public IP destinations.
 
-**1. The resolver is part of the policy.** Surfguard resolves with `Resolv.getaddresses`, which
-honours `/etc/hosts` and search domains **and** returns every address. The obvious alternatives each
-drop something a guard can't afford to lose:
+## Three things worth knowing
+
+**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.
+
+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
+can't afford to lose:
 
 - `Resolv.getaddress` honours `/etc/hosts` but returns only the **first** address — so an AAAA-only
   host deterministically takes the IPv6 path, and a multi-homed host is validated on one address
   while the connection may use another.
-- `Resolv::DNS.open` returns every address but **ignores** `/etc/hosts` and search domains — so it
-  validates a different set than `Net::HTTP` (which resolves through `getaddrinfo`) will actually
-  connect to. Demonstrable: `Resolv.getaddresses("localhost")` → `["::1","127.0.0.1"]` while
-  `Resolv::DNS.open`'s `each_address("localhost")` → `["::","0.0.0.0"]`.
+- `Resolv::DNS.open` returns every DNS address but **ignores** `/etc/hosts` and the other parts of
+  the default resolver chain.
 
-`getaddresses` is both complete (every address) and faithful (the same chain the connection layer
-uses).
+Ruby `Resolv` is not a universal substitute for the system `getaddrinfo` name-service chain. A host
+with custom NSS sources such as mDNS or LDAP can produce a different answer at connection time.
+Pinning a returned address avoids that second name lookup; non-pinning deployments need a resolver
+configuration in which Ruby's hosts-plus-DNS answers match the connection layer, or an independent
+egress control. Resolver-chain equivalence does not eliminate the separate DNS-rebinding window.
 
 **2. A resolver-level "no AAAA" switch is not a mitigation.** Disabling AAAA at the system resolver
 (for example Kamal's `dns-opt: no-aaaa`) is a glibc `getaddrinfo` option. Surfguard resolves through
 pure-Ruby `Resolv`, which requests AAAA regardless, so IPv6 answers still reach it. Don't treat that
 deploy setting as if it narrowed Surfguard's input.
 
+**3. Custom DNS64 prefixes need their own enforcement.** Surfguard can decode and re-check the
+fixed NAT64 well-known prefix `64:ff9b::/96`, and it refuses the RFC 8215 local-use block outright.
+It cannot infer the embedded IPv4 address in an arbitrary network-specific Pref64 from the
+synthesized IPv6 address alone. A deployment using DNS64 with another Pref64 must enforce the same
+blocked-address policy at its DNS64/NAT64 or egress layer.
+
 ## Testing
 
 ```bash
@@ -116,5 +141,5 @@ issue tracker.
 ## Status
 
 Extracted and consolidated from several in-house SSRF guards, tested against the full
-IPv4 × IPv6 special-use matrix. Resolve-and-classify only; callers pin. See the
+policy matrix. Resolve-and-classify only; callers pin. See the
 [releases page](https://github.com/basecamp/surfguard/releases) for versions and changes.

data/SECURITY.md

@@ -23,16 +23,20 @@ Anything that lets a blocked address through, for example:
 - An address in a blocked range that Surfguard classifies as public.
 - A resolution path (encoding, embedding, transition mechanism) that reaches a blocked address
   despite validation.
-- A discrepancy between what Surfguard validates and what a caller following the documented
-  pinning contract would connect to.
+- A parser or resolver discrepancy that lets a caller following a documented API contract connect
+  to a different address than Surfguard classified.
+
+Surfguard does not perform the fetch itself. Scheme restrictions, redirect handling, connection
+pinning, custom DNS64 prefixes, and nonstandard NSS sources have caller or deployment requirements
+documented in the README. Those boundaries by themselves are not classification bugs, but a bypass
+when the documented contract is followed qualifies.
 
 Non-security bugs and questions belong in the
 [regular issue tracker](https://github.com/basecamp/surfguard/issues).
 
 ## Supported versions
 
-No packaged release exists yet, so `main` is the supported version. Once releases ship, it
-becomes the latest released version. Fixes ship as a new release, not backports.
+The latest released version. Fixes ship as a new release, not backports.
 
 ## What to expect
 

data/lib/surfguard/version.rb

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

data/lib/surfguard.rb

@@ -2,6 +2,7 @@
 
 require "ipaddr"
 require "resolv"
+require "socket"
 require "uri"
 
 require_relative "surfguard/version"
@@ -15,13 +16,16 @@ require_relative "surfguard/version"
 # Two policy decisions the copies drifted on, settled here and explained where
 # they live in the code:
 #
-#   * Resolver (see .resolve_public_ips): resolve with Resolv.getaddresses, which
-#     honours /etc/hosts and search domains AND returns every address. One copy
-#     used Resolv.getaddress (honours hosts, but only the FIRST address, so an
-#     AAAA-only host deterministically selected the IPv6 path); another used
-#     Resolv::DNS.open (all addresses, but ignores /etc/hosts, so it validated a
-#     different set than Net::HTTP would actually connect to). getaddresses is
-#     both complete and faithful to what the connection layer resolves.
+#   * Resolver (see .resolve_public_ips): first use getaddrinfo's numeric-only
+#     parser so legacy decimal, hex, octal, and short IPv4 forms mean exactly
+#     what they do to Net::HTTP; never send those tokens to DNS. Names resolve
+#     with Resolv.getaddresses, which honours /etc/hosts and search domains AND
+#     returns every address. One copy used Resolv.getaddress (honours hosts, but
+#     only the FIRST address, so an AAAA-only host deterministically selected the
+#     IPv6 path); another used Resolv::DNS.open (all addresses, but ignores
+#     /etc/hosts, so it validated a different set than Net::HTTP would connect
+#     to). getaddresses is complete for Ruby's hosts-plus-DNS chain; system
+#     getaddrinfo may additionally consult NSS sources such as mDNS or LDAP.
 #
 #   * `no-aaaa` in Kamal `dns-opt` is NOT a mitigation. It is a glibc
 #     getaddrinfo option; every guard here resolves through pure-Ruby Resolv,
@@ -39,6 +43,12 @@ require_relative "surfguard/version"
 module Surfguard
   class Violation < StandardError; end
 
+  # Internal signal for something IPAddr can parse, but which is a network
+  # rather than a host. Keep it separate from a lookup failure: callers must
+  # refuse these inputs without asking DNS to reinterpret them as names.
+  class InvalidHost < ArgumentError; end
+  private_constant :InvalidHost
+
   # The host answered with no address at all. Deliberately NOT a Violation:
   # nothing was refused here, the lookup simply came back empty, which is
   # usually a transient upstream failure. A caller that gives up permanently on
@@ -78,14 +88,31 @@ module Surfguard
   DISALLOWED_IPV6 = [
     IPAddr.new("::/128"),           # Unspecified (RFC 4291)
     IPAddr.new("100::/64"),         # Discard-only (RFC 6666)
+    IPAddr.new("100:0:0:1::/64"),   # Dummy IPv6 destination (RFC 9780)
     IPAddr.new("2001::/32"),        # Teredo (RFC 4380)
     IPAddr.new("2001:2::/48"),      # Benchmark testing (RFC 5180)
     IPAddr.new("2001:db8::/32"),    # Documentation (RFC 3849)
     IPAddr.new("2002::/16"),        # 6to4 (RFC 3056)
+    IPAddr.new("3fff::/20"),        # Documentation (RFC 9637)
+    IPAddr.new("5f00::/16"),        # SRv6 SIDs, confined to SR domains (RFC 9602)
     IPAddr.new("fec0::/10"),        # Deprecated site-local (RFC 3879)
     IPAddr.new("ff00::/8")          # Multicast (RFC 4291)
   ].freeze
 
+  # The IANA parent assignment is non-source, non-destination, non-forwardable,
+  # and non-global unless a more-specific allocation says otherwise. Refuse it
+  # by default so unallocated/future-special space cannot become an internal
+  # fetch path. These are the current, narrowly scoped IP-layer services whose
+  # registrations explicitly permit globally reachable destinations without
+  # selecting nearby infrastructure. PCP, TURN, and DNS-SD SRP anycast remain
+  # refused because they deliberately target on-path or local services. ORCHID,
+  # ORCHIDv2, and DET are overlay identifiers, not ordinary IP-layer locators.
+  IETF_PROTOCOL_ASSIGNMENTS = IPAddr.new("2001::/23")
+  GLOBALLY_REACHABLE_IETF_ASSIGNMENTS = [
+    IPAddr.new("2001:3::/32"),       # AMT (RFC 7450)
+    IPAddr.new("2001:4:112::/48")    # AS112-v6 (RFC 7535)
+  ].freeze
+
   # NAT64 embeds an IPv4 target that must be re-checked as IPv4. The well-known
   # prefix is a fixed /96, so the embedded octets are always the low 32 bits:
   # decode and re-check them, and NAT64 to a public address still resolves.
@@ -123,6 +150,8 @@ module Surfguard
              .partition(&:ipv4?)
              .flatten
              .map(&:to_s)
+  rescue InvalidHost
+    []
   end
 
   # True only if the URL's host resolves to at least one address and NONE are
@@ -171,6 +200,7 @@ module Surfguard
   # it cannot parse is blocked.
   def blocked_address?(ip)
     ipaddr = ip.is_a?(IPAddr) ? ip : IPAddr.new(ip.to_s)
+    return true unless host_address?(ipaddr)
 
     # DNS never legitimately returns an IPv4 address embedded these two ways, so
     # refuse them regardless of the address they wrap.
@@ -191,15 +221,19 @@ module Surfguard
 
   private
 
-  # An IP-literal host skips DNS so a public literal URL resolves directly and an
-  # internal literal is still caught by blocked_address?. Otherwise resolve via
-  # Resolv.getaddresses — the Hosts+DNS chain, matching what the connection layer
-  # will use, and returning every address. Returns [IPAddr].
+  # A numeric host skips DNS so a public literal URL resolves directly and an
+  # internal literal is still caught by blocked_address?. Socket's numeric-only
+  # parser comes first because it accepts every legacy IPv4 spelling the
+  # connection layer does (decimal, hex, octal, and shortened forms), while
+  # IPAddr does not. Otherwise resolve via Resolv.getaddresses, returning every
+  # address from Ruby's hosts-plus-DNS chain. System getaddrinfo may consult
+  # additional NSS sources; pinning an address returned here avoids that second
+  # resolution. Returns [IPAddr].
   def resolve(host)
-    literal = ip_literal(host)
+    literals = numeric_literals(host)
 
-    if literal
-      [ literal ]
+    if literals
+      literals
     else
       Resolv.getaddresses(host).map { |a| IPAddr.new(a) }
     end
@@ -207,15 +241,53 @@ module Surfguard
     []
   end
 
-  # nil for anything that isn't already an address. Kept separate so the DNS
-  # call above sits in the method body, where the ResolvError rescue can reach
-  # it — inside a sibling rescue clause it could not.
+  # Every address Socket's numeric-only parser finds. AI_NUMERICHOST guarantees
+  # this call never falls through to DNS. Its success is authoritative: these
+  # tokens must not be reinterpreted as names by Resolv, because Net::HTTP's
+  # getaddrinfo call will reinterpret them as the numeric addresses returned
+  # 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)
+    Socket.getaddrinfo(
+      host, nil, Socket::AF_UNSPEC, Socket::SOCK_STREAM, 0, Socket::AI_NUMERICHOST
+    ).map { |address| IPAddr.new(address[3]) }.uniq
+  rescue SocketError
+    literal = ip_literal(host)
+    return [ literal ] if literal
+
+    # An ordinary name may proceed to Resolv after AI_NUMERICHOST says it is
+    # not numeric. A token shaped like a legacy IPv4 spelling may not: if the
+    # system numeric parser itself failed abnormally, asking DNS would recreate
+    # the parser/resolver identity gap this method exists to close.
+    raise InvalidHost, "numeric-looking host #{host.inspect} could not be classified" if numeric_host_candidate?(host)
+
+    nil
+  end
+
+  def numeric_host_candidate?(host)
+    text = host.to_s
+    return true if text.include?(":") # Invalid IPv6 syntax is never a DNS name.
+
+    parts = text.split(".", -1)
+    (1..4).cover?(parts.length) &&
+      parts.all? { |part| part.match?(/\A(?:0[xX][0-9A-Fa-f]+|[0-9]+)\z/) }
+  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)
-    IPAddr.new(host)
+    ipaddr = IPAddr.new(host)
+    raise InvalidHost, "#{host.inspect} is a network, not a host" unless host_address?(ipaddr)
+
+    ipaddr
   rescue IPAddr::InvalidAddressError
     nil
   end
 
+  def host_address?(ipaddr)
+    ipaddr.prefix == (ipaddr.ipv4? ? 32 : 128)
+  end
+
   def host_of(url)
     # URI#host is "" for "http://" and nil when there's no authority at all.
     # Neither is a name to look up, so both are malformed rather than a lookup
@@ -232,7 +304,10 @@ module Surfguard
   end
 
   def disallowed_ipv6?(ipaddr)
+    return false if GLOBALLY_REACHABLE_IETF_ASSIGNMENTS.any? { |range| range.include?(ipaddr) }
+
     ipaddr.private? || ipaddr.loopback? || ipaddr.link_local? ||
+      IETF_PROTOCOL_ASSIGNMENTS.include?(ipaddr) ||
       DISALLOWED_IPV6.any? { |range| range.include?(ipaddr) }
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: surfguard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - 37signals