README

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

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:

composer require craftcms/url-validator

Usage

use CraftCms\UrlValidator\UrlValidationException;
use CraftCms\UrlValidator\UrlValidator;

$validator = new UrlValidator();
$url = 'https://example.com/image.jpg';

try {
    // Returns the validated IP addresses the host resolves to.
    $ips = $validator->validate($url);
} catch (UrlValidationException $e) {
    // The URL, or an IP it resolves to, is disallowed.
    echo $e->getMessage();
}

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:

$parts = parse_url($url);
$host = $parts['host'];
$port = $parts['port'] ?? ($parts['scheme'] === 'https' ? 443 : 80);

$client = new \GuzzleHttp\Client();
$response = $client->get($url, [
    'curl' => [
        // Pin the hostname/port to the IPs we just validated.
        CURLOPT_RESOLVE => ["$host:$port:" . implode(',', $ips)],
    ],
]);

Validating an IP address directly

$validator = new UrlValidator();

$validator->validateIp('8.8.8.8'); // true
$validator->validateIp('169.254.169.254'); // false (AWS metadata IP)
$validator->validateIp('10.0.0.5'); // false (private range)

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:

$validator = new UrlValidator(fn(string $host): array => [
    // ...resolved IP addresses for $host
]);

Testing

composer test

composer analyse

composer format

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

License

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

craftcms / url-validator

Maintainers

Package info

Statistics

Security