{"record":{"id":"3ad2a21e8879c87b","repo":"dromara/Sa-Token","slug":"path-requestpath","errorCode":null,"errorMessage":"请求 path 包含禁止字符：{requestPath}","messagePattern":"请求 path 包含禁止字符：(.+?)","errorType":"exception","errorClass":"RequestPathInvalidException","httpStatus":null,"severity":"error","filePath":"sa-token-core/src/main/java/cn/dev33/satoken/strategy/hooks/SaFirewallCheckHookForPathBannedCharacter.java","lineNumber":61,"sourceCode":"     * @param bannedPercentage 是否严格禁止出现百分号字符 % （默认：否）\n     */\n    public void resetConfig(boolean bannedPercentage) {\n        this.bannedPercentage = bannedPercentage;\n    }\n\n    /**\n     * 执行的方法\n     *\n     * @param req 请求对象\n     * @param res 响应对象\n     * @param extArg 预留扩展参数\n     */\n    @Override\n    public void execute(SaRequest req, SaResponse res, Object extArg) {\n        // 非可打印 ASCII 字符检查\n        String requestPath = req.getRequestPath();\n        if(SaFoxUtil.hasNonPrintableASCII(requestPath)) {\n            throw new RequestPathInvalidException(\"请求 path 包含禁止字符：\" + requestPath, requestPath);\n        }\n        if(bannedPercentage && requestPath.contains(\"%\")) {\n            throw new RequestPathInvalidException(\"请求 path 包含禁止字符 %：\" + requestPath, requestPath);\n        }\n    }\n\n}\n","sourceCodeStart":43,"sourceCodeEnd":69,"githubUrl":"https://github.com/dromara/Sa-Token/blob/ac2c7f6e94a78573cf0bcb932dd8b04e68fad189/sa-token-core/src/main/java/cn/dev33/satoken/strategy/hooks/SaFirewallCheckHookForPathBannedCharacter.java#L43-L69","documentation":"The PathBannedCharacter firewall hook runs SaFoxUtil.hasNonPrintableASCII on the raw request path and throws RequestPathInvalidException if any non-printable ASCII character (control characters, etc.) is present. This blocks control-character injection into paths, which some proxies and log systems mishandle. It is one of two checks in the same hook; the other (message with '%') covers percent signs.","triggerScenarios":"A request path containing control chars such as \\x00-\\x1F, \\x7F, or other non-printable bytes — e.g. curl with a raw newline or null byte in the URL, or an encoded %0A that was decoded before the check runs.","commonSituations":"Attackers probing with null-byte or CRLF injection in URLs; buggy clients that embed unescaped newline/tab into paths; a gateway that percent-decodes the path before forwarding so %0d%0a becomes literal CR LF.","solutions":["Reject/fix the client that produces paths with control characters — URL-encode such data instead","If a front proxy decodes percent-escapes too early, configure it to pass the path through encoded","Treat occurrences as security events: these paths are almost never legitimate traffic"],"exampleFix":"// before\nString path = \"/files/a\" + (char)0 + \".txt\"; // non-printable in path\n\n// after\nString path = \"/files/a%00.txt\"; // kept percent-encoded on the wire","handlingStrategy":"validation","validationCode":"String path = SaHolder.getRequest().getRequestPath();\nif (SaFoxUtil.hasNonPrintableASCII(path)) {\n    // reject with 400; never normalize control chars into the path\n}","typeGuard":null,"tryCatchPattern":"try {\n    chain.doFilter(req, res);\n} catch (RequestPathInvalidException e) {\n    res.setStatus(400);\n}","preventionTips":["Always percent-encode non-ASCII/control data in URLs","Ensure proxies do not decode percent-escapes before the app sees them","Alert on repeated control-char paths — it is reconnaissance, not user error"],"tags":["sa-token","firewall","security","request-path","injection"],"backgroundTag":null,"analyzedSha":"ac2c7f6e94a78573cf0bcb932dd8b04e68fad189","analyzedAt":"2026-08-14T14:36:10.271Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}