microsoft/semantic-kernel · critical · KernelException

Path '{path}' contains a dot-segment, which could lead to pa

Error message

Path '{path}' contains a dot-segment, which could lead to path traversal.

What it means

SSRF guard in RestApiOperation.BuildPath (via ValidatePathSegments / ContainsDotSegment). After path parameters are substituted, the resulting path is scanned for '.' or '..' segments - including percent-encoded forms like %2e, %2e%2e, and even double-encoded %252e that Uri would canonicalize at request time. A dot-segment can navigate outside the intended path, so the request is refused.

Source

Thrown at dotnet/src/Functions/Functions.OpenApi/Model/RestApiOperation.cs:460

    {
        { RestApiParameterStyle.Simple, SimpleStyleParameterSerializer.Serialize },
        { RestApiParameterStyle.Form, FormStyleParameterSerializer.Serialize },
        { RestApiParameterStyle.SpaceDelimited, SpaceDelimitedStyleParameterSerializer.Serialize },
        { RestApiParameterStyle.PipeDelimited, PipeDelimitedStyleParameterSerializer.Serialize }
    };

    /// <summary>
    /// Validates that the path does not contain dot-segments (. or ..) that could enable path traversal,
    /// including percent-encoded forms (e.g. "%2e%2e") that <see cref="Uri"/> canonicalizes at request time.
    /// ".." navigates up one path segment, enabling traversal to unintended endpoints.
    /// "." refers to the current directory — harmless but unexpected, so rejected to prevent misuse.
    /// </summary>
    /// <param name="path">The path to validate.</param>
    private static void ValidatePathSegments(string path)
    {
        if (ContainsDotSegment(path))
        {
            throw new KernelException($"Path '{path}' contains a dot-segment, which could lead to path traversal.");
        }
    }

    /// <summary>
    /// Determines whether the supplied path contains a dot-segment (. or ..), including percent-encoded
    /// forms (e.g. "%2e%2e") that <see cref="Uri"/> canonicalizes at request time. This is used both to
    /// reject such paths when building a request URL and to exclude them during operation selection so an
    /// encoded dot-segment cannot bypass an include/exclude operation-selection filter.
    /// </summary>
    /// <param name="path">The path to inspect.</param>
    /// <returns><see langword="true"/> if the path contains a dot-segment; otherwise, <see langword="false"/>.</returns>
    internal static bool ContainsDotSegment(string path)
    {
        if (string.IsNullOrEmpty(path))
        {
            return false;
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Sanitize path argument values before invocation: reject any value whose segments decode to '.' or '..' (see the ContainsDotSegment algorithm).
  2. Avoid putting free-form user input directly into path parameters; validate against an allow-list of safe segment characters.
  3. If '..' is legitimately part of a name (rare), encode it differently or move the value to a query parameter instead of a path segment.
  4. Treat this as a security control, not a bug to suppress - it blocks path traversal.

Example fix

// before - unsanitized value can carry a dot-segment
arguments["file"] = "../../etc/passwd";

// after - validate the segment first
static bool IsSafePathSegment(string v)
    => !v.Split('/', '\\').Select(Uri.UnescapeDataString).Any(s => s is "." or "..");
if (!IsSafePathSegment(value)) throw new ArgumentException("unsafe path segment");
arguments["file"] = value;
Defensive patterns

Strategy: validation

Validate before calling

static bool ContainsDotSegment(string path)
{
    if (string.IsNullOrEmpty(path)) return false;
    foreach (var raw in path.Split('/'))
    {
        var d = raw;
        for (int i = 0; i < 5; i++) { var u = Uri.UnescapeDataString(d); if (u == d) break; d = u; }
        foreach (var seg in d.Split('/', '\\')) if (seg is "." or "..") return true;
    }
    return false;
}
if (ContainsDotSegment(value)) throw new ArgumentException("Path argument contains a dot-segment.");

Type guard

static bool IsSafePathValue(string v)
{
    if (string.IsNullOrEmpty(v)) return true;
    foreach (var raw in v.Split('/', '\\'))
    { var d = raw; for (int i=0;i<5;i++){var u=Uri.UnescapeDataString(d); if(u==d)break; d=u;} if (d is "." or "..") return false; }
    return true;
}

Try / catch

try { var url = operation.BuildOperationUrl(arguments); }
catch (KernelException ex) when (ex.Message.Contains("dot-segment"))
{ logger.LogWarning(ex, "Path traversal attempt blocked in a path argument."); throw; }

Prevention

When it happens

Trigger: A path parameter value (or a literal path template) containing '.', '..', %2e, %2e%2e, or encoded separator forms (%2f/%5c) that decode to a dot-segment. Because argument values are URL-encoded into the path, a malicious or malformed value can introduce traversal.

Common situations: User- or model-supplied path argument that includes '..'; a spec path authored with a '..' literal; an attempt to supply a value like '..%2fadmin'; values that, once percent-decoded and re-split on '/' or backslash, yield a '.' or '..' token.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/05b77cb81f7e5f41. Report an issue: GitHub.