Screen an outbound server-to-server URL against SSRF and pin the target to a checked IP address.
screen/2 validates that the URL uses https (or http only when
allow_loopback: true, and then only to loopback addresses), resolves both A (:inet) and
AAAA (:inet6) records via :resolver (default :inet.getaddrs/2),
checks every returned address against
Attesto.IPAddress.public_fetch_destination?/1, and returns the URL
and all checked IP addresses in resolution order, alongside the original
host and authority.
Exceptions an operator takes on
Both options below open the screen on purpose. Each is exact: there is no "allow private addresses" switch.
:allowed_cidrsnames the non-public networks a destination may resolve into, for a service that is only reachable at a private address (a cluster-internal name, split-horizon DNS). It is a list of CIDR blocks and nothing else. A host name is not accepted as an allowance, because that would trust DNS: whoever controls the name's answer could point it at any private address. With a block, the answer is still checked, and an address outside every listed block is refused.:allow_loopbackis for development against a server on the local machine.
The screen applies to the one URL it is given. A caller that follows redirects screens every hop with the same options, so a redirect to an address outside the allowance is refused like any other.
Callers connect to the pinned IP while keeping TLS SNI, certificate-hostname
verification, and the HTTP Host header on the original name, closing the
DNS-rebinding TOCTOU window between resolution and connection.
Summary
Functions
Screen url and return a pinned target map {:ok, %{url, addresses, host, authority}}
or {:error, reason}.
Types
@type error_reason() :: :invalid_url | :insecure_or_hostless_url | :invalid_resolver | :unresolvable | {:blocked_ip, Attesto.IPAddress.ip_address()}
@type screened() :: %{ url: String.t(), addresses: [Attesto.IPAddress.ip_address(), ...], host: String.t(), authority: String.t() }
A screened outbound target:
:url- the original URL, unchanged.:addresses- every checked IP tuple, in resolution order (A then AAAA).:host- the original bare hostname for TLS SNI and certificate checks.:authority- the originalhost[:port](with IPv6 bracketed) for the HTTPHostheader.
Functions
@spec screen( String.t(), keyword() ) :: {:ok, screened()} | {:error, error_reason()}
Screen url and return a pinned target map {:ok, %{url, addresses, host, authority}}
or {:error, reason}.
Options:
:resolver- a(charlist(), :inet | :inet6 -> {:ok, [:inet.ip_address()]} | {:error, term()})function (defaults to&:inet.getaddrs/2).:allow_loopback- development/test escape hatch (defaultfalse). Whentrue, loopback addresses (127.0.0.0/8,::1, and IPv4-mapped::ffff:127.0.0.0/8) are permitted.httpis accepted only when every address the host resolves to is a loopback address; a destination anywhere else still needshttps. Every other special-use range remains blocked. A caller that wants to accepthttponly forlocalhostand literal loopback addresses, without a lookup, checks the URL withAttesto.URI.https_identifier?/2andallow_loopback_http: truefirst.:allowed_cidrs- a list of CIDR strings (default[]) naming non-public networks a destination may resolve into, such as["10.20.0.0/16", "fd12:3456::/32"]. Every resolved address must be a public destination or fall inside one of the blocks. Validated byAttesto.IPAddress.parse_cidrs!/1, which raisesArgumentErrorfor a malformed block, a block with host bits set, or a zero-length prefix. This is an SSRF exception: list only networks whose every host the caller is willing to send this request to.