Go url.URL Userinfo 字段的脱敏输出方式

Go 输出带 Userinfo 的 URL 时，优先使用 u.Redacted()，不要直接调用 u.String()。标准库会保留用户名，并把 u.User 中存在的密码替换为固定文本 xxxxx。但它只处理 Userinfo 密码：用户名、查询参数里的 token、api_key 等字段不会自动脱敏，需要再加一层日志策略。

官方文档：https://pkg.go.dev/net/url#URL.Redacted

先确定真正需要保护的 URL 数据

url.URL 的 User 字段指向不可变的 Userinfo，其中包含用户名和可选密码。调用 URL.String() 会重新组装 URL，也会把 userinfo 放回 authority 部分；调用 Userinfo.String() 会得到编码后的 username[:password]。如果这些字符串进入访问日志、错误链、追踪标签或告警消息，凭据就可能被复制到更多系统。

保护对象可以按风险分成三层：

url.UserPassword 本身也只适合兼容旧系统。Go 官方文档明确提示，把认证信息放进 URI 的做法存在安全风险。新接口优先使用请求头、受控凭据存储和短期令牌，不要把“日志已脱敏”当作继续在 URL 中传密码的理由。

标准库能遮住什么，不能遮住什么

下面的最小示例展示 String 与 Redacted 的差异：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u := &url.URL{
        Scheme:   "https",
        User:     url.UserPassword("alice", "secret-pass"),
        Host:     "api.example.com",
        Path:     "/v1/orders",
        RawQuery: "token=abc123&mode=fast",
    }

    // String 会包含原始密码，不应写入生产日志。
    fmt.Println(u.String())

    // Redacted 只把 Userinfo 密码替换为 xxxxx。
    fmt.Println(u.Redacted())
}

第二行输出会呈现类似 https://alice:xxxxx@api.example.com/v1/orders?token=abc123&mode=fast 的形式。密码被遮住了，但用户名 alice 和查询参数 token 仍然可见。因此 Redacted 是安全基线，不是完整的 URL 隐私策略。

直接输出原 URL 的泄露路径

很多泄露并不是显式写下密码，而是发生在通用日志语句中：

// 这些写法都可能触发完整 URL 字符串化，包含原始 Userinfo。
log.Printf("upstream=%s", u)
log.Printf("request failed: url=%v", u)
err := fmt.Errorf("connect %s: %w", u, cause)

// 结构体调试输出也不应被当作脱敏替代方案。
log.Printf("url detail=%+v", *u)

最后一种写法的具体格式取决于 fmt 如何处理字段和实现，不应依赖它“看起来没打印密码”。安全规则应该是：只要日志需要 URL，就先经过统一函数生成允许输出的字符串；调用方不能自行选择格式化动词。

封装一条不修改原 URL 的安全输出路径

下面的封装支持两种策略：可选隐藏用户名，并按传入的敏感查询键替换值。它先复制 URL，再修改副本，因此不会影响后续真实请求。

package safeurl

import "net/url"

func LogString(u *url.URL, hideUsername bool, sensitiveKeys ...string) string {
    if u == nil {
        // nil URL 用空字符串表示，避免日志路径发生 panic。
        return ""
    }

    // 复制结构体，所有脱敏修改都只作用于副本。
    safe := *u

    if safe.User != nil && hideUsername {
        _, hasPassword := safe.User.Password()
        if hasPassword {
            // 保留“存在 userinfo 与密码”的形态，但替换真实用户名和密码。
            safe.User = url.UserPassword("xxxxx", "xxxxx")
        } else {
            safe.User = url.User("xxxxx")
        }
    }

    // Query 会解析 RawQuery；只替换合同中明确列出的敏感键。
    query := safe.Query()
    for _, key := range sensitiveKeys {
        if query.Has(key) {
            query.Set(key, "xxxxx")
        }
    }
    safe.RawQuery = query.Encode()

    // 即使保留用户名，Redacted 也会遮住剩余的 Userinfo 密码。
    return safe.Redacted()
}

调用时把策略集中在一个地方：

safe := safeurl.LogString(
    u,
    true, // 用户名也按敏感信息处理。
    "token",
    "api_key",
    "signature",
)

// 日志入口只接收已脱敏字符串，不再接收原始 *url.URL。
logger.Info("upstream request", "url", safe)

对于示例 URL，输出会保留协议、主机、路径和非敏感的 mode，把用户名、密码与 token 都替换为 xxxxx。因为 Values.Encode() 会按键生成规范查询串，参数顺序可能与输入不同；日志分析不要依赖原始顺序。

风险分级决定保留多少信息

不是所有日志都需要完整 URL。可以按使用场景逐级收紧：

如果查询参数种类变化很快，敏感键黑名单容易漏项。更严格的做法是只允许少量已知安全键进入日志，其余全部删除；也可以直接记录 u.Scheme、u.Host 和 u.EscapedPath()，完全不输出 RawQuery。

审计记录不要回流原始凭据

统一函数之外还要控制调用方式。错误包装、重试队列、指标标签和 tracing attribute 都可能长期保存字符串。建议让这些接口接收已经处理过的字段，避免把 *url.URL 传入通用序列化器。指标标签尤其不适合完整 URL：除了泄密，还会因为高基数增加存储压力。

脱敏失败时应选择“少记”而不是回退到原值。例如 URL 解析失败，只记录错误类别和输入长度，不把原始文本拼进错误消息。

用回归测试锁住禁止出现的内容

测试不只比较期望字符串，还要明确断言秘密和用户名没有出现，并确认原对象没有被修改：

package safeurl

import (
    "net/url"
    "strings"
    "testing"
)

func TestLogStringHidesUserinfoAndToken(t *testing.T) {
    u, err := url.Parse("https://alice:secret-pass@example.com/a?token=abc123&mode=fast")
    if err != nil {
        t.Fatal(err)
    }
    original := u.String()

    got := LogString(u, true, "token")

    // 禁止真实凭据和用户名进入日志输出。
    for _, forbidden := range []string{"alice", "secret-pass", "abc123"} {
        if strings.Contains(got, forbidden) {
            t.Fatalf("脱敏输出仍包含敏感值 %q: %s", forbidden, got)
        }
    }

    // 函数必须只修改副本，真实请求仍使用原 URL。
    if u.String() != original {
        t.Fatalf("原 URL 被修改: got=%s want=%s", u.String(), original)
    }

    // 保留的业务信息仍应可用于定位目标。
    if !strings.Contains(got, "example.com/a") || !strings.Contains(got, "mode=fast") {
        t.Fatalf("脱敏过度，必要定位信息丢失: %s", got)
    }
}

上线前检查清单

• 所有 URL 日志都经过统一的安全输出函数。
• 只隐藏密码的场景使用 URL.Redacted()，不再调用 String()。
• 用户名是否敏感有明确策略，而不是由调用方临时决定。
• 查询参数采用允许列表或集中维护的敏感键集合。
• 错误消息、追踪标签、指标标签和队列载荷不保存原始 URL。
• 回归测试包含密码、用户名、token、多值参数和 nil URL。
• 新系统不再把密码放进 URL Userinfo。

相关问题

URL.Redacted 会隐藏用户名吗？

不会。它保留用户名，只把 u.User 中存在的密码替换为 xxxxx。用户名也敏感时需要在副本上替换 User。

URL.Redacted 会处理 token 查询参数吗？

不会。官方定义明确限定为 Userinfo 密码；查询参数、路径和片段需要单独的日志策略。

为什么脱敏时要复制 url.URL？

日志输出不应改变真实请求目标。复制后替换 User 和 RawQuery，可以让脱敏副本与业务使用的原对象相互隔离。