Skip to content
Original file line number Diff line number Diff line change
Expand Up @@ -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.
/// </remarks>
internal static partial class AgentMcpSkillArchiveExtractor
{
Expand Down Expand Up @@ -83,7 +84,7 @@ internal static ArchiveFormat DetectFormat(byte[] bytes, string? mediaType, stri
/// <param name="maxUncompressedSizeBytes">The maximum total uncompressed size, in bytes, of all extracted files.</param>
/// <param name="logger">An optional logger reporting each skipped colliding archive member.</param>
/// <exception cref="NotSupportedException">The format is not <see cref="ArchiveFormat.Zip"/>.</exception>
/// <exception cref="InvalidDataException">The archive exceeds one of the supplied limits.</exception>
/// <exception cref="InvalidDataException">The archive exceeds one of the supplied limits or contains file names that differ only by case.</exception>
internal static void Extract(
byte[] bytes,
ArchiveFormat format,
Expand Down Expand Up @@ -113,7 +114,7 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun

long remainingBytes = maxUncompressedSizeBytes;
int fileCount = 0;
var destinations = new HashSet<string>(OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal);
var destinations = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
string skillName = SanitizePathForLog(Path.GetFileName(fullTarget));

foreach (ZipArchiveEntry entry in archive.Entries)
Expand All @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ 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.
/// Names are compared using <see cref="StringComparer.OrdinalIgnoreCase"/>; 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.
/// </remarks>
Expand Down Expand Up @@ -223,6 +226,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)) ||
Comment thread
SergeyMenshykh marked this conversation as resolved.
Resolved
this.HasCaseVariantNames(frontmatter.Name, "script", scripts.Select(s => s.Name)))
Comment thread
SergeyMenshykh marked this conversation as resolved.
Resolved
{
return null;
}

return new AgentFileSkill(
frontmatter: frontmatter,
content: content,
Expand All @@ -231,6 +240,31 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull
scripts: scripts);
}

/// <summary>
/// Checks for collisions among the supplied names using <see cref="StringComparer.OrdinalIgnoreCase"/>
/// and logs the first collision.
/// </summary>
/// <param name="skillName">The owning skill's name, used only in the log message, not in comparisons.</param>
/// <param name="kind">The entry category ("resource" or "script"), used only in the log message.</param>
/// <param name="entryNames">The resource or script names to compare with each other.</param>
/// <returns><see langword="true"/> if a collision is found; otherwise, <see langword="false"/>.</returns>
private bool HasCaseVariantNames(string skillName, string kind, IEnumerable<string> entryNames)
{
var seen = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
foreach (string name in entryNames)
{
if (seen.TryGetValue(name, out string? previous))
{
LogCaseVariantNames(this._logger, skillName, kind, SanitizePathForLog(previous), SanitizePathForLog(name));
return true;
}

seen.Add(name, name);
}

return false;
Comment thread
eavanvalkenburg marked this conversation as resolved.
Resolved
}

private bool TryParseFrontmatter(string content, string skillFilePath, [NotNullWhen(true)] out AgentSkillFrontmatter? frontmatter)
{
frontmatter = null;
Expand Down Expand Up @@ -785,6 +819,9 @@ private static void ValidateExtensions(IEnumerable<string>? 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);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,6 @@ public static TheoryData<string, bool, bool, bool> ArchiveCollisionCases
};
if (OperatingSystem.IsWindows())
{
aliases.Add("refs/POLICY.md");
aliases.Add("refs/policy.md.");
}

Expand Down Expand Up @@ -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");
Expand All @@ -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<string, byte[]> { ["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)]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2151,6 +2151,41 @@ 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")]
[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
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);
Expand Down
Loading
Loading