Go symlink 检查通过但打开了意外文件怎么办

如果代码先用 filepath.EvalSymlinks 检查路径，再把检查结果交给 os.Open，却仍然打开了意外文件，重点通常不在“解析错了”，而在检查和使用之间存在一个可被替换的时间窗口。符号链接或父目录在这段时间发生变化，就可能让第二次路径解析得到不同结果。

官方地址：https://go.dev/

先看清：EvalSymlinks 解决了什么，没解决什么

filepath.EvalSymlinks 的职责是返回经过符号链接解析后的路径，并对结果做清理。它适合帮助程序回答“当前这一刻，这个名字解析到了哪里”。如果输入只是普通用户提供的相对文件名，配合 filepath.IsLocal 还可以挡住绝对路径和 .. 这类明显的越界输入。

但下面这种写法把“判断”和“打开”拆成了两个独立动作。它可以作为说明问题的旧模式，不能当成对抗可修改本地文件系统的完整方案：

package main

import (
	"errors"
	"os"
	"path/filepath"
)

func openAfterCheck(baseDir, name string) (*os.File, error) {
	// 先做词法检查，阻止绝对路径和 .. 直接离开业务目录。
	if !filepath.IsLocal(name) {
		return nil, errors.New("文件名必须是本地相对路径")
	}

	// 解析当下可见的符号链接，但这一步不会固定后续 Open 的解析环境。
	resolved, err := filepath.EvalSymlinks(filepath.Join(baseDir, name))
	if err != nil {
		return nil, err
	}
	if !filepath.IsLocal(resolved) {
		return nil, errors.New("解析后的路径越出允许范围")
	}

	// 检查完成后再次按路径打开，期间文件系统状态可能已经改变。
	return os.Open(resolved)
}

这里还有一个容易忽略的细节：即使 resolved 在检查时位于预期目录，后续 os.Open 仍会重新遍历路径。程序没有把“检查时看到的目录项”绑定成“打开时必须使用的对象”。

为什么检查通过，第二次打开仍可能指向意外文件

假设业务目录是固定的，外部输入指定了其中一个文件名。第一次解析时，路径中的链接指向目录内，检查自然通过；随后另一个进程把链接或父目录替换成了不同对象；最后 os.Open 再遍历同一个字符串时，看到的已经不是第一次检查时的目录结构。

这就是 TOCTOU，也就是 time-of-check 与 time-of-use 之间的竞态。它不是把 EvalSymlinks 的返回值读错，而是“检查结果”没有成为“打开操作”的不可变前提。风险成立需要额外条件：运行环境中的其他参与者能够影响相关目录、链接或挂载结构。单纯面向普通用户输入的词法校验，不能自动等价为同一类防护。

Go 1.24 及以上优先迁移到 os.OpenInRoot

如果需求是“打开某个固定目录内的不可信文件名”，Go 1.24 新增的 os.OpenInRoot 更贴合这个约束。它接收根目录和相对文件名，返回越出根目录的路径错误；内部 API 的目标就是避免程序在路径检查与使用之间重复暴露一个可替换的窗口。

package main

import (
	"errors"
	"io"
	"os"
	"path/filepath"
)

func readUnderRoot(rootDir, name string) ([]byte, error) {
	// 先限制输入格式，给调用方一个明确的参数错误。
	if !filepath.IsLocal(name) {
		return nil, errors.New("文件名必须是本地相对路径")
	}

	// OpenInRoot 把 name 解释在 rootDir 内，阻止 .. 和越出根目录的符号链接。
	f, err := os.OpenInRoot(rootDir, name)
	if err != nil {
		return nil, err
	}
	defer f.Close() // 文件读取结束后释放句柄，避免长期占用根目录下的资源。

	return io.ReadAll(f)
}

如果一个请求要多次操作同一棵目录树，可以先调用 os.OpenRoot 得到 *os.Root，随后使用 root.Open、root.Stat 等方法。这样可以把“允许访问的根”变成一个明确的对象，而不是每次都重新拼接绝对路径：

func openConfig(rootDir, relativeName string) (*os.File, error) {
	// 根对象代表允许访问的目录树，调用方结束时统一关闭。
	root, err := os.OpenRoot(rootDir)
	if err != nil {
		return nil, err
	}
	defer root.Close()

	// 文件名只在 root 内解析，越界路径会由 Root 方法返回错误。
	return root.Open(relativeName)
}

代码中的 root.Open 返回文件后，根对象仍然需要由负责创建它的函数关闭。实际项目还应根据用途决定是否允许写入、是否需要 OpenFile 的只读标志，以及是否对文件大小做业务限制。

不能升级时，如何把降级策略说准确

旧版本没有 os.Root 时，可以组合使用 filepath.IsLocal、可信且权限隔离的目录、最小化进程权限和一次性打开后的句柄操作，降低普通输入错误的风险。但这组措施不应该被表述成“彻底修复 TOCTOU”。如果威胁模型允许其他参与者在本地文件系统中替换链接，优先升级 Go，或采用经过维护的目录约束文件 API。

还要把平台边界写进设计说明：os.Root 会阻止通过符号链接越出根目录，但不等于阻止所有挂载点、设备文件或平台实现差异；官方文档也对 Unix、Windows、WASI、JavaScript 等环境分别列出限制。不要为了追求一个统一的“安全路径字符串”，把平台语义压平。

按场景决定使用哪种写法

最终排查顺序可以压缩成一句话：先问“输入是否只是词法不可信”，再问“谁能在本地改变目录项”，最后决定是用 IsLocal 做清理，还是用 OpenInRoot 把打开动作约束在目录根内。对本文主题，修复关键不是多调用一次 EvalSymlinks，而是减少路径检查与文件使用之间的分离。

技术事实可继续参考 https://pkg.go.dev/path/filepath#EvalSymlinks、https://pkg.go.dev/os#OpenInRoot 和 Go 官方文章 https://go.dev/blog/osroot。

相关问题

filepath.IsLocal 能替代 EvalSymlinks 吗？

不能简单替代。IsLocal 是词法判断，不会考虑文件系统中已经存在的符号链接；它适合过滤明显的绝对路径和 ..，而不是单独承担目录树访问隔离。

EvalSymlinks 之后再调用 filepath.Rel 就安全了吗？

这仍然是先检查、后使用的两步逻辑。它可以改善路径比较，却不会把后续的文件打开变成与检查绑定的原子操作。

os.OpenInRoot 会禁止根目录内的所有符号链接吗？

不会。根目录内、最终仍然落在根目录树中的链接可以被跟随；真正被拒绝的是解析后越出根目录的路径。挂载点、设备文件和具体平台限制仍要单独纳入威胁模型。