sa-token/sa-token-doc/fun/firewall.md

防火墙

Sa-Token 内置防火墙组件 SaFirewallStrategy，用于拦截一些可能造成攻击的危险请求。 例如当前端提交的 path 为 /test//login 时，框架将会强制截断请求，响应以下内容：

非法请求：/test//login

因为包含双斜杠的 path 请求通常被用于鉴权绕行攻击。类似的拦截规则还有很多， SaFirewallStrategy 采用 hooks 机制，允许开发者自由扩展拦截规则， 框架默认具有以下 hook 拦截规则：

• SaFirewallCheckHookForWhitePath：请求 path 白名单放行。
• SaFirewallCheckHookForBlackPath：请求 path 黑名单校验。
• SaFirewallCheckHookForPathDangerCharacter：请求 path 危险字符校。
• SaFirewallCheckHookForPathBannedCharacter：请求 path 禁止字符校验。
• SaFirewallCheckHookForDirectoryTraversal：请求 path 目录遍历符检测。
• SaFirewallCheckHookForHost：Host 检测。
• SaFirewallCheckHookForHttpMethod：请求 Method 检测。
• SaFirewallCheckHookForHeader：请求头检测。
• SaFirewallCheckHookForParameter：请求参数检测。

1、默认 hook 配置：

假设我们想要增加请求 path 黑名单，可以使用如下代码：

@Configuration
public class SaTokenConfigure {
	@PostConstruct
	public void saTokenPostConstruct() {
		SaFirewallCheckHookForBlackPath.instance.resetConfig("/abc");
	}
}

现在从浏览器访问 /abc，将会被防火墙组件直接拦截：

非法请求：/abc

除了 SaFirewallCheckHookForBlackPath 以外，其它所有 hook 均可通过此方式重载配置，在此暂不冗余演示。

2、注册新的 hook 规则：

你可以使用如下代码注册新的 hook 规则：

@PostConstruct
public void saTokenPostConstruct() {
	// 注册新 hook 演示，拦截所有带有 pwd 参数的请求，拒绝响应 
	SaFirewallStrategy.instance.registerHook((req, res, extArg)->{
		if(req.getParam("pwd") != null) {
			throw new FirewallCheckException("请求中不可包含 pwd 参数");
		}
	});
}

除了注册新 hook 规则，你还可以移除默认 hook ，来删减你认为不必要存在的校验规则：

// 移除指定类型的 hook 验证
SaFirewallStrategy.instance.removeHook(SaFirewallCheckHookForHost.class);

3、利用自动注入特性注册 hook

如果你的项目属于 IOC 环境（例如 SpringBoot 项目），还可以这样注册 hook：

// 自定义防火墙校验 hook 
@Component
public class SaFirewallCheckHookForXxx implements SaFirewallCheckHook {
    @Override
    public void execute(SaRequest req, SaResponse res, Object extArg) {
        System.out.println("----------- 自定义防火墙校验 hook ");
    }
}

4、指定异常处理：

被防火墙拦截的请求不会做出格式化响应，因为通常这些请求为非正常业务请求，只需阻断即可，无需前端依照响应做出页面提示。

如果你的业务切实需要对防火墙拦截做出格式化响应，可以通过以下代码完成：

@PostConstruct
public void saTokenPostConstruct() {
	// 指定防火墙校验不通过时的处理方案
	SaFirewallStrategy.instance.checkFailHandle = (e, req, res, extArg) -> {
		System.out.println("防火墙校验不通过：" + e.getMessage());
		try {
			HttpServletResponse response = (HttpServletResponse)res.getSource();
			response.setContentType("application/json;charset=UTF-8");
			String resJson = SaResult.error(e.getMessage()).toString();
			response.getWriter().print(resJson);
			response.getWriter().flush();
		} catch (IOException ex) {
			throw new RuntimeException(ex);
		}
	};
}

浏览器将得到以下 json 格式响应：

{
  "code": 500,
  "msg": "非法请求：/abc",
  "data": null
}