敏感字段已经写入日志，怎样从源头建立不可绕过的脱敏层

敏感字段已经进入日志时，先把它当成一次数据泄露处理：停止继续写入、限制日志访问范围，确认泄露的是密码、访问令牌、会话标识、连接串还是个人信息；能够轮换的凭据立即轮换，已经扩散到日志平台、备份或导出文件的数据按团队制度处置。修代码只能阻止后续泄露，不能让历史日志自动消失。

后续要建立的也不应只是一个 mask() 工具函数。更可靠的结构是三层：敏感类型通过 slog.LogValuer 提供安全表示，最终 Handler 通过 ReplaceAttr 做字段级兜底，应用入口统一创建 Logger 并压缩旁路。这样“调用点忘记脱敏”不再是唯一防线。

Go slog 文档：https://pkg.go.dev/log/slog

OWASP 日志安全建议：https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html

先止住已经发生的泄露

先不要急着改正则。你需要知道泄露值的性质，因为处置动作不同：

OWASP 的日志建议把访问令牌、密码、数据库连接串、加密密钥和敏感个人信息列为通常不应直接记录的数据，并建议在记录前删除、遮蔽、清洗、哈希或加密。具体采用哪一种，取决于数据是否真的需要出现在日志里；对密码和主密钥，最安全的答案通常是“不记录”，而不是“打码后继续记录”。

按日志入口分层定位旁路

同样是“日志里出现了 token”，来源可能完全不同。先在代码中按下面四层排查，证据会直接决定修复位置：

1. 自由文本："login failed: " + token。此时敏感值已经并入消息字符串，字段级 Handler 看不到边界。
2. 结构化属性：slog.String("token", token)。键和值仍然分离，适合在 ReplaceAttr 兜底。
3. 嵌套对象：slog.Any("request", req)。普通结构体可能被整体编码，单纯匹配子字段名并不可靠。
4. 旁路输出：fmt.Println、自建文件 Writer、第三方 Logger。它们根本不会经过你的 slog Handler。

判断方法也很直接：如果日志平台里字段名仍是独立的 token、password，优先检查结构化属性路径；如果秘密出现在 msg 里，说明自由文本规范已经失守；如果只在某个库的日志中出现，则先确认它是否使用了统一 Handler。

让敏感类型自己提供安全日志表示

第一层防线应靠类型，而不是靠字段名。字段名会变化，类型的语义更稳定。log/slog 在输出值前会解析 LogValuer，官方文档也专门给出了隐藏秘密值的示例方向。

package safelog

import "log/slog"

// Secret 保存运行时需要的敏感值，但日志中永远只输出占位符。
type Secret string

func (Secret) LogValue() slog.Value {
    // 不返回原始字符串，避免调用方换一个键名就绕过脱敏。
    return slog.StringValue("[REDACTED]")
}

// Email 只暴露经过业务确认的最小信息。
type Email string

func (e Email) LogValue() slog.Value {
    // 示例只保留“已提供邮箱”这一事实，不泄露地址本身。
    return slog.GroupValue(
        slog.Bool("present", e != ""),
        slog.String("class", "email"),
    )
}

使用时保持结构化：

logger.Info("request authenticated",
    slog.String("user_id", userID),
    slog.Any("access_token", safelog.Secret(token)), // 输出 [REDACTED]。
    slog.Any("contact", safelog.Email(email)),       // 只输出安全分组。
)

核对点是：无论键名叫 access_token、credential 还是嵌在一个 Group 里，Secret 的日志表示都不包含原值。它比“所有开发者记得调用 maskToken”更难绕过。

但不要把普通 string 强行断言成 Secret。类型防线只有在领域边界就使用安全类型时才有效，例如配置加载后立即把令牌包装成 Secret，而不是到日志调用点才临时转换。

在最终 Handler 建立字段级输出闸门

第二层使用 HandlerOptions.ReplaceAttr。官方定义说明它会在非 Group 属性写出前被调用，返回零值 slog.Attr{} 可以删除字段；回调还能拿到当前打开的 Group 路径，因此可以按完整路径制定策略。属性值在进入回调前已被解析。

package safelog

import (
    "log/slog"
    "strings"
)

var dropKeys = map[string]struct{}{
    "password":          {},
    "passwd":            {},
    "token":             {},
    "access_token":      {},
    "refresh_token":     {},
    "authorization":     {},
    "database_url":      {},
    "connection_string": {},
}

func ReplaceSensitive(groups []string, attr slog.Attr) slog.Attr {
    // Value 已由 slog 解析；先统一键名，再执行明确策略。
    key := strings.ToLower(strings.TrimSpace(attr.Key))
    if _, blocked := dropKeys[key]; blocked {
        // 零 Attr 表示完全删除，避免“脱敏值”仍暴露长度或格式。
        return slog.Attr{}
    }

    // Group 路径可用于处理同名字段的语义差异。
    path := strings.ToLower(strings.Join(appendPath(groups, key), "."))
    switch path {
    case "customer.email", "profile.phone":
        return slog.String(attr.Key, "[MASKED]")
    default:
        return attr
    }
}

func appendPath(groups []string, key string) []string {
    // 复制切片，避免修改 slog 临时提供的 groups。
    path := make([]string, 0, len(groups)+1)
    path = append(path, groups...)
    return append(path, key)
}

统一装配输出 Handler：

options := &slog.HandlerOptions{
    Level:       slog.LevelInfo,
    ReplaceAttr: safelog.ReplaceSensitive, // 最终写出前执行统一策略。
}

handler := slog.NewJSONHandler(os.Stdout, options)
logger := slog.New(handler)

// 让标准 log 包也进入同一个 slog Handler，减少旧代码旁路。
slog.SetDefault(logger)

这层能覆盖直接属性、Group 内属性以及通过 Logger.With 预绑定的属性，因为最终都由同一个内置 Handler 输出。核对时要特别测试 logger.With("token", value)，很多泄露就藏在初始化阶段。

封住 Logger 构造与自由文本旁路

“不可绕过”不是某一个回调能保证的，而是输出路径足够少。建议把 Logger 构造放在 internal/observability，业务包只接收已经配置好的 *slog.Logger。除了测试，禁止业务包直接调用 slog.NewJSONHandler、slog.NewTextHandler 或自行打开日志文件。

同时必须承认两个技术边界：

• ReplaceAttr 不能可靠拆分自由文本。秘密一旦被拼进 msg，你只剩容易误伤的字符串扫描。正确修复是禁止拼接敏感值，改成结构化字段和安全类型。
• 普通结构体不是自动递归字段策略。把请求对象整体交给 slog.Any，不等于 Handler 能按每个结构体字段名脱敏。要么把允许记录的字段显式组成 slog.Group，要么为该类型实现 LogValuer。

错误对象也要小心。err.Error() 可能携带原始 SQL、连接串、完整 URL 或上游响应。不要把未知来源的错误全文当作安全数据；可以记录稳定错误码和安全摘要，把详细诊断放在权限更严的专用通道。

用反向样例确认脱敏没有漏口

不用只测“正常键名”。检查清单要刻意覆盖绕过方式：

1. 根级 password、大小写变化和首尾空格是否被删除。
2. slog.Group("customer", slog.String("email", ...)) 是否按完整路径遮蔽。
3. logger.With("access_token", ...) 预绑定后是否仍被处理。
4. Secret 换成任意字段名时是否仍只输出 [REDACTED]。
5. 使用标准 log.Printf 的旧代码是否已经进入默认 slog Handler。
6. 第三方 Logger、fmt.Println 和自建 Writer 是否仍存在旁路；若存在，是否已禁用或单独配置。
7. 消息文本里出现测试秘密时，检查是否能追溯到违规拼接点，而不是只靠输出正则掩盖。
8. 日志系统、转发器、缓冲队列、归档和备份是否都执行了相同的数据访问与保留策略。

常见追问

只用 ReplaceAttr 可以吗？

适合做最终兜底，不适合成为唯一防线。它依赖键名和结构化边界，无法可靠识别自由文本，也可能看不到普通对象内部的敏感字段。安全类型能减少字段名变化造成的绕过。

把所有敏感值哈希后记录是否安全？

不一定。低熵值可能被猜测，稳定哈希也可能形成跨事件追踪标识。只有明确需要关联、完成威胁评估并采用合适密钥或盐策略后才考虑；密码、访问令牌和主密钥默认不应进入日志。

日志已经删除，为什么还要轮换令牌？

日志可能已经被转发、缓存、下载、备份或被他人读取。删除当前索引不能证明所有副本都消失，因此可撤销的秘密应按已暴露处理。

怎样让团队长期不绕过？

把约束写进架构：统一 Logger 工厂、安全领域类型、结构化字段规范、代码评审清单和针对旁路调用的静态检查。运行时闸门与工程约束一起使用，才接近“不可绕过”。

最后可以用一句话判断方案是否到位：业务调用点即使忘记“手动打码”，原始秘密也不该抵达最终日志输出。安全类型保护数据语义，ReplaceAttr 保护字段出口，统一装配保护日志路径；自由文本和旁路则必须通过编码规范与工具约束被消除。