Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(cli): normalize skill zip paths (#2615)

Zayn Jarvis56c903afc65a
diff --git a/crates/ov_cli/src/base_client.rs b/crates/ov_cli/src/base_client.rs
index 810c97b9f..1cf5e58ef 100644
--- a/crates/ov_cli/src/base_client.rs
+++ b/crates/ov_cli/src/base_client.rs
@@ -52,6 +52,20 @@ fn ignore_dirs_filter<'a>(
}
}
+fn normalize_zip_entry_name(path: &str) -> String {
+ path.replace('\\', "/")
+}
+
+fn zip_entry_name(relative_path: &Path) -> Result<String> {
+ let name = relative_path.to_str().ok_or_else(|| {
+ Error::InvalidPath(format!(
+ "Non-UTF-8 path: {}",
+ relative_path.to_string_lossy()
+ ))
+ })?;
+ Ok(normalize_zip_entry_name(name))
+}
+
pub fn api_error_from_envelope(json: &Value, status: StatusCode) -> String {
let error_code = json
.get("error")
@@ -626,6 +640,22 @@ mod tests {
assert_eq!(params, vec![("profile".to_string(), "1".to_string())]);
}
+
+ #[test]
+ fn zip_entry_name_normalizes_windows_separators() {
+ let entry = zip_entry_name(Path::new("scripts\\check_bounding_boxes.py"))
+ .expect("path should be utf-8");
+
+ assert_eq!(entry, "scripts/check_bounding_boxes.py");
+ }
+
+ #[test]
+ fn zip_entry_name_preserves_posix_separators() {
+ let entry = zip_entry_name(Path::new("scripts/check_bounding_boxes.py"))
+ .expect("path should be utf-8");
+
+ assert_eq!(entry, "scripts/check_bounding_boxes.py");
+ }
}
// ============ FileUploader ============
@@ -677,9 +707,7 @@ impl<'a> FileUploader<'a> {
let path = entry.path();
if path.is_file() {
let name = path.strip_prefix(dir_path).unwrap_or(path);
- let name_str = name.to_str().ok_or_else(|| {
- Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
- })?;
+ let name_str = zip_entry_name(name)?;
zip.start_file(name_str, options)?;
let mut file = File::open(path)?;
std::io::copy(&mut file, &mut zip)?;
@@ -752,9 +780,7 @@ impl<'a> FileUploader<'a> {
let path = entry.path();
if path.is_file() {
let name = path.strip_prefix(dir_path).unwrap_or(path);
- let name_str = name.to_str().ok_or_else(|| {
- Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
- })?;
+ let name_str = zip_entry_name(name)?;
if verbose {
eprintln!(" Adding: {}", name_str);
}
diff --git a/openviking/parse/parsers/upload_utils.py b/openviking/parse/parsers/upload_utils.py
index 7a61e82e2..9d1f98069 100644
--- a/openviking/parse/parsers/upload_utils.py
+++ b/openviking/parse/parsers/upload_utils.py
@@ -4,7 +4,6 @@
import asyncio
import os
-import re
from pathlib import Path
from typing import Any, List, Optional, Set, Tuple, Union
@@ -18,6 +17,7 @@ from openviking.parse.parsers.constants import (
TEXT_ENCODINGS,
UTF8_VARIANTS,
)
+from openviking.utils.path_safety import safe_join_viking_uri, sanitize_relative_viking_path
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
@@ -150,29 +150,9 @@ def should_skip_directory(
return dir_name in effective_ignore_dirs or dir_name.startswith(".")
-_UNSAFE_PATH_RE = re.compile(r"(^|[\\/])\.\.($|[\\/])")
-_DRIVE_RE = re.compile(r"^[A-Za-z]:")
-
-
def _sanitize_rel_path(rel_path: str) -> str:
- """Normalize a relative path and reject unsafe components.
-
- Uses OS-independent checks so that Windows-style drive prefixes and
- backslash separators are rejected even when running on Linux/macOS.
- """
- if not rel_path:
- raise ValueError(f"Unsafe relative path rejected: {rel_path!r}")
- # Reject absolute paths (Unix or Windows style)
- if rel_path.startswith("/") or rel_path.startswith("\\"):
- raise ValueError(f"Unsafe relative path rejected: {rel_path}")
- # Reject Windows drive letters (C:\..., C:foo)
- if _DRIVE_RE.match(rel_path):
- raise ValueError(f"Unsafe relative path rejected: {rel_path}")
- # Reject parent-directory traversal (../ or ..\)
- if _UNSAFE_PATH_RE.search(rel_path):
- raise ValueError(f"Unsafe relative path rejected: {rel_path}")
- # Normalize to forward slashes
- return rel_path.replace("\\", "/")
+ """Compatibility wrapper for existing upload utility callers/tests."""
+ return sanitize_relative_viking_path(rel_path)
async def upload_text_files(
@@ -186,8 +166,7 @@ async def upload_text_files(
for file_path, rel_path in file_paths:
try:
- safe_rel = _sanitize_rel_path(rel_path)
- target_uri = f"{viking_uri_base}/{safe_rel}"
+ target_uri = safe_join_viking_uri(viking_uri_base, rel_path)
content = file_path.read_bytes()
content = detect_and_convert_encoding(content, file_path)
await viking_fs.write_file_bytes(target_uri, content)
@@ -262,13 +241,12 @@ async def upload_directory(
rel_path_str = str(file_path.relative_to(local_dir)).replace(os.sep, "/")
try:
- safe_rel = _sanitize_rel_path(rel_path_str)
+ target_uri = safe_join_viking_uri(viking_uri_base, rel_path_str)
except ValueError as exc:
warning = f"Skipping {file_path}: {exc}"
warnings.append(warning)
logger.warning(warning)
continue
- target_uri = f"{viking_uri_base}/{safe_rel}"
files_to_upload.append((file_path, target_uri))
parent_uris.add(target_uri.rsplit("/", 1)[0])
diff --git a/openviking/utils/path_safety.py b/openviking/utils/path_safety.py
new file mode 100644
index 000000000..0e7104f11
--- /dev/null
+++ b/openviking/utils/path_safety.py
@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Shared helpers for safe user-supplied path handling."""
+
+import re
+
+from openviking_cli.utils.uri import VikingURI
+
+_UNSAFE_REL_PATH_RE = re.compile(r"(^|[\\/])\.\.($|[\\/])")
+_WINDOWS_DRIVE_RE = re.compile(r"^[A-Za-z]:")
+
+
+def sanitize_relative_viking_path(rel_path: str) -> str:
+ """Normalize a relative path for use inside Viking URI paths.
+
+ The returned path always uses forward slashes. Absolute paths, Windows
+ drive-prefixed paths, and parent-directory traversal are rejected with
+ OS-independent checks.
+ """
+ if not rel_path:
+ raise ValueError(f"Unsafe relative path rejected: {rel_path!r}")
+ if rel_path.startswith("/") or rel_path.startswith("\\"):
+ raise ValueError(f"Unsafe relative path rejected: {rel_path}")
+ if _WINDOWS_DRIVE_RE.match(rel_path):
+ raise ValueError(f"Unsafe relative path rejected: {rel_path}")
+ if _UNSAFE_REL_PATH_RE.search(rel_path):
+ raise ValueError(f"Unsafe relative path rejected: {rel_path}")
+ return rel_path.replace("\\", "/")
+
+
+def safe_join_viking_uri(base_uri: str, rel_path: str) -> str:
+ """Join a Viking URI base with a sanitized relative child path."""
+ safe_rel_path = sanitize_relative_viking_path(rel_path)
+ return VikingURI(base_uri).join(safe_rel_path).uri
diff --git a/openviking/utils/skill_processor.py b/openviking/utils/skill_processor.py
index dd7f1fcab..66d63116c 100644
--- a/openviking/utils/skill_processor.py
+++ b/openviking/utils/skill_processor.py
@@ -32,6 +32,7 @@ from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConve
from openviking.storage.viking_fs import VikingFS
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
+from openviking.utils.path_safety import safe_join_viking_uri
from openviking.utils.zip_safe import safe_extract_zip
from openviking_cli.exceptions import InvalidArgumentError
from openviking_cli.utils import get_logger
@@ -526,9 +527,10 @@ class SkillProcessor:
for aux_file in auxiliary_files:
if base_path:
rel_path = aux_file.relative_to(base_path)
- aux_uri = f"{skill_dir_uri}/{rel_path}"
+ rel_uri_path = rel_path.as_posix()
else:
- aux_uri = f"{skill_dir_uri}/{aux_file.name}"
+ rel_uri_path = aux_file.name
+ aux_uri = safe_join_viking_uri(skill_dir_uri, rel_uri_path)
file_bytes = aux_file.read_bytes()
try:
diff --git a/openviking/utils/zip_safe.py b/openviking/utils/zip_safe.py
index c6883988f..451bd3aee 100644
--- a/openviking/utils/zip_safe.py
+++ b/openviking/utils/zip_safe.py
@@ -3,10 +3,13 @@
"""Safe ZIP extraction with Zip Slip protection."""
import os
+import re
+import shutil
import zipfile
-from pathlib import Path
+from pathlib import Path, PurePosixPath
_UTF8_FLAG = 0x800
+_WINDOWS_DRIVE_RE = re.compile(r"^[A-Za-z]:$")
def _contains_cjk(text: str) -> bool:
@@ -56,17 +59,45 @@ def normalize_zip_filenames(zipf: zipfile.ZipFile) -> None:
zipf.metadata_encoding = "utf-8"
+def _safe_zip_member_path(filename: str) -> Path:
+ normalized = filename.replace("\\", "/")
+ posix_path = PurePosixPath(normalized)
+ if posix_path.is_absolute():
+ raise ValueError(f"Zip Slip attempt detected: {filename}")
+
+ safe_parts: list[str] = []
+ for part in posix_path.parts:
+ if part in {"", "."}:
+ continue
+ if part == ".." or _WINDOWS_DRIVE_RE.match(part):
+ raise ValueError(f"Zip Slip attempt detected: {filename}")
+ safe_parts.append(part)
+
+ if not safe_parts:
+ raise ValueError(f"Zip Slip attempt detected: {filename}")
+ return Path(*safe_parts)
+
+
def safe_extract_zip(zipf: zipfile.ZipFile, dest_dir: Path) -> None:
"""Extract ZIP archive with Zip Slip protection.
Validates every member path stays within dest_dir before extraction.
- Rejects absolute paths and parent-directory traversal (..).
+ Rejects absolute paths, Windows drive prefixes, and parent-directory
+ traversal (..). Windows-style backslash separators are normalized to
+ forward slash semantics before extraction.
"""
dest_dir = Path(dest_dir).resolve()
normalize_zip_filenames(zipf)
for member in zipf.infolist():
- member_path = (dest_dir / member.filename).resolve()
+ safe_rel_path = _safe_zip_member_path(member.filename)
+ member_path = (dest_dir / safe_rel_path).resolve()
# Ensure the resolved path is inside dest_dir
if not str(member_path).startswith(str(dest_dir) + os.sep):
raise ValueError(f"Zip Slip attempt detected: {member.filename}")
- zipf.extract(member, dest_dir)
+ if member.is_dir() or member.filename.endswith(("/", "\\")):
+ member_path.mkdir(parents=True, exist_ok=True)
+ continue
+
+ member_path.parent.mkdir(parents=True, exist_ok=True)
+ with zipf.open(member) as source, member_path.open("wb") as target:
+ shutil.copyfileobj(source, target)
diff --git a/tests/misc/test_zip_safe.py b/tests/misc/test_zip_safe.py
index 92e61ad34..f126ec879 100644
--- a/tests/misc/test_zip_safe.py
+++ b/tests/misc/test_zip_safe.py
@@ -5,7 +5,6 @@
from __future__ import annotations
import io
-import os
import stat
import zipfile
from pathlib import Path
@@ -281,7 +280,6 @@ class TestSafeExtractZipSlipPrevention:
safe_extract_zip(zf, dest)
_assert_no_escape(tmp_path, dest)
- @pytest.mark.skipif(os.name != "nt", reason="Windows-specific test")
def test_rejects_windows_drive_path(self, tmp_path: Path) -> None:
dest = tmp_path / "out"
dest.mkdir()
@@ -324,6 +322,22 @@ class TestSafeExtractZipSlipPrevention:
safe_extract_zip(zf, dest)
assert (dest / "safe.txt").exists()
+ def test_normalizes_windows_separators(self, tmp_path: Path) -> None:
+ """Benign Windows-style member paths should extract as directories."""
+ dest = tmp_path / "out"
+ dest.mkdir()
+ data = _make_zip_bytes(
+ {
+ "project\\file1.txt": "content1",
+ "project\\subdir\\file2.txt": "content2",
+ }
+ )
+ with zipfile.ZipFile(io.BytesIO(data), "r") as zf:
+ safe_extract_zip(zf, dest)
+
+ assert (dest / "project" / "file1.txt").read_text() == "content1"
+ assert (dest / "project" / "subdir" / "file2.txt").read_text() == "content2"
+
def test_first_malicious_entry_prevents_all_extraction(self, tmp_path: Path) -> None:
"""If the first entry is malicious, no files should be extracted."""
dest = tmp_path / "out"
diff --git a/tests/server/test_api_local_input_security.py b/tests/server/test_api_local_input_security.py
index 03883053b..189c941c5 100644
--- a/tests/server/test_api_local_input_security.py
+++ b/tests/server/test_api_local_input_security.py
@@ -4,6 +4,7 @@
"""Security tests for HTTP server local input handling."""
import threading
+import zipfile
from http.server import BaseHTTPRequestHandler, HTTPServer
import httpx
@@ -72,6 +73,38 @@ description: temp uploaded skill
assert body["result"]["uri"].startswith("viking://user/default/skills/")
+async def test_add_skill_accepts_uploaded_zip_with_windows_separators(
+ client: httpx.AsyncClient,
+ upload_temp_dir,
+):
+ skill_zip = upload_temp_dir / "windows-skill.zip"
+ with zipfile.ZipFile(skill_zip, "w") as zf:
+ zf.writestr(
+ "SKILL.md",
+ """---
+name: windows-skill
+description: uploaded skill with Windows-style zip paths
+---
+
+# Windows Skill
+""",
+ )
+ zf.writestr("scripts\\check_bounding_boxes.py", "print('ok')\n")
+
+ resp = await client.post(
+ "/api/v1/skills",
+ json={"temp_file_id": skill_zip.name, "wait": True},
+ )
+ assert resp.status_code == 200, resp.text
+ body = resp.json()
+ assert body["status"] == "ok"
+
+ script_uri = f"{body['result']['uri']}/scripts/check_bounding_boxes.py"
+ read_resp = await client.get("/api/v1/content/read", params={"uri": script_uri})
+ assert read_resp.status_code == 200, read_resp.text
+ assert read_resp.json()["result"] == "print('ok')\n"
+
+
async def test_add_skill_rejects_direct_local_path(client: httpx.AsyncClient):
resp = await client.post(
"/api/v1/skills",
diff --git a/tests/unit/test_path_safety.py b/tests/unit/test_path_safety.py
new file mode 100644
index 000000000..9910cbfd4
--- /dev/null
+++ b/tests/unit/test_path_safety.py
@@ -0,0 +1,57 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.utils.path_safety import safe_join_viking_uri, sanitize_relative_viking_path
+
+
+def test_sanitize_relative_viking_path_normalizes_windows_separators():
+ assert (
+ sanitize_relative_viking_path("scripts\\check_bounding_boxes.py")
+ == "scripts/check_bounding_boxes.py"
+ )
+
+
+def test_sanitize_relative_viking_path_preserves_posix_separators():
+ assert (
+ sanitize_relative_viking_path("scripts/check_bounding_boxes.py")
+ == "scripts/check_bounding_boxes.py"
+ )
+
+
+ "rel_path",
+ [
+ "",
+ "/absolute/file.txt",
+ "\\absolute\\file.txt",
+ "C:\\Windows\\System32",
+ "C:Windows\\System32",
+ "../outside.txt",
+ "nested/../../outside.txt",
+ ],
+)
+def test_sanitize_relative_viking_path_rejects_unsafe_paths(rel_path):
+ with pytest.raises(ValueError):
+ sanitize_relative_viking_path(rel_path)
+
+
+def test_safe_join_viking_uri_sanitizes_relative_path():
+ assert (
+ safe_join_viking_uri(
+ "viking://user/default/skills/pdf/",
+ "scripts\\check_bounding_boxes.py",
+ )
+ == "viking://user/default/skills/pdf/scripts/check_bounding_boxes.py"
+ )
+
+
+def test_safe_join_viking_uri_preserves_posix_relative_path():
+ assert (
+ safe_join_viking_uri(
+ "viking://user/default/skills/pdf/",
+ "scripts/check_bounding_boxes.py",
+ )
+ == "viking://user/default/skills/pdf/scripts/check_bounding_boxes.py"
+ )
diff --git a/tests/unit/test_skill_processor_windows_paths.py b/tests/unit/test_skill_processor_windows_paths.py
new file mode 100644
index 000000000..a211ab469
--- /dev/null
+++ b/tests/unit/test_skill_processor_windows_paths.py
@@ -0,0 +1,122 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import shutil
+import zipfile
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.utils.skill_processor import SkillProcessor
+
+
+def test_resolve_skill_zip_normalizes_windows_separators(tmp_path):
+ skill_zip = tmp_path / "pdf.zip"
+ with zipfile.ZipFile(skill_zip, "w") as zf:
+ zf.writestr(
+ "SKILL.md",
+ """---
+name: pdf
+description: PDF helper
+---
+
+# PDF
+""",
+ )
+ zf.writestr("scripts\\check_bounding_boxes.py", "print('ok')\n")
+
+ resolved_path, cleanup_path = SkillProcessor._resolve_skill_path(skill_zip)
+ try:
+ assert (resolved_path / "SKILL.md").exists()
+ assert (resolved_path / "scripts" / "check_bounding_boxes.py").read_text() == (
+ "print('ok')\n"
+ )
+ finally:
+ if cleanup_path:
+ shutil.rmtree(cleanup_path, ignore_errors=True)
+
+
+def test_resolve_skill_zip_preserves_posix_separators(tmp_path):
+ skill_zip = tmp_path / "pdf.zip"
+ with zipfile.ZipFile(skill_zip, "w") as zf:
+ zf.writestr(
+ "SKILL.md",
+ """---
+name: pdf
+description: PDF helper
+---
+
+# PDF
+""",
+ )
+ zf.writestr("scripts/check_bounding_boxes.py", "print('ok')\n")
+
+ resolved_path, cleanup_path = SkillProcessor._resolve_skill_path(skill_zip)
+ try:
+ assert (resolved_path / "SKILL.md").exists()
+ assert (resolved_path / "scripts" / "check_bounding_boxes.py").read_text() == (
+ "print('ok')\n"
+ )
+ finally:
+ if cleanup_path:
+ shutil.rmtree(cleanup_path, ignore_errors=True)
+
+
+async def test_write_auxiliary_files_normalizes_windows_separators(tmp_path):
+ base_path = tmp_path / "pdf"
+ base_path.mkdir()
+ aux_file = base_path / "scripts\\check_bounding_boxes.py"
+ aux_file.write_text("print('ok')", encoding="utf-8")
+
+ viking_fs = SimpleNamespace(
+ write_file=AsyncMock(),
+ write_file_bytes=AsyncMock(),
+ )
+ processor = SkillProcessor(vikingdb=None)
+
+ await processor._write_auxiliary_files(
+ viking_fs,
+ [aux_file],
+ base_path,
+ "viking://user/default/skills/pdf",
+ ctx=None,
+ )
+
+ viking_fs.write_file.assert_awaited_once_with(
+ "viking://user/default/skills/pdf/scripts/check_bounding_boxes.py",
+ "print('ok')",
+ ctx=None,
+ )
+ viking_fs.write_file_bytes.assert_not_awaited()
+
+
+async def test_write_auxiliary_files_preserves_posix_separators(tmp_path):
+ base_path = tmp_path / "pdf"
+ scripts_dir = base_path / "scripts"
+ scripts_dir.mkdir(parents=True)
+ aux_file = scripts_dir / "check_bounding_boxes.py"
+ aux_file.write_text("print('ok')", encoding="utf-8")
+
+ viking_fs = SimpleNamespace(
+ write_file=AsyncMock(),
+ write_file_bytes=AsyncMock(),
+ )
+ processor = SkillProcessor(vikingdb=None)
+
+ await processor._write_auxiliary_files(
+ viking_fs,
+ [aux_file],
+ base_path,
+ "viking://user/default/skills/pdf",
+ ctx=None,
+ )
+
+ viking_fs.write_file.assert_awaited_once_with(
+ "viking://user/default/skills/pdf/scripts/check_bounding_boxes.py",
+ "print('ok')",
+ ctx=None,
+ )
+ viking_fs.write_file_bytes.assert_not_awaited()