webfetch/

guard.rs

//! SSRF guard for the fetch path.
//!
//! `fetch` is reachable from the CLI and the MCP server, so a crafted URL or a
//! prompt-injected link could otherwise be used to reach the cloud metadata
//! endpoint (`169.254.169.254`), `localhost`, or services on the private
//! network. This module rejects non-`http(s)` schemes and any URL whose host
//! resolves to a non-public IP address, on both the initial request and every
//! redirect hop.
//!
//! Set `WEBFETCH_ALLOW_PRIVATE=1` to disable the guard (for trusted internal
//! use or tests).

use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use std::sync::Once;

use url::{Host, Url};

/// Env var that, when set to `1`/`true`, disables the SSRF guard.
const ALLOW_PRIVATE_ENV: &str = "WEBFETCH_ALLOW_PRIVATE";

static ALLOW_PRIVATE_WARNING: Once = Once::new();

/// Whether the guard is disabled via environment opt-out.
///
/// When active, emits a one-line warning to stderr (once per process) so an
/// operator can see the SSRF guard has been turned off and private, loopback,
/// and cloud-metadata addresses are reachable.
pub fn allow_private() -> bool {
    let enabled = matches!(
        std::env::var(ALLOW_PRIVATE_ENV).ok().as_deref(),
        Some("1") | Some("true") | Some("TRUE")
    );
    if enabled {
        ALLOW_PRIVATE_WARNING.call_once(|| {
            eprintln!(
                "warning: {ALLOW_PRIVATE_ENV} is set — SSRF guard disabled; \
                 private, loopback, and metadata IPs are reachable"
            );
        });
    }
    enabled
}

/// Returns true if `ip` is not safe to fetch from a public-web client:
/// loopback, private, link-local (incl. cloud metadata), CGNAT, unspecified,
/// multicast, broadcast, documentation/benchmark ranges, and the IPv6
/// equivalents (ULA, link-local, IPv4-mapped).
pub fn is_blocked_ip(ip: IpAddr) -> bool {
    match ip {
        IpAddr::V4(v4) => is_blocked_ipv4(v4),
        IpAddr::V6(v6) => is_blocked_ipv6(v6),
    }
}

fn is_blocked_ipv4(ip: Ipv4Addr) -> bool {
    let o = ip.octets();
    ip.is_loopback()           // 127.0.0.0/8
        || ip.is_private()         // 10/8, 172.16/12, 192.168/16
        || ip.is_link_local()     // 169.254.0.0/16 (cloud metadata)
        || ip.is_broadcast()      // 255.255.255.255
        || ip.is_unspecified()    // 0.0.0.0
        || ip.is_multicast()      // 224.0.0.0/4
        || ip.is_documentation()  // 192.0.2/24, 198.51.100/24, 203.0.113/24
        || o[0] == 0              // 0.0.0.0/8 "this network"
        || (o[0] == 100 && (o[1] & 0xc0) == 64) // 100.64.0.0/10 CGNAT
        || (o[0] == 192 && o[1] == 0 && o[2] == 0) // 192.0.0.0/24 IETF protocol
        || (o[0] == 198 && (o[1] & 0xfe) == 18) // 198.18.0.0/15 benchmarking
        || o[0] >= 240 // 240.0.0.0/4 reserved (excludes broadcast already)
}

fn is_blocked_ipv6(ip: Ipv6Addr) -> bool {
    // IPv4-mapped / -compatible: classify by the embedded IPv4 address.
    if let Some(v4) = ip.to_ipv4_mapped() {
        return is_blocked_ipv4(v4);
    }
    if let Some(v4) = ip.to_ipv4() {
        // Covers ::a.b.c.d (incl. ::1 loopback and :: unspecified).
        return is_blocked_ipv4(v4);
    }
    let seg = ip.segments();

    // Transition mechanisms embed an IPv4 address inside an IPv6 one, which is
    // a way to name 169.254.169.254 without writing it down. Classify by the
    // address they carry.
    if let Some(v4) = embedded_ipv4(ip) {
        if is_blocked_ipv4(v4) {
            return true;
        }
    }

    ip.is_loopback()
        || ip.is_unspecified()
        || ip.is_multicast()
        || (seg[0] & 0xffc0) == 0xfe80 // fe80::/10 link-local
        || (seg[0] & 0xfe00) == 0xfc00 // fc00::/7 unique local (ULA)
        || (seg[0] == 0x2001 && seg[1] == 0x0db8) // 2001:db8::/32 documentation
}

/// Pull the IPv4 address out of a transition-mechanism IPv6 address.
///
/// - `64:ff9b::/96` and `64:ff9b:1::/48` — NAT64, which forwards to the
///   embedded IPv4 address.
/// - `2002::/16` — 6to4, whose next two groups are the IPv4 address.
fn embedded_ipv4(ip: Ipv6Addr) -> Option<Ipv4Addr> {
    let seg = ip.segments();
    let from = |hi: u16, lo: u16| Some(Ipv4Addr::from(((hi as u32) << 16) | lo as u32));

    // NAT64 well-known prefix: 64:ff9b:: with the IPv4 in the last 32 bits.
    if seg[0] == 0x0064 && seg[1] == 0xff9b && seg[2] == 0 && seg[3] == 0 && seg[4] == 0 {
        return from(seg[6], seg[7]);
    }
    // 6to4: 2002:V4ADDR::/48.
    if seg[0] == 0x2002 {
        return from(seg[1], seg[2]);
    }
    None
}

/// Ports that are never an HTTP service, and that an SSRF probe would love to
/// reach: mail, shells, and databases on an otherwise public host.
///
/// This mirrors what browsers refuse. It is a blocklist rather than an
/// allowlist because HTTP legitimately runs on all sorts of ports (8080, 3000,
/// 8443) and refusing those would break ordinary use.
const BLOCKED_PORTS: [u16; 21] = [
    22,    // ssh
    23,    // telnet
    25,    // smtp
    53,    // dns
    69,    // tftp
    110,   // pop3
    119,   // nntp
    135,   // msrpc
    137,   // netbios
    139,   // netbios
    143,   // imap
    445,   // smb
    465,   // smtps
    587,   // smtp submission
    993,   // imaps
    995,   // pop3s
    1433,  // mssql
    3306,  // mysql
    5432,  // postgres
    6379,  // redis
    11211, // memcached
];

/// An error describing why a URL was rejected by the guard.
#[derive(Debug)]
pub struct BlockedUrl(pub String);

impl std::fmt::Display for BlockedUrl {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "blocked URL: {}", self.0)
    }
}

impl std::error::Error for BlockedUrl {}

/// Only `http(s)` is fetchable. Checked before the env opt-out is consulted:
/// `WEBFETCH_ALLOW_PRIVATE` exists to reach internal *hosts*, not to turn an
/// HTTP client into a file reader.
fn check_scheme(url: &Url) -> Result<(), BlockedUrl> {
    match url.scheme() {
        "http" | "https" => Ok(()),
        other => Err(BlockedUrl(format!("scheme `{other}` not allowed"))),
    }
}

/// Refuse ports that never speak HTTP. See [`BLOCKED_PORTS`].
fn check_port(url: &Url) -> Result<(), BlockedUrl> {
    match url.port() {
        Some(port) if BLOCKED_PORTS.contains(&port) => Err(BlockedUrl(format!(
            "port {port} is not an HTTP service and is not fetchable"
        ))),
        _ => Ok(()),
    }
}

/// Validate a URL's scheme, port and host, resolving and classifying the host.
/// On success returns the validated socket addresses (host resolved to public
/// IPs) so the caller can pin the connection and avoid a DNS-rebinding TOCTOU
/// window.
///
/// Host classification is skipped when the guard is disabled via env; the
/// scheme and port checks always run.
///
/// Async because domain validation resolves DNS via [`tokio::net::lookup_host`]
/// rather than the blocking `std` resolver — important on the async fetch path
/// (and the concurrent MCP server) so a slow lookup never blocks a tokio worker.
pub async fn validate_url(url: &Url) -> Result<Vec<std::net::SocketAddr>, BlockedUrl> {
    check_scheme(url)?;
    check_port(url)?;

    if allow_private() {
        return Ok(Vec::new());
    }

    let host = url
        .host()
        .ok_or_else(|| BlockedUrl(format!("no host in {url}")))?;

    match host {
        Host::Ipv4(ip) => {
            if is_blocked_ip(IpAddr::V4(ip)) {
                return Err(BlockedUrl(format!("host IP {ip} is not public")));
            }
            Ok(Vec::new())
        }
        Host::Ipv6(ip) => {
            if is_blocked_ip(IpAddr::V6(ip)) {
                return Err(BlockedUrl(format!("host IP {ip} is not public")));
            }
            Ok(Vec::new())
        }
        Host::Domain(domain) => validate_domain(url, domain).await,
    }
}

async fn validate_domain(url: &Url, domain: &str) -> Result<Vec<std::net::SocketAddr>, BlockedUrl> {
    // Block obvious local names early; DNS may also resolve these.
    let lower = domain.to_ascii_lowercase();
    if lower == "localhost" || lower.ends_with(".localhost") {
        return Err(BlockedUrl(format!("host `{domain}` is local")));
    }

    let port = url
        .port_or_known_default()
        .ok_or_else(|| BlockedUrl(format!("no port for {url}")))?;

    // Resolve (non-blocking) and require that EVERY resolved address is public,
    // then return them so the connection can be pinned to the validated set.
    let addrs: Vec<_> = tokio::net::lookup_host((domain, port))
        .await
        .map_err(|e| BlockedUrl(format!("cannot resolve `{domain}`: {e}")))?
        .collect();

    if addrs.is_empty() {
        return Err(BlockedUrl(format!("`{domain}` resolved to no addresses")));
    }
    for addr in &addrs {
        if is_blocked_ip(addr.ip()) {
            return Err(BlockedUrl(format!(
                "`{domain}` resolves to non-public IP {}",
                addr.ip()
            )));
        }
    }
    Ok(addrs)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn blocked(s: &str) -> bool {
        is_blocked_ip(s.parse::<IpAddr>().unwrap())
    }

    #[test]
    fn blocks_loopback_and_private_and_metadata() {
        assert!(blocked("127.0.0.1"));
        assert!(blocked("10.0.0.1"));
        assert!(blocked("172.16.5.4"));
        assert!(blocked("192.168.1.1"));
        assert!(blocked("169.254.169.254")); // cloud metadata
        assert!(blocked("100.64.0.1")); // CGNAT
        assert!(blocked("0.0.0.0"));
        assert!(blocked("255.255.255.255"));
        assert!(blocked("224.0.0.1")); // multicast
        assert!(blocked("240.0.0.1")); // reserved
    }

    #[test]
    fn blocks_ipv6_local_and_mapped() {
        assert!(blocked("::1")); // loopback
        assert!(blocked("::")); // unspecified
        assert!(blocked("fe80::1")); // link-local
        assert!(blocked("fc00::1")); // ULA
        assert!(blocked("::ffff:127.0.0.1")); // v4-mapped loopback
        assert!(blocked("::ffff:169.254.169.254")); // v4-mapped metadata
    }

    #[test]
    fn allows_public() {
        assert!(!blocked("1.1.1.1"));
        assert!(!blocked("8.8.8.8"));
        assert!(!blocked("93.184.216.34")); // example.com
        assert!(!blocked("2606:4700:4700::1111")); // cloudflare v6
    }

    /// Transition mechanisms are another way to spell an IPv4 address, so they
    /// are another way to spell the metadata endpoint.
    #[test]
    fn blocks_ipv4_embedded_in_transition_addresses() {
        assert!(blocked("64:ff9b::169.254.169.254")); // NAT64
        assert!(blocked("64:ff9b::a00:1")); // NAT64 → 10.0.0.1
        assert!(blocked("2002:a9fe:a9fe::1")); // 6to4 → 169.254.169.254
        assert!(blocked("2002:7f00:1::1")); // 6to4 → 127.0.0.1
                                            // The same mechanisms pointing at public space stay allowed.
        assert!(!blocked("64:ff9b::8.8.8.8"));
        assert!(!blocked("2002:0808:0808::1")); // 6to4 → 8.8.8.8
    }

    #[tokio::test]
    async fn rejects_non_http_ports() {
        for target in [
            "http://example.com:22/",
            "http://example.com:6379/",
            "https://example.com:3306/",
            "http://example.com:25/",
        ] {
            let url = Url::parse(target).unwrap();
            assert!(
                validate_url(&url).await.is_err(),
                "{target} should be blocked"
            );
        }
    }

    #[test]
    fn allows_ordinary_http_ports() {
        // HTTP runs on all sorts of ports; only the never-HTTP ones are refused.
        for target in [
            "http://example.com/",
            "https://example.com/",
            "http://example.com:8080/",
            "http://example.com:3000/",
            "https://example.com:8443/",
        ] {
            assert!(check_port(&Url::parse(target).unwrap()).is_ok(), "{target}");
        }
    }

    #[tokio::test]
    async fn rejects_non_http_scheme() {
        let url = Url::parse("file:///etc/passwd").unwrap();
        assert!(validate_url(&url).await.is_err());
        let url = Url::parse("ftp://example.com/x").unwrap();
        assert!(validate_url(&url).await.is_err());
    }

    #[tokio::test]
    async fn rejects_literal_metadata_ip_url() {
        let url = Url::parse("http://169.254.169.254/latest/meta-data/").unwrap();
        assert!(validate_url(&url).await.is_err());
    }

    #[tokio::test]
    async fn rejects_localhost_name() {
        let url = Url::parse("http://localhost:8080/admin").unwrap();
        assert!(validate_url(&url).await.is_err());
    }

    /// The env opt-out widens which hosts are reachable; it must not widen
    /// which schemes are. Tested against the scheme check directly rather than
    /// by setting the variable, which is process-global and would race every
    /// other test in this binary.
    #[test]
    fn scheme_check_is_independent_of_the_env_opt_out() {
        for bad in ["file:///etc/passwd", "ftp://example.com/x", "gopher://x/"] {
            assert!(check_scheme(&Url::parse(bad).unwrap()).is_err(), "{bad}");
        }
        assert!(check_scheme(&Url::parse("https://example.com").unwrap()).is_ok());
    }

    // A redirect target is validated by the exact same `validate_url` the fetch
    // loop runs (and pins) on every hop, so a redirect to a private/loopback IP
    // is rejected before any connection is made.
    #[tokio::test]
    async fn rejects_redirect_target_to_private_ip() {
        for target in [
            "http://127.0.0.1/internal",
            "http://10.0.0.1/admin",
            "http://192.168.1.1/",
            "http://169.254.169.254/latest/meta-data/",
        ] {
            let url = Url::parse(target).unwrap();
            assert!(
                validate_url(&url).await.is_err(),
                "redirect target {target} should be blocked"
            );
        }
    }
}