Go tar 解包出现目录穿越时如何识别危险路径

Go 用 archive/tar 读取归档时，真正需要先审查的不是文件内容，而是每个 Header.Name 将要落到哪里。../../etc/app.conf、/tmp/out、带反斜杠的跨平台路径，以及指向根目录外部的链接条目，都不能直接交给 filepath.Join 和文件写入 API。

最小可靠判断是：先把条目名当成不可信输入，拒绝非本地路径，再把规范化后的目标与允许根目录做相对路径比较；对符号链接、硬链接和特殊文件则默认拒绝。词法判断通过，只代表字符串没有越界，不代表真实文件系统一定安全。

步骤一：先把 Header.Name 当成不可信输入

archive/tar 的读取循环会逐个返回归档条目。归档来自上传、下载或第三方构建产物时，Header.Name 就相当于外部输入；不要因为它来自 tar 头部而默认可信。目录名末尾的斜杠只是类型提示，真正决定写入位置的是完整路径。

for {
    hdr, err := tr.Next()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return fmt.Errorf("读取 tar 条目失败: %w", err)
    }
    // 先检查 hdr.Name，再根据类型决定是否创建目标。
    fmt.Println(hdr.Name, hdr.Typeflag)
}

需要重点拦截的信号包括绝对路径、清理后仍含 .. 的相对路径、空名称和包含反斜杠的名称。后者在 Unix 上可能只是普通字符，但在 Windows 上会参与目录分隔；跨平台服务最好统一拒绝，避免同一归档在不同系统上解释不一致。

步骤二：用 IsLocal 和 Rel 做根目录边界判断

filepath.Clean 会整理字符串，但不会替你授权路径。Go 1.20 及以后可以先用 filepath.IsLocal 判断路径是否非空、非绝对且词法上不会走出当前目录；再把它拼到已经确定的根目录下，用 filepath.Rel 检查最终结果。这两层写在同一个入口里，后面的解包逻辑就不会各自发明判断。

func resolveTarPath(root, name string) (string, error) {
    if name == "" || strings.ContainsRune(name, 0) {
        return "", errors.New("tar 条目名为空或含 NUL")
    }
    // tar 约定使用斜杠；拒绝反斜杠，避免跨平台产生另一种路径解释。
    if strings.ContainsRune(name, '\\') {
        return "", errors.New("tar 条目名含反斜杠")
    }

    localName := filepath.FromSlash(name)
    if !filepath.IsLocal(localName) {
        return "", fmt.Errorf("危险 tar 路径: %q", name)
    }
    base, err := filepath.Abs(root)
    if err != nil {
        return "", fmt.Errorf("解析目标根目录失败: %w", err)
    }
    target := filepath.Join(base, localName)
    rel, err := filepath.Rel(base, target)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", fmt.Errorf("目标超出根目录: %q", name)
    }
    return target, nil
}

这里的 Rel 判断不能换成 strings.HasPrefix(target, base)。例如根目录是 /srv/app，目标 /srv/application 也会通过字符串前缀判断，但它并不在 /srv/app 子树中。路径比较要按分隔符和相对结果来做。

步骤三：目录穿越不只发生在普通文件名上

只检查 Header.Name 还不够。tar 头部还可能表示目录、符号链接、硬链接、设备节点或 FIFO。特别是符号链接的 Header.Linkname 是另一条路径输入：即使链接本身的名字位于根目录内，链接目标仍可能指向根目录外。

如果业务只是解包配置、静态资源和普通目录，最简单的策略是只接受 TypeReg 与 TypeDir，其他类型直接记录并拒绝：

func allowedTarType(hdr *tar.Header) error {
    switch hdr.Typeflag {
    case tar.TypeReg, tar.TypeRegA, tar.TypeDir:
        return nil
    case tar.TypeSymlink, tar.TypeLink:
        // 不写入链接，避免 Linkname 把访问引向根目录之外。
        return fmt.Errorf("拒绝链接条目 %q -> %q", hdr.Name, hdr.Linkname)
    default:
        // 设备、FIFO 等特殊文件不属于普通应用解包范围。
        return fmt.Errorf("拒绝特殊 tar 条目 %q，类型=%q", hdr.Name, hdr.Typeflag)
    }
}

如果确实要保留链接，必须把 Linkname 按与 Name 同等严格的规则校验，还要明确链接相对于哪个目录解释；这不是在 os.Symlink 前加一行 Clean 就能完成的功能。多数上传解包场景并不需要链接，默认拒绝更容易审计。

步骤四：词法校验通过后仍要看符号链接

filepath.IsLocal 和 filepath.Rel 都是词法层面的操作。假设根目录中已经存在 cache 符号链接，它指向另一个目录，那么 cache/report.txt 在字符串上完全合法，实际打开时却可能落到允许根目录之外。filepath.EvalSymlinks 可以解析已经存在的路径，再做一次边界判断，但它只适合解决“当前文件系统状态”的检查。

func existingTargetUnder(root, target string) (string, error) {
    realRoot, err := filepath.EvalSymlinks(root)
    if err != nil {
        return "", fmt.Errorf("解析根目录链接失败: %w", err)
    }
    realTarget, err := filepath.EvalSymlinks(target)
    if err != nil {
        return "", fmt.Errorf("解析目标链接失败: %w", err)
    }
    rel, err := filepath.Rel(realRoot, realTarget)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", errors.New("符号链接解析后超出目标根目录")
    }
    return realTarget, nil
}

这段代码适合检查已有目录或文件。新文件在写入前可能还不存在，不能简单地对最终路径调用 EvalSymlinks；应检查其父目录并控制创建过程。更重要的是，检查和打开之间存在竞态：另一个进程可能在两次操作之间替换目录。面对不可信写入者时，应使用操作系统提供的目录句柄、禁止跟随链接的打开选项，或把整个解包过程放进隔离的临时目录，再以受控方式移动结果。

步骤五：把拒绝原因写进审计清单

安全判断最怕“返回错误但没有上下文”。建议为每个拒绝条目保留归档标识、Header.Name、Header.Linkname、条目类型和原因，例如 absolute-path、parent-escape、link-entry 或 special-file。日志中不要把服务器绝对路径直接回显给外部请求，但内部记录应足够让运维定位来源归档。

• 目标根目录是否在解包开始前已解析为绝对路径，并且权限属于专用工作目录？
• 每个 Header.Name 是否先经过空值、分隔符、IsLocal 和 Rel 检查？
• 是否默认拒绝符号链接、硬链接、设备节点和 FIFO？
• 是否限制单个文件大小、条目数量和总解包容量，避免路径安全检查通过后又被资源耗尽？
• 失败时是否删除临时目录，并区分“危险路径”和普通 I/O 错误？

可以把 Clean 理解为整理文本，把 IsLocal 和 Rel 理解为词法边界，把 EvalSymlinks 和文件系统级打开策略理解为真实目标边界。三层职责分开，才不会把“字符串看起来正常”误当成“归档可以安全落盘”。

相关问题

Go 的 tar.Reader.Next 会自动阻止目录穿越吗？

当前文档说明，遇到非本地名称时，Next 可在特定 GODEBUG 设置下返回 ErrInsecurePath；应用仍应在写文件前自行执行明确的路径和条目类型策略，不能把运行时开关当成完整解包授权。

filepath.Clean 能不能替代 filepath.IsLocal？

不能。Clean 只规范化路径文本；IsLocal 才明确判断路径是否为空、绝对或词法上离开当前目录。两者都不处理已有符号链接。

只拒绝 ../ 就够了吗？

不够。还要拒绝绝对路径、跨平台分隔符、链接条目和特殊文件，并在实际文件系统可能存在链接时补做真实目标或隔离写入检查。