路径穿越(Path Traversal)本质上不是“能不能写出代码”的问题,而是后端在接收文件名时把用户输入当成了文件系统的一部分。攻击者提交 "../../etc/passwd" 或 "..%2f..%2fconfig" 这类值,一旦后端不做归一化和边界校验,文件读取、写入、删除、下载接口就会变成任意文件操作入口。安全校验文件名不能只做黑名单过滤,因为编码、斜杠、反斜杠、空字节、Unicode 同形字符都会绕过简单规则。
先规范化路径,再判断归属目录
后端拿到文件名后,第一步不是检查字符串里有没有 "..",而是用当前运行环境提供的路径规范化能力,把相对路径转成绝对路径。Java 里可以用 "Paths.get(baseDir, fileName).normalize()",Node.js 用 "path.resolve(baseDir, fileName)",Python 用 "os.path.realpath" 或 "Path.resolve()"。规范化之后,再检查结果是否仍然位于允许的目录之下。
// Java 示例:校验文件是否在指定目录内
Path basePath = Paths.get("/var/app/files").toAbsolutePath().normalize();
Path targetPath = basePath.resolve(fileName).normalize();
if (!targetPath.startsWith(basePath)) {
throw new SecurityException("非法文件路径");
}
这里的关键点是 "normalize()" 会折叠 ".." 和 ".",把路径整理成标准形式。"startsWith" 判断的是规范化后的绝对路径前缀。如果攻击者传入 "../../etc/passwd",规范化后路径会跳出 "/var/app/files",前缀检查直接失败。不要用字符串包含判断,比如 "if (fileName.contains(".."))",因为 "....//"、"..%2f"、Unicode 斜杠变体都可能绕过。
拒绝绝对路径和盘符,统一使用文件名白名单
很多后端接口允许客户端传完整路径,这本身就是危险设计。业务上如果只是下载用户上传的某个文件,接口应当只接收“文件名”或“文件ID”,而不是相对路径或绝对路径。后端可以在入口处直接拒绝包含 "/"、"\"、盘符(如 "C:")的输入。更稳妥的做法是只允许符合命名规则的文件名,例如正则 "^[a-zA-Z0-9._-]+$",并且不允许连续点号或结尾点号。
// 严格文件名白名单
private static final Pattern SAFE_FILE_NAME = Pattern.compile("^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$");
public static boolean isValidFileName(String fileName) {
if (fileName == null || fileName.isEmpty()) {
return false;
}
if (fileName.startsWith(".") || fileName.endsWith(".")) {
return false;
}
return SAFE_FILE_NAME.matcher(fileName).matches();
}
白名单比黑名单可靠得多。黑名单需要枚举所有可能的危险字符和编码形式,而白名单只放行明确安全的字符集。如果业务必须支持中文文件名,可以扩展为 Unicode 字母和数字范围,但不要直接放行任意字符。另外,Windows 系统还有保留设备名问题,比如 "CON"、"PRN"、"AUX"、"NUL"、"COM1" 等,即使加了扩展名也可能触发设备访问。跨平台部署时,应当把这些保留名也列入拒绝名单。
处理编码和空字节,防止规范化绕过
路径穿越攻击经常利用 URL 编码、双重编码和空字节截断。例如 "%2e%2e%2f" 解码后是 "../","..%252f" 在部分框架中会二次解码变成 "../"。后端校验前必须确保输入已经完成一次标准解码,并且不要进行二次解码。对于空字节 "%00",Java 和 C 系语言历史上会把空字节当作字符串终止符,导致校验时看到的是 "safe.txt",实际文件系统操作时截断成另一个路径。现代运行时大多已修复空字节问题,但显式拒绝空字节仍然是必要防线。
// 拒绝空字节和未解码的危险编码
if (fileName.indexOf('\0') != -1) {
throw new SecurityException("文件名包含非法空字节");
}
// 解码后再次校验,避免双重编码绕过
String decodedFileName = URLDecoder.decode(fileName, StandardCharsets.UTF_8);
if (!decodedFileName.equals(fileName)) {
// 如果解码后内容发生变化,需要重新走完整校验流程
validateFileName(decodedFileName);
}
实际开发中,最好在框架层统一处理解码,不要在业务代码里反复解码。如果使用 Spring,可以在拦截器或过滤器中完成一次解码和校验,后续控制器拿到的就是干净的文件名。对于 Multipart 文件上传,原始文件名来自客户端,必须视为不可信输入,不能直接拼接到存储路径。
文件操作前做归属校验,而不是只校验输入字符串
即使输入字符串通过了白名单,文件系统操作仍可能受到符号链接、硬链接和目录连接的影响。攻击者可能提前在允许目录内放置一个指向敏感目录的符号链接,然后请求该符号链接下的文件。规范化路径时,"normalize()" 不会解析符号链接,因此前缀检查可能通过,但实际读取会跟随链接跳出目录。要彻底解决,需要在规范化路径后再用 "toRealPath()" 解析真实路径,然后做归属判断。
// Java 解析真实路径,防止符号链接绕过
Path baseRealPath = basePath.toRealPath();
Path targetRealPath = targetPath.toRealPath();
if (!targetRealPath.startsWith(baseRealPath)) {
throw new SecurityException("文件路径超出允许范围");
}
"toRealPath()" 会解析所有符号链接并返回真实绝对路径,但要求文件必须存在。如果文件尚不存在,例如写入新文件场景,可以先对父目录调用 "toRealPath()",再拼接文件名后做前缀检查。对于删除操作,同样先解析父目录真实路径,避免删除符号链接指向的文件。Python 中可以使用 "os.path.realpath",Node.js 使用 "fs.realpathSync",核心逻辑一致。
文件名存储与展示分离,降低直接暴露风险
很多路径穿越漏洞源于后端直接使用客户端提供的原始文件名存储文件。更好的做法是后端生成随机文件名或使用文件ID作为存储名,将原始文件名作为元数据存入数据库。下载时根据ID查询真实存储路径,响应头里可以设置经过清洗的原始文件名用于展示。这样即使攻击者提交了危险文件名,也不会影响实际文件系统路径。
// 生成安全存储文件名
String safeStorageName = UUID.randomUUID().toString().replace("-", "");
Path storagePath = basePath.resolve(safeStorageName);
// 原始文件名仅作为展示,不参与路径拼接
String originalFileName = sanitizeDisplayName(file.getOriginalFilename());
如果业务必须保留用户文件名的目录结构,例如网盘类产品,那么每个路径段都必须单独校验,不能只校验完整字符串。将路径按 "/" 拆分后,对每一段执行白名单校验,并拒绝空段、"." 和 ".."。同时限制路径深度,避免超长路径导致系统调用失败或触发其他边界问题。
配置层防御:最小权限和运行目录隔离
代码校验之外,运行环境的配置同样关键。后端服务运行时使用的系统账号,不应当拥有对敏感目录的读取权限。即使出现路径穿越漏洞,权限限制也能降低影响。文件存储目录应当独立于应用代码目录,并且不要放在 Web 根目录下。对于容器化部署,可以将文件目录挂载为只读或独立卷,限制攻击者写入任意位置的能力。
另外,在反向代理或网关层可以增加路径规范化规则,拦截包含 ".."、"%2e%2e"、"%2f" 等特征的请求。但这只能作为辅助手段,不能替代后端校验,因为编码方式和代理配置差异可能导致绕过。
测试用例要覆盖真实攻击变体
安全校验是否有效,不能只看正常文件名能否通过。测试时至少覆盖以下输入:"../etc/passwd"、"..\\..\\windows\\system32"、"....//....//etc/passwd"、"%2e%2e%2f%2e%2e%2fetc/passwd"、"..%252f..%252fetc/passwd"、"%00" 截断、Unicode 斜杠 "∕" 和全角字符、超长文件名、以点号结尾或开头的文件名、Windows 保留设备名。每个用例都要验证读取、写入、删除、下载接口的响应,确认不会返回敏感文件内容或执行越权操作。
路径穿越的防护核心是“先规范化、再验归属、后操作”,并且每一步都使用文件系统真实路径,而不是信任字符串形式。白名单限制文件名格式、随机化存储名、解析符号链接、拒绝空字节和二次编码、配置最小权限,这些措施组合起来才能形成有效防线。单独依赖任何一项都可能被绕过,安全校验必须贯穿从输入到文件系统调用的完整链路。
