Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(context): reject Markdown junction imports

Saurabh Meena560ffef59fa7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 @KaifAhmad1
diff --git a/docs/reference/context.md b/docs/reference/context.md
index 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 unchanged
files is idempotent. Memory-local `entities` and `relationships` are preserved as
provenance but are not applied to `ContextGraph` by Markdown import. Use a dedicated
export 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 and
normalized to UTC only for comparisons, so aware and local-naive records can be
queried together safely. Vector-store writes are deferred until the in-memory import
diff --git a/semantica/context/_markdown_filesystem.py b/semantica/context/_markdown_filesystem.py
new file mode 100644
index 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 None
diff --git a/semantica/context/agent_memory.py b/semantica/context/agent_memory.py
index 7fef3b38..cd98dab2 100644
--- a/semantica/context/agent_memory.py
+++ b/semantica/context/agent_memory.py
@@ -77,6 +77,7 @@ import yaml
from ..utils.logging import get_logger
from ..utils.progress_tracker import get_progress_tracker
from ..utils.types import EntityDict, RelationshipDict
+from ._markdown_filesystem import find_filesystem_link
class _UniqueKeySafeLoader(yaml.SafeLoader):
@@ -1742,9 +1743,10 @@ class AgentMemory:
@staticmethod
def _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 memories
def _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:
@staticmethod
def _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_RDONLY
nofollow_flag = getattr(os, "O_NOFOLLOW", 0)
flags |= nofollow_flag
try:
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 exc
raise
try:
+ 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.py
index 807e5858..44f75bc9 100644
--- a/tests/context/test_agent_memory_markdown.py
+++ b/tests/context/test_agent_memory_markdown.py
@@ -1,5 +1,7 @@
import errno
import os
+import stat
+import subprocess
from copy import deepcopy
from datetime import datetime, timedelta, timezone
from 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 = {