zip 解包中的相对路径校验与目录穿越防护

Go 用 archive/zip 解包时，最容易出问题的地方不是“能不能读出文件”，而是“条目名最终会写到哪里”。ZIP 内的 File.Name 来自外部输入，不能直接与目标目录拼接；正确顺序是先把它限制为安全的相对路径，再计算目标文件，最后创建目录和写入文件。

本文只处理路径穿越这一条主线：拒绝绝对路径、../、反斜杠混用和非本地路径，并说明为什么安全根目录还要保持隔离、不能预先放入可跟随的符号链接。

archive/zip 的条目名为什么不能直接落盘

archive/zip 的 FileHeader.Name 应该是相对路径，并使用正斜杠；目录通常以末尾的斜杠表示。官方文档还提供了 ErrInsecurePath，当条目名不是本地路径，或包含反斜杠且启用了相应的 GODEBUG 行为时，打开归档可能返回这个错误。

但应用不能把“当前 Go 版本是否返回错误”当作唯一防线。业务代码仍应在写盘前显式检查，因为解包目标、运行平台和兼容策略可能变化。下面这段小函数把检查集中在一个地方，避免每个调用点各写一套不完整的字符串判断。

先把条目名限制为安全相对路径

package main

import (
    "fmt"
    "os"
    "path"
    "path/filepath"
    "strings"
)

// safeTarget 只返回安全根目录下的目标路径，不负责创建文件。
func safeTarget(root, entryName string) (string, error) {
    // ZIP 规范使用正斜杠，先统一分隔符，避免混合写法绕过检查。
    normalized := strings.ReplaceAll(entryName, `\`, "/")
    normalized = path.Clean(normalized)
    if normalized == "." || normalized == "" {
        return "", fmt.Errorf("empty zip entry: %q", entryName)
    }

    // 先拒绝明显的绝对路径和父目录跳转，再交给平台规则判断。
    if strings.HasPrefix(normalized, "/") || normalized == ".." ||
        strings.HasPrefix(normalized, "../") {
        return "", fmt.Errorf("path traversal is not allowed: %q", entryName)
    }
    if !filepath.IsLocal(normalized) {
        return "", fmt.Errorf("non-local zip path: %q", entryName)
    }

    rootAbs, err := filepath.Abs(root)
    if err != nil {
        return "", fmt.Errorf("resolve root: %w", err)
    }
    targetAbs, err := filepath.Abs(filepath.Join(rootAbs, filepath.FromSlash(normalized)))
    if err != nil {
        return "", fmt.Errorf("resolve target: %w", err)
    }

    // 再做一次相对关系复核，确保目标仍位于 rootAbs 内。
    rel, err := filepath.Rel(rootAbs, targetAbs)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
        return "", fmt.Errorf("target escapes root: %q", entryName)
    }
    return targetAbs, nil
}

这里的关键不是把字符串“清理得更漂亮”，而是把结果限定成一个可证明的关系：targetAbs 必须位于 rootAbs 下面。filepath.IsLocal 负责平台相关的本地路径判断，最后的 filepath.Rel 则是对目标关系的二次确认。

先校验，再创建目录和文件

有了安全目标路径后，解包循环要保持固定顺序：读取条目、校验名称、判断目录、创建父目录、以不覆盖模式创建文件、复制内容。不要先根据原始名称调用 MkdirAll，再回头检查；那样已经把外部输入带进了文件系统操作。

package main

import (
    "archive/zip"
    "errors"
    "fmt"
    "io"
    "os"
    "path/filepath"
    "strings"
)

// extractZip 把归档内容写入一个由调用方准备好的安全根目录。
func extractZip(zipName, root string) error {
    zr, err := zip.OpenReader(zipName)
    if err != nil {
        // OpenReader 可能同时返回 reader 和 ErrInsecurePath，避免泄漏句柄。
        if zr != nil {
            _ = zr.Close()
        }
        if errors.Is(err, zip.ErrInsecurePath) {
            return fmt.Errorf("reject insecure zip paths: %w", err)
        }
        return fmt.Errorf("open zip: %w", err)
    }
    defer zr.Close()

    for _, entry := range zr.File {
        target, err := safeTarget(root, entry.Name)
        if err != nil {
            return err
        }

        // 目录只创建经过校验的目标路径，不能使用原始条目名。
        if entry.FileInfo().IsDir() || strings.HasSuffix(entry.Name, "/") {
            if err := os.MkdirAll(target, 0750); err != nil {
                return fmt.Errorf("create directory %q: %w", entry.Name, err)
            }
            continue
        }

        if err := os.MkdirAll(filepath.Dir(target), 0750); err != nil {
            return fmt.Errorf("create parent for %q: %w", entry.Name, err)
        }

        // O_EXCL 防止在同一次解包中静默覆盖已有文件。
        dst, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
        if err != nil {
            return fmt.Errorf("create file %q: %w", entry.Name, err)
        }
        src, err := entry.Open()
        if err != nil {
            _ = dst.Close()
            _ = os.Remove(target)
            return fmt.Errorf("open entry %q: %w", entry.Name, err)
        }

        // 复制完成后同时检查 Copy 和 Close，避免吞掉写盘错误。
        _, copyErr := io.Copy(dst, src)
        closeSrcErr := src.Close()
        closeDstErr := dst.Close()
        if copyErr != nil || closeSrcErr != nil || closeDstErr != nil {
            _ = os.Remove(target)
            return fmt.Errorf("write entry %q: copy=%v source_close=%v dest_close=%v",
                entry.Name, copyErr, closeSrcErr, closeDstErr)
        }
    }
    return nil
}

O_EXCL 是一个有意的取舍：同名文件直接报错，调用方可以选择整包失败、换一个临时目录，或由上层定义覆盖策略。若业务必须覆盖文件，也应把“是否允许覆盖”作为显式策略，而不是让解包过程默认覆盖。

ErrInsecurePath、反斜杠和目录条目怎么处理

当 OpenReader 返回 ErrInsecurePath 时，示例选择拒绝整个归档。这适合上传解包、插件导入和自动化流水线：调用方不需要猜测哪些条目安全，也不会因为忽略错误而把同一批输入分成难以审计的两种结果。

目录条目同样先经过 safeTarget。不能因为它没有文件内容，就跳过路径校验；目录穿越可能发生在创建父目录阶段。反斜杠也不要当成普通字符放行，尤其是服务需要在不同操作系统上运行时，统一分隔符后再做平台路径判断更稳妥。

词法校验之外，还要留意符号链接

上面的代码解决的是条目名的词法越界。它默认 root 是新建或隔离的目录，里面没有攻击者预先放置的符号链接。如果目标目录可被其他进程写入，或者归档本身包含需要特殊处理的链接条目，那么“路径看起来在 root 下”并不等于最终文件系统访问一定留在 root 内。

生产环境可以采用三条策略：把每个归档解到独立临时目录，完成后再以受控方式搬运结果；拒绝符号链接等特殊条目；在支持的平台和 Go 版本上使用带 root/no-follow 语义的文件打开方式。无论采用哪一条，都要把目录权限、并发访问者和清理失败纳入设计。

一份可落地的解包检查表

相关问题

只调用 filepath.Clean 就够了吗？

不够。Clean 只是规范化字符串，不能替你决定绝对路径是否允许，也不能证明最终目标没有离开安全根目录。它应该是路径处理的一环，而不是完整的安全策略。

为什么不直接忽略 ErrInsecurePath？

只有在业务明确接受非本地名称，并且后续仍会逐条执行同等严格的路径策略时才有理由忽略。对上传文件和自动化导入，直接拒绝通常更容易审计。

用 filepath.Join(root, entry.Name) 会自动防穿越吗？

不能把它当作防护。即使路径拼接结果经过清理，也需要显式确认目标仍在 root 内，并处理符号链接、覆盖策略和目录权限。