Download the PHP package craftcms/url-validator without Composer

URL Validator

Validate URLs and IP addresses before opening a connection, to guard against Server-Side Request Forgery (SSRF) and DNS rebinding.

By default, the validator rejects:

• Schemes other than http and https (blocking file://, ftp://, gopher://, etc.)
• Raw IP literals, hex-encoded hostnames, and well-known cloud-metadata domains (AWS, GCP, Kubernetes, …)
• Hostnames that resolve to a private, reserved, loopback, link-local, CGNAT, or cloud-metadata IP address
• IPv6 addresses that embed or tunnel an IPv4 address (IPv4-mapped, NAT64, 6to4, Teredo, …)

All checks happen before any connection is opened, and the validator returns the set of IP addresses the host resolved to so you can pin the eventual connection to them (preventing DNS rebinding between validation and download).

Installation

Install the package via Composer:

Usage

Use the resolved IPs to pin the connection (e.g. with cURL’s CURLOPT_RESOLVE) so the hostname can’t be re-resolved to a different, internal address between validation and the request:

Validating an IP address directly

validateScheme(string $url): bool and validateHostname(string $url): bool are also exposed if you need to check those pieces individually.

Customizing DNS resolution

By default hostnames are resolved against the system DNS. You can pass a custom resolver to the constructor — useful for testing, or for plugging in a caching/alternate resolver:

Customizing other options

The following options can also be configured by passing an array to the constructor as a second parameter. The following options are customizable:

• allowedSchemes
• disallowedHostnames
• disallowedIpv4Addresses
• disallowedIpv4Ranges
• disallowedIpv6Addresses
• ipv4FilterFlags (the FILTER_FLAG_IPV4 will always be added automatically)
• ipv6FilterFlags (the FILTER_FLAG_IPV6 will always be added automatically)
• allowedPrivateHosts (see Allowing internal hosts)

See the codebase for the default values and expected types.

Allowing internal hosts

Private IP addresses (e.g. 10.0.0.0/8, 192.168.0.0/16, fd00::/8) are rejected by default. If your app needs to reach internal services, for example in local development or between containers in Docker or Kubernetes, list the hostnames that may resolve to private addresses:

• An exact hostname matches only that host.
• A leading *. wildcard matches any subdomain, e.g. *.site.testing.local matches api.site.testing.local and a.b.site.testing.local, but not site.testing.local itself.
• * isn’t allowed anywhere else, and a bare * isn’t allowed at all. Invalid patterns throw an InvalidArgumentException.
• Only the private-range check is relaxed for these hosts. Loopback, link-local, reserved and cloud-metadata addresses, and disallowed hostnames such as kubernetes.default.svc, are still rejected.

[!WARNING]

• Only list hostnames whose DNS you control.
• List individual services rather than whole internal domains. Every listed host is reachable by anyone who can make your app send a request to it.

Pinning with curl

Validating a URL and then letting curl resolve its hostname again leaves room for DNS rebinding. curlResolve() validates the URL and returns a CURLOPT_RESOLVE value that pins the hostname and port to the validated IP addresses.

Using with Guzzle

Requires guzzlehttp/guzzle. GuzzleMiddleware validates and pins every request a Guzzle client sends, including the ones sent while following redirects. A disallowed URL makes the request throw an UrlValidationException.

If the client has already been created, you can add the middleware to its handler stack:

Otherwise, create the client with the handler stack:

[!NOTE]

• Pinning only works with Guzzle’s curl handler. The middleware turns the stream request option off, because the stream handler would ignore the pin.
• When requests go through an HTTP proxy, the proxy resolves the hostname itself, so the pin doesn’t apply there. URLs are still validated, but the proxy should enforce its own egress rules.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Pixel & Tonic
• All Contributors

License

The MIT License (MIT). Please see License File for more information.