Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
fix(context): reject Markdown junction imports
Saurabh Meena560ffef59fa7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 372550a2..639e6569 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -69,11 +69,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed-- **Markdown import followed symbolic links even though Markdown export already refused to overwrite them** (#851, follow-up to #765, #786) by @SaurabhScripts- - `AgentMemory._read_markdown_path()` now rejects a symlink file, a broken symlink, or a symlinked directory supplied directly as an import path, and rejects any symlinked Markdown entry discovered while walking an import directory - before any parsing happens, so an import can no longer read a different file or directory than the path presented to the caller- - New `_read_markdown_file()` re-checks `is_symlink()` immediately before opening (closing the window between directory-scan validation and the actual read), opens with `O_NOFOLLOW` on platforms that support it, and verifies the resulting descriptor is a regular file via `fstat`/`S_ISREG` before reading, so a symlink swapped in after validation is still rejected rather than silently followed- - Documented the import restriction in `docs/reference/context.md`; added 8 tests to `tests/context/test_agent_memory_markdown.py` covering file/directory/broken-symlink rejection for both `str` and `Path` inputs, plus a simulated-race test proving the `O_NOFOLLOW` open still catches a symlink when the pre-open `is_symlink()` check is bypassed- - Disclosed limitation: `O_NOFOLLOW` isn't available on Windows, so the final open there relies solely on the pre-open `is_symlink()` check rather than a kernel-enforced guarantee against a race+- **Markdown import followed filesystem links even though Markdown export already refused to overwrite them** (#851, follow-up to #765, #786) by @SaurabhScripts+ - `AgentMemory._read_markdown_path()` now rejects symlink files, broken symlinks, symlinked directories, Windows directory junctions, and other Windows reparse points before parsing, including linked Markdown entries discovered while walking an import directory+ - New `_read_markdown_file()` re-checks the file and parent directory immediately before and after opening, uses `O_NOFOLLOW` where available, and verifies the resulting descriptor is a regular file via `fstat`/`S_ISREG`, so link swaps are rejected rather than silently followed+ - Junction detection uses `os.path.isjunction()` where available and falls back to the Windows reparse-point file attribute on older Python versions; export applies the same link check before replacing a Markdown file+ - Documented the import restriction in `docs/reference/context.md`; added 11 tests to `tests/context/test_agent_memory_markdown.py` covering file/directory/broken-symlink rejection, simulated open races, mocked and real Windows junctions, and the reparse-point fallback- Any additional review follow-up commits land in this same PR/entry rather than as a separate changelog item- **`VectorStore.search_vectors()` returned inconsistent result shapes across backend implementations** (#853, closes #845) by @Sameer6305, reviewed by @KaifAhmad1diff --git a/docs/reference/context.md b/docs/reference/context.mdindex 94bcd115..02ac9afc 100644--- a/docs/reference/context.md+++ b/docs/reference/context.md@@ -625,8 +625,9 @@ malformed or duplicate fields before changing memory, and re-importing unchangedfiles is idempotent. Memory-local `entities` and `relationships` are preserved asprovenance but are not applied to `ContextGraph` by Markdown import. Use a dedicatedexport directory: matching files are overwritten, but unrelated or stale Markdown-files are not deleted automatically. Export refuses to overwrite symbolic links and-uses atomic file replacement; import also refuses symbolic-link files and directories.+files are not deleted automatically. Export refuses to overwrite filesystem links and+uses atomic file replacement; import also refuses symlinks, Windows directory+junctions, and other Windows reparse points.Timestamp offsets are preserved in Markdown andnormalized to UTC only for comparisons, so aware and local-naive records can bequeried together safely. Vector-store writes are deferred until the in-memory importdiff --git a/semantica/context/_markdown_filesystem.py b/semantica/context/_markdown_filesystem.pynew file mode 100644index 00000000..70872f85--- /dev/null+++ b/semantica/context/_markdown_filesystem.py@@ -0,0 +1,32 @@+"""Filesystem safety helpers for human-editable Markdown persistence."""++import os+import stat+from pathlib import Path+from typing import Optional+++def is_filesystem_link(path: Path) -> bool:+ """Return whether *path* is a symlink, junction, or Windows reparse point."""+ if path.is_symlink():+ return True++ isjunction = getattr(os.path, "isjunction", None)+ if isjunction is not None and isjunction(path):+ return True++ try:+ attributes = getattr(os.lstat(path), "st_file_attributes", 0)+ except (FileNotFoundError, NotADirectoryError):+ return False++ reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)+ return bool(attributes & reparse_point)+++def find_filesystem_link(path: Path) -> Optional[Path]:+ """Return the first linked component in *path*, including its ancestors."""+ for candidate in (path, *path.parents):+ if is_filesystem_link(candidate):+ return candidate+ return Nonediff --git a/semantica/context/agent_memory.py b/semantica/context/agent_memory.pyindex 7fef3b38..cd98dab2 100644--- a/semantica/context/agent_memory.py+++ b/semantica/context/agent_memory.py@@ -77,6 +77,7 @@ import yamlfrom ..utils.logging import get_loggerfrom ..utils.progress_tracker import get_progress_trackerfrom ..utils.types import EntityDict, RelationshipDict+from ._markdown_filesystem import find_filesystem_linkclass _UniqueKeySafeLoader(yaml.SafeLoader):@@ -1742,9 +1743,10 @@ class AgentMemory:@staticmethoddef _write_markdown_file(file_path: Path, document: str) -> None:"""Atomically replace a Markdown file without following output symlinks."""- if file_path.is_symlink():+ if find_filesystem_link(file_path) is not None:raise ValueError(- f"Refusing to overwrite Markdown symbolic link: {file_path}"+ "Refusing to overwrite Markdown symbolic link or junction: "+ f"{file_path}")temporary_path = None@@ -1867,8 +1869,8 @@ class AgentMemory:if "\n" not in data and "\r" not in data:candidate = Path(data)try:- candidate_is_symlink = candidate.is_symlink()- candidate_exists = candidate_is_symlink or candidate.exists()+ candidate_is_link = find_filesystem_link(candidate) is not None+ candidate_exists = candidate_is_link or candidate.exists()except OSError as exc:error_message = ("Failed to inspect possible Markdown import "@@ -1910,8 +1912,10 @@ class AgentMemory:return memoriesdef _read_markdown_path(self, path: Path) -> List[Tuple[str, str]]:- if path.is_symlink():- raise ValueError(f"Refusing to import Markdown symbolic link: {path}")+ if find_filesystem_link(path) is not None:+ raise ValueError(+ f"Refusing to import Markdown symbolic link or junction: {path}"+ )if not path.exists():raise FileNotFoundError(f"Markdown import path does not exist: {path}")@@ -1921,9 +1925,10 @@ class AgentMemory:for file_path in path.iterdir():if file_path.suffix.lower() not in self._MARKDOWN_EXTENSIONS:continue- if file_path.is_symlink():+ if find_filesystem_link(file_path) is not None:raise ValueError(- f"Refusing to import Markdown symbolic link: {file_path}"+ "Refusing to import Markdown symbolic link or junction: "+ f"{file_path}")if file_path.is_file():file_paths.append(file_path)@@ -1941,30 +1946,41 @@ class AgentMemory:@staticmethoddef _read_markdown_file(file_path: Path) -> str:"""Read a regular Markdown file without following a raced symlink."""- if file_path.is_symlink():- raise ValueError(f"Refusing to import Markdown symbolic link: {file_path}")+ if find_filesystem_link(file_path) is not None:+ raise ValueError(+ f"Refusing to import Markdown symbolic link or junction: {file_path}"+ )# Defend the open itself against a symlink introduced after the# is_symlink() check above (TOCTOU). O_NOFOLLOW is used where the# platform supports it, causing os.open() to fail with ELOOP if the# target became a symlink in the meantime. On platforms without- # O_NOFOLLOW (e.g. Windows), os.open() follows symlinks and there is- # no kernel-level way to close this race; the preceding- # is_symlink() check is the only protection there, so the strength- # of the final-open race protection differs by platform.+ # O_NOFOLLOW (e.g. Windows), os.open() may follow a link introduced+ # during the open. The pre/post-open reparse-point checks still reject+ # persistent swaps, but they cannot provide the same kernel-enforced+ # guarantee as O_NOFOLLOW.flags = os.O_RDONLYnofollow_flag = getattr(os, "O_NOFOLLOW", 0)flags |= nofollow_flagtry:file_descriptor = os.open(file_path, flags)except OSError as exc:- if nofollow_flag and exc.errno == errno.ELOOP:+ if (+ (nofollow_flag and exc.errno == errno.ELOOP)+ or find_filesystem_link(file_path) is not None+ ):raise ValueError(- f"Refusing to import Markdown symbolic link: {file_path}"+ "Refusing to import Markdown symbolic link or junction: "+ f"{file_path}") from excraisetry:+ if find_filesystem_link(file_path) is not None:+ raise ValueError(+ "Refusing to import Markdown symbolic link or junction: "+ f"{file_path}"+ )if not stat.S_ISREG(os.fstat(file_descriptor).st_mode):raise ValueError(f"Markdown import path is not a regular file: {file_path}"diff --git a/tests/context/test_agent_memory_markdown.py b/tests/context/test_agent_memory_markdown.pyindex 807e5858..44f75bc9 100644--- a/tests/context/test_agent_memory_markdown.py+++ b/tests/context/test_agent_memory_markdown.py@@ -1,5 +1,7 @@import errnoimport os+import stat+import subprocessfrom copy import deepcopyfrom datetime import datetime, timedelta, timezonefrom pathlib import Path@@ -806,6 +808,66 @@ def test_markdown_import_does_not_follow_symlink_raced_before_open(tmp_path):AgentMemory._read_markdown_file(source)+def test_markdown_import_rejects_windows_junction(tmp_path, monkeypatch):+ source = tmp_path / "junction"+ source.mkdir()+ (source / "memory.md").write_text("not read", encoding="utf-8")++ monkeypatch.setattr(+ os.path,+ "isjunction",+ lambda candidate: Path(candidate) == source,+ raising=False,+ )++ with pytest.raises(ValueError, match="junction"):+ AgentMemory().import_data(source, format="markdown")+++def test_markdown_import_rejects_windows_reparse_point_fallback(tmp_path, monkeypatch):+ source = tmp_path / "reparse-point"+ source.mkdir()+ real_lstat = os.lstat++ class ReparseStat:+ st_file_attributes = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)++ monkeypatch.delattr(os.path, "isjunction", raising=False)+ monkeypatch.setattr(Path, "is_symlink", lambda self: False)+ monkeypatch.setattr(+ os,+ "lstat",+ lambda candidate: (+ ReparseStat() if Path(candidate) == source else real_lstat(candidate)+ ),+ )++ with pytest.raises(ValueError, match="junction"):+ AgentMemory().import_data(source, format="markdown")++[email protected](os.name != "nt", reason="requires Windows junctions")+def test_markdown_import_rejects_real_windows_junction(tmp_path):+ outside = tmp_path / "outside"+ outside.mkdir()+ (outside / "memory.md").write_text("not read", encoding="utf-8")+ source = tmp_path / "junction"+ result = subprocess.run(+ ["cmd.exe", "/c", "mklink", "/J", str(source), str(outside)],+ capture_output=True,+ text=True,+ check=False,+ )+ if result.returncode != 0:+ pytest.skip(f"could not create Windows junction: {result.stderr}")++ try:+ with pytest.raises(ValueError, match="junction"):+ AgentMemory().import_data(source, format="markdown")+ finally:+ os.rmdir(source)++def test_legacy_dict_import_behavior_is_unchanged():memory = AgentMemory()data = {