Go filepath.IsLocal 如何拦住相对路径逃逸：Clean、绝对路径与跨平台边界

下载接口收到用户传来的 ../reports/today.csv 时，最容易犯的错是只调用 filepath.Clean，看到路径“变干净了”就直接打开。更稳妥的顺序是先让 filepath.IsLocal 判断输入是否仍是当前目录下的本地路径，再用 filepath.Join 拼到服务端根目录；真正访问文件时，还要把符号链接等文件系统因素单独考虑。

filepath.IsLocal 解决的是词法上的“路径会不会离开当前目录”，不是完整沙箱；通过后再组合根目录，并对打开文件的实际结果做验证。

先把下载接口的资产边界说清楚

这里的资产不是“一个字符串”，而是服务端根目录下允许被读取的文件。假设接口把 name 作为相对文件名，预期输入是 reports/today.csv，那么 /etc/passwd、空字符串以及清理后落到根目录之外的 ../reports/today.csv 都不应该进入打开文件的阶段。

这也是威胁建模的第一步：攻击者控制 name，代码负责判断输入边界，最后的 os.Open 才是触碰实际文件的动作。三者混在一个“清洗字符串”的函数里，出了问题很难知道是判断错了，还是文件系统状态发生了变化。

filepath.IsLocal 比 filepath.Clean 多做了什么

filepath.Clean 会折叠重复分隔符、处理 . 和 ..，它的职责是得到规范形式；规范形式本身不等于“可以安全读取”。例如在 Unix 上，filepath.Clean("../reports/today.csv") 仍然是一个向上走的相对路径。

filepath.IsLocal 使用词法分析检查四个关键条件：路径非空、不是绝对路径、不会离开当前目录树；在 Windows 上还会排除类似 NUL 的保留名。它不读取磁盘，也不会跟随符号链接，因此速度和边界都应按“输入门”理解。

最小防护写法：先判 name，再拼 root

下面的函数只把通过 filepath.IsLocal 的值交给 filepath.Join。注意不要先把 root 和用户输入拼好，再对完整路径调用 IsLocal；那样判断的参照目录已经变了，代码意图也不清楚。

func openDownload(root, name string) (*os.File, error) {
    if !filepath.IsLocal(name) {
        return nil, fmt.Errorf("invalid local name")
    }
    full := filepath.Join(root, name)
    return os.Open(full)
}

这段代码的安全责任可以拆成两条：filepath.IsLocal 拦住输入路径的词法逃逸，filepath.Join 负责按当前操作系统的规则组合路径，os.Open 只负责报告最终打开结果。文件不存在、权限不足和 I/O 错误，仍然要由调用方按错误类型处理。

三个不能被“清洗”替代的边界

只调用 filepath.Clean 不够

Clean 会返回可读的规范路径，却不会告诉你这个路径是否越出了允许目录。把 Clean(name) 的结果直接交给 os.Open，仍可能让 .. 把读取点带到上级目录。

符号链接需要另一个策略

IsLocal 不考虑文件系统里已经存在的符号链接。一个词法上本地的 reports/latest.csv，如果 reports/latest.csv 是指向其他目录的链接，最终打开位置仍取决于文件系统。敏感场景要结合受控根目录、符号链接检查或平台提供的目录句柄能力，不要把 IsLocal 说成沙箱。

跨平台测试不能只测 Linux

path/filepath 会使用目标系统的分隔符和路径规则。Windows 的盘符、UNC 路径和保留名与 Unix 不同，至少应在 CI 中补充代表性输入，验证拒绝分支，而不是拿 Linux 的字符串经验推断所有平台。

如何留下可审计的验证记录

安全检查不应只记录“返回 false”。建议把拒绝原因映射为稳定的业务事件，例如 invalid local name，同时记录请求追踪 ID 和经过脱敏的输入摘要；不要把完整的敏感路径写入公开日志。测试里至少覆盖本地文件、..、绝对路径、空字符串，以及 Windows 保留名。

验收的重点是顺序：非法 name 必须在 filepath.Join 和 os.Open 之前返回；合法的 name 才能进入打开阶段；打开失败时不能把“路径通过检查”误报成“文件读取成功”。

相关问题

filepath.IsLocal 会检查符号链接吗？

不会。它是纯词法操作，只分析路径字符串，不会解析磁盘上的符号链接。

filepath.Clean 能代替 filepath.IsLocal 吗？

不能。Clean 负责规范化，IsLocal 负责判断路径是否为空、绝对或清理后越出当前目录。

filepath.Join 会自动拒绝危险输入吗？

不能把 Join 当输入校验器。先判断用户提供的 name，再 Join 到受控的 root，责任边界更明确。

小结

处理用户可控文件名时，把 filepath.IsLocal 放在输入门，把 filepath.Join 放在路径组合处，把 os.Open 放在最终访问处。这样既能覆盖常见的词法路径逃逸，也不会掩盖符号链接、权限和跨平台差异带来的真实风险。