Go tar.Header.Name包含相对路径时的安全判断方法

处理 tar 包时，Header.Name 不是天然可信的本地文件名。docs/readme.txt 这类带目录的相对路径通常是正常条目；真正需要拦截的是绝对路径、包含父目录跳转的路径，以及会通过链接目标绕出解压目录的条目。实用做法是把路径判断、条目类型和最终写入根目录分开处理。

先分清“带目录的相对路径”和路径穿越

tar 名称使用斜杠表示归档内部层级，所以 assets/css/app.css 仍然是本地相对路径。/etc/passwd、../config.yaml 和 cache/../../secret 则可能把写入位置带出预期目录。判断时应让 Go 按当前平台规则处理，而不是自己拼一组字符串前缀。

// isSafeTarName 只判断归档条目名的词法边界，不负责验证链接目标。
func isSafeTarName(name string) bool {
	if name == "" {
		return false // 空名称无法映射成稳定的输出文件
	}
	local := filepath.FromSlash(name) // tar 使用 /，落盘前转换为当前平台分隔符
	if filepath.IsAbs(local) || !filepath.IsLocal(local) {
		return false // 拒绝绝对路径和清理后会离开当前目录的路径
	}
	return filepath.Clean(local) != "." // 不把归档根目录写成一个普通文件
}

filepath.IsLocal 的价值在于覆盖绝对路径、.. 组件和当前平台的特殊名称。它不会判断文件内容，也不会因为条目名安全就让符号链接安全。第一张说明图把 Header.Name、FromSlash、Clean 和 IsLocal 的静态关系放在同一边界里，便于区分“名称检查”和“写文件”。

ErrInsecurePath 只解决名称层，链接仍要单独处理

官方 archive/tar 文档说明：当 GODEBUG=tarinsecurepath=0 时，Reader.Next 遇到非本地文件名会返回带有 tar.ErrInsecurePath 的 Header。生产解压器不应简单忽略这个错误；如果应用明确支持这类归档，也应先完成自己的清理和策略判断，再决定是否继续。

// extractEntry 展示落盘前的最小策略：拒绝不安全名称和链接条目。
func extractEntry(root string, hdr *tar.Header, tr io.Reader) error {
	if !isSafeTarName(hdr.Name) {
		return fmt.Errorf("拒绝不安全归档路径: %q", hdr.Name)
	}
	if hdr.Typeflag == tar.TypeSymlink || hdr.Typeflag == tar.TypeLink {
		return fmt.Errorf("拒绝链接条目: %q", hdr.Name) // 链接目标不属于 ErrInsecurePath 的检查范围
	}
	if hdr.Size  64

这个示例适合“只接收普通文件和目录”的场景。若业务必须保留链接，不能只把 hdr.Linkname 再做一次字符串替换；应把链接目标也限定在根目录内，并使用更强的受限文件 API 或创建后复查。第二张说明图对应的是条目类型、固定根目录、大小限制和目标文件之间的静态边界。

上线前用五项清单复核

相关问题

所有包含斜杠的 Header.Name 都要拒绝吗？

不用。pkg/config.yaml 是常见的本地相对路径，关键是它清理后不能越出当前目录。

忽略 ErrInsecurePath 就一定会被攻击吗？

不一定，但这代表调用方主动接管了不安全名称。若继续直接 Join 到输出目录，就把风险留给了文件系统。

filepath.IsLocal 能替代完整的安全解压吗？

不能。它主要解决条目名的词法边界；链接、文件大小、权限、磁盘配额和竞态仍需要独立策略。