Merge PR #386: fix symlink boundary check prefix confusion in skills_guard

Authored by Farukest. Fixes #385.

Replaces startswith() with Path.is_relative_to() in _check_structure()
symlink escape check — same fix pattern as skill_view() (PR #352).
Prevents symlinks escaping to sibling directories with shared name prefixes.

tests/tools/test_skills_guard.py

@@ -1,9 +1,26 @@
-"""Tests for tools/skills_guard.py — security scanner for skills."""
+"""Tests for tools/skills_guard.py - security scanner for skills."""
 
 import os
 import stat
+import tempfile
 from pathlib import Path
 
+import pytest
+
+
+def _can_symlink():
+    """Check if we can create symlinks (needs admin/dev-mode on Windows)."""
+    try:
+        with tempfile.TemporaryDirectory() as d:
+            src = Path(d) / "src"
+            src.write_text("x")
+            lnk = Path(d) / "lnk"
+            lnk.symlink_to(src)
+            return True
+    except OSError:
+        return False
+
+
 from tools.skills_guard import (
     Finding,
     ScanResult,
@@ -263,6 +280,45 @@ class TestCheckStructure:
         findings = _check_structure(tmp_path / "skill")
         assert any(fi.pattern_id == "symlink_escape" for fi in findings)
 
+    @pytest.mark.skipif(
+        not _can_symlink(), reason="Symlinks need elevated privileges"
+    )
+    def test_symlink_prefix_confusion_blocked(self, tmp_path):
+        """A symlink resolving to a sibling dir with a shared prefix must be caught.
+
+        Regression: startswith('axolotl') matches 'axolotl-backdoor'.
+        is_relative_to() correctly rejects this.
+        """
+        skills = tmp_path / "skills"
+        skill_dir = skills / "axolotl"
+        sibling_dir = skills / "axolotl-backdoor"
+        skill_dir.mkdir(parents=True)
+        sibling_dir.mkdir(parents=True)
+
+        malicious = sibling_dir / "malicious.py"
+        malicious.write_text("evil code")
+
+        link = skill_dir / "helper.py"
+        link.symlink_to(malicious)
+
+        findings = _check_structure(skill_dir)
+        assert any(fi.pattern_id == "symlink_escape" for fi in findings)
+
+    @pytest.mark.skipif(
+        not _can_symlink(), reason="Symlinks need elevated privileges"
+    )
+    def test_symlink_within_skill_dir_allowed(self, tmp_path):
+        """A symlink that stays within the skill directory is fine."""
+        skill_dir = tmp_path / "my-skill"
+        skill_dir.mkdir()
+        real_file = skill_dir / "real.py"
+        real_file.write_text("print('ok')")
+        link = skill_dir / "alias.py"
+        link.symlink_to(real_file)
+
+        findings = _check_structure(skill_dir)
+        assert not any(fi.pattern_id == "symlink_escape" for fi in findings)
+
     def test_clean_structure(self, tmp_path):
         (tmp_path / "SKILL.md").write_text("# Skill\n")
         (tmp_path / "main.py").write_text("print(1)\n")
@@ -339,3 +395,65 @@ class TestUnicodeCharName:
     def test_unknown_char(self):
         result = _unicode_char_name("\u0041")  # 'A'
         assert "U+" in result
+
+
+# ---------------------------------------------------------------------------
+# Regression: symlink prefix confusion (Bug fix)
+# ---------------------------------------------------------------------------
+
+
+class TestSymlinkPrefixConfusionRegression:
+    """Demonstrate the old startswith() bug vs the is_relative_to() fix.
+
+    The old symlink boundary check used:
+        str(resolved).startswith(str(skill_dir.resolve()))
+    without a trailing separator. A path like 'axolotl-backdoor/file'
+    starts with the string 'axolotl', so it was silently allowed.
+    """
+
+    def test_old_startswith_misses_prefix_confusion(self, tmp_path):
+        """Old check fails: sibling dir with shared prefix passes startswith."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sibling_file = tmp_path / "skills" / "axolotl-backdoor" / "evil.py"
+        skill_dir.mkdir(parents=True)
+        sibling_file.parent.mkdir(parents=True)
+        sibling_file.write_text("evil")
+
+        resolved = sibling_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Old check: startswith without trailing separator - WRONG
+        old_escapes = not str(resolved).startswith(str(skill_dir_resolved))
+        assert old_escapes is False  # Bug: old check thinks it's inside
+
+    def test_is_relative_to_catches_prefix_confusion(self, tmp_path):
+        """New check catches: is_relative_to correctly rejects sibling dir."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sibling_file = tmp_path / "skills" / "axolotl-backdoor" / "evil.py"
+        skill_dir.mkdir(parents=True)
+        sibling_file.parent.mkdir(parents=True)
+        sibling_file.write_text("evil")
+
+        resolved = sibling_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # New check: is_relative_to - correctly detects escape
+        new_escapes = not resolved.is_relative_to(skill_dir_resolved)
+        assert new_escapes is True  # Fixed: correctly flags as outside
+
+    def test_legitimate_subpath_passes_both(self, tmp_path):
+        """Both old and new checks correctly allow real subpaths."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sub_file = skill_dir / "utils" / "helper.py"
+        skill_dir.mkdir(parents=True)
+        sub_file.parent.mkdir(parents=True)
+        sub_file.write_text("ok")
+
+        resolved = sub_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Both checks agree this is inside
+        old_escapes = not str(resolved).startswith(str(skill_dir_resolved))
+        new_escapes = not resolved.is_relative_to(skill_dir_resolved)
+        assert old_escapes is False
+        assert new_escapes is False

tests/tools/test_symlink_prefix_confusion.py

@@ -0,0 +1,172 @@
+"""Tests for the symlink boundary check prefix confusion fix in skills_guard.py.
+
+Regression test: the original check used startswith() without a trailing
+separator, so a symlink resolving to 'axolotl-backdoor/' passed the check
+for 'axolotl/' because the string prefix matched. Now uses
+Path.is_relative_to() which handles directory boundaries correctly.
+"""
+
+import os
+import pytest
+from pathlib import Path
+
+
+def _old_check_escapes(resolved: Path, skill_dir_resolved: Path) -> bool:
+    """The BROKEN check that used startswith without separator.
+
+    Returns True when the path is OUTSIDE the skill directory.
+    """
+    return (
+        not str(resolved).startswith(str(skill_dir_resolved))
+        and resolved != skill_dir_resolved
+    )
+
+
+def _new_check_escapes(resolved: Path, skill_dir_resolved: Path) -> bool:
+    """The FIXED check using is_relative_to().
+
+    Returns True when the path is OUTSIDE the skill directory.
+    """
+    return not resolved.is_relative_to(skill_dir_resolved)
+
+
+class TestPrefixConfusionRegression:
+    """The core bug: startswith() can't distinguish directory boundaries."""
+
+    def test_old_check_misses_sibling_with_shared_prefix(self, tmp_path):
+        """Old startswith check fails on sibling dirs that share a prefix."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sibling_file = tmp_path / "skills" / "axolotl-backdoor" / "evil.py"
+        skill_dir.mkdir(parents=True)
+        sibling_file.parent.mkdir(parents=True)
+        sibling_file.write_text("evil")
+
+        resolved = sibling_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Bug: old check says the file is INSIDE the skill dir
+        assert _old_check_escapes(resolved, skill_dir_resolved) is False
+
+    def test_new_check_catches_sibling_with_shared_prefix(self, tmp_path):
+        """is_relative_to() correctly rejects sibling dirs."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sibling_file = tmp_path / "skills" / "axolotl-backdoor" / "evil.py"
+        skill_dir.mkdir(parents=True)
+        sibling_file.parent.mkdir(parents=True)
+        sibling_file.write_text("evil")
+
+        resolved = sibling_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Fixed: new check correctly says it's OUTSIDE
+        assert _new_check_escapes(resolved, skill_dir_resolved) is True
+
+    def test_both_agree_on_real_subpath(self, tmp_path):
+        """Both checks allow a genuine subpath."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        sub_file = skill_dir / "utils" / "helper.py"
+        skill_dir.mkdir(parents=True)
+        sub_file.parent.mkdir(parents=True)
+        sub_file.write_text("ok")
+
+        resolved = sub_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        assert _old_check_escapes(resolved, skill_dir_resolved) is False
+        assert _new_check_escapes(resolved, skill_dir_resolved) is False
+
+    def test_both_agree_on_completely_outside_path(self, tmp_path):
+        """Both checks block a path that's completely outside."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        outside_file = tmp_path / "etc" / "passwd"
+        skill_dir.mkdir(parents=True)
+        outside_file.parent.mkdir(parents=True)
+        outside_file.write_text("root:x:0:0")
+
+        resolved = outside_file.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        assert _old_check_escapes(resolved, skill_dir_resolved) is True
+        assert _new_check_escapes(resolved, skill_dir_resolved) is True
+
+    def test_skill_dir_itself_allowed(self, tmp_path):
+        """Requesting the skill directory itself is fine."""
+        skill_dir = tmp_path / "skills" / "axolotl"
+        skill_dir.mkdir(parents=True)
+
+        resolved = skill_dir.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Both should allow the dir itself
+        assert _old_check_escapes(resolved, skill_dir_resolved) is False
+        assert _new_check_escapes(resolved, skill_dir_resolved) is False
+
+
+def _can_symlink():
+    """Check if we can create symlinks (needs admin/dev-mode on Windows)."""
+    import tempfile
+    try:
+        with tempfile.TemporaryDirectory() as d:
+            src = Path(d) / "src"
+            src.write_text("x")
+            lnk = Path(d) / "lnk"
+            lnk.symlink_to(src)
+            return True
+    except OSError:
+        return False
+
+
+@pytest.mark.skipif(not _can_symlink(), reason="Symlinks need elevated privileges")
+class TestSymlinkEscapeWithActualSymlinks:
+    """Test the full symlink scenario with real filesystem symlinks."""
+
+    def test_symlink_to_sibling_prefix_dir_detected(self, tmp_path):
+        """A symlink from axolotl/ to axolotl-backdoor/ must be caught."""
+        skills = tmp_path / "skills"
+        skill_dir = skills / "axolotl"
+        sibling_dir = skills / "axolotl-backdoor"
+        skill_dir.mkdir(parents=True)
+        sibling_dir.mkdir(parents=True)
+
+        malicious = sibling_dir / "malicious.py"
+        malicious.write_text("evil code")
+
+        link = skill_dir / "helper.py"
+        link.symlink_to(malicious)
+
+        resolved = link.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        # Old check would miss this (prefix confusion)
+        assert _old_check_escapes(resolved, skill_dir_resolved) is False
+        # New check catches it
+        assert _new_check_escapes(resolved, skill_dir_resolved) is True
+
+    def test_symlink_within_skill_dir_allowed(self, tmp_path):
+        """A symlink that stays within the skill directory is fine."""
+        skill_dir = tmp_path / "my-skill"
+        skill_dir.mkdir()
+        real_file = skill_dir / "real.py"
+        real_file.write_text("print('ok')")
+        link = skill_dir / "alias.py"
+        link.symlink_to(real_file)
+
+        resolved = link.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        assert _new_check_escapes(resolved, skill_dir_resolved) is False
+
+    def test_symlink_to_parent_dir_blocked(self, tmp_path):
+        """A symlink pointing outside (to parent) is blocked."""
+        skill_dir = tmp_path / "skill"
+        skill_dir.mkdir()
+        outside = tmp_path / "secret.env"
+        outside.write_text("SECRET=123")
+
+        link = skill_dir / "config.env"
+        link.symlink_to(outside)
+
+        resolved = link.resolve()
+        skill_dir_resolved = skill_dir.resolve()
+
+        assert _new_check_escapes(resolved, skill_dir_resolved) is True

tools/skills_guard.py

@@ -743,7 +743,7 @@ def _check_structure(skill_dir: Path) -> List[Finding]:
         if f.is_symlink():
             try:
                 resolved = f.resolve()
-                if not str(resolved).startswith(str(skill_dir.resolve())):
+                if not resolved.is_relative_to(skill_dir.resolve()):
                     findings.append(Finding(
                         pattern_id="symlink_escape",
                         severity="critical",