http_acl_reqwest/

lib.rs

#![doc = include_str!("../README.md")]
#![warn(missing_docs)]

use std::future;
use std::net::{SocketAddr, ToSocketAddrs};
use std::sync::Arc;

use anyhow::anyhow;
use http::Extensions;
use http_acl::utils::authority::{Authority, Host};
use reqwest::{
    Request, Response,
    dns::{Name, Resolve, Resolving},
    redirect,
};
use reqwest_middleware::{Error, Middleware, Next};
use thiserror::Error;

pub use http_acl::{self, HttpAcl, HttpAclBuilder};

#[derive(Debug, Clone)]
/// A reqwest middleware that enforces an [`HttpAcl`].
///
/// On each request, checks (in order) the scheme, method, host or IP, port, headers,
/// URL path, and finally any custom `ValidateFn`, returning
/// [`reqwest_middleware::Error::Middleware`] on the first denial. This alone only
/// covers the request as originally built: attach [`Self::dns_resolver`] to the
/// `Client` as well, so domains are checked against the ACL as they resolve, and
/// [`Self::redirect_policy`], so redirect targets are checked too. See the crate-level
/// documentation for a full example wiring all three together.
pub struct HttpAclMiddleware {
    acl: Arc<HttpAcl>,
}

impl HttpAclMiddleware {
    /// Create a new HTTP ACL middleware from an already-built [`HttpAcl`].
    pub fn new(acl: HttpAcl) -> Self {
        Self { acl: Arc::new(acl) }
    }

    /// Get the [`HttpAcl`] this middleware enforces.
    pub fn acl(&self) -> Arc<HttpAcl> {
        self.acl.clone()
    }

    /// Create a DNS resolver that enforces the ACL, using `getaddrinfo` to actually
    /// resolve hostnames.
    ///
    /// Set via `Client::builder().dns_resolver(...)`. Without this, a domain that
    /// resolves to a denied or non-global IP (the classic SSRF vector) is never
    /// checked, since [`HttpAclMiddleware`] only ever sees the request as built, not
    /// the address it eventually connects to.
    pub fn dns_resolver(&self) -> Arc<HttpAclDnsResolver> {
        Arc::new(HttpAclDnsResolver::new(self))
    }

    /// Same as [`Self::dns_resolver`], but delegating actual resolution to a custom
    /// [`Resolve`] implementation instead of `getaddrinfo`.
    pub fn with_dns_resolver(&self, dns_resolver: Arc<dyn Resolve>) -> Arc<HttpAclDnsResolver> {
        Arc::new(HttpAclDnsResolver::with_dns_resolver(self, dns_resolver))
    }

    /// Create a [`redirect::Policy`] that enforces the ACL on every redirect hop.
    ///
    /// # Why this is necessary
    ///
    /// `HttpAclMiddleware` only validates the request it is given. By default `reqwest`
    /// follows HTTP redirects internally (up to 10 hops) before control ever returns to
    /// the middleware chain, so a server an allowed host redirects to - e.g. a `302` to
    /// `http://169.254.169.254/` - is never re-checked against the ACL. Set this policy
    /// on the `Client` (in addition to [`Self::dns_resolver`]) to close that gap:
    ///
    /// ```no_run
    /// # use http_acl_reqwest::HttpAclMiddleware;
    /// # use http_acl::HttpAcl;
    /// # let middleware = HttpAclMiddleware::new(HttpAcl::builder().build());
    /// let client = reqwest::Client::builder()
    ///     .dns_resolver(middleware.dns_resolver())
    ///     .redirect(middleware.redirect_policy())
    ///     .build()
    ///     .unwrap();
    /// ```
    ///
    /// Uses a maximum of 10 redirects, matching `reqwest`'s own default. Use
    /// [`Self::redirect_policy_with_max`] to customise this.
    ///
    /// # Limitations
    ///
    /// Only the scheme, host/IP, port, and URL path of each redirect target can be
    /// checked this way - `reqwest`'s redirect policy does not expose the headers or
    /// body of the redirected request, so denied headers, denied bodies, and any custom
    /// `validate_fn` are not re-evaluated per hop.
    pub fn redirect_policy(&self) -> redirect::Policy {
        self.redirect_policy_with_max(10)
    }

    /// Same as [`Self::redirect_policy`], but with a custom maximum number of redirects.
    pub fn redirect_policy_with_max(&self, max_redirects: usize) -> redirect::Policy {
        let acl = self.acl.clone();
        redirect::Policy::custom(move |attempt| {
            // `Attempt::error`/`follow`/`stop` consume `attempt` by value, so the denial
            // reason (if any) is computed into an owned `String` first, in its own scope,
            // to release the borrow of `attempt` held by `attempt.url()`/`attempt.previous()`.
            let deny_reason = 'reason: {
                if attempt.previous().len() > max_redirects {
                    break 'reason Some("too many redirects".to_string());
                }

                let url = attempt.url();

                let scheme = url.scheme();
                if acl.is_scheme_allowed(scheme).is_denied() {
                    break 'reason Some(format!("scheme {scheme} is denied"));
                }

                let Some(host) = url.host() else {
                    break 'reason Some("missing host".to_string());
                };

                match host {
                    url::Host::Domain(domain) => {
                        if acl.is_host_allowed(domain).is_denied() {
                            break 'reason Some(format!("host {domain} is denied"));
                        }
                    }
                    url::Host::Ipv4(ip) => {
                        let ip = std::net::IpAddr::V4(ip);
                        if acl.is_ip_allowed(&ip).is_denied() {
                            break 'reason Some(format!("ip {ip} is denied"));
                        }
                    }
                    url::Host::Ipv6(ip) => {
                        let ip = std::net::IpAddr::V6(ip);
                        if acl.is_ip_allowed(&ip).is_denied() {
                            break 'reason Some(format!("ip {ip} is denied"));
                        }
                    }
                }

                if let Some(port) = url.port_or_known_default()
                    && acl.is_port_allowed(port).is_denied()
                {
                    break 'reason Some(format!("port {port} is denied"));
                }

                // `Url::path()` is percent-encoded; `is_url_path_allowed` expects a
                // decoded path.
                match percent_encoding::percent_decode_str(url.path()).decode_utf8() {
                    Ok(path) => {
                        if acl.is_url_path_allowed(&path).is_denied() {
                            break 'reason Some(format!("path {path} is denied"));
                        }
                    }
                    Err(_) => break 'reason Some("invalid URL path encoding".to_string()),
                }

                None
            };

            match deny_reason {
                Some(reason) => attempt.error(std::io::Error::other(reason)),
                None => attempt.follow(),
            }
        })
    }
}

#[async_trait::async_trait]
impl Middleware for HttpAclMiddleware {
    async fn handle(
        &self,
        req: Request,
        extensions: &mut Extensions,
        next: Next<'_>,
    ) -> std::result::Result<Response, Error> {
        let scheme = req.url().scheme();
        let acl_scheme_match = self.acl.is_scheme_allowed(scheme);
        if acl_scheme_match.is_denied() {
            return Err(Error::Middleware(anyhow!(
                "scheme {} is denied - {}",
                scheme,
                acl_scheme_match
            )));
        }

        let method = req.method().as_str();
        let acl_method_match = self.acl.is_method_allowed(method);
        if acl_method_match.is_denied() {
            return Err(Error::Middleware(anyhow!(
                "method {} is denied - {}",
                method,
                acl_method_match
            )));
        }

        if let Some(host) = req.url().host_str() {
            let authority = Authority::parse(host)
                .map_err(|_| Error::Middleware(anyhow!("invalid host: {}", host)))?;

            match &authority.host {
                Host::Ip(ip) => {
                    let acl_ip_match = self.acl.is_ip_allowed(ip);
                    if acl_ip_match.is_denied() {
                        return Err(Error::Middleware(anyhow!(
                            "ip {} is denied - {}",
                            ip,
                            acl_ip_match
                        )));
                    }
                }
                Host::Domain(domain) => {
                    let acl_host_match = self.acl.is_host_allowed(domain);
                    if acl_host_match.is_denied() {
                        return Err(Error::Middleware(anyhow!(
                            "host {} is denied - {}",
                            domain,
                            acl_host_match
                        )));
                    }
                }
            }

            if let Some(port) = req.url().port_or_known_default() {
                let acl_port_match = self.acl.is_port_allowed(port);
                if acl_port_match.is_denied() {
                    return Err(Error::Middleware(anyhow!(
                        "port {} is denied - {}",
                        port,
                        acl_port_match
                    )));
                }
            }

            for (key, value) in req.headers() {
                let header_name = key.as_str();
                let header_value = value.to_str().map_err(|_| {
                    Error::Middleware(anyhow!("invalid header value for {}", header_name))
                })?;
                let acl_header_match = self.acl.is_header_allowed(header_name, header_value);
                if acl_header_match.is_denied() {
                    return Err(Error::Middleware(anyhow!(
                        "header {}: {} is denied - {}",
                        header_name,
                        header_value,
                        acl_header_match
                    )));
                }
            }

            // `Url::path()` is percent-encoded; `is_url_path_allowed` expects a
            // decoded path.
            let url_path = percent_encoding::percent_decode_str(req.url().path())
                .decode_utf8()
                .map_err(|_| Error::Middleware(anyhow!("invalid URL path encoding")))?;
            let acl_url_path_match = self.acl.is_url_path_allowed(&url_path);
            if acl_url_path_match.is_denied() {
                return Err(Error::Middleware(anyhow!(
                    "path {} is denied - {}",
                    url_path,
                    acl_url_path_match
                )));
            }

            let valid_match = self.acl.is_valid(
                scheme,
                &authority,
                req.headers()
                    .iter()
                    .filter_map(|(k, v)| Some((k.as_str(), v.to_str().ok()?))),
                req.body().and_then(|b| b.as_bytes()),
            );
            if valid_match.is_denied() {
                return Err(Error::Middleware(anyhow!(
                    "request is denied - {}",
                    valid_match
                )));
            }

            next.run(req, extensions).await
        } else {
            return Err(Error::Middleware(anyhow!("missing host")));
        }
    }
}

type BoxError = Box<dyn std::error::Error + Send + Sync>;

struct GaiResolver;

impl Resolve for GaiResolver {
    fn resolve(&self, name: Name) -> Resolving {
        Box::pin(async move {
            // `Name` is a bare hostname with no port, so `ToSocketAddrs` must be given one
            // explicitly (e.g. via a tuple) - calling it on the string directly always fails.
            let addresses = (name.as_str(), 0)
                .to_socket_addrs()
                .map_err(|e| Box::new(e) as BoxError)?;
            Ok(Box::new(addresses.into_iter()) as Box<dyn Iterator<Item = SocketAddr> + Send>)
        })
    }
}

/// A [`Resolve`]r that checks each resolved address against an [`HttpAcl`] before
/// handing it back to `reqwest`.
///
/// Denies the hostname itself first via [`HttpAcl::is_host_allowed`]. For the
/// addresses it resolves to, a trusted static DNS mapping (see
/// [`HttpAclBuilder::add_trusted_static_dns_mapping`]) is returned as-is; a regular
/// static mapping or a genuinely resolved address is
/// filtered through [`HttpAcl::is_ip_allowed`] and [`HttpAcl::is_port_allowed`], so
/// only addresses the ACL permits are ever handed to `reqwest`. Constructed via
/// [`HttpAclMiddleware::dns_resolver`] or [`HttpAclMiddleware::with_dns_resolver`],
/// not directly.
pub struct HttpAclDnsResolver {
    dns_resolver: Arc<dyn Resolve>,
    acl: Arc<HttpAcl>,
}

impl HttpAclDnsResolver {
    /// Create a new ACL resolver that resolves hostnames via `getaddrinfo`.
    pub fn new(middleware: &HttpAclMiddleware) -> Self {
        Self {
            dns_resolver: Arc::new(GaiResolver),
            acl: middleware.acl(),
        }
    }

    /// Create a new ACL resolver that delegates actual resolution to a custom
    /// [`Resolve`] implementation.
    pub fn with_dns_resolver(
        middleware: &HttpAclMiddleware,
        dns_resolver: Arc<dyn Resolve>,
    ) -> Self {
        Self {
            dns_resolver,
            acl: middleware.acl(),
        }
    }
}

impl Resolve for HttpAclDnsResolver {
    fn resolve(&self, name: Name) -> Resolving {
        if self.acl.is_host_allowed(name.as_str()).is_denied() {
            let err: BoxError = Box::new(HttpAclError::HostDenied {
                host: name.as_str().to_string(),
            });
            return Box::pin(future::ready(Err(err)));
        }

        let acl = self.acl.clone();
        let resolver = self.dns_resolver.clone();

        Box::pin(async move {
            if let Some(tcp_address) = acl.resolve_trusted_static_dns_mapping(name.as_str()) {
                // Trusted mappings intentionally bypass the IP/port ACL - the caller
                // vouches for this destination (e.g. pinning a hostname to an internal
                // address on purpose).
                Ok(Box::new(std::iter::once(tcp_address))
                    as Box<dyn Iterator<Item = SocketAddr> + Send>)
            } else if let Some(tcp_address) = acl.resolve_static_dns_mapping(name.as_str()) {
                // Regular static mappings must still pass the IP/port ACL, just like
                // resolved addresses do below - otherwise they'd be a way to bypass it
                // entirely (e.g. mapping a host to a private IP while non-global IPs
                // are denied).
                if acl.is_ip_allowed(&tcp_address.ip()).is_allowed()
                    && acl.is_port_allowed(tcp_address.port()).is_allowed()
                {
                    Ok(Box::new(std::iter::once(tcp_address))
                        as Box<dyn Iterator<Item = SocketAddr> + Send>)
                } else {
                    let err: BoxError =
                        Box::new(std::io::Error::other("Static DNS mapping denied by ACL"));
                    Err(err)
                }
            } else {
                let resolved = resolver.resolve(name).await;
                match resolved {
                    Ok(addresses) => {
                        let filtered = addresses
                            .into_iter()
                            .filter(|addr| {
                                acl.is_ip_allowed(&addr.ip()).is_allowed()
                                    && acl.is_port_allowed(addr.port()).is_allowed()
                            })
                            .collect::<Vec<_>>();
                        Ok(Box::new(filtered.into_iter())
                            as Box<dyn Iterator<Item = SocketAddr> + Send>)
                    }
                    Err(e) => Err(e),
                }
            }
        })
    }
}

#[derive(Error, Debug)]
/// An error that can occur when resolving a host.
///
/// Returned by [`HttpAclDnsResolver`] when a hostname itself is denied by the ACL.
/// Downcast the boxed error from a failed resolution to check for this specifically,
/// as opposed to a lower-level resolution failure.
pub enum HttpAclError {
    /// Host resolution denied by ACL.
    #[error("Host resolution denied by ACL: {host}")]
    HostDenied {
        /// The host that was denied.
        host: String,
    },
}

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

    #[tokio::test]
    async fn test_http_acl_middleware() {
        let acl = HttpAcl::builder()
            .add_denied_host("example.com".to_string())
            .unwrap()
            .build();

        let middleware = HttpAclMiddleware::new(acl);

        let client = reqwest_middleware::ClientBuilder::new(
            reqwest::Client::builder()
                .dns_resolver(middleware.dns_resolver())
                .build()
                .unwrap(),
        )
        .with(middleware)
        .build();

        let request = client.get("http://example.com/").send().await;

        assert!(request.is_err());
        assert_eq!(
            request.unwrap_err().to_string(),
            "host example.com is denied - The entity is denied according to the denied ACL."
        );
    }

    #[tokio::test]
    async fn test_middleware_decodes_percent_encoded_path() {
        let acl = HttpAcl::builder()
            .add_allowed_host("example.com".to_string())
            .unwrap()
            .add_denied_url_path("/secret file".to_string())
            .unwrap()
            .build();

        let middleware = HttpAclMiddleware::new(acl);

        let client =
            reqwest_middleware::ClientBuilder::new(reqwest::Client::builder().build().unwrap())
                .with(middleware)
                .build();

        // Regression test: `Url::path()` is percent-encoded ("%20" for the space
        // here), but `is_url_path_allowed` matches against the decoded path, so the
        // middleware must decode before checking - otherwise this denied path would
        // never match and the request would go through.
        let request = client.get("http://example.com/secret%20file").send().await;

        assert!(request.is_err());
        assert!(
            request
                .unwrap_err()
                .to_string()
                .contains("path /secret file is denied")
        );
    }

    #[tokio::test]
    async fn test_dns_resolver_returns_typed_error_for_denied_host() {
        let acl = HttpAcl::builder()
            .add_denied_host("denied.example.com".to_string())
            .unwrap()
            .build();

        let middleware = HttpAclMiddleware::new(acl);
        let resolver = middleware.dns_resolver();

        let name: reqwest::dns::Name = "denied.example.com".parse().unwrap();
        let err = match resolver.resolve(name).await {
            Ok(_) => panic!("expected resolution to be denied"),
            Err(e) => e,
        };

        let acl_err = err
            .downcast_ref::<HttpAclError>()
            .expect("expected a HttpAclError");
        assert!(matches!(
            acl_err,
            HttpAclError::HostDenied { host } if host == "denied.example.com"
        ));
    }

    #[tokio::test]
    async fn test_dns_resolver_resolves_hostnames() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        use tokio::net::TcpListener;

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();

        tokio::spawn(async move {
            if let Ok((mut socket, _)) = listener.accept().await {
                let mut buf = [0u8; 1024];
                let _ = socket.read(&mut buf).await;
                let response = "HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n";
                let _ = socket.write_all(response.as_bytes()).await;
            }
        });

        let acl = HttpAcl::builder()
            .non_global_ip_ranges(true)
            .ip_acl_default(true)
            .port_acl_default(true)
            .host_acl_default(true)
            .build();

        let middleware = HttpAclMiddleware::new(acl);

        let client = reqwest_middleware::ClientBuilder::new(
            reqwest::Client::builder()
                .dns_resolver(middleware.dns_resolver())
                .build()
                .unwrap(),
        )
        .with(middleware)
        .build();

        // Regression test: the default `GaiResolver` used to call `to_socket_addrs()` on a
        // bare hostname (no port), which always errors, so *no* hostname could ever resolve.
        let request = client
            .get(format!("http://localhost:{}/", addr.port()))
            .send()
            .await;

        assert!(request.is_ok(), "{:?}", request.err());
    }

    #[tokio::test]
    async fn test_trusted_static_dns_mapping_bypasses_ip_port_acl() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        use tokio::net::TcpListener;

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();

        tokio::spawn(async move {
            if let Ok((mut socket, _)) = listener.accept().await {
                let mut buf = [0u8; 1024];
                let _ = socket.read(&mut buf).await;
                let response = "HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n";
                let _ = socket.write_all(response.as_bytes()).await;
            }
        });

        // Deny everything at the IP/port level (the default), but pin "trusted.internal"
        // to our mock server via a *trusted* static mapping, which should bypass that.
        let acl = HttpAcl::builder()
            .host_acl_default(true)
            .add_trusted_static_dns_mapping("trusted.internal".to_string(), addr)
            .unwrap()
            .build();

        assert!(acl.is_ip_allowed(&addr.ip()).is_denied());
        assert!(acl.is_port_allowed(addr.port()).is_denied());

        let middleware = HttpAclMiddleware::new(acl);

        let client = reqwest_middleware::ClientBuilder::new(
            reqwest::Client::builder()
                .dns_resolver(middleware.dns_resolver())
                .build()
                .unwrap(),
        )
        .with(middleware)
        .build();

        // No explicit port in the URL - the connector must pick up the trusted
        // mapping's port, proving both the IP and port ACL were bypassed for it.
        let request = client.get("http://trusted.internal/").send().await;

        assert!(request.is_ok(), "{:?}", request.err());
    }

    #[tokio::test]
    async fn test_redirect_policy_blocks_disallowed_target() {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        use tokio::net::TcpListener;

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();

        tokio::spawn(async move {
            if let Ok((mut socket, _)) = listener.accept().await {
                let mut buf = [0u8; 1024];
                let _ = socket.read(&mut buf).await;
                let response = "HTTP/1.1 302 Found\r\nLocation: http://192.168.1.1/\r\nContent-Length: 0\r\n\r\n";
                let _ = socket.write_all(response.as_bytes()).await;
            }
        });

        // Allow everything except one specific (non-global) IP, so the initial request to
        // our local mock server succeeds but the redirect target is denied.
        let acl = HttpAcl::builder()
            .non_global_ip_ranges(true)
            .ip_acl_default(true)
            .port_acl_default(true)
            .add_denied_ip_range((
                "192.168.1.1".parse::<std::net::IpAddr>().unwrap(),
                "192.168.1.1".parse::<std::net::IpAddr>().unwrap(),
            ))
            .unwrap()
            .build();

        let middleware = HttpAclMiddleware::new(acl);

        let client = reqwest_middleware::ClientBuilder::new(
            reqwest::Client::builder()
                .dns_resolver(middleware.dns_resolver())
                .redirect(middleware.redirect_policy())
                .build()
                .unwrap(),
        )
        .with(middleware)
        .build();

        let request = client
            .get(format!("http://127.0.0.1:{}/", addr.port()))
            .send()
            .await;

        assert!(request.is_err());
    }
}