Attesto.OutboundTarget (Attesto v2.28.0)

Copy Markdown View Source

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_cidrs names 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_loopback is 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

Types

A screened outbound target

Functions

Screen url and return a pinned target map {:ok, %{url, addresses, host, authority}} or {:error, reason}.

Types

error_reason()

@type error_reason() ::
  :invalid_url
  | :insecure_or_hostless_url
  | :invalid_resolver
  | :unresolvable
  | {:blocked_ip, Attesto.IPAddress.ip_address()}

screened()

@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 original host[:port] (with IPv6 bracketed) for the HTTP Host header.

Functions

screen(url, opts \\ [])

@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 (default false). When true, loopback addresses (127.0.0.0/8, ::1, and IPv4-mapped ::ffff:127.0.0.0/8) are permitted. http is accepted only when every address the host resolves to is a loopback address; a destination anywhere else still needs https. Every other special-use range remains blocked. A caller that wants to accept http only for localhost and literal loopback addresses, without a lookup, checks the URL with Attesto.URI.https_identifier?/2 and allow_loopback_http: true first.
  • :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 by Attesto.IPAddress.parse_cidrs!/1, which raises ArgumentError for 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.