Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

11.1 KB
Raw Blame
//! URL scrub. `None` means "unchanged".
//!
//! Hostnames identify the customer (the business running PostHog), not an individual user, so
//! they pass through intact; the parts of a URL that can identify a user or a machine are
//! scrubbed:
//!
//! - Numbers (a bare run of digits) are masked to `$` per digit (length-preserving; `$` rather than
//!   `#` so it doesn't clash with the fragment separator).
//! - Host: an IP-address host -> `[ip_address]`; a port -> `:[port]`; domain names are kept.
//! - Path: keep allow-listed segments; a number -> `$$`; anything else -> `[redacted]`.
//! - Query: a param survives only if its key or value is an allow-listed alphanumeric token.
//! - Fragment: kept only if it is an allow-listed alphanumeric token.
//! - Userinfo (`user:pass@`) is always stripped from the authority.
//! - A scheme without slashes (`mailto:`, `tel:`) is kept; the rest is scrubbed as a path.

use url::Host;

use crate::allow_lists::AllowLists;
use crate::context::Ctx;

pub const URL_ALLOWLIST: &[&str] = &["about:blank", "about:srcdoc"];

pub fn scrub_url(ctx: &Ctx<'_>, input: &str) -> Option<String> {
    let allow = ctx.allow;
    if URL_ALLOWLIST.contains(&input) {
        return None;
    }
    let tail_idx = input.find(['?', '#']);
    let (base, tail) = match tail_idx {
        Some(i) => (&input[..i], &input[i..]),
        None => (input, ""),
    };
    let mut changed = false;

    let (scheme, authority, path) = split_url(base);
    let mut out = String::with_capacity(input.len());
    out.push_str(scheme);
    if !authority.is_empty() {
        let host_port = match authority.rfind('@') {
            Some(at) => {
                changed = true;
                &authority[at + 1..]
            }
            None => authority,
        };
        if !is_valid_host_port(host_port) {
            // A structurally invalid "host" (e.g. an unencoded `?` in userinfo makes `user:pa`
            // parse as the authority) must not pass through as if it were a hostname.
            out.push_str("[redacted]");
            changed = true;
        } else {
            changed |= push_host_port(host_port, &mut out);
        }
    }

    let mut first = true;
    for raw in path.split('/') {
        if first {
            first = false;
        } else {
            out.push('/');
        }
        if raw.is_empty() {
            continue;
        }
        if is_numeric(raw) {
            mask_number_into(raw, &mut out);
            changed = true;
        } else if is_safe_segment(raw) || allow.url_contains(raw) {
            out.push_str(raw);
        } else {
            out.push_str("[redacted]");
            changed = true;
        }
    }

    let tail_out = scrub_tail(allow, tail);
    if tail_out != tail {
        changed = true;
    }
    out.push_str(&tail_out);

    if changed {
        Some(out)
    } else {
        None
    }
}

fn scrub_tail(allow: &AllowLists, tail: &str) -> String {
    if tail.is_empty() {
        return String::new();
    }
    let starts_query = tail.as_bytes()[0] == b'?';
    let (query, frag) = if starts_query {
        match tail[1..].find('#') {
            Some(h) => (&tail[1..1 + h], &tail[1 + h + 1..]),
            None => (&tail[1..], ""),
        }
    } else {
        ("", &tail[1..]) // tail starts with '#'
    };

    let mut out = String::new();
    if starts_query {
        let mut kept: Vec<String> = Vec::new();
        for pair in query.split('&') {
            if pair.is_empty() {
                continue;
            }
            match pair.find('=') {
                None => {
                    if is_allowed(allow, pair) {
                        kept.push(pair.to_string());
                    }
                }
                Some(eq) => {
                    let key = &pair[..eq];
                    let value = &pair[eq + 1..];
                    // A param survives only if its key or (non-empty) value is an allow-listed token.
                    let key_ok = is_allowed(allow, key);
                    let value_ok = !value.is_empty() && is_allowed(allow, value);
                    if !key_ok && !value_ok {
                        continue;
                    }
                    let kr = render_token(allow, key).unwrap_or_else(|| "[key]".to_string());
                    let vr = if value.is_empty() {
                        String::new()
                    } else {
                        render_token(allow, value).unwrap_or_else(|| "[value]".to_string())
                    };
                    kept.push(format!("{kr}={vr}"));
                }
            }
        }
        if !kept.is_empty() {
            out.push('?');
            out.push_str(&kept.join("&"));
        }
    }
    if !frag.is_empty() && is_allowed(allow, frag) {
        out.push('#');
        out.push_str(frag);
    }
    out
}

// Pinned by `tests/fixtures/url-scheme-allowlist.json` (see `tests/parity.rs`).
pub const URL_SCHEME_ALLOWLIST: &[&str] = &[
    // Web platform
    "about",
    "blob",
    "data",
    "file",
    "ftp",
    "geo",
    "javascript",
    "magnet",
    "mailto",
    "sms",
    "tel",
    "urn",
    "ws",
    "wss", // Microsoft
    "ms-access",
    "ms-excel",
    "ms-outlook",
    "ms-powerpoint",
    "ms-project",
    "ms-publisher",
    "ms-visio",
    "ms-word",
    "msteams",
    "onenote",
    "sip",
    "sips",
    "skype", // Google
    "comgooglemaps",
    "googlechrome",
    "googlegmail",
    "googlemaps", // Apple
    "facetime",
    "facetime-audio",
    "itms",
    "itms-apps",
    "maps",
    "music",
    "shortcuts",
    // Chat and social
    "bluesky",
    "callto",
    "discord",
    "fb",
    "fb-messenger",
    "instagram",
    "irc",
    "line",
    "linkedin",
    "matrix",
    "reddit",
    "sgnl",
    "slack",
    "snapchat",
    "telegram",
    "tg",
    "tiktok",
    "twitter",
    "viber",
    "wechat",
    "weixin",
    "whatsapp",
    "xmpp",
    // Media, payments, and tools
    "bitcoin",
    "bittorrent",
    "figma",
    "notion",
    "obsidian",
    "spotify",
    "steam",
    "vscode",
    "zoommtg",
    "zoomus",
];

fn scheme_without_slashes(s: &str) -> Option<usize> {
    let colon = s.find(':')?;
    let prefix = &s[..colon];
    if URL_SCHEME_ALLOWLIST
        .iter()
        .any(|scheme| prefix.eq_ignore_ascii_case(scheme))
    {
        Some(colon + 1)
    } else {
        None
    }
}

fn is_valid_scheme(prefix: &str) -> bool {
    let bytes = prefix.as_bytes();
    match bytes.split_first() {
        Some((&first, rest)) => {
            first.is_ascii_alphabetic()
                && rest
                    .iter()
                    .all(|&b| b.is_ascii_alphanumeric() || matches!(b, b'+' | b'-' | b'.'))
        }
        None => false,
    }
}

// Split into scheme prefix (incl. `://` or `//`), authority (`[userinfo@]host[:port]`), and path.
fn split_url(s: &str) -> (&str, &str, &str) {
    let (scheme, rest) = if let Some(scheme_end) = s
        .find("://")
        .filter(|&scheme_end| is_valid_scheme(&s[..scheme_end]))
    {
        (&s[..scheme_end + 3], &s[scheme_end + 3..])
    } else if let Some(rest) = s.strip_prefix("//") {
        (&s[..2], rest)
    } else if let Some(end) = scheme_without_slashes(s) {
        // Free text before a colon (or before an embedded `://`) must not pass through as a
        // "scheme"; only allowlisted schemes survive, and only in the slashless form.
        return (&s[..end], "", &s[end..]);
    } else {
        return ("", "", s); // relative URL: all path
    };
    match rest.find('/') {
        None => (scheme, rest, ""),
        Some(path_off) => (scheme, &rest[..path_off], &rest[path_off..]),
    }
}

// A domain name passes through, but an IP address identifies a machine (possibly an end user's)
// and a port is infrastructure detail, so both are masked. Returns whether anything was masked.
// `host_port` has already passed `is_valid_host_port`, so a colon outside brackets can only
// introduce a port.
fn push_host_port(host_port: &str, out: &mut String) -> bool {
    let (host, port) = match host_port.split_once(']') {
        Some((bracketed, rest)) => (&host_port[..bracketed.len() + 1], rest.strip_prefix(':')),
        None => match host_port.split_once(':') {
            Some((host, port)) => (host, Some(port)),
            None => (host_port, None),
        },
    };
    let mut changed = false;
    if is_ip_host(host) {
        out.push_str("[ip_address]");
        changed = true;
    } else {
        out.push_str(host);
    }
    if port.is_some() {
        out.push_str(":[port]");
        changed = true;
    }
    changed
}

// The WHATWG host parser (what browsers use) decides what is an IP: bracketed IPv6, plus every
// IPv4 encoding browsers resolve (`192.168.0.1`, hex `0xc0a80101`, octal `0300.0250.0.1`, decimal
// `3232235777`). Unparseable hosts mask too, incidentally — a browser can't have produced a
// replay from one, so the case doesn't matter.
fn is_ip_host(host: &str) -> bool {
    if host.is_empty() {
        return false;
    }
    !matches!(Host::parse(host), Ok(Host::Domain(_)))
}

// Host or `[ipv6]`, with an optional `:digits` port.
fn is_valid_host_port(host_port: &str) -> bool {
    let host = match host_port.split_once(':') {
        None => host_port,
        Some(_) if host_port.starts_with('[') => match host_port.rfind(']') {
            Some(close) => {
                let bracketed = &host_port[1..close];
                let port = &host_port[close + 1..];
                let port_ok = port.is_empty()
                    || (port.starts_with(':')
                        && port.len() > 1
                        && port[1..].bytes().all(|b| b.is_ascii_digit()));
                return port_ok
                    && bracketed
                        .bytes()
                        .all(|b| b.is_ascii_hexdigit() || b == b':' || b == b'.');
            }
            None => return false,
        },
        Some((host, port)) => {
            if port.is_empty() || !port.bytes().all(|b| b.is_ascii_digit()) {
                return false;
            }
            host
        }
    };
    host.bytes()
        .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'))
}

fn is_safe_segment(seg: &str) -> bool {
    matches!(seg, "" | "." | "..")
}

// `$`, not `#` (the fragment separator).
fn mask_number_into(n: &str, out: &mut String) {
    for _ in 0..n.len() {
        out.push('$');
    }
}

fn is_numeric(t: &str) -> bool {
    !t.is_empty() && t.bytes().all(|b| b.is_ascii_digit())
}

// 100% alphanumeric (empty allowed).
fn is_simple(t: &str) -> bool {
    t.bytes().all(|b| b.is_ascii_alphanumeric())
}

// An allow-listed, alphanumeric, non-number token — the only kind that keeps a query param/fragment
// alive.
fn is_allowed(allow: &AllowLists, t: &str) -> bool {
    !t.is_empty() && is_simple(t) && !is_numeric(t) && allow.url_contains(t)
}

// Rendered form of a surviving token: a number -> `$$`, an allow-listed token -> itself, else None.
fn render_token(allow: &AllowLists, t: &str) -> Option<String> {
    if is_numeric(t) {
        let mut s = String::with_capacity(t.len());
        mask_number_into(t, &mut s);
        Some(s)
    } else if is_allowed(allow, t) {
        Some(t.to_string())
    } else {
        None
    }
}