From 13ca088fc4daebb9b73f64ac20a4926bbd864e23 Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Fri, 6 Nov 2026 18:52:07 +0000 Subject: [PATCH 1/7] Reject file skill resource and script names that differ only by case FileSkill lookup is case-insensitive, so names such as readme.md and README.md were ambiguous and could resolve to the wrong file. The FileSkill constructor now rejects such resource or script names, and file and MCP archive skill sources skip the affected skill with a warning. ZIP extraction rejects members that normalize to the same path instead of keeping the first. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../packages/core/agent_framework/_skills.py | 92 +++++++++++------- .../core/tests/core/test_mcp_skills.py | 97 ++++++++++--------- .../packages/core/tests/core/test_skills.py | 64 ++++++++++++ .../references/harness-agent-builder.md | 3 + 4 files changed, 175 insertions(+), 81 deletions(-) diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 464d79ac7e2..37eac4561e2 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -1851,6 +1851,10 @@ async def get_script(self, name: str) -> SkillScript | None: class FileSkill(Skill): """A :class:`Skill` discovered from a filesystem directory backed by a SKILL.md file. + Resource and script lookup is case-insensitive, so two resources or two + scripts whose names differ only by case (e.g. ``readme.md`` and + ``README.md``) are ambiguous and rejected with :class:`ValueError`. + Attributes: path: Absolute path to the directory containing this skill. """ @@ -1874,6 +1878,9 @@ def __init__( path: Absolute path to the skill directory on disk. resources: Resources discovered for this skill. scripts: Scripts discovered for this skill. + + Raises: + ValueError: If resource or script names differ only by case. """ self._frontmatter = frontmatter @@ -1881,6 +1888,8 @@ def __init__( self.path = path self._resources: list[SkillResource] = list(resources) if resources is not None else [] self._scripts: list[SkillScript] = list(scripts) if scripts is not None else [] + self._reject_case_variant_names(frontmatter.name, "resource", self._resources) + self._reject_case_variant_names(frontmatter.name, "script", self._scripts) self._cached_content: str | None = None @property @@ -1938,6 +1947,21 @@ async def get_script(self, name: str) -> SkillScript | None: name_lower = name.lower() return next((s for s in self._scripts if s.name.lower() == name_lower), None) + @staticmethod + def _reject_case_variant_names(skill_name: str, kind: str, entries: Sequence[SkillResource | SkillScript]) -> None: + """Reject names that case-insensitive lookup could not tell apart. + + Raises: + ValueError: If two names differ only by case. + """ + names: dict[str, str] = {} + for entry in entries: + previous = names.setdefault(entry.name.lower(), entry.name) + if previous != entry.name: + raise ValueError( + f"Skill '{skill_name}' has {kind} names that differ only by case: '{previous}' and '{entry.name}'." + ) + # endregion @@ -3143,6 +3167,9 @@ class FileSkillsSource(SkillsSource): Use *script_filter* and *resource_filter* predicates to control which discovered files are included. + Resource and script names that differ only by case skip the whole skill + with a warning. + Security: file-based metadata is XML-escaped before prompt injection, and resource reads are guarded against path traversal and symlink escape. Only use skills from trusted sources. @@ -3295,13 +3322,17 @@ async def get_skills(self, context: SkillsSourceContext) -> list[Skill]: ) ) - file_skill = FileSkill( - frontmatter=frontmatter, - content=content, - path=skill_path, - resources=resources, - scripts=scripts, - ) + try: + file_skill = FileSkill( + frontmatter=frontmatter, + content=content, + path=skill_path, + resources=resources, + scripts=scripts, + ) + except ValueError as exc: + logger.warning("Skipping skill '%s' at '%s': %s", frontmatter.name, skill_path, exc) + continue skills[file_skill.frontmatter.name] = file_skill logger.info("Loaded skill: %s", file_skill.frontmatter.name) @@ -5029,8 +5060,7 @@ def _extract_archive_to_memory( ``..`` parent-traversal ("zip-slip") aborts extraction of the whole archive by raising. Extraction is bounded by a maximum file count and total uncompressed size to mitigate decompression-bomb attacks. No filesystem is touched. - Later members whose normalized paths match case-insensitively are skipped - with a warning; the first member's spelling and content are retained. + Duplicate normalized member paths reject the archive. Args: data: The raw archive bytes. @@ -5043,7 +5073,7 @@ def _extract_archive_to_memory( Raises: ValueError: If the format is unknown, a limit is exceeded, or a member attempts - a path-traversal ("zip-slip") escape. + a path-traversal ("zip-slip") escape, or two members normalize to the same path. OSError: If the payload cannot be read. zipfile.BadZipFile: If a ZIP payload is malformed. """ @@ -5061,7 +5091,6 @@ def _extract_zip_to_memory( """Read regular files from a ZIP archive into memory. See :func:`_extract_archive_to_memory`.""" remaining_bytes = max_uncompressed_size_bytes files: dict[str, bytes] = {} - seen_names: set[str] = set() file_count = 0 for info in archive.infolist(): @@ -5075,22 +5104,12 @@ def _extract_zip_to_memory( name = _normalize_archive_member_name(info.filename) if name is None: continue - - # Match FileSkill's case-insensitive lookup; retain the first member's spelling. - lookup_name = name.lower() - if lookup_name in seen_names: - logger.warning( - "Skipping duplicate archive member %r: normalized path %r matches an earlier member; " - "keeping the first file", - info.filename, - name, - ) - continue + if name in files: + raise ValueError(f"Duplicate archive member {info.filename!r}: normalized path {name!r}.") with archive.open(info) as source: content, remaining_bytes = _read_member_with_limit(source, remaining_bytes) files[name] = content - seen_names.add(lookup_name) return files @@ -5110,8 +5129,8 @@ class _ArchiveEntryLoader: Extraction is hardened against path-traversal ("zip-slip") member names, oversized downloads, excessive file counts, and decompression bombs. - Member paths are compared case-insensitively; collisions are skipped with a - warning, keeping the first file's spelling and content. + Duplicate normalized member paths reject the archive, and resource names that + differ only by case reject the skill. Supplied SHA-256 digests are verified before extraction; archives without a digest remain supported. """ @@ -5305,13 +5324,17 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) # ``path`` records the archive's origin URL; it is informational only, as the # skill and its resources are served entirely from memory (no filesystem access). - return FileSkill( - frontmatter=frontmatter, - content=content, - path=cast(str, entry.url), - resources=resources, - scripts=[], - ) + try: + return FileSkill( + frontmatter=frontmatter, + content=content, + path=cast(str, entry.url), + resources=resources, + scripts=[], + ) + except ValueError as exc: + logger.warning("Skipping skill '%s': %s", entry.name, exc) + return None @staticmethod def _find_skill_md(files: dict[str, bytes]) -> str | None: @@ -5386,9 +5409,8 @@ class MCPSkillsSource(SkillsSource): archive are surfaced as read-only resources only; MCP-delivered scripts are never discovered as runnable. - Archive member paths are compared case-insensitively, matching resource lookup. - The first file's spelling and content are retained; later colliding members - are skipped with a warning. + Archive resource names that differ only by case, or members that normalize + to the same path, skip the whole archive skill with a warning. Entries whose type has no registered handler (e.g. ``mcp-resource-template``) are skipped. diff --git a/python/packages/core/tests/core/test_mcp_skills.py b/python/packages/core/tests/core/test_mcp_skills.py index ac7b122d4ed..e2241e74ff4 100644 --- a/python/packages/core/tests/core/test_mcp_skills.py +++ b/python/packages/core/tests/core/test_mcp_skills.py @@ -1536,7 +1536,7 @@ async def test_zip_slip_archive_skips_whole_skill(self) -> None: class TestMCPSkillsSourceArchiveCollisions: - """Colliding archive members warn and preserve the first file through discovery.""" + """Colliding archive members reject only the affected skill.""" @pytest.mark.parametrize( "alias", @@ -1553,7 +1553,7 @@ class TestMCPSkillsSourceArchiveCollisions: @pytest.mark.parametrize("alias_first", [False, True]) @pytest.mark.parametrize("identical", [False, True]) @pytest.mark.parametrize("with_digest", [False, True]) - async def test_colliding_resources_keep_first_file_and_warn( + async def test_colliding_resources_reject_skill_and_warn( self, alias: str, alias_first: bool, identical: bool, with_digest: bool, caplog: pytest.LogCaptureFixture ) -> None: url = "skill://archives/packaged-skill.zip" @@ -1572,24 +1572,15 @@ async def test_colliding_resources_keep_first_file_and_warn( for _ in range(2): skills = await source.get_skills(_SOURCE_CTX) - assert len(skills) == 1 - for resource_name in ("refs/policy.md", "REFS/POLICY.MD"): - resource = await skills[0].get_resource(resource_name) - assert resource is not None - assert await resource.read() == "First resource." - other = await skills[0].get_resource("refs/other.md") - assert other is not None - assert await other.read() == "Unaffected resource." - - collisions = [record for record in caplog.records if "duplicate archive member" in record.getMessage()] - assert len(collisions) == 2 - assert all(record.levelname == "WARNING" for record in collisions) - assert all("keeping the first file" in record.getMessage() for record in collisions) - assert all("Substituted resource." not in record.getMessage() for record in collisions) - - @pytest.mark.parametrize("alias", ["SKILL.md", ".//SKILL.md", "/SKILL.md", "skill.md", "Skill.MD"]) + assert skills == [] + + warnings = [record for record in caplog.records if record.levelname == "WARNING"] + assert len(warnings) == 2 + assert all("'packaged-skill'" in record.getMessage() for record in warnings) + + @pytest.mark.parametrize("alias", [".//SKILL.md", "/SKILL.md"]) @pytest.mark.parametrize("alias_first", [False, True]) - async def test_colliding_skill_md_keeps_first_file_and_warns( + async def test_duplicate_skill_md_rejects_skill_and_warns( self, alias: str, alias_first: bool, caplog: pytest.LogCaptureFixture ) -> None: url = "skill://archives/packaged-skill.zip" @@ -1605,28 +1596,52 @@ async def test_colliding_skill_md_keeps_first_file_and_warns( _SOURCE_CTX ) - assert len(skills) == 1 - assert skills[0].frontmatter.name == "packaged-skill" - assert "Instructions from an archive." in await skills[0].get_content() + assert skills == [] assert len(caplog.records) == 1 assert caplog.records[0].levelname == "WARNING" - assert "duplicate archive member" in caplog.text + assert "Failed to extract archive" in caplog.text - async def test_collision_does_not_skip_other_skills(self, caplog: pytest.LogCaptureFixture) -> None: + @pytest.mark.parametrize("duplicate", ["./reference.md", "REFERENCE.md"]) + async def test_collision_does_not_skip_other_skills(self, duplicate: str, caplog: pytest.LogCaptureFixture) -> None: url = "skill://archives/packaged-skill.zip" index_data = json.loads(SAMPLE_SKILL_INDEX) index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"]) archive = _make_zip([ ("SKILL.md", ARCHIVE_SKILL_MD.encode()), ("reference.md", b"First."), - ("./reference.md", b"Second."), + (duplicate, b"Second."), ]) client = _archive_client(json.dumps(index_data), url, archive, "application/zip") skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX) - assert sorted(skill.frontmatter.name for skill in skills) == ["packaged-skill", "unit-converter"] - assert "duplicate archive member" in caplog.text + assert [skill.frontmatter.name for skill in skills] == ["unit-converter"] + assert "'packaged-skill'" in caplog.text + + async def test_distinct_resource_paths_load_with_case_insensitive_lookup(self) -> None: + url = "skill://archives/packaged-skill.zip" + archive = _make_zip([ + ("SKILL.md", ARCHIVE_SKILL_MD.encode()), + ("reference.md", b"Root resource."), + ("REFERENCE.MD/nested.md", b"Nested resource."), + ("refs/one.md", b"One."), + ("REFS/two.md", b"Two."), + ]) + index = _make_archive_index("packaged-skill", url) + skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills( + _SOURCE_CTX + ) + + assert len(skills) == 1 + for name, content in ( + ("REFERENCE.MD", "Root resource."), + ("reference.md/NESTED.MD", "Nested resource."), + ("REFS/ONE.MD", "One."), + ("refs/two.md", "Two."), + ): + resource = await skills[0].get_resource(name) + assert resource is not None + assert await resource.read() == content class TestMCPSkillsSourceArchiveDigest: @@ -1941,30 +1956,20 @@ def test_duplicate_members_count_toward_file_limit(self) -> None: with pytest.raises(ValueError, match="file count"): _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 1, 1024 * 1024) - def test_skipped_duplicate_is_not_decompressed(self, caplog: pytest.LogCaptureFixture) -> None: - from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory, _read_member_with_limit - - archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"x" * 100)]) - with patch("agent_framework._skills._read_member_with_limit", wraps=_read_member_with_limit) as read: - files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, len(b"First.")) + def test_duplicate_normalized_path_rejects_archive(self) -> None: + from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory - assert files == {"reference.md": b"First."} - read.assert_called_once() - assert "duplicate archive member" in caplog.text + archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"Second.")]) + with pytest.raises(ValueError, match="Duplicate archive member"): + _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024) - @pytest.mark.parametrize("first_name", ["reference.md", "REFERENCE.md"]) - def test_case_collision_keeps_first_name_and_warns(self, first_name: str, caplog: pytest.LogCaptureFixture) -> None: + def test_case_variants_are_extracted_as_is(self) -> None: from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory - second_name = "REFERENCE.md" if first_name == "reference.md" else "reference.md" - archive = _make_zip([(first_name, b"First."), (second_name, b"Second.")]) - - files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024) + entries = {"reference.md": b"First.", "REFERENCE.md": b"Second."} + files = _extract_archive_to_memory(_make_zip(entries), _ArchiveFormat.ZIP, 20, 1024 * 1024) - assert files == {first_name: b"First."} - assert len(caplog.records) == 1 - assert caplog.records[0].levelname == "WARNING" - assert "duplicate archive member" in caplog.text + assert files == entries def test_distinct_lowercase_resource_names_are_preserved(self, caplog: pytest.LogCaptureFixture) -> None: from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py index 944c7d74a18..3e3ddd3dc78 100644 --- a/python/packages/core/tests/core/test_skills.py +++ b/python/packages/core/tests/core/test_skills.py @@ -2583,6 +2583,70 @@ async def test_resources_populated(self, tmp_path: Path) -> None: # --------------------------------------------------------------------------- +class TestFileSkillNameCollisions: + @pytest.mark.parametrize("kind", ["resource", "script"]) + @pytest.mark.parametrize("names", [("readme.md", "README.md"), ("refs/one.md", "REFS/ONE.md")]) + @pytest.mark.parametrize("reverse", [False, True]) + def test_constructor_rejects_names_differing_only_by_case( + self, kind: str, names: tuple[str, str], reverse: bool + ) -> None: + names = names[::-1] if reverse else names + resources = [InlineSkillResource(name=name, content="data") for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + with pytest.raises(ValueError, match=f"{kind} names that differ only by case"): + FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources if kind == "resource" else [], + scripts=scripts if kind == "script" else [], + ) + + async def test_resource_and_script_names_are_checked_separately(self) -> None: + resource = InlineSkillResource(name="run.py", content="data") + script = FileSkillScript(name="RUN.py", full_path=f"{_ABS}\\RUN.py") + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=[resource], + scripts=[script], + ) + assert await skill.get_resource("RUN.PY") is resource + assert await skill.get_script("run.py") is script + + async def test_distinct_names_allow_case_insensitive_lookup(self) -> None: + names = ["readme.md", "refs/one.md", "REFS/two.md"] + resources = [InlineSkillResource(name=name, content=name) for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources, + scripts=scripts, + ) + for resource, script in zip(resources, scripts): + assert await skill.get_resource(resource.name.upper()) is resource + assert await skill.get_script(script.name.upper()) is script + + async def test_filesystem_collision_skips_only_affected_skill( + self, tmp_path: Path, caplog: pytest.LogCaptureFixture + ) -> None: + _write_skill(tmp_path, "bad") + _write_skill(tmp_path, "good") + original = FileSkillsSource._discover_script_files + + def discover_script_files(self: FileSkillsSource, skill_path: str, skill_name: str) -> list[str]: + return ["run.py", "RUN.py"] if skill_name == "bad" else original(self, skill_path, skill_name) + + with patch.object(FileSkillsSource, "_discover_script_files", discover_script_files): + skills = await FileSkillsSource(tmp_path).get_skills(_SOURCE_CTX) + + assert [skill.frontmatter.name for skill in skills] == ["good"] + assert "Skipping skill 'bad'" in caplog.text + + class TestLoadSkillFormatting: """Tests for _load_skill output formatting differences between file-based and code-defined skills.""" diff --git a/skills/agent-framework-builder-python/references/harness-agent-builder.md b/skills/agent-framework-builder-python/references/harness-agent-builder.md index fb92cdab26a..195686ec745 100644 --- a/skills/agent-framework-builder-python/references/harness-agent-builder.md +++ b/skills/agent-framework-builder-python/references/harness-agent-builder.md @@ -34,6 +34,9 @@ complete option list. - For hosted or untrusted workloads, disable file memory or supply tenant-scoped storage with quotas, retention, and server-owned cleanup. Do not rely on the shared default working-directory store. - Load skills and background agents only from trusted sources; their content crosses the model and tool boundary. +- File-backed skill resource and script lookup is case-insensitive, so a skill whose resource or script names differ + only by case (for example `readme.md` and `README.md`) is skipped with a warning. ZIP archives with two members that + normalize to the same path are also skipped. - Bound autonomous loops and stop for unresolved approvals or user input. - Treat shell command filters as a usability guard, not a security boundary. The host owns sandboxing and executor lifecycle. Apply resource limits to the host agent process as well as the shell container; container memory From 6424dc69593dbe0527e04b31754ec2d99f6dcb18 Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Fri, 6 Nov 2026 19:45:13 +0000 Subject: [PATCH 2/7] Skip .NET file skills with resource or script names that differ only by case Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Skills/File/AgentFileSkillsSource.cs | 27 +++++++++++++++++ .../AgentSkills/FileAgentSkillLoaderTests.cs | 29 +++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs index 5484348c59e..dc303b903a1 100644 --- a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs +++ b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs @@ -27,6 +27,7 @@ namespace Microsoft.Agents.AI; /// value is retained for duplicate keys, and subsequent entries produce warnings without rejecting the skill. /// Resource and script files are discovered by scanning the skill /// directory for files with matching extensions. Invalid resources are skipped with logged warnings. +/// Skills whose resource names or script names differ only by case are skipped. /// Resource and script paths are checked against path traversal and symlink escape attacks. /// Discovered files are revalidated against their trusted skill directory immediately before use. /// @@ -223,6 +224,12 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull var resources = this.DiscoverResourceFiles(scope, frontmatter.Name); var scripts = this.DiscoverScriptFiles(scope, frontmatter.Name); + if (this.HasCaseVariantNames(frontmatter.Name, "resource", resources.Select(r => r.Name)) || + this.HasCaseVariantNames(frontmatter.Name, "script", scripts.Select(s => s.Name))) + { + return null; + } + return new AgentFileSkill( frontmatter: frontmatter, content: content, @@ -231,6 +238,23 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull scripts: scripts); } + private bool HasCaseVariantNames(string skillName, string kind, IEnumerable names) + { + var seen = new Dictionary(StringComparer.OrdinalIgnoreCase); + foreach (string name in names) + { + if (seen.TryGetValue(name, out string? previous)) + { + LogCaseVariantNames(this._logger, skillName, kind, SanitizePathForLog(previous), SanitizePathForLog(name)); + return true; + } + + seen.Add(name, name); + } + + return false; + } + private bool TryParseFrontmatter(string content, string skillFilePath, [NotNullWhen(true)] out AgentSkillFrontmatter? frontmatter) { frontmatter = null; @@ -785,6 +809,9 @@ private static void ValidateExtensions(IEnumerable? extensions) [LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}': skill name '{SkillName}' does not match parent directory name '{DirectoryName}'")] private static partial void LogNameDirectoryMismatch(ILogger logger, string skillFilePath, string skillName, string directoryName); + [LoggerMessage(LogLevel.Error, "Skipping skill '{SkillName}': {Kind} names '{FirstName}' and '{SecondName}' differ only by case")] + private static partial void LogCaseVariantNames(ILogger logger, string skillName, string kind, string firstName, string secondName); + [LoggerMessage(LogLevel.Warning, "Skipping resource in skill '{SkillName}': '{ResourcePath}' references a path outside the skill directory")] private static partial void LogResourcePathTraversal(ILogger logger, string skillName, string resourcePath); diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs index 1599023e1b7..5decdce2d77 100644 --- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs @@ -2151,6 +2151,35 @@ public async Task GetSkillsAsync_DeepResource_DiscoveredWithHigherDepthAsync() Assert.Equal("f1/f2/f3/data.json", skill.GetTestResources()![0].Name); } + [Theory] + [InlineData("test.md", "TEST.md")] + [InlineData("refs/test.md", "REFS/test.md")] + [InlineData("scripts/run.py", "scripts/RUN.py")] + public async Task GetSkillsAsync_NamesDifferOnlyByCase_SkipsSkillAsync(string firstName, string secondName) + { + // Arrange + string skillDir = this.CreateSkillDirectory("case-skill", "A skill", "Body."); + string firstPath = Path.Combine(skillDir, firstName); + string secondPath = Path.Combine(skillDir, secondName); + Directory.CreateDirectory(Path.GetDirectoryName(firstPath)!); + Directory.CreateDirectory(Path.GetDirectoryName(secondPath)!); + File.WriteAllText(firstPath, "first"); + File.WriteAllText(secondPath, "second"); + if (Directory.EnumerateFiles(skillDir, "*", SearchOption.AllDirectories).Count() != 3) + { + Assert.Skip("The filesystem is not case-sensitive."); + } + + this.CreateSkillDirectory("other-skill", "A skill", "Body."); + var source = new AgentFileSkillsSource(this._testRoot, s_noOpExecutor); + + // Act + var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create()); + + // Assert + Assert.Equal("other-skill", Assert.Single(skills).Frontmatter.Name); + } + private string CreateSkillDirectory(string name, string description, string body) { string skillDir = Path.Combine(this._testRoot, name); From b2642200eb4eee227a9a53b7b230707d36e8e138 Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Fri, 6 Nov 2026 20:25:59 +0000 Subject: [PATCH 3/7] Reject MCP archive file names that differ only by case Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Loaders/AgentMcpSkillArchiveExtractor.cs | 14 ++++-- .../AgentMcpSkillsSourceArchiveTests.cs | 44 +++++++++++++++++-- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs index f9d5dcc5328..d58328ab3ac 100644 --- a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs @@ -17,6 +17,7 @@ namespace Microsoft.Agents.AI; /// Supports ZIP payloads. Extraction is guarded against path-traversal ("zip-slip") attacks and /// bounded by a maximum file count and total uncompressed size to mitigate decompression-bomb attacks. /// Later entries resolving to an existing file are skipped, preserving the first file's content. +/// Archives containing file names that differ only by case are rejected. /// internal static partial class AgentMcpSkillArchiveExtractor { @@ -83,7 +84,7 @@ internal static ArchiveFormat DetectFormat(byte[] bytes, string? mediaType, stri /// The maximum total uncompressed size, in bytes, of all extracted files. /// An optional logger reporting each skipped colliding archive member. /// The format is not . - /// The archive exceeds one of the supplied limits. + /// The archive exceeds one of the supplied limits or contains file names that differ only by case. internal static void Extract( byte[] bytes, ArchiveFormat format, @@ -113,7 +114,7 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun long remainingBytes = maxUncompressedSizeBytes; int fileCount = 0; - var destinations = new HashSet(OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal); + var destinations = new Dictionary(StringComparer.OrdinalIgnoreCase); string skillName = SanitizePathForLog(Path.GetFileName(fullTarget)); foreach (ZipArchiveEntry entry in archive.Entries) @@ -136,12 +137,19 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun } // Normalization can map distinct archive names to one path; keep the first file. - if (!destinations.Add(destination)) + if (destinations.TryGetValue(destination, out string? previous)) { + if (!string.Equals(previous, destination, StringComparison.Ordinal)) + { + throw new InvalidDataException("Skill archive contains file names that differ only by case."); + } + LogArchiveMemberCollision(logger, skillName, SanitizePathForLog(entry.FullName)); continue; } + destinations.Add(destination, destination); + Directory.CreateDirectory(Path.GetDirectoryName(destination)!); // CreateNew also prevents overwrites through filesystem aliases, such as trailing dots on Windows. diff --git a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs index 6a4ed11b222..fe3db8cb764 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs @@ -259,7 +259,6 @@ public static TheoryData ArchiveCollisionCases }; if (OperatingSystem.IsWindows()) { - aliases.Add("refs/POLICY.md"); aliases.Add("refs/policy.md."); } @@ -312,8 +311,7 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs for (int i = 0; i < 2; i++) { var skill = Assert.Single(await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create())); - string resourceName = aliasFirst && alias == "refs/POLICY.md" ? alias : "refs/policy.md"; - var resource = await skill.GetResourceAsync(resourceName); + var resource = await skill.GetResourceAsync("refs/policy.md"); Assert.NotNull(resource); Assert.Equal("First resource.", await resource.ReadAsync()); var other = await skill.GetResourceAsync("refs/other.md"); @@ -334,6 +332,46 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs Times.Exactly(2)); } + [Theory] + [InlineData("refs/policy.md", "refs/POLICY.md", false)] + [InlineData("refs/policy.md", "refs/POLICY.md", true)] + [InlineData("refs/policy.md", "REFS/policy.md", false)] + [InlineData("refs/policy.md", "REFS/policy.md", true)] + [InlineData("scripts/run.py", "scripts/RUN.py", false)] + [InlineData("scripts/run.py", "scripts/RUN.py", true)] + [InlineData("SKILL.md", "skill.md", false)] + [InlineData("SKILL.md", "skill.md", true)] + public async Task GetSkillsAsync_CaseVariantArchiveNames_SkipsSkillAsync(string name, string variant, bool variantFirst) + { + // Arrange + var files = new List<(string Path, string Content)> + { + (variantFirst ? variant : name, ArchivedSkillMd), + (variantFirst ? name : variant, ArchivedSkillMd), + }; + if (!string.Equals(name, "SKILL.md", StringComparison.Ordinal)) + { + files.Add(("SKILL.md", ArchivedSkillMd)); + } + + byte[] archive = BuildZip(files.ToArray()); + await using var server = CreateArchiveServer( + ArchiveIndex("archived-skill", "skill://archives/archived-skill.zip"), + new Dictionary { ["archived-skill"] = archive }); + await using var client = await server.CreateClientAsync(); + var source = new AgentMcpSkillsSource(client, new() { ArchiveSkillsDirectory = this._extractionRoot }); + + for (int i = 0; i < 2; i++) + { + // Act + var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create()); + + // Assert + Assert.Empty(skills); + Assert.False(Directory.Exists(Path.Combine(this._extractionRoot, "archived-skill"))); + } + } + [Theory] [InlineData("SKILL.md", false)] [InlineData("SKILL.md", true)] From c9c47e5e4813e470b700014aa018d81b00de1744 Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Fri, 6 Nov 2026 20:38:47 +0000 Subject: [PATCH 4/7] Reject Python skill archives with case-variant manifest paths Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../packages/core/agent_framework/_skills.py | 10 +++- .../core/tests/core/test_mcp_skills.py | 51 +++++++++++++++++++ .../references/harness-agent-builder.md | 2 +- 3 files changed, 60 insertions(+), 3 deletions(-) diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 37eac4561e2..55336f51c4e 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -5292,7 +5292,11 @@ def _build_skill(self, entry: _McpSkillIndexEntry, data: bytes, mime_type: str | def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) -> FileSkill | None: """Assemble an in-memory :class:`FileSkill` from the archive's extracted files.""" - skill_md_key = self._find_skill_md(files) + try: + skill_md_key = self._find_skill_md(files) + except ValueError as exc: + logger.warning("Skipping skill '%s': %s", entry.name, exc) + return None if skill_md_key is None: logger.warning("Skipping skill '%s': archive contains no SKILL.md", entry.name) return None @@ -5338,10 +5342,12 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) @staticmethod def _find_skill_md(files: dict[str, bytes]) -> str | None: - """Return the key of the shallowest ``SKILL.md`` (case-insensitive), or ``None``.""" + """Return the shallowest ``SKILL.md`` key, rejecting manifest paths that differ only by case.""" candidates = [key for key in files if key.rsplit("/", 1)[-1].upper() == SKILL_FILE_NAME.upper()] if not candidates: return None + if len({key.lower() for key in candidates}) != len(candidates): + raise ValueError("Archive contains SKILL.md paths that differ only by case.") # Prefer the shallowest SKILL.md; break ties deterministically by name. return min(candidates, key=lambda key: (key.count("/"), key)) diff --git a/python/packages/core/tests/core/test_mcp_skills.py b/python/packages/core/tests/core/test_mcp_skills.py index e2241e74ff4..4b8bf6994d4 100644 --- a/python/packages/core/tests/core/test_mcp_skills.py +++ b/python/packages/core/tests/core/test_mcp_skills.py @@ -1601,6 +1601,57 @@ async def test_duplicate_skill_md_rejects_skill_and_warns( assert caplog.records[0].levelname == "WARNING" assert "Failed to extract archive" in caplog.text + @pytest.mark.parametrize( + ("manifest", "variant"), + [ + ("SKILL.md", "skill.md"), + ("SKILL.md", "Skill.MD"), + ("nested/SKILL.md", "nested/skill.md"), + ("nested/SKILL.md", "NESTED/SKILL.md"), + ], + ) + @pytest.mark.parametrize("variant_first", [False, True]) + async def test_case_variant_manifests_skip_only_affected_skill( + self, manifest: str, variant: str, variant_first: bool, caplog: pytest.LogCaptureFixture + ) -> None: + url = "skill://archives/packaged-skill.zip" + manifests = [ + (manifest, ARCHIVE_SKILL_MD.encode()), + (variant, ARCHIVE_SKILL_MD.replace("Instructions from an archive.", "Other instructions.").encode()), + ] + if variant_first: + manifests.reverse() + archive = _make_zip(manifests) + index_data = json.loads(SAMPLE_SKILL_INDEX) + index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"]) + client = _archive_client(json.dumps(index_data), url, archive, "application/zip") + + skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX) + + assert [skill.frontmatter.name for skill in skills] == ["unit-converter"] + assert len(caplog.records) == 1 + assert caplog.records[0].levelname == "WARNING" + assert "'packaged-skill'" in caplog.text + assert "SKILL.md paths that differ only by case" in caplog.text + + @pytest.mark.parametrize( + ("manifest", "other"), + [("SKILL.md", "nested/skill.md"), ("a/SKILL.md", "b/skill.md")], + ) + async def test_manifests_in_distinct_directories_are_not_case_variants(self, manifest: str, other: str) -> None: + url = "skill://archives/packaged-skill.zip" + archive = _make_zip([ + (manifest, ARCHIVE_SKILL_MD.encode()), + (other, ARCHIVE_SKILL_MD.encode()), + ]) + index = _make_archive_index("packaged-skill", url) + + skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills( + _SOURCE_CTX + ) + + assert [skill.frontmatter.name for skill in skills] == ["packaged-skill"] + @pytest.mark.parametrize("duplicate", ["./reference.md", "REFERENCE.md"]) async def test_collision_does_not_skip_other_skills(self, duplicate: str, caplog: pytest.LogCaptureFixture) -> None: url = "skill://archives/packaged-skill.zip" diff --git a/skills/agent-framework-builder-python/references/harness-agent-builder.md b/skills/agent-framework-builder-python/references/harness-agent-builder.md index 195686ec745..b559b5bcb0c 100644 --- a/skills/agent-framework-builder-python/references/harness-agent-builder.md +++ b/skills/agent-framework-builder-python/references/harness-agent-builder.md @@ -36,7 +36,7 @@ complete option list. - Load skills and background agents only from trusted sources; their content crosses the model and tool boundary. - File-backed skill resource and script lookup is case-insensitive, so a skill whose resource or script names differ only by case (for example `readme.md` and `README.md`) is skipped with a warning. ZIP archives with two members that - normalize to the same path are also skipped. + normalize to the same path, or with manifest paths differing only by case (`SKILL.md` and `skill.md`), are also skipped. - Bound autonomous loops and stop for unresolved approvals or user input. - Treat shell command filters as a usability guard, not a security boundary. The host owns sandboxing and executor lifecycle. Apply resource limits to the host agent process as well as the shell container; container memory From 7865be586a6a9d0bb732f3bcb8c87eb3e75a83f5 Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Fri, 6 Nov 2026 20:41:35 +0000 Subject: [PATCH 5/7] Preserve tuple length in skill collision test Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- python/packages/core/tests/core/test_skills.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py index 3e3ddd3dc78..4c37684f815 100644 --- a/python/packages/core/tests/core/test_skills.py +++ b/python/packages/core/tests/core/test_skills.py @@ -2590,7 +2590,7 @@ class TestFileSkillNameCollisions: def test_constructor_rejects_names_differing_only_by_case( self, kind: str, names: tuple[str, str], reverse: bool ) -> None: - names = names[::-1] if reverse else names + names = (names[1], names[0]) if reverse else names resources = [InlineSkillResource(name=name, content="data") for name in names] scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] with pytest.raises(ValueError, match=f"{kind} names that differ only by case"): From 334352f1b296b97de3582cf65040ce9e71f1265a Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Mon, 9 Nov 2026 10:14:19 +0000 Subject: [PATCH 6/7] Clarify skill name comparison rules and remove builder skill changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Skills/File/AgentFileSkillsSource.cs | 5 +++++ .../AgentSkills/FileAgentSkillLoaderTests.cs | 6 ++++++ python/packages/core/agent_framework/_skills.py | 3 ++- python/packages/core/tests/core/test_skills.py | 16 ++++++++++++++++ .../references/harness-agent-builder.md | 3 --- 5 files changed, 29 insertions(+), 4 deletions(-) diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs index dc303b903a1..8e7fcea9aad 100644 --- a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs +++ b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs @@ -28,6 +28,8 @@ namespace Microsoft.Agents.AI; /// Resource and script files are discovered by scanning the skill /// directory for files with matching extensions. Invalid resources are skipped with logged warnings. /// Skills whose resource names or script names differ only by case are skipped. +/// Names are compared using ; Unicode equivalence +/// follows the target runtime. /// Resource and script paths are checked against path traversal and symlink escape attacks. /// Discovered files are revalidated against their trusted skill directory immediately before use. /// @@ -238,6 +240,9 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull scripts: scripts); } + /// + /// Checks names using . + /// private bool HasCaseVariantNames(string skillName, string kind, IEnumerable names) { var seen = new Dictionary(StringComparer.OrdinalIgnoreCase); diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs index 5decdce2d77..3603498d9a2 100644 --- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs @@ -2155,6 +2155,12 @@ public async Task GetSkillsAsync_DeepResource_DiscoveredWithHigherDepthAsync() [InlineData("test.md", "TEST.md")] [InlineData("refs/test.md", "REFS/test.md")] [InlineData("scripts/run.py", "scripts/RUN.py")] + [InlineData("\u00e9.md", "\u00c9.md")] + [InlineData("scripts/\u00e9.py", "scripts/\u00c9.py")] +#if NET10_0_OR_GREATER + [InlineData("\u03a3.md", "\u03c2.md")] + [InlineData("scripts/\u03a3.py", "scripts/\u03c2.py")] +#endif public async Task GetSkillsAsync_NamesDifferOnlyByCase_SkipsSkillAsync(string firstName, string secondName) { // Arrange diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 55336f51c4e..4fd42e7ddf5 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -1854,6 +1854,7 @@ class FileSkill(Skill): Resource and script lookup is case-insensitive, so two resources or two scripts whose names differ only by case (e.g. ``readme.md`` and ``README.md``) are ambiguous and rejected with :class:`ValueError`. + Comparison uses :meth:`str.lower`, not :meth:`str.casefold`. Attributes: path: Absolute path to the directory containing this skill. @@ -1949,7 +1950,7 @@ async def get_script(self, name: str) -> SkillScript | None: @staticmethod def _reject_case_variant_names(skill_name: str, kind: str, entries: Sequence[SkillResource | SkillScript]) -> None: - """Reject names that case-insensitive lookup could not tell apart. + """Reject names with equal ``str.lower()`` keys, matching resource and script lookup. Raises: ValueError: If two names differ only by case. diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py index 4c37684f815..bfb3e63d12e 100644 --- a/python/packages/core/tests/core/test_skills.py +++ b/python/packages/core/tests/core/test_skills.py @@ -2615,6 +2615,22 @@ async def test_resource_and_script_names_are_checked_separately(self) -> None: assert await skill.get_resource("RUN.PY") is resource assert await skill.get_script("run.py") is script + @pytest.mark.parametrize("names", [("\u03a3.md", "\u03c2.md"), ("stra\u00dfe.md", "strasse.md")]) + async def test_unicode_names_with_distinct_lowercase_keys_remain_distinct(self, names: tuple[str, str]) -> None: + resources = [InlineSkillResource(name=name, content=name) for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources, + scripts=scripts, + ) + + for resource, script in zip(resources, scripts): + assert await skill.get_resource(resource.name.lower()) is resource + assert await skill.get_script(script.name.lower()) is script + async def test_distinct_names_allow_case_insensitive_lookup(self) -> None: names = ["readme.md", "refs/one.md", "REFS/two.md"] resources = [InlineSkillResource(name=name, content=name) for name in names] diff --git a/skills/agent-framework-builder-python/references/harness-agent-builder.md b/skills/agent-framework-builder-python/references/harness-agent-builder.md index b559b5bcb0c..fb92cdab26a 100644 --- a/skills/agent-framework-builder-python/references/harness-agent-builder.md +++ b/skills/agent-framework-builder-python/references/harness-agent-builder.md @@ -34,9 +34,6 @@ complete option list. - For hosted or untrusted workloads, disable file memory or supply tenant-scoped storage with quotas, retention, and server-owned cleanup. Do not rely on the shared default working-directory store. - Load skills and background agents only from trusted sources; their content crosses the model and tool boundary. -- File-backed skill resource and script lookup is case-insensitive, so a skill whose resource or script names differ - only by case (for example `readme.md` and `README.md`) is skipped with a warning. ZIP archives with two members that - normalize to the same path, or with manifest paths differing only by case (`SKILL.md` and `skill.md`), are also skipped. - Bound autonomous loops and stop for unresolved approvals or user input. - Treat shell command filters as a usability guard, not a security boundary. The host owns sandboxing and executor lifecycle. Apply resource limits to the host agent process as well as the shell container; container memory From 18cc83dedd3ef974a15862d4f7fcea1fd2d33e6a Mon Sep 17 00:00:00 2001 From: SergeyMenshykh Date: Mon, 9 Nov 2026 20:54:03 +0000 Subject: [PATCH 7/7] Clarify skill name collision helper parameters Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Skills/File/AgentFileSkillsSource.cs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs index 8e7fcea9aad..34a91b34b90 100644 --- a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs +++ b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs @@ -241,12 +241,17 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull } /// - /// Checks names using . + /// Checks for collisions among the supplied names using + /// and logs the first collision. /// - private bool HasCaseVariantNames(string skillName, string kind, IEnumerable names) + /// The owning skill's name, used only in the log message, not in comparisons. + /// The entry category ("resource" or "script"), used only in the log message. + /// The resource or script names to compare with each other. + /// if a collision is found; otherwise, . + private bool HasCaseVariantNames(string skillName, string kind, IEnumerable entryNames) { var seen = new Dictionary(StringComparer.OrdinalIgnoreCase); - foreach (string name in names) + foreach (string name in entryNames) { if (seen.TryGetValue(name, out string? previous)) {