{"record":{"id":"efde863dbadf3c73","repo":"alibaba/spring-ai-alibaba","slug":"path-traversal-not-allowed-efde86","errorCode":null,"errorMessage":"Path traversal not allowed: ","messagePattern":"Path traversal not allowed: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/FilesystemInterceptor.java","lineNumber":162,"sourceCode":"\t\tthis.tools = Collections.unmodifiableList(toolList);\n\t}\n\n\tpublic static Builder builder() {\n\t\treturn new Builder();\n\t}\n\n\t/**\n\t * Validate and normalize file path for security.\n\t * Prevents directory traversal attacks by checking for \"..\" and \"~\".\n\t *\n\t * @param path The path to validate\n\t * @param allowedPrefixes Optional list of allowed path prefixes\n\t * @return Normalized canonical path\n\t * @throws IllegalArgumentException if path is invalid\n\t */\n\tpublic static String validatePath(String path, List<String> allowedPrefixes) {\n\t\tif (TRAVERSAL_PATTERN.matcher(path).find()) {\n\t\t\tthrow new IllegalArgumentException(\"Path traversal not allowed: \" + path);\n\t\t}\n\n\t\t// Normalize path\n\t\tString normalized = path.replace(\"\\\\\", \"/\");\n\t\tnormalized = Paths.get(normalized).normalize().toString().replace(\"\\\\\", \"/\");\n\n\t\tif (!normalized.startsWith(\"/\")) {\n\t\t\tnormalized = \"/\" + normalized;\n\t\t}\n\n\t\t// Check allowed prefixes if specified\n\t\tif (allowedPrefixes != null && !allowedPrefixes.isEmpty()) {\n\t\t\tboolean hasValidPrefix = false;\n\t\t\tfor (String prefix : allowedPrefixes) {\n\t\t\t\tif (normalized.startsWith(prefix)) {\n\t\t\t\t\thasValidPrefix = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/FilesystemInterceptor.java#L144-L180","documentation":"FilesystemInterceptor.validatePath() runs a TRAVERSAL_PATTERN regex over the supplied path and rejects any match (typically \"..\", leading \"~\", etc.) with IllegalArgumentException(\"Path traversal not allowed: <path>\"). It is the interceptor-layer guard ensuring normalized, in-bounds paths before backend operations.","triggerScenarios":"Calling validatePath(path, allowedPrefixes) with a string containing traversal sequences such as \"../../secret\", backslash tricks like \"..\\\\..\\\\x\", or \"~/file\" matching the pattern.","commonSituations":"Agent/LLM tool calls receiving unsanitized user paths; Windows-style separators slipping past naive checks; legacy code that predates the traversal-pattern guard.","solutions":["Strip or reject '..' segments and '~' prefixes from user input before calling validatePath().","Normalize the path (replace \\\\ with /, run Paths.get(...).normalize()) yourself, then re-check.","Restrict inputs to identifiers resolved server-side rather than raw paths.","Return a safe validation error to the caller (e.g. an agent tool 'invalid path' result) instead of propagating the exception."],"exampleFix":"// before\nString p = FilesystemInterceptor.validatePath(userInput, prefixes); // throws\n\n// after\nString cleaned = userInput.replace(\"\\\\\", \"/\");\nif (cleaned.contains(\"..\") || cleaned.startsWith(\"~\")) {\n    throw new IllegalArgumentException(\"invalid path from user\");\n}\nString p = FilesystemInterceptor.validatePath(cleaned, prefixes);","handlingStrategy":"validation","validationCode":"if (path == null || TRAVERSAL_PATTERN.matcher(path).find()) {\n    throw new IllegalArgumentException(\"Unsafe path supplied: \" + path);\n}","typeGuard":"boolean passesTraversalCheck(String path) {\n    return path != null && !FilesystemInterceptor.TRAVERSAL_PATTERN.matcher(path).find();\n}","tryCatchPattern":"try {\n    String canonical = FilesystemInterceptor.validatePath(path, prefixes);\n} catch (IllegalArgumentException e) {\n    return Map.of(\"error\", \"invalid path\", \"detail\", e.getMessage()); // tool-result style\n}","preventionTips":["Never forward raw user/LLM path strings directly to validatePath().","Normalize backslashes and '.' segments before validation.","Treat rejection as a expected, reportable outcome in agent tools.","Add unit tests covering '../', '~/', and backslash traversal variants."],"tags":["security","path-traversal","interceptor"],"backgroundTag":"path-traversal-blocked","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}