Tencent/WeKnora · error

object key contains path traversal

Error message

object key contains path traversal

What it means

SafeObjectKey validates object-storage keys (COS/MinIO/S3 object names) before they are used in API calls. It rejects keys containing ".." to prevent path-traversal attacks where a crafted key could escape its intended prefix/directory and access other objects or paths. An empty key is also rejected.

Source

Thrown at internal/utils/security.go:153

	if base == "" || base == "." || base == ".." {
		return "", fmt.Errorf("invalid fileName: path traversal or empty name")
	}
	if strings.Contains(base, "..") {
		return "", fmt.Errorf("invalid fileName: contains path traversal")
	}
	if len(base) > 255 {
		return "", fmt.Errorf("fileName too long")
	}
	return base, nil
}

// SafeObjectKey 校验对象存储的 key（如 COS/MinIO objectName），禁止包含 ".." 等路径遍历
func SafeObjectKey(objectKey string) error {
	if objectKey == "" {
		return fmt.Errorf("object key cannot be empty")
	}
	if strings.Contains(objectKey, "..") {
		return fmt.Errorf("object key contains path traversal")
	}
	return nil
}

// IsValidURL 验证 URL 是否安全
func IsValidURL(url string) bool {
	if url == "" {
		return false
	}

	// 检查长度
	if len(url) > 2048 {
		return false
	}

	// Internal resource references are resolved through authenticated file
	// proxies; provider schemes remain supported for legacy stored content.
	allowedProtocols := []string{

View on GitHub (pinned to 988cbb0330)

Solutions

1. Strip or reject ".." segments from the key before calling the API: use path.Clean and verify the cleaned key still lies under the intended prefix
2. Sanitize user input: replace path separators, remove leading slashes, and reject any segment equal to ".."
3. Construct keys programmatically from safe identifiers (UUIDs, hashes) instead of raw user filenames
4. If ".." is legitimately part of a filename (e.g. "report..v2.pdf"), rename the object or escape/encode it

Example fix

// before
key := "uploads/" + userFilename // userFilename = "../../secret"
err := SafeObjectKey(key)
// after
key := path.Clean("uploads/" + strings.ReplaceAll(userFilename, "..", "_"))
if strings.HasPrefix(key, "uploads/") {
    err := SafeObjectKey(key)
}

func safeKey(key string) error {
    if key == "" || strings.Contains(key, "..") {
        return fmt.Errorf("invalid object key: %q", key)
    }
    return nil
}
if err := safeKey(userKey); err != nil { return err }

func isSafeObjectKey(key string) bool {
    return key != "" && !strings.Contains(key, "..")
}

key, err := buildKey(userInput)
if err != nil {
    var secErr *SecurityError
    if errors.As(err, &secErr) {
        http.Error(w, "invalid object key", http.StatusBadRequest)
        return
    }
    return err
}

When it happens

Trigger: Calling GetFile, DeleteFile, CopyFile, or GetFileURL (or parseMinioFilePath/parseS3FilePath) with an object key that contains the substring "..", e.g. "../../etc/passwd", "a/../b", or "file..txt".

Common situations: Building keys from user-supplied file names without sanitizing; joining paths manually with filepath.Join and not cleaning the result; legacy clients uploading keys with dot-dot segments; bugs in relative-path resolution.

Related errors

• invalid file path: %w
• invalid file name: %w
• invalid source path: %w
• invalid file path: %w
• join request not found

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/1c97664d06d1a208. Report an issue: GitHub.