Go os.DirFS 为什么不保证阻止符号链接逃逸

os.DirFS 不保证阻止符号链接逃逸，因为它提供的是“打开路径以指定目录为前缀”的语义，而不是一个会约束最终文件位置的沙箱。根目录里的文件如果是符号链接，操作系统照常解析它；目标位于根目录外时，DirFS 本身不会拦截。

我在设计一个只读文件浏览小项目时，最容易做出的错误判断是：只要输入通过 fs.ValidPath，再交给 os.DirFS，目录边界就已经成立。官方文档明确否定了这个推断。对 Go 1.24 及以上版本，接收不可信路径时更合适的基础设施是 os.OpenRoot 配合 Root.FS，单次操作也可以直接使用 os.OpenInRoot。

Go os 文档：https://pkg.go.dev/os#DirFS

Go io/fs 文档：https://pkg.go.dev/io/fs#ValidPath

从一个看似安全的只读资源层开始

假设小项目只允许客户端读取 site 目录中的静态文件。最初的实现很自然：先验证相对路径，再用 DirFS 暴露目录。

package assets

import (
    "io/fs"
    "os"
)

func ReadAsset(root, name string) ([]byte, error) {
    // 拒绝绝对路径、点目录和不规范的斜杠形式。
    if !fs.ValidPath(name) {
        return nil, fs.ErrInvalid
    }

    // DirFS 将 root 作为后续文件名的路径前缀。
    return fs.ReadFile(os.DirFS(root), name)
}

这段代码对 ../secret.txt 很有效，因为它不符合 fs.ValidPath。问题在于，攻击者不一定要把 .. 写进请求。只要目录内容中已经存在一个名字正常、目标越界的符号链接，输入可以简单到只有 leak。

fs.ValidPath 检查的是字符串，不是文件系统

fs.ValidPath 规定的是 fs.FS 使用的 slash 分隔路径格式。合法路径不能是空字符串，不能是绝对路径，不能包含空组件、. 或 .. 组件；根目录用单独的 . 表示。

这些规则能阻止直接的路径穿越字符串，却无法回答“这个名字在磁盘上最终指向哪里”。符号链接的解析发生在文件系统层，而不是字符串校验层。下面这个目录结构就足以展示差异：

/srv/
├── secret.txt
└── site/
    ├── public.txt
    └── leak -> ../secret.txt

leak 本身是一个完全合法的 fs.ValidPath。代码最终请求打开 /srv/site/leak，操作系统解析符号链接后却访问了 /srv/secret.txt。从字符串看没有越界组件，从真实文件位置看已经离开根目录。

DirFS 只限定打开路径前缀

官方对 DirFS 的描述很直接：DirFS("/prefix").Open("file") 等价于 os.Open("/prefix/file")。它保证传给操作系统打开函数的路径以这个前缀开头，但如果 /prefix/file 是指向目录树外部的符号链接，DirFS 不会阻止访问。

换句话说，DirFS 的边界停在“构造了哪个路径”这里；符号链接的最终解析仍遵循普通操作系统规则。这也是为什么 filepath.Clean、禁止 .. 或检查字符串前缀都不能补齐漏洞：这些办法仍然只处理词法路径。

还有一个容易遗漏的细节：如果使用 os.DirFS("site") 这样的相对根目录，后续调用 os.Chdir 会改变它实际指向的位置。长期运行的服务最好至少传入绝对路径，但“改成绝对路径”依然只解决工作目录漂移，不能解决符号链接逃逸。

用 Root.FS 建立目录边界

Go 1.24 引入的 os.Root 面向的正是“只能访问某个目录树下面的路径”这一需求。os.OpenRoot 打开根目录并返回句柄，Root.FS 再把这个边界适配为标准 fs.FS。符号链接仍然可以使用，但只有解析结果继续位于根目录内时才允许访问；绝对符号链接不会被接受。

package assets

import (
    "io/fs"
    "os"
)

type Store struct {
    root *os.Root
}

func OpenStore(dir string) (*Store, error) {
    // 打开受限根目录，后续访问都从这个目录句柄出发。
    root, err := os.OpenRoot(dir)
    if err != nil {
        return nil, err
    }
    return &Store{root: root}, nil
}

func (s *Store) Read(name string) ([]byte, error) {
    // ValidPath 负责 fs.FS 的输入格式，Root.FS 负责目录边界。
    if !fs.ValidPath(name) {
        return nil, fs.ErrInvalid
    }
    return fs.ReadFile(s.root.FS(), name)
}

func (s *Store) Close() error {
    // 服务退出时释放根目录句柄。
    return s.root.Close()
}

这里仍然保留 fs.ValidPath，但职责已经拆清楚：它确保传给 fs.FS 的名称格式正确；真正阻止最终目标离开根目录的是 Root。即使 site/leak 指向外部，读取也会返回错误，而不是跟随到根目录之外。

只打开一个文件时使用 OpenInRoot

如果没有长期复用文件系统对象的需求，只想执行一次受限打开，可以直接使用 os.OpenInRoot。它等价于先 OpenRoot、再调用根对象的 Open，并在名字的任何组件指向目录外时返回错误。

package assets

import (
    "io"
    "os"
)

func ReadOnce(rootDir, name string) ([]byte, error) {
    // OpenInRoot 在打开过程中约束最终路径仍位于 rootDir 下。
    file, err := os.OpenInRoot(rootDir, name)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    // 示例读取全部内容；生产代码还应按业务限制文件大小。
    return io.ReadAll(file)
}

两种接口的选择很简单：需要重复读取、遍历或传给接收 fs.FS 的库时，用 OpenRoot 加 Root.FS；一次性打开文件时，用 OpenInRoot 更直接。

为什么 Clean 加前缀检查仍然不够

旧项目里常见的补丁是先 filepath.Clean，再把根目录和用户路径拼接，最后检查结果是否仍以根目录字符串开头。这个办法最多处理显式的 .. 与分隔符问题，不能保证系统解析符号链接后的最终位置。

更重要的是，先解析真实路径再打开文件也可能留下检查与使用之间的竞争窗口。Root 提供的是面向文件操作的目录范围原语，避免让业务层靠字符串规则自行模拟边界。

Root 也不是完整的操作系统沙箱

把实现换成 os.Root 后，项目获得的是“路径不能逃离指定目录”的能力，不是全部隔离能力。官方文档列出了需要单独评估的范围：

• 文件系统边界：Root 不阻止访问根目录树中的挂载点，也不隔离 Linux bind mount。
• 特殊文件：/proc 风格的特殊内容和 Unix 设备文件可能提供超出普通文件读取的能力。
• 平台差异：不同操作系统的底层保证并不完全相同，面向多平台发布时应阅读目标版本文档。
• 业务限制：文件大小、类型、数量、读取速率与权限策略仍要在应用层控制。

如果目录本身由应用打包、内容可信且不会被外部用户修改，DirFS 仍然非常实用，例如嵌入式测试替身、可信静态资源目录或只需要统一 fs.FS 接口的场景。风险来自把它误当成面对恶意路径或任意目录内容时的安全边界。

项目改写后的检查清单

1. 确认输入是否来自用户、归档包、插件或其他不可信来源。
2. 确认根目录内容是否可能包含外部创建的符号链接。
3. Go 1.24+ 优先把受限访问收口到 os.Root 或 os.OpenInRoot。
4. 继续使用 fs.ValidPath 维护 fs.FS 名称契约，但不要把它当成越界防护。
5. 测试普通文件、根内符号链接、根外符号链接、绝对链接和多层链接。
6. 在业务层补充文件大小、类型、读取次数和错误日志限制。

这次小项目最关键的改动，不是把一个 API 名字换成另一个，而是把两类责任拆开：词法路径由 fs.ValidPath 管，真实目录边界由 os.Root 管。这样代码审查时就不必再从一串清理、拼接和前缀判断中猜测安全属性。

相关问题

os.DirFS 还适合用于生产吗？

适合。只要目录内容可信、调用者不依赖它提供安全隔离，DirFS 是轻量而方便的 fs.FS 适配器。问题在于把它当作 chroot 式边界。

禁止用户输入 .. 就足够了吗？

不够。用户可以请求一个普通名称，而这个名称在根目录中恰好是指向外部的符号链接，整个请求里完全不需要出现 ..。

Go 1.23 及更早版本怎么办？

os.Root 从 Go 1.24 开始提供。旧版本若有安全边界需求，应优先升级；不能升级时需要采用目标平台专用的安全打开机制并进行严格审计，不建议用字符串拼接规则自行近似。

Root.FS 会完全禁止符号链接吗？

不会。它允许最终目标仍位于根目录内的符号链接，拒绝绝对链接和解析后离开根目录的链接。