diff --git a/backend/snapstudio_core/passport_cli.py b/backend/snapstudio_core/passport_cli.py index b8cc9178..0967f6d9 100644 --- a/backend/snapstudio_core/passport_cli.py +++ b/backend/snapstudio_core/passport_cli.py @@ -13,24 +13,24 @@ Nothing here writes next to or over an input: `export -o` refuses an existing file and any path that is one of the inputs. -Known limit (accepted for the unmerged development branches): path validation and the filesystem -operations that follow it are separate steps. Another process or principal able to modify the output -directory, or any of its ancestors, after validation could redirect `export -o` (for example by -swapping the directory for a link to a network share). Use an output directory whose ancestors other -actors cannot modify. The UNC/device/link refusals and the no-overwrite rule are best-effort checks, -not a filesystem sandbox and not an absolute no-network guarantee. See docs/internal/PASSPORT.md. +Publication: `export -o` pins the output directory once (a held descriptor on POSIX; a handle that +forbids rename/delete on Windows) and writes through that pin (snapstudio_core.safe_publish), so swapping the +directory or an ancestor after the check cannot redirect the write. It is still not a filesystem +sandbox: someone who can already write inside the pinned directory can create or remove entries there, +and the UNC/device/link refusals are checks on the pinned path, not an absolute no-network guarantee. +See docs/internal/PASSPORT.md. """ from __future__ import annotations import json import os -import tempfile from functools import wraps from typing import Any import click from snapstudio_core import localpath +from snapstudio_core.safe_publish import UnsafeOutput, publish_new_file from snapstudio_core.passport import build_passport, import_passport, verify_passport from snapstudio_core.passport.model import decode_passport @@ -140,29 +140,13 @@ def export_cmd(original, prepared, sliced, recipes_file, mappings_file, out): if os.path.exists(target): _error("output_exists", "The output file already exists.") try: - fd, tmp = tempfile.mkstemp(dir=os.path.dirname(target) or ".", suffix=".tmp") - except OSError: - _error("write_failed", "The passport could not be written.") - try: - with os.fdopen(fd, "w", encoding="utf-8") as handle: - json.dump(document, handle, indent=2) - try: - os.link(tmp, target) # fails if the destination appeared meanwhile - except FileExistsError: - raise - except OSError: - if os.name != "nt": - raise # POSIX rename would replace; refuse rather than risk it - os.rename(tmp, target) # Windows rename is atomic and refuses an existing file + publish_new_file(target, json.dumps(document, indent=2).encode("utf-8")) except FileExistsError: _error("output_exists", "The output file already exists.") + except UnsafeOutput: + _error("bad_output", "The output directory could not be verified as a local folder.") except OSError: _error("write_failed", "The passport could not be written.") - finally: - try: - os.remove(tmp) # the passport is already published or refused - except OSError: - pass written = os.path.basename(target) _emit({"ok": True, "passport_id": document["passport_id"], "written": written, "passport": document, "diagnostics": [d.to_dict() for d in built.diagnostics], "losses": document["losses"]}, 0) diff --git a/backend/snapstudio_core/safe_publish.py b/backend/snapstudio_core/safe_publish.py new file mode 100644 index 00000000..9b72d711 --- /dev/null +++ b/backend/snapstudio_core/safe_publish.py @@ -0,0 +1,226 @@ +"""Publish a new local file without a validate-then-write race on the output directory. + +`publish_new_file(target, data)` writes `data` to `target` only if `target` does not exist, and +never replaces anything. The directory that will hold the file is opened ONCE ("pinned") and every +later operation goes through that pin, so a later swap of the directory, or of any ancestor, cannot +redirect the write: + +* POSIX: the directory is held as a file descriptor and the temporary file, the no-replace link and + the cleanup are all `dir_fd`-relative. The pinned directory's real path is checked for + network/device locations after the pin, from the descriptor (`/proc/self/fd`, or `F_GETPATH` on macOS). +* Windows: the directory is opened with a share mode that omits FILE_SHARE_DELETE, so the directory + and its ancestors cannot be renamed, replaced or removed while the handle is held. The final path + is read from the handle and checked for network/device locations. A junction cannot be renamed in, but + it can be set in place on an empty directory, so the final name is created exclusively with sharing + off, and the file HANDLE's own final path must equal the verified directory plus the name; a mismatch + discards the empty file before any content is written. + +Remaining limits (stated, not hidden): this is not a sandbox. Anyone who can already write inside the +pinned directory can still create or remove entries there, and a platform that can neither report the +pinned directory's path nor pin it is refused (`UnsafeOutput`) rather than written best-effort. +""" +from __future__ import annotations + +import os +import secrets +import sys + +from snapstudio_core import localpath + + +class UnsafeOutput(Exception): + """The output location could not be pinned and verified as a local directory.""" + + +def _after_pin() -> None: + """Seam for tests: runs after the directory is pinned and verified, before any file is created.""" + + +def _before_create() -> None: + """Seam for tests (Windows): runs after the pinned directory's reparse re-check, immediately before the create.""" + + +def _check_name(name: str) -> None: + separators = ("/", "\\") if sys.platform == "win32" else ("/",) + if not name or name in (".", "..") or "\x00" in name or any(sep in name for sep in separators): + raise UnsafeOutput("the output must be a plain file name") + + +def _tmp_name() -> str: + """A bounded temporary name that does not depend on the destination name (NAME_MAX safe).""" + return f".snapstudio-{secrets.token_hex(8)}.tmp" + + +def publish_new_file(target: str, data: bytes, mode: int = 0o600) -> None: + """Create `target` with `data`; FileExistsError if it exists; UnsafeOutput if not pinnable/local.""" + absolute = os.path.abspath(target) + parent, name = os.path.split(absolute) + _check_name(name) + if sys.platform == "win32": + _publish_windows(parent, name, data) + else: + _publish_posix(parent, name, data, mode) + + +# ---------------------------------------------------------------- POSIX + +def _pinned_path_posix(dfd: int) -> str: + if sys.platform.startswith("linux"): + try: + resolved = os.readlink(f"/proc/self/fd/{dfd}") # fails closed when /proc is unavailable + except OSError: + raise UnsafeOutput("this system cannot report the output directory's real path") from None + if not os.path.isabs(resolved) or resolved.endswith(" (deleted)"): + raise UnsafeOutput("the output directory's real path could not be verified") + return resolved + try: + import fcntl + raw = fcntl.fcntl(dfd, getattr(fcntl, "F_GETPATH"), b"\0" * 1024) + return os.fsdecode(raw.split(b"\0", 1)[0]) + except (ImportError, AttributeError, OSError): + raise UnsafeOutput("this platform cannot report the output directory's real path") from None + + +def _publish_posix(parent: str, name: str, data: bytes, mode: int) -> None: + flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_CLOEXEC", 0) + try: + dfd = os.open(parent, flags) + except OSError as error: + raise UnsafeOutput("the output directory could not be opened") from error + tmp = None + try: + real = _pinned_path_posix(dfd) + if not real or localpath._reaches_network(real): + raise UnsafeOutput("the output directory is not a local directory") + _after_pin() + tmp = _tmp_name() + fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), mode, dir_fd=dfd) + with os.fdopen(fd, "wb") as handle: + handle.write(data) + os.link(tmp, name, src_dir_fd=dfd, dst_dir_fd=dfd, follow_symlinks=False) # refuses an existing name + finally: + if tmp is not None: + try: + os.unlink(tmp, dir_fd=dfd) + except OSError: + pass + os.close(dfd) + + +# ---------------------------------------------------------------- Windows + +def _publish_windows(parent: str, name: str, data: bytes) -> None: + """Pin the directory, then create the FINAL name exclusively and verify where it really landed. + + Holding the directory handle (no FILE_SHARE_DELETE) stops a rename or delete of the directory and its + ancestors, but an actor with write access to an EMPTY directory can still turn it into a junction in + place. So the file handle itself is checked: after the exclusive create (CREATE_NEW, share mode none, so + nobody can read a partial file) its final path must sit directly inside the pinned directory's path; + otherwise the just-created empty file is deleted through the handle and nothing is written. The residual + exposure is an empty, immediately removed file in the redirected location; no passport content is written. + """ + import ctypes + from ctypes import wintypes + + kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + kernel32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID, + wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE] + kernel32.CreateFileW.restype = wintypes.HANDLE + kernel32.GetFinalPathNameByHandleW.argtypes = [wintypes.HANDLE, wintypes.LPWSTR, wintypes.DWORD, wintypes.DWORD] + kernel32.GetFinalPathNameByHandleW.restype = wintypes.DWORD + kernel32.GetFileInformationByHandle.argtypes = [wintypes.HANDLE, wintypes.LPVOID] + kernel32.GetFileInformationByHandle.restype = wintypes.BOOL + kernel32.SetFileInformationByHandle.argtypes = [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD] + kernel32.SetFileInformationByHandle.restype = wintypes.BOOL + kernel32.WriteFile.argtypes = [wintypes.HANDLE, wintypes.LPCVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), + wintypes.LPVOID] + kernel32.WriteFile.restype = wintypes.BOOL + kernel32.CloseHandle.argtypes = [wintypes.HANDLE] + + FILE_LIST_DIRECTORY = 0x0001 + GENERIC_WRITE = 0x40000000 + DELETE = 0x00010000 + SHARE_READ_WRITE = 0x1 | 0x2 # deliberately NOT FILE_SHARE_DELETE (0x4) + OPEN_EXISTING, CREATE_NEW = 3, 1 + FILE_FLAG_BACKUP_SEMANTICS = 0x02000000 + FILE_ATTRIBUTE_NORMAL = 0x80 + FILE_ATTRIBUTE_REPARSE_POINT = 0x400 + FILE_DISPOSITION_INFO = 4 + ERROR_FILE_EXISTS, ERROR_ALREADY_EXISTS = 80, 183 + invalid = wintypes.HANDLE(-1).value + + class FILETIME(ctypes.Structure): + _fields_ = [("lo", wintypes.DWORD), ("hi", wintypes.DWORD)] + + class BY_HANDLE_FILE_INFORMATION(ctypes.Structure): + _fields_ = [("attributes", wintypes.DWORD), ("created", FILETIME), ("accessed", FILETIME), + ("written", FILETIME), ("volume", wintypes.DWORD), ("size_hi", wintypes.DWORD), + ("size_lo", wintypes.DWORD), ("links", wintypes.DWORD), ("index_hi", wintypes.DWORD), + ("index_lo", wintypes.DWORD)] + + def final_path(h) -> str: + buffer = ctypes.create_unicode_buffer(32768) + length = kernel32.GetFinalPathNameByHandleW(h, buffer, len(buffer), 0) + if not length or length >= len(buffer): + raise UnsafeOutput("a real path could not be read") + text = buffer.value + if text.upper().startswith("\\\\?\\UNC\\"): + raise UnsafeOutput("the output location is not local") + if text.startswith("\\\\?\\") and len(text) > 6 and text[5] == ":": + text = text[4:] # strip the extended-length prefix from a local drive path + return text + + def is_reparse(h) -> bool: + info = BY_HANDLE_FILE_INFORMATION() + if not kernel32.GetFileInformationByHandle(h, ctypes.byref(info)): + raise UnsafeOutput("the output directory could not be inspected") + return bool(info.attributes & FILE_ATTRIBUTE_REPARSE_POINT) + + directory = kernel32.CreateFileW(parent, FILE_LIST_DIRECTORY, SHARE_READ_WRITE, None, OPEN_EXISTING, + FILE_FLAG_BACKUP_SEMANTICS, None) + if directory in (None, invalid): + raise UnsafeOutput("the output directory could not be opened") + out = None + try: + real = final_path(directory) + if localpath._reaches_network(real): + raise UnsafeOutput("the output directory is not a local directory") + _after_pin() + if is_reparse(directory): # turned into a link in place after the pin + raise UnsafeOutput("the output directory was redirected") + destination = os.path.join(real, name) + _before_create() + out = kernel32.CreateFileW(destination, GENERIC_WRITE | DELETE, 0, None, CREATE_NEW, + FILE_ATTRIBUTE_NORMAL, None) + if out in (None, invalid): + if ctypes.get_last_error() in (ERROR_FILE_EXISTS, ERROR_ALREADY_EXISTS): + raise FileExistsError(destination) + raise OSError(ctypes.get_last_error(), "the passport could not be created") + + def discard(reason): + flag = wintypes.DWORD(1) + if not kernel32.SetFileInformationByHandle(out, FILE_DISPOSITION_INFO, ctypes.byref(flag), + ctypes.sizeof(flag)): + raise UnsafeOutput("the output could not be verified and the file it created could not be " + "removed") from reason + + try: + landed = final_path(out) + # Both strings are canonical on-disk spellings (GetFinalPathNameByHandle), so compare them exactly: + # case-folding would accept a junction to a distinct directory on a case-sensitive volume. + if os.path.normpath(landed) != os.path.normpath(destination) or localpath._reaches_network(landed): + raise UnsafeOutput("the output was redirected away from the verified directory") + view = memoryview(data) + while len(view): + written = wintypes.DWORD(0) + chunk = bytes(view[: 1 << 20]) + if not kernel32.WriteFile(out, chunk, len(chunk), ctypes.byref(written), None): + raise OSError(ctypes.get_last_error(), "the passport could not be written") + view = view[written.value:] + except BaseException as error: + discard(error) + raise + finally: + if out not in (None, invalid): + kernel32.CloseHandle(out) + kernel32.CloseHandle(directory) diff --git a/backend/tests/passport/test_export_publication.py b/backend/tests/passport/test_export_publication.py new file mode 100644 index 00000000..4d77acf6 --- /dev/null +++ b/backend/tests/passport/test_export_publication.py @@ -0,0 +1,284 @@ +"""R4-F1: `passport export -o` must publish into the directory it validated, even if that directory +(or an ancestor) is swapped between the check and the write. Evidence label: fixture-tested. + +The swap is simulated deterministically. Both the old write path (`tempfile.mkstemp` in the validated +directory) and the new one (`safe_publish._after_pin`, after the directory is pinned) trigger it exactly +once, immediately before the first file is created. The directory swap is a rename of the validated +directory plus a rename of a decoy into its place; on Windows the new code's pinned handle makes the +first rename fail, which is the protection under test. +""" +from __future__ import annotations + +import json +import os +import tempfile + +import pytest +from click.testing import CliRunner + +from snapstudio_core import passport_cli + +try: + from snapstudio_core import safe_publish +except ImportError: # the pre-fix tree: let the behavioural assertion fail instead + safe_publish = None + + +def _run(*args): + return CliRunner().invoke(passport_cli.passport, list(args)) + + +@pytest.fixture +def layout(tmp_path): + victim = tmp_path / "victim" + decoy = tmp_path / "decoy" + victim.mkdir() + decoy.mkdir() + (victim / "orig.marker").write_text("victim") + (decoy / "decoy.marker").write_text("decoy") + source = tmp_path / "part.3mf" + source.write_bytes(b"synthetic original") + return tmp_path, victim, decoy, source + + +def _install_swap(monkeypatch, victim, decoy): + moved = victim.with_name("victim_moved") + state = {"armed": True, "swapped": False} + + def swap(): + if not state["armed"]: + return + state["armed"] = False + try: + os.rename(victim, moved) + os.rename(decoy, victim) + state["swapped"] = True + except OSError: + pass # a pinned directory refuses to be renamed (Windows) + + real_mkstemp = tempfile.mkstemp + + def mkstemp(*args, **kwargs): + swap() + return real_mkstemp(*args, **kwargs) + + monkeypatch.setattr(tempfile, "mkstemp", mkstemp) + if safe_publish is not None: + monkeypatch.setattr(safe_publish, "_after_pin", swap) + return state, moved + + +def test_a_directory_swapped_after_validation_does_not_redirect_the_passport(layout, monkeypatch): + tmp_path, victim, decoy, source = layout + state, moved = _install_swap(monkeypatch, victim, decoy) + out = victim / "job.passport.json" + + result = _run("export", "--original", str(source), "-o", str(out)) + + assert result.exit_code == 0, result.output + assert json.loads(result.output)["written"] == "job.passport.json" + holders = [d for d in (victim, moved) if (d / "job.passport.json").exists()] + assert len(holders) == 1 + assert (holders[0] / "orig.marker").exists(), "the passport landed in the swapped-in directory" + assert not [p for p in (victim, moved) if (p / "decoy.marker").exists() and (p / "job.passport.json").exists()] + assert not list(holders[0].glob("*.tmp")) and not list(holders[0].glob(".*.tmp")) + + +def test_export_writes_a_new_file_and_refuses_an_existing_one(tmp_path): + source = tmp_path / "part.3mf" + source.write_bytes(b"x") + out = tmp_path / "p.json" + first = _run("export", "--original", str(source), "-o", str(out)) + assert first.exit_code == 0 and json.loads(out.read_text(encoding="utf-8"))["passport_id"] + before = out.read_bytes() + second = _run("export", "--original", str(source), "-o", str(out)) + assert second.exit_code == 1 and json.loads(second.output)["error"]["code"] == "output_exists" + assert out.read_bytes() == before + assert sorted(p.name for p in tmp_path.iterdir()) == ["p.json", "part.3mf"] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_publish_new_file_never_replaces_and_leaves_no_temporary(tmp_path): + target = tmp_path / "a.json" + safe_publish.publish_new_file(str(target), b"one") + with pytest.raises(FileExistsError): + safe_publish.publish_new_file(str(target), b"two") + assert target.read_bytes() == b"one" + assert [p.name for p in tmp_path.iterdir()] == ["a.json"] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +@pytest.mark.parametrize("name", ["", "..", "a/b"]) +def test_publish_refuses_a_name_that_is_not_a_plain_file_name(tmp_path, name): + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish._check_name(name) + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_backslash_is_a_separator_only_on_windows(): + if os.name == "nt": + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish._check_name("a\\b") + else: + safe_publish._check_name("a\\b") # an ordinary POSIX file name + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_directory_that_resolves_to_a_network_location_is_refused(tmp_path, monkeypatch): + monkeypatch.setattr(safe_publish.localpath, "_reaches_network", lambda path, depth=0: True) + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish.publish_new_file(str(tmp_path / "a.json"), b"x") + assert list(tmp_path.iterdir()) == [] + + +@pytest.mark.skipif(safe_publish is None, reason="needs safe_publish") +def test_a_missing_output_directory_is_refused_not_created(tmp_path): + with pytest.raises(safe_publish.UnsafeOutput): + safe_publish.publish_new_file(str(tmp_path / "nope" / "a.json"), b"x") + assert not (tmp_path / "nope").exists() + + +# ------------------------------------------------------------ in-place link on an empty directory + +def _make_junction_in_place(directory, target) -> bool: + """Turn the EMPTY `directory` into a junction to `target` without renaming it (Windows only).""" + import ctypes + import struct + from ctypes import wintypes + + kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + kernel32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID, + wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE] + kernel32.CreateFileW.restype = wintypes.HANDLE + kernel32.DeviceIoControl.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD, + wintypes.LPVOID, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD), + wintypes.LPVOID] + kernel32.DeviceIoControl.restype = wintypes.BOOL + h = kernel32.CreateFileW(str(directory), 0x40000000, 0x7, None, 3, 0x02000000 | 0x00200000, None) + if h in (None, wintypes.HANDLE(-1).value): + return False + try: + substitute = ("\\??\\" + str(target)).encode("utf-16-le") + printable = str(target).encode("utf-16-le") + path_buffer = substitute + b"\0\0" + printable + b"\0\0" + header = struct.pack("